6.5.1 Reading a Raster Image: DFR8getimage
If dimensions of the image are known, DFR8getimage is the only function call needed to read a raster image. If a file is being opened for the first time, DFR8getimage returns the first image in the file. Additional calls will return successive images in the file, therefore images are read in the order which they were written to the file. DFR8getdims is called before DFR8getimage so that space allocations for the image and palette can be checked and the dimensions verified. If this information is already known, DFR8getdims may be omitted.C: status = DFR8getimage(filename, image, width, height, palette);
FORTRAN: status = d8gimg(filename, image, width, height, palette)
DFR8getimage retrieves the next 8-bit image from the HDF file name specified by the filename parameter. If the image in the file is compressed, DFR8getimage first decompresses it then places it in memory at the location pointed to by the image parameter. The dimensions of the array allocated to hold the image are specified by the width and height parameters and may be larger than the actual image.The palette, if present, is stored in memory at the location pointed to by the palette parameter. If it contains a NULL value the palette is not loaded, even if there is one stored with the image. The parameters for DFR8getimage are defined further in Table 6G below.
Notice that in Example 4, as in the case of DFR8addimage, the order in which the dimensions for the image array are declared differs between C and FORTRAN-77. FORTRAN-77 declarations require the width before the height while the C declaration requires the height before the width as FORTRAN-77 arrays are stored in column-major order, while C arrays are stored in row-major order. (row-major order implies that the second coordinate varies fastest). When d8gimg reads an image from a file, it assumes column-major order.
6.5.2 Querying the Dimensions of an 8-Bit Raster Image: DFR8getdims
DFR8getdims opens a named file, finds the next image or the first image if the file is being opened for the first time, retrieves the dimensions of the image and determines if there is a palette associated with the image. If the file is being opened for the first time, DFR8getdims returns information about the first image in the file. If an image has already been read, DFR8getdims finds the next image. In this way, images are read in the same order in which they were written to the file.C: status = DFR8getdims(filename, width, height, haspalette);
status = DFR8getimage(filename, image, width, height, palette);
FORTRAN: status = d8gdim(filename, width, height, haspalette)
status = d8gimg(filename, image, width, height, palette)
DFR8getdims retrieves dimension and palette information about the next 8-bit image in the file specified by filename. The returned information is pointed to by the width and height parameters. The haspalette parameter determines the presence of a palette and returns a value of 1 if it exists and 0 otherwise. The parameters for DFR8getdims are defined further in the following table.TABLE 6G - DFR8getdims and DFR8getimage Parameter List
NULL is passed as the palette parameter. If the palette argument is NULL (or "0" in FORTRAN-77), all palette data is ignored.
6.5.3 Reading an Image with a Given Reference Number: DFR8readref
DFR8readref accesses specific images that are stored in files containing multiple raster image sets. It is an optionally used before DFR8getimage to set the access pointer to the specified raster image. DFR8readref can be used in connection with vgroups, which identify their members by tag/reference number pairs. See Chapter 5, titled Vgroups (V API), for a discussion of vgroups and tag/reference number pairs.C: status = DFR8readref(filename, ref);
status = DFR8getimage(filename, image, width, height, palette);
FORTRAN: status = d8rref(filename, ref)
status = d8gimg(filename, image, width, height, palette)
DFR8readref specifies that the target for the next read operation performed on the HDF file specified by the filename parameter is the object with the reference number named in the ref parameter. The parameters required for DFR8readref are defined further in the following table.TABLE 6H - DFR8readref Parameter List
C: status = DFR8restart( );
FORTRAN: status = d8first( )