[Top] [Prev] [Next]

6.4 Writing 8-Bit Raster Images

The DFR8 programming model for writing an 8-bit raster image sets is as follows:

  1. Set the compression type if the image is to be compressed. (optional)
  2. Identify the palette if one is to be stored with the image. (optional)
  3. Write the raster data to the file.

The two optional steps can be invoked in any order, as long as they are executed before Step 3. By default, images are stored uncompressed with no associated palette.

6.4.1 Storing a Raster Image: DFR8putimage and DFR8addimage

To write a raster image to an HDF file, the calling program must contain the following:

C:		status = DFR8putimage(filename, image, width, height, compress);
FORTRAN:	status = d8pimg(filename, image, width, height, compress)
OR

C:		status = DFR8addimage(filename, image, width, height, compress);
FORTRAN:	status = d8aimg(filename, image, width, height, compress)
DFR8putimage and DFR8addimage write an 8-bit raster image to an HDF file named by the filename parameter. When given a new filename, DFR8putimage and DFR8addimage create a new file and write the raster image as the first raster image in the file. When given an existing filename, DFR8putimage overwrites the file whereas DFR8addimage appends data to the end of the file.

In the DFR8putimage and DFR8addimage functions, the raster data is passed in the image parameter and the width and height of the image are passed in the width and height parameters. The compression algorithm used to store the image is passed in the compress parameter. Valid compress values include COMP_NONE, COMP_RLE, COMP_JPEG and COMP_IMCOMP. COMP_NONE represents no compression (storage only), COMP_RLE represents run-length encoding, COMP_JPEG represents JPEG compression and COMP_IMCOMP represents IMCOMP encoding.

Parameters for DFR8putimage and DFR8addimage are further described below. Table 6C on page 235

TABLE 6C - DFR8putimage and DFR8addimage Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFR8putimage

[intn]

(d8pimg)

and

DFR8addimage

[intn]

(d8aimg)
filename
char *
character*(*)
Name of file the raster image will be stored in.

image
VOIDP
<valid numeric data type>
Image data array.

width
int32
integer
Number of columns in the raster image.

height
int32
integer
Number of rows in the raster image.

compress
int16
integer
Compression type.

EXAMPLE 1. Writing an 8-Bit Raster Image to an HDF File

In the following code examples, DFR8addimage and d8aimg are used to write an 8-bit image to a file named "Example1.hdf". Note that the order in which the dimensions for the image array are declared differs between C and FORTRAN-77.

C version

FORTRAN-77 version

6.4.2 Adding a Palette to an RIS8 Object: DFR8setpalette

DFR8setpalette identifies the palette to be used for the subsequent write operations. It may be used to assign a palette to a single image or several images. After a palette has been set, it acts as the current palette until it is replaced by another call to DFR8setpalette. To create a raster image set containing a palette, the calling program must contain the following:

C:		status = DFR8setpalette(palette);
		status = DFR8addimage(filename, image, width, height, compress);
FORTRAN:	status = d8spal(palette)
		status = d8aimg(filename, image, width, height, compress)
DFR8setpalette takes palette as its only parameter. To set the default palette to "no palette", pass NULL as the palette parameter. DFR8setpalette is further defined in the following table.

TABLE 6D - DFR8setpalette Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFR8setpalette

[intn]

(d8spal)
palette
uint8 *
character*(*)
Palette to be assigned.

EXAMPLE 2. Writing a Palette and an Image in RIS8 Format

These examples demonstrate how a palette stored in the array colors and the raw image stored in the 20 x 20 array picture is written to a RIS8 object. The image is not compressed and, in these examples, uninitialized. The raster image set is stored as the first image in "Example2.hdf". Note that because DFR8putimage recreates the file, anything previously contained in this file will be erased.

C version

FORTRAN-77 version

6.4.3 Compressing 8-Bit Raster Image Data: DFR8setcompress

The compression type is determined by the tag passed as the fifth argument in calls to the DFR8putimage and DFR8addimage routines. DFR8setcompress is currently required only to reset the default JPEG compression options. However, future versions of this routine will support additional compression schemes.

To set non-default compression parameters, the calling program should contain the following sequence of routines:

C:		status = DFR8setcompress(type, c_info);
		status = DFR8addimage(filename, image, width, height, compress);
FORTRAN:	status = d8scomp(type)
		<compression-specific code>
		status = d8aimg(filename, image, width, height, compress)
Notice that the calling sequence for C differs from the calling sequence for FORTRAN-77. Once the compression is set, the parameter type in the DFR8setcompress routine, or d8scomp in FORTRAN-77, specifies the compression method that will be used when storing the raster images. However, the c_info parameter, which is a pointer to a structure that contains information specific to the compression scheme indicated by the type parameter in DFR8setcompress, is missing from d8scomp. Because data structures of variable size are not supported in FORTRAN-77, another routine specific to the compression library is required in the FORTRAN-77 calling sequence.

The c_info union is described in Chapter 3, titled Scientific Data Sets (SD API). The values contained in this union are passed into the d8sjpeg FORTRAN-77-specific routine.

Parameters for DFR8setcompress and d8sjpeg are further described in Table 6E below.

TABLE 6E - DFR8setcompress Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFR8setcompress

[intn]

(d8scomp)
type
int32
integer
Compression method.

c_info
comp_info *
None
Pointer to JPEG information structure.

(d8sjpeg)
[integer]
quality
none
integer
JPEG quality factor.

baseline
none
integer
JPEG baseline.

EXAMPLE 3. Writing a Set of Compressed 8-Bit Raster Images

These examples contain a series of calls in which four 20 x 20 images are written to the same file. The first two use palette paletteA and are compressed using the RLE method; the third and fourth use palette paletteB and are not compressed.

C version

FORTRAN-77 version

EXAMPLE 4. Compressing and Writing a 8-Bit Raster Image

In the following examples, DFR8addimage and DFR8compress are used to compress an 8-bit image and write it to an HDF file named "Example2.hdf". Notice that compressing an image in C requires only one function call, whereas compressing an image using FORTRAN-77 requires two. The second FORTRAN-77 call is required because it is not valid to pass a structure as a parameter in FORTRAN-77.

C version

FORTRAN-77 version

6.4.4 Specifying the Reference Number of an RIS8: DFR8writeref

DFR8writeref specifies the reference number of the image to be written when DFR8addimage or DFR8putimage is called. Use the following calling sequence to invoke DFR8writeref:

C:		status = DFR8writeref(filename, ref);
		status = DFR8addimage(filename, image, width, height, compress);
FORTRAN:	status = d8wref(filename, ref)
		status = d8aimg(filename, image, width, height, compress)
DFR8writeref assigns the reference number passed in the ref parameter to the next image the file specified by the filename parameter. If the value of ref is the same as the reference number of an existing RIS8, the existing raster image data will be overwritten. The parameters for DFR8writeref are further described below. (See Table 6F.)

It is unlikely that you will need this routine, but if you do, use it with caution. It is not safe to assume that a reference number indicates the file position of the corresponding image as there is no guarantee that reference numbers appear in sequence in an HDF file.

TABLE 6F - DFR8writeref Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFR8writeref

[intn]

(d8wref)
filename
char *
character*(*)
Name of the HDF file containing the raster image.

ref
uint16
integer
Reference number for next call to DFR8getimage.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.