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

8.7 Obtaining Information About Files and General Raster Images

The routines covered in this section provide methods for obtaining information about the images in a file, for identifying images that meet certain criteria, and for obtaining information about the data sets themselves.

GRfileinfo gives the number of images and file attributes in a file, and GRgetiminfo provides information about individual images. To cycle through the images in a file, a calling program must use GRfileinfo to determine the number of images, followed by repeated calls to GRgetiminfo to view them. The parameters for these routines are described below. (See Table 8F on page 219.)

8.7.1 Obtaining Information about the Contents of a File: GRfileinfo

It is often useful to determine the number of images and global file attributes contained in a file before executing a series of read or write operations. The GRfileinfo routine is designed for this purpose. To determine the contents of a file, the calling program must contain the following:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		status = GRfileinfo(gr_id, &n_datasets, &n_file_attr);
		status = GRend(gr_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access_mode, number_of_desc)
		gr_id = mgstart(filename, access_mode)
		status = mgfinfo(gr_id, n_datasets, n_file_attr)
		status = mgend(gr_id)
		status = hclose(file_id)

The number of images in the file will be returned in the n_datasets argument, and n_file_attr will contain the total number of file attributes.

8.7.2 Obtaining Information About an Image: GRgetiminfo

It is impossible to allocate the proper amount of memory to buffer the image data when the number of components, dimension sizes and/or data type of the image are unknown. The GRgetiminfo routine provides necessary information about images for this purpose. To access information about an image, the calling program must contain the following:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		ri_id = GRselect(gr_id, gr_index);
		status = GRgetiminfo(ri_id, name, &ncomp, &data_type, &il, dim_sizes,
			&n_attr);
		status = GRend(gr_id);
		status = GRendaccess(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, gr_index)
		status = mggiinf(ri_id, name, ncomp, data_type, il, dim_sizes,
			n_attr)
		status = mgend(gr_id)
		status = mgendac(ri_id);
		status = hclose(file_id)

GRgetiminfo takes a raster image identifier as input, and returns the name, number of components, data type, interlace mode, dimension size and number of attributes for the corresponding image in the name, ncomp, nt, il, dim_sizes and n_attr arguments respectively. The number of components of an image array element corresponds to the order of a vdata field, therefore this implementation of image components in the GR interface is flexible enough to accommodate any representation of pixel data. The calling program determines this representation; the GR interface recognizes only the raw byte configuration of the data. The attribute count will only reflect the number of attributes assigned to the image array; file attributes are not included.

TABLE 8F GRfileinfo and GRgetiminfo Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRfileinfo

(mgfinfo)

gr_id

int32

integer

General raster data set identifier.

n_datasets

int32 *

integer

Number of data sets in the file.

n_file_attr

int32 *

integer

Number of global attributes in the file.

GRgetiminfo

(mggiinf)

ri_id

int32

integer

Image identifier.

name

char *

character* (*)

Buffer for the name of the image.

ncomp

int32 *

integer

Buffer for the number of components in the image.

data_type

int32 *

integer

Buffer for the data type for the data in the image.

il

int32 *

integer

Buffer for the interlace type of the data in the image.

dim_sizes

int32 [2]

integer (2)

Buffer for the size of each dimension in the image.

nattrs

int32 *

integer

Buffer for the number of attributes in the image.

EXAMPLE 6. Retrieving Image Information

The following examples illustrate the use of the GRgetiminfo routine.

C:

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

#define X_LENGTH 15
#define Y_LENGTH 10

main( ) 
{
	int32 gr_id, ri_id, file_id, status, il;
	int32 nt, dimsizes[2], ncomp, nattrs;
	int32 start[2], edges[2];
	int16 image_data[Y_LENGTH][X_LENGTH][2];
	char name[MAX_GR_NAME];

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

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

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

	/* Verify the characteristics of the image. */
	status = GRgetiminfo(ri_id, name, &ncomp, &nt, &il, dimsizes, &nattrs);

	/* Define the location, pattern, and size of the data to read from \
		the image. */
	start[0] = start[1] = 0;
	edges[0] = dimsizes[0];
	edges[1] = dimsizes[1];

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

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

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

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

}

FORTRAN:

	 PROGRAM GET IMAGE INFO

      integer*4 gr_id, ri_id, file_id, il, ncomp
      integer*4 data_type, nattrs, status
      integer start(2), edge(2), stride(2)
      integer mgstart, mgselct, mggiinf
      integer mgrdimg, mgendac, mgend, hopen, hclose
      integer*4 DFACC_RDONLY, MAX_GR_NAME
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_RDONLY = 1, MAX_GR_NAME = 256, 
     +           X_LENGTH = 15, Y_LENGTH = 10)
      integer*2 image_data(2, X_LENGTH, Y_LENGTH)
      character name(MAX_GR_NAME)
      integer*4 dimsizes(2)

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) image in the file.
      ri_id = mgselct(gr_id, 0)

C     Verify the characteristics of the image.
      status = mggiinf(ri_id, name, ncomp, data_type, il, dimsizes,
     +            nattrs)

C     Define the location, pattern, and size of the data to read
C     from the image.
      start(1) = 0
      start(2) = 0
      stride(1) = 1
      stride(2) = 1
      edge(1) = dimsizes(1)
      edge(2) = dimsizes(2)

C     Read the image.
      status = mgrdimg(ri_id, start, stride, edge, image_data)

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

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

C     Close the file.
      status = hclose(file_id)

      end

EXAMPLE 7. Printing Image Names

The GRgetiminfo function can be called within a loop to retrieve the names of all images in an HDF file, as shown in the following examples.

C:

#include "hdf.h"

main( ) 
{
	int32 gr_id, ri_id, file_id, n_datasets, n_file_attrs, gr_index;
	int32 dim_sizes[2];
	int32 ncomp, il, data_type, attributes, status;
	char name[MAX_GR_NAME];

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

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Determine the contents of the file. */
	status = GRfileinfo(gr_id, &n_datasets, &n_file_attrs);

	/* Access and print the name of each image in the file. */
	for (gr_index = 0; gr_index < n_datasets; gr_index++) {
		ri_id = GRselect(gr_id, gr_index);
		status = GRgetiminfo(ri_id, name, &ncomp, &data_type, \
        					&il, dim_sizes, &attributes);
		printf("name = %s\n", name);
		status = GRendaccess(ri_id);
	}

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

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

}

FORTRAN:

	 PROGRAM PRINT NAMES

      integer*4 gr_id, ri_id, file_id
      integer*4 n_datasets, n_file_attrs, index, status
      integer*4 attributes
      integer mgstart, mgfinfo, mgselct, mggiinf
      integer mgendac, mgend, hopen, hclose

      integer*4 DFACC_RDONLY, MAX_GR_NAME
      parameter (DFACC_RDONLY = 1, MAX_GR_NAME = 256)

      integer*4 dim_sizes(2)
      character name *(MAX_GR_NAME)

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

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

C     Determine the contents of the file.
      status = mgfinfo(gr_id, n_datasets, n_file_attrs)

C     Access and print the names of every data set in the file.
      do 10 gr_index = 0, n_datasets - 1
         ri_id = mgselct(gr_id, index)
         status = mggiinf(ri_id, name, ncomp, data_type, il,
     +                    dim_sizes, attributes)
         print *, "name = ", name
         status = mgendac(ri_id)
10    continue

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

C     Close the file.
      status = hclose(file_id)

      end

8.7.3 Getting the Index of an Image: GRreftoindex and GRnametoindex

In addition to an index and name, images are also assigned a tag and reference number. GRreftoindex determines the index of the image from its reference number.

Selecting a data set from a given reference number involves the following steps:

1. Open the file.
2. Convert the reference number for the image into an index number.
3. Select the image by obtaining its identifier from its index number.
The calling program must contain the following:

C:		gr_id = GRstart(file_id);
		gs_index = GRreftoindex(gr_id, ref);
		ri_id = GRselect(gr_id, gs_index);

FORTRAN:	gr_id = mgstart(file_id)
		gs_index = mgr2idx(gr_id, ref)
		ri_id = mgselct(gr_id, gs_index)

GRreftoindex returns the index specified by the gs_index parameter for the image in the file with the reference number ref. The index gs_index can then be passed to GRselect to obtain an identifier for the image.

Images can also be selected using the image name as the search criteria. The calling sequence described above is the same for this purpose, except GRnametoindex is called instead of GRreftoindex and the image name is passed as the second parameter to GRnametoindex. As with GRreftoindex, GRnametoindex returns the index number of the target image.

TABLE 8G GRreftoindex and GRnametoindex Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRreftoindex

(mgr2idx)

gr_id

int32

integer

General raster data set identifier.

ref

uint16

integer

Reference number of the target image.

GRnametoindex

(mgn2ndx)

gr_id

int32

integer

General raster data set identifier.

name

char *

character (*)

Name of the target image.

EXAMPLE 8. Searching for an Image Index

If the index of a image isn't known, the GRnametoindex function can be used to retrieve the index based on a given data set name. In these examples, an invalid image name is given which results in GRnametoindex returning a value of -1. A valid image name is then provided and the returned index is used to read the contents of the corresponding image.

C:

#include "hdf.h"

#define X_LENGTH 10
#define Y_LENGTH 20

main( ) 
{

	int32 gr_id, gr_index, ri_id, file_id, status;
	int32 start[2], edges[2]; 
	int16 image_data[Y_LENGTH][X_LENGTH][2];

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

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Search for the index of a non-existent image. */
	gr_index = GRnametoindex(gr_id, "Invalid_Data_Set_Name");

	/* Error condition: gr_index contains the value -1. */

	/* Search for the index of the image named "Image_array_5". */
	gr_index = GRnametoindex(gr_id, "Image_array_5");

	/* Select the image corresponding to the returned index. */
	ri_id = GRselect(gr_id, gr_index);

	/* Read the data set data into the array_data array. */
	start[0] = start[1] = 0;
	edges[0] = X_LENGTH;
	edges[1] = Y_LENGTH;
	status = GRreadimage(ri_id, start, NULL, edges, (VOIDP)image_data);

	/* 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 SEARCH INDEX

      integer*4 gr_id, gr_index, ri_id, file_id, status
      integer*4 start(2), edges(2), stride(2) 
      integer mgstart, mgn2ndx, mgrdimg, mgendac, mgselct
      integer mgend, 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 = 10, Y_LENGTH = 20)
      integer*2 image_data(2, X_LENGTH, Y_LENGTH)

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

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

C     Search for the index of a non-existent image. 
      gr_index = mgn2ndx(gr_id, `Invalid_Data_Set_Name')

C     Error condition: gr_index contains the value -1. 
C     Search for the index of the image named `Image_array_5'. 
      gr_index = mgn2ndx(gr_id, `Image_array_5')

C     Select the image corresponding to the returned index.
      ri_id = mgselct(gr_id, gr_index)

C     Read the image data into the image_data array. 
      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, image_data)

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.
      status = hclose(file_id)

      end

8.7.4 Compressing General Raster Images

Images can be compressed by calling the GRsetcompress routine. GRsetcompress compresses the image data at the time it is called and supports all standard HDF compression algorithms. The syntax of the GRsetcompress routine is as follows:

C:		status = GRsetcompress(ri_id, comp_type, c_info);

As with SDsetcompress, the comp_type argument is the compression type definition and all compression method definitions supported in SDsetcompress are also supported in GRsetcompress. The c_info argument is a structure of type comp_info - this structure is defined in the "hcomp.h" header file and in Chapter 3 titled Scientific Data Sets (SD API). It contains the algorithm-specific information necessary for GRsetcompress to perform the specified data compression.

TABLE 8H GRsetcompress Parameter List
Routine Name

Parameter

Data Type

Description

C

GRsetcompress

ri_id

int32

Image identifier.

comp_type

int32

Compression method.

c_info

comp_info *

Pointer to compresion infomation structure.

8.7.5 External File Operations Using the GR API

An external image array is one that is stored in a file that is not the file containing the metadata for the image. The concept of externally stored data is described in Chapter 3, titled Scientific Data Sets (SD API). The GR interface supports the same functionality as the SD interface.

8.7.5.1 Creating a General Raster Image in an External File

Creating an image using external data involves the same general steps as with the SD interface:

1. Create the image array.
2. Specify that an external data file is to be used.
3. Write data to the image array.
4. Terminate access to the image.
To create a data set containing an external file, the calling program must make the following calls.

C:		ri_id = GRcreate(gr_id, name, ncomp, nt, il, dim_sizes);
		status = GRsetexternalfile(ri_id, filename, offset);
		status = GRwriteimage(ri_id, start, stride, edge, image_data);
		status = GRendaccess(ri_id);

FORTRAN:	ri_id = mgcreat(gr_id, name, ncomp, nt, il, dim_sizes)
		status = mgsxfil(ri_id, filename, offset)
		status = mgwrimg(ri_id, start, stride, edge, image_data)
		status = mgendac(ri_id)

GRsetexternalfile marks the image identified by ri_id as one whose data is to be written to an external file. The parameter filename is the name of the external data file, and offset is the number of bytes from the beginning of the external file to the location where the first byte of data will be written.

GRsetexternalfile can only be called once per data set. If a file with the same name as filename exists in the current directory, HDF will use it as the external file. If the file does not exist, HDF will create one. Once the external filename is specified, it is impossible to change it without breaking the association between the general raster data set and its image data.

Use caution when writing to existing files because the GRwriteimage library begins its write at the specified offset without checking whether data is being overwritten. When different data sets have arrays occupying the same external file, the calling program is responsible for avoiding any overlap between them.

For more information on the parameters used in GRsetexternalfile refer to the following table.

TABLE 8I GRsetexternalfile Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRsetexternalfile

(mgsxfil)

ri_id

int32

integer

Image identifier.

filename

char *

character* (*)

Name of the external data set.

offset

int32

integer

Offset in bytes from the beginning of the external file to the image data

8.7.5.2 Moving General Raster Images to an External File

Images can be moved from a primary file to an external file. To do so requires the following steps:

1. Select the image.
2. Specify the external data file.
3. Terminate access to the image.
The calling program must make the following calls:

C:		ri_id = GRselect(gr_id, gr_index);
		status = GRsetexternalfile(ri_id, filename, offset);
		status = GRendaccess(ri_id);

When GRsetexternalfile is used in conjunction with GRselect, it will immediately write the existing data to the external file and any data in the external file that occupies the space reserved for the external array will be overwritten as a result of this operation. A data set can only be moved to an external file once.

During the operation, the data is written to the external file as a contiguous stream regardless of how it is stored in the primary file. Because data is moved "as is", any unwritten locations in the data set are preserved in the external file. Subsequent read and write operations performed on the data set will access the external file.

8.7.5.3 Setting the I/O Mode for External General Raster Image Access

In situations where it is necessary to perform parallel I/O access to external image objects - for instance, if the external image data resides on a RAID array and is to be accessed by a multiprocessor system - the GRsetaccesstype routine can be used to set the access mode to either parallel or serial I/O. The syntax of the GRsetaccesstype routine is as follows:

C:		status = GRsetaccesstype(ri_id, access_mode);

FORTRAN:	status = mgsactp(ri_id, access_mode)

The access_mode argument can be set to either DFACC_SERIAL for serial mode or DFACC_PARALLEL for parallel mode. GRsetaccesstype returns a status code of 0 for successful completion or 1 if an error occurred.

TABLE 8J GRsetaccesstype Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRsetaccesstype

(mgsactp)

ri_id

int32

integer

Image identifier.

access_mode

char *

character* (*)

Access mode.



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

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