8-Bit Raster Images (DFR8 API)

6.5 Reading 8-Bit Raster Images

The DFR8 programming model for reading an 8-bit raster image set is as follows:

Determine the dimensions of the image if they are not known prior to the read operation.
Read the image from the file.

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.

To read a raster image from an HDF file, the calling program must contain the following:

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.

To determine the dimensions of an image before attempting to read it, the calling program must include the following routines:

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

Routine Name

[Return Type]
(FORTRAN-77) Parameter Parameter Type Description

C FORTRAN-77

DFR8getdims

[intn]

(d8gdims)
`filename` `char ` `character()` Name of the HDF file containing the set of raster images.

`width` `int32 ` `integer` Number of columns in the next raster image.

`height` `int32 ` `integer` Number of rows in the next raster image.

`ispalette` `intn ` `integer` "1" if a palette exists, otherwise "0".

DFR8getimage

[intn]

(d8gimg)
`filename` `char ` `character()` Name of HDF file with the raster image.

`image` `uint8 ` `character()` Buffer for the raster image.

`width` `int32` `integer` Width of the raster image buffer.

`height` `int32` `integer` Height of the raster image buffer.

`palette` `uint8 ` `character(*)` Palette assigned to the raster image.

Routine Name [Return Type] (FORTRAN-77)	Parameter	Parameter Type	Description
C	FORTRAN-77
DFR8getdims [intn] (d8gdims)	`filename`	`char *`	`character()`	Name of the HDF file containing the set of raster images.
`width`	`int32 *`	`integer`	Number of columns in the next raster image.
`height`	`int32 *`	`integer`	Number of rows in the next raster image.
`ispalette`	`intn *`	`integer`	"1" if a palette exists, otherwise "0".
DFR8getimage [intn] (d8gimg)	`filename`	`char *`	`character()`	Name of HDF file with the raster image.
`image`	`uint8 *`	`character()`	Buffer for the raster image.
`width`	`int32`	`integer`	Width of the raster image buffer.
`height`	`int32`	`integer`	Height of the raster image buffer.
`palette`	`uint8 *`	`character()`	Palette assigned to the raster image.

EXAMPLE 5. Reading an 8-Bit Raster Image

The following examples search the "Example1.hdf" file created in Example 1 for the dimensions of an 8-bit image. Although the DFR8getdims call is optional, it is included as a demonstration of how to check the dimensions of an image. This example also assumes that the data set does not include a palette, therefore NULL is passed as the palette parameter. If the palette argument is NULL (or "0" in FORTRAN-77), all palette data is ignored.

C version

FORTRAN-77 version

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.

To access a specific raster image set, use the following calling sequence:

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

Routine Name

[Return Type]
(FORTRAN-77) Parameter Parameter Type Description

C FORTRAN-77

DFR8readref

[intn]

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

`ref` `uint16` `integer` Reference number for next call to DFR8getimage.

Routine Name [Return Type] (FORTRAN-77)	Parameter	Parameter Type	Description
C	FORTRAN-77
DFR8readref [intn] (d8rref)	`filename`	`char *`	`character()`	Name of HDF file containing the raster image.
`ref`	`uint16`	`integer`	Reference number for next call to DFR8getimage.

6.5.4 Specifying the Next 8-Bit Raster Image to be Read: DFR8restart

DFR8restart causes the next call to DFR8getimage or DFR8getdims to read the first raster image set in the file. Use the following call to invoke DFR8restart:

C:		status = DFR8restart( );

FORTRAN:	status = d8first( )

[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu