[Top] [Prev] [Next]

7.5 Reading 24-Bit Raster Images

The DF24 programming model for reading a 24-bit raster image set is as follows:

  1. Determine the dimensions for an image if necessary.
  2. Specify the interlace format to use when reading the image. (optional)
  3. Read the image data from the file.

7.5.1 Reading a Raster Image: DF24getimage

If the dimensions and interlace format of the image are known, DF24getimage is the only function call required to read a raster image. If a file is being opened for the first time, DF24getimage returns the first image in the file. Additional calls will return successive images in the file, therefore images are read in the same order in which they were written to the file. Normally, DF24getdims and DF24getil are called before DF24getimage so that, if necessary, space allocations and interlace format for the image can be checked and the dimensions verified. If this information is already known, both function calls may be omitted.

The syntax of the DF24getimage routine is as follows:

C:		status = DF24getimage(filename, image, width, height);
FORTRAN:	status = d2gimg(filename, image, width, height)			
DF24getimage retrieves the next 24-bit image from the HDF file specified by the filename parameter. If the image is compressed, DF24getimage decompresses it and places it in memory at the location pointed to by the image parameter. DF24getimage assumes the data is stored using pixel interlacing. The space allocated to hold the image is specified by the width and height parameters and may be larger than the actual image.The parameters for DF24getimage are further defined below. Table 7F on page 254

7.5.2 Determining the Dimensions of an Image: DF24getdims

DF24getdims 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, then determines the interlace format of the image. Images are read in the order they were written.

To determine the dimensions and interlace format for an image, the calling program must call the following routines:

C:		status = DF24getdims(filename, width, height, il);
		status = DF24getimage(filename, image, width, height);
FORTRAN:	status = d2gdim(filename, width, height, il)
		status = d2gimg(filename, image, width, height)			
DF24getdims takes four parameters: filename, width, height, and il. It retrieves dimension and interlace format information of the next 24-bit image stored in the HDF file specified by the filename parameter. The width and height are returned in the space pointed to by the width and height parameters respectively. The il parameter is used to determine the interlace format. The parameters for DF24getdims are further defined below. (See Table 7F.)

7.5.3 Modifying the Interlacing of an Image: DF24reqil

DF24reqil specifies an interlace format to be used when reading a 24-bit image from a file into memory. Regardless of what interlace format is used to store the image, DF24reqil forces the image to be loaded into memory using the specified interlace format.

To set or reset the interlace format, the calling program should call the following routines:

C:		status = DF24reqil(il);
		status = DF24getimage(filename, image, width, height);
FORTRAN:	status = d2reqil(il)
		status = d2gimg(filename, image, width, height)
DF24reqil takes il as its only parameter. Valid il values are DFIL_PIXEL, DFIL_LINE and DFIL_PLANE. As a call to DF24reqil may require a substantial reordering of the data, a much slower I/O performance than would be achieved if the interlace format wasn't reset may result.

The parameters of DF24reqil is further defined below. (See Table 7F.)

TABLE 7F - DF24getimage, DF24getdims and DF24reqil Parameter List

Routine Name

[Return Type]

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

[intn]

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

image
VOIDP
<valid numeric data type>
Buffer for the raster image.

width
int32
integer
Width of the raster image buffer.

height
int32
integer
Height of the raster image buffer.

DF24getdims
[intn]
(d2gdims)
filename
char *
character*(*)
Name of HDF file containing the raster image.

width
int32 *
integer
Pointer to the number of columns in the raster image.

height
int32 *
integer
Pointer to the number of rows in the raster image.

il
intn
integer
Pointer to the interlace format of the raster image.

DF24reqil
[intn]
(d2reqil)
il
intn
integer
Pointer to the interlace format of the raster image.

EXAMPLE 4. Reading a 24-Bit Raster Image from an HDF File

The following examples read a 24-bit image from the "Example2.hdf" HDF file created in Example 2. Although the DF24getdims function call is optional, it is included as a demonstration of how to verify the image dimensions and interlace format before reading the image data. If the image dimensions and interlace format are known, only the DF24getimage call is required.

C version

FORTRAN-77 version

7.5.4 Reading a 24-Bit Raster Image with a Given Reference Number: DF24readref

DF24readref is used to access specific images stored in files containing multiple raster image sets. It is optionally used before DF24getimage. DF24readref can be used in connection with vgroups, which identify their members by tag/reference number pairs. See Chapter 5, Vgroups (V API), for a discussion of vgroups and tag/reference number pairs.

To access a specific raster image set, use the following sequence of routine calls:

C:		status = DF24readref(filename, ref);
		status DF24getimage(filename, image, width, height);
FORTRAN:	status = d2rref(filename, ref)
		status = d2gimg(filename, image, width, height)
DF24readref sets the reference number for the next read operation performed on the HDF file filename to the reference number contained in ref. Because reference numbers are not always assigned in sequence, it is not guaranteed that a reference number represents the location of the image in the file.

The parameters of DF24readref are further described in the following table.

TABLE 7G - DF24readref Parameter List

Routine Name

[Return Type]

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

[intn]

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

ref
uint16
integer
Reference number for the next call to DF24getimage.

7.5.5 Specifying that the Next Image Read to be the First 24-Bit Raster Image in the File: DF24restart

DF24restart causes the next call to DF24getimage or DF24getdims to read from the first raster image set in the file, rather than the RIS24 following the one that was most recently read. Use the following call to invoke DF24restart:

C:		status = DF24restart( );
FORTRAN:	status = d2first( )

TABLE 7H - DF24restart Parameter List

Routine Name

[Return Type]

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

[intn]

(d2first)
None
None
None
None.



[Top] [Prev] [Next]

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