[Top] [Prev] [Next] [Bottom]

8.6 Reading Data from an Image: GRreadimage

Reading one or more slabs from an image array involves the following steps:

1. Open the file and initialize the GR interface.
2. Select a data set.
3. Read data from the image array.
4. Terminate access to the data set.
5. Terminate access to the GR interface and close the file.
To read data from an image array, the calling program must contain the following function calls:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		ri_id = GRselect(gr_id, gr_index);
		status = GRreadimage(ri_id, start, stride, edge, data);
		status = GRendaccess(gr_id);
		status = GRend(ri_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access_mode, number_of_desc)
		gr_id = mgstart(file_id)
		ri_id = mgselct(gr_id, GRs_index)
		status = mgrdimg(ri_id, start, stride, edge, data)
		status = mgendac(gr_id)
		status = mgend(ri_id)
		status = hclose(file_id)

GRreadimage can be used to read either an entire image or a subset of the image. The ri_id argument is the raster image identifier returned by GRselect. As with GRwriteimage, the arguments start, stride, and edge 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. 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.

There are two Fortran-77 versions of this routine: mgrdimg and mgrcimg. The mgrdimg routine reads numeric image data and mgrcimg reads character image data.

The parameters for GRreadimage are further defined below. (See Table 8E.)

8.6.1 Reading General Raster Images from an External File

Image data is read from an external or compressed file in the same way that it is read from a primary file.

8.6.2 Setting the Interlace Mode for a Palette or Image Read

There are two GR routines that deal with setting the interlace in raster image data sets: GRreqlutil and GRreqimageil. Refer to Section 8.5.2 on page 205 for a description of the GR interlace modes.

The GRreqlutil routine sets the interlace mode for the next palette read. It can be called at anytime before the read operation and takes two parameters, ri_id and interlace_mode. The ri_id parameter is the image array identifier returned by the GRselect routine and the interlace_mode is the interlace mode that will be in effect for the next image or palette read operation.

The GRreqimageil routine sets the interlace mode for the next image read. It also can be called at anytime before the read operation and takes the same two parameters as GRreqlutil. GRreqlutil and GRreqimageil may be called more than once; the interlace mode setting specified by the last call to either routine will be used for the next read operation.

Descriptions of both interlace mode routines are included in the following table. The GR palette read and write routines are covered in Section 8.9 on page 233. Note that, because there are two Fortran-77 versions of GRreadimage, there are correspondingly two entries in the "Data Type" field of the data parameter.

TABLE 8E GRreadimage, GRreqlutil and GRreqimageil Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRreadimage

(mgrdimg/

mgrcimg)

ri_id

int32

integer

Image identifier.

start

int32[2]

integer (2)

Array containing the starting read coordinates.

stride

int32[2]

integer (2)

Array containing the number of data locations the current location is to be moved forward before the next read.

edge

int32[2]

integer (2)

Array containing the number of data element that will be read along each dimension.

data

VOIDP

<valid numeric data type>

Buffer for the returned image data.

GRreqlutil

(mgrltil)

ri_id

int32

integer

Image identifier.

interlace_mode

intn

integer

Interlace mode for the next palette read operation.

GRreqimageil

(mgrimil)

ri_id

int32

integer

Image identifier

interlace_mode

intn

integer

Interlace mode for the next image read operation.

EXAMPLE 3. Reading an Image

When GRreadimage is used to read an entire image array, the coordinates for the start position must begin at 0 for each dimension (start={0,0}), the interval between each read must equal 1 for each dimension (stride=NULL or stride={1,1}), and the size of each dimension must equal the size of the array itself (edge={dim_size_1, dim_size_2}). The data buffer must have enough space allocated to hold the data. In these examples, the image created in Example 2 is read.

C:

#include "hdf.h"

#define X_LENGTH 15
#define Y_LENGTH 10

main( )
{
	int32 gr_id, ri_id, file_id, status;
	int32 start[2], edges[2], dims[2], nattrs;
	int16 image_data[Y_LENGTH][X_LENGTH][2];

	/* Open the file. */
	file_id = Hopen("Example2.hdf", DFACC_RDONLY, 0);

	/* Open the file and initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Select the first (and in this case, only) data set in the file. */
	ri_id = GRselect(gr_id, 0);

	/* Define the location, pattern, and size of the data to read. */
	dims[0] = X_LENGTH;
	dims[1] = Y_LENGTH;
	start[0] = start[1] = 0;
	edges[0] = dims[0];
	edges[1] = dims[1];

	/* Read the data in the image array. */
	status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)image_data);

	/* Terminate access to the image array */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM READ ARRAY

      integer*4 gr_id, ri_id, file_id, status
      integer start(2), edge(2), stride(2)
      integer hopen, hclose, mgstart, mgselct, mgrdimg
      integer mgendac, mgend

C     DFACC_RDONLY is defined in hdf.h. MAX_NC_NAME and MAX_VAR_DIMS
C     are defined in netcdf.h.
      integer*4 DFACC_RDONLY, MAX_NC_NAME, MAX_VAR_DIMS
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_RDONLY = 1, MAX_NC_NAME = 256, 
     +           MAX_VAR_DIMS = 32, X_LENGTH = 15, 
     +           Y_LENGTH = 10)
      integer*2 array_data(2, X_LENGTH, Y_LENGTH)
      integer dims(MAX_VAR_DIMS)

C     Open the file.
      file_id = hopen(`Example2.hdf', DFACC_RDONLY, 0)

C     Initiate the GR interface.
      gr_id = mgstart(file_id)

C     Select the first (and in this case, only) data set in the file.
      ri_id = mgselct(gr_id, 0)

C     Define the location, pattern, and size of the data to read
C     from the data set.
      dims(1) = X_LENGTH
      dims(2) = Y_LENGTH
      start(1) = 0
      start(2) = 0
      stride(1) = 1
      stride(2) = 1
      edge(1) = dims(1)
      edge(2) = dims(2)

C     Read the array data set.
      status = mgrdimg(ri_id, start, stride, edge, array_data)

C     Terminate access to the image array.
      status = mgendac(ri_id)

C     Terminate access to the GR interface and the file.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)

      end

EXAMPLE 4. Reading a Subset of an Image Array

The following examples show how the start and edges arguments of the GRreadimage function can be initialized so that a subset of the data set can be read.

C:

#include "hdf.h"

#define X_LENGTH 15
#define Y_LENGTH 10

main( ) 
{
	int32 gr_id, ri_id, file_id;
	int32 start[2], edges[2];
	int16 all_image[2][Y_LENGTH][X_LENGTH];
	int16 subset_image[2][7][3], status;

	/* Open the file. */
	file_id = Hopen("Example2.hdf", DFACC_RDONLY, 0);

	/* Open the file for read-only access. */
	gr_id = GRstart(file_id);

	/* Select the first data set. */
	ri_id = GRselect(gr_id, 0);

	/* First, read the entire data set. */
	start[0] = start[1] = 0;
	edges[0] = X_LENGTH;
	edges[1] = Y_LENGTH;
	status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)all_image);

	/* Read a subset of the data set. */
	start[0] = 1;
	start[1] = 1;
	edges[0] = 3;
	edges[1] = 7;
	status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)subset_image);

	/* Terminate access to the array. */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM READ SUBSET

      integer*4 gr_id, ri_id, file_id
      integer start(2), edges(2), stride(2), status
      integer mgstart, mgselct, mgrdimg, mgendac, mgend
      integer hopen, hclose

C     DFACC_RDONLY is defined in hdf.h.
      integer*4 DFACC_RDONLY
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_RDONLY = 1, X_LENGTH = 15, Y_LENGTH = 10)
      integer*2 all_image(2, X_LENGTH, Y_LENGTH)
      integer*2 subset_image(2, 3, 7)

C     Open the file.
      file_id = hopen(`Example2.hdf', DFACC_RDONLY, 0)

C     Initialize the GR interface. 
      gr_id = mgstart(file_id)

C     Select the first data set. 
      ri_id = mgselct(gr_id, 0)

C     Read the entire data set. 
      start(1) = 0
      start(2) = 0
      edges(1) = X_LENGTH
      edges(2) = Y_LENGTH
      stride(1) = 1
      stride(2) = 1
      status = mgrdimg(ri_id, start, stride, edges, all_image)

C     Read a subset from the middle of the data set. 
      start(1) = 1
      start(2) = 1
      edges(1) = 3
      edges(2) = 7
      status = mgrdimg(ri_id, start, stride, edges, subset_image)

C     Terminate access to the array. 
      status = mgendac(ri_id)

C     Terminate access to the GR interface and the file. 
      status = mgend(gr_id)

C     Close the file.
      file_id = hclose(file_id)

      end

EXAMPLE 5. Sampling Image Data

These examples illustrate how samples of data set elements can be read by using the stride argument of the GRreadimage function. Here we read every fourth row and every other column.

C:

#include "hdf.h"
#include "mfgr.h"

#define X_LENGTH 10
#define Y_LENGTH 20

main( ) 
{
	int32 gr_id, ri_id, file_id, start[2], edges[2], ncomp, il;
	int32 stride[2], dims[2];
	int16 all_image[Y_LENGTH][X_LENGTH][2], sample_image[5][5][2], status;
	intn i, j;

	/* Open the file. */
	file_id = Hopen("Example5.hdf", DFACC_CREATE, 0);

	/* Open the file. */
	gr_id = GRstart(file_id);

	/* Define the number of components and dimensions of the image. */
	ncomp = 2;
	dims[0] = X_LENGTH;
	dims[1] = Y_LENGTH;	
	il = MFGR_INTERLACE_PIXEL;

	/* 	Create the array. */
	ri_id = GRcreate(gr_id, "Image_array_5", ncomp, DFNT_INT16, il, dims);

	/* 	Compute and store the data values. */
	for (j = 0; j < Y_LENGTH; j++) {
		for (i = 0; i < X_LENGTH; i++) {
			all_image[j][i][0] = i + j * 10;
			all_image[j][i][1] = i + j * 10;
		}
	}

	/* Define the start and edge parameters. */
	start[0] = start[1] = 0;
	edges[0] = X_LENGTH;
	edges[1] = Y_LENGTH;

	/* Write the buffered data in all_image to the array. */
	status = GRwriteimage(ri_id, start, NULL, edges, (VOIDP)all_image);

	/* Close the GR interface and the file, then re-open both and 
	select the first and only data set in the file. */
	status = GRendaccess(ri_id);
	status = GRend(gr_id);
	status = Hclose(file_id);
	file_id = Hopen("Example5.hdf", DFACC_RDONLY, 0);
	gr_id = GRstart(file_id);
	ri_id = GRselect(gr_id, 0);

	/* Read the data into sample_image, skipping every fourth \
	row and every other column. */
	start[0] = start[1] = 0;
	edges[0] = 5;
	edges[1] = 5;
	stride[0] = 2;
	stride[1] = 4;
	status = GRreadimage(ri_id, start, stride, edges, (VOIDP)sample_image);

	/* Terminate access to the array */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface the file */
	status = GRend(gr_id);

	/* Close the file */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM READ STRIDES

      integer*4 gr_id, ri_id, file_id, ncomp, il
      integer*4 start(2), edges(2), stride(2), dims(2)
      integer i, j, status
      integer mgstart, mgcreat, mgwrimg, mgendac
      integer mgselct, mgend, hopen, hclose

C     DFACC_CREATE and DFNT_INT16 are defined in hdf.h.
      integer*4 DFACC_CREATE, DFACC_RDONLY, DFNT_INT16
      integer*4 X_LENGTH, Y_LENGTH

      parameter (DFACC_CREATE = 4, DFACC_RDONLY = 1, DFNT_INT16 = 22,
     +           X_LENGTH = 10, Y_LENGTH = 20)
      integer*2 all_image(2, X_LENGTH, Y_LENGTH)

C     Create the file.
      file_id = hopen(`Example5.hdf', DFACC_CREATE, 0)

C     Create the file.
      gr_id = mgstart(file_id)

C     Define the number of components and dimensions of the image.
      ncomp = 2
      dims(1) = X_LENGTH
      dims(2) = Y_LENGTH

C     Create the array.
      ri_id = mgcreat(gr_id, `Image_array_5', ncomp, DFNT_INT16, il,
     +           dims)

C     Compute and store the data values.
      do 20 j = 1, Y_LENGTH
         do 10 i = 1, X_LENGTH
            all_image(1, i, j) = i + j * 10
            all_image(2, i, j) = i + j * 10
10       continue
20    continue

C     Set up the start and edge parameters to write the buffered
C     data to the entire array.
      start(1) = 0
      start(2) = 0
      edges(1) = X_LENGTH
      edges(2) = Y_LENGTH
      stride(1) = 1
      stride(2) = 1

C     Write the buffered data in all_image to the data set array.
      status = mgwrimg(ri_id, start, stride, edges, all_image)

C     Close the GR interface and the file, then re-open both and
C     select the first and only data set in the file.
      status = mgendac(ri_id)
      status = mgend(gr_id)
      status = hclose(file_id)
      file_id = hopen(`Example5.hdf', DFACC_RDONLY, 0)
      gr_id = mgstart(file_id)
      ri_id = mgselct(gr_id, 0)

C     Read the data into sample_image, skipping every fourth row
C     and every other column.
      edges(1) = 5
      edges(2) = 5
      stride(1) = 4
      stride(2) = 2

C     Terminate access to the array.
      status = mgendac(ri_id)

C     Terminate access to the GR interface.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)

      end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.