[Top] [Prev] [Next]

8.7 Reading Raster Images

Image array data can be read as an entire array or as a subsample of the array. Raster image data is read from an external file in the same way that it is read from a primary file; whether the image array is stored in an external file is transparent to the user. This section describes how GRreadimage is used to read an entire image and part of an image. The section also describes the routine GRreqimageil that sets the interlacing for reading image data.

8.7.1 Reading Data from an Image: GRreadimage

Reading data subsamples from an image array involves the following steps:

  1. Select a data set.
  2. Read data from the image array.
  3. Terminate access to the data set.

To read data from an image array, the calling program must contain the following function calls:

C:		ri_id = GRselect(gr_id, ri_index);
		status = GRreadimage(ri_id, start, stride, edges, data);
		status = GRendaccess(ri_id);
FORTRAN:	ri_id = mgselct(gr_id, ri_index)
		status = mgrdimg(ri_id, start, stride, edges, data)
	OR	status = mgrcimg(ri_id, start, stride, edges, data)
		status = mgendac(gr_id)
GRreadimage can be used to read either an entire image or a subsample of the image. The ri_id argument is the raster image identifier returned by GRselect. As with GRwriteimage, the arguments start, stride, and edges respectively describe the starting location for the read operation, the number of locations the current image array location will be moved forward after each read, and the length of each dimension to be read. Refer to Section 8.6.1 on page 267 for detailed descriptions of the parameters start, stride, and edges. If the image array is smaller than the data argument array, the amount of data read will be limited to the maximum size of the image array.

Note that the FORTRAN-77 version of GRreadimage has two routines; mgrdimg reads numeric image data and mgrcimg reads character image data.

GRreadimage returns either SUCCEED (or 0) or FAIL (or -1). The parameters for GRreadimage are further defined in (See Table 8F.).

8.7.2 Setting the Interlace Mode for an Image Read: GRreqimageil

The GRreqimageil routine sets the interlace mode for the next image read. The syntax of this routine is as follows:

C:		status = GRreqimageil(ri_id, interlace_mode);
FORTRAN:	status = mgrimil(ri_id, interlace_mode)
GRreqimageil can be called at any time before the read operation and takes two parameters, ri_id and interlace_mode. The parameter ri_id is the raster image identifier returned by the GRselect routine and the parameter interlace_mode specifies the interlace mode that will be in effect for the image read operation. Refer to Section 8.5.1 on page 266 for a description of the GR interlace modes.

GRreqimagetil may be called more than once; the interlace mode setting specified by the last call to the routine will be used for the next read operation.

GRreqimagetil returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 8F.

TABLE 8F - GRreadimage and GRreqimageil Parameter Lists

Routine Name

[Return Type]

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

[intn]

(mgrdimg/
mgrcimg)
ri_id
int32
integer
Raster image identifier

start
int32[2]
integer (2)
Array containing the starting read coordinates

stride
int32[2]
integer (2)
Array specifying the interval between the values that will be read along each dimension

edges
int32[2]
integer (2)
Array containing the number of data elements that will be read along each dimension

data
VOIDP
<valid numeric data type>(*)/character*(*)
Buffer for the image data to be read

GRreqimageil

[intn]

(mgrimil)
ri_id
int32
integer
Raster image identifier

interlace_mode
intn
integer
Interlace mode for the next image read operation

EXAMPLE 3. Reading a Raster Image.

This example illustrates the use of the routine GRreadimage/mgrdimg to read an image and its subsets.

In this example, the program reads the image written by Example 1 and modified by Example 2 in the file "General_RImages.hdf". Recall that this image has two components and has 5 rows and 10 columns. The program first reads the entire image, then reads a subset of the image, 3 rows and 2 columns starting at the 2nd row and the 4th column, and finally reads the image skipping all the even rows and all the odd columns. Reading patterns are applied to all components.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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