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)
ORC: 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.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.
TABLE 6C - DFR8putimage and DFR8addimage Parameter List
C 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
|
|
|
|
| |
|
|
| |||
|
|
|
Palette to be assigned.
| |
C 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. 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.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.
TABLE 6E - DFR8setcompress Parameter List
paletteA and are compressed using the RLE method; the third and fourth use palette paletteB and are not compressed. C 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.
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