[Top] [Prev] [Next]

8.8 Obtaining Information about Files and Raster Images

The routines covered in this section provide methods for obtaining information about all of the images in a file, for identifying images that meet certain criteria, and for obtaining information about specific raster images.

GRfileinfo retrieves the number of images and file attributes in a file. GRgetiminfo provides information about individual images. To retrieve information about all images in a file, a calling program can use GRfileinfo to determine the number of images, followed by repeated calls to GRgetiminfo to obtain information about each image.

GRnametoindex or GRreftoindex can be used to obtain the index of a raster image in a file knowing its name or reference number, respectively. Refer to Section 8.2.1 on page 262 for a description of the raster image index and reference number. GRidtoref is used when the reference number of an image is required by another routine and the raster image identifier is available.

These routines are described individually in the following subsections.

8.8.1 Obtaining Information about the Contents of a File: GRfileinfo

GRfileinfo retrieves the number of raster images and the number of file attributes contained in a file. This information is often useful in index validation, sequential searches, or memory allocation. The syntax of GRfileinfo is as follows:

C:		status = GRfileinfo(gr_id, &n_images, &n_file_attrs);
FORTRAN:	status = mgfinfo(gr_id, n_images, n_file_attrs)
The number of images in the file and the total number of file attributes will be stored in the arguments n_images and n_file_attrs, respectively.

GRfileinfo returns SUCCEED (or 0) if successful or FAIL (or -1) otherwise. The parameters for GRfileinfo are further described in Table 8G on page 275.

8.8.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 routine GRgetiminfo retrieves this required information. To access information about an image, the calling program must contain the following:

C:		status = GRgetiminfo(ri_id, name, &n_comps, &data_type, &interlace_mode, dim_sizes, &n_attrs);
FORTRAN:	status = mggiinf(ri_id, name, n_comps, data_type, interlace_mode, dim_sizes, n_attrs)
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 arguments name, n_comps, data_type, interlace_mode, dim_sizes, and n_attrs 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.

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

TABLE 8G - GRfileinfo and GRgetiminfo Parameter Lists

Routine Name

[Return Type]

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

[intn]

(mgfinfo)
gr_id
int32
integer
GR interface identifier

n_images
int32 *
integer
Number of raster images in the file

n_file_attrs
int32 *
integer
Number of global attributes in the file

GRgetiminfo

[intn]

(mggiinf)
ri_id
int32
integer
Raster image identifier

name
char *
character*(*)
Name of the raster image

n_comps
int32 *
integer
Number of pixel components in the pixel

data_type
int32 *
integer
Pixel data type

interlace_mode
int32 *
integer
Interlace mode of the data in the raster image

dim_sizes
int32 [2]
integer (2)
Array containing the size of each dimension in the raster image

n_attrs
int32 *
integer
Number of raster image attributes

8.8.3 Obtaining the Reference Number of a Raster Image from Its Identifier: GRidtoref

GRidtoref returns either the reference number of the raster image identified by the parameter ri_id, or FAIL (or -1) upon unsuccessful completion. The syntax of GRidtoref is as follows:

C:		ref = GRidtoref(ri_id);
FORTRAN:	ref = mgid2rf(ri_id)
This routine is further defined in Table 8H on page 276.

8.8.4 Obtaining the Index of a Raster Image from Its Reference Number: GRreftoindex

GRreftoindex returns either the index of the raster image specified by its reference number, ref, or FAIL (or -1) upon unsuccessful completion. The syntax of GRreftoindex is as follows:

C:		ri_index = GRreftoindex(gr_id, ref);
FORTRAN:	ri_index = mgr2idx(gr_id, ref)
This routine is further defined in Table 8H.

8.8.5 Obtaining the Index of a Raster Image from Its Name: GRnametoindex

GRnametoindex returns the index of the raster image specified by its name or FAIL (or -1) upon unsuccessful completion. The syntax of GRnametoindex is as follows:

C:		ri_index = GRnametoindex(gr_id, name);
FORTRAN:	ri_index = mgr2idx(gr_id, name)
This routine is further defined in Table 8H.

TABLE 8H - GRidtoref, GRreftoindex, and GRnametoindex Parameter Lists

Routine Name

[Return Type]

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

[uint16]

(mgid2rf)
ri_id
int32
integer
Raster image identifier

GRreftoindex

[int32]

(mgr2idx)
gr_id
int32
integer
GR interface identifier

ref
uint16
integer
Reference number of the raster image

GRnametoindex

[int32]

(mgn2ndx)
gr_id
int32
integer
GR interface identifier

name
char *
character *(*)
Name of the raster image

EXAMPLE 4. Obtaining File and Image Information.

This example illustrates the use of the routines GRfileinfo/mgfinfo and GRgetiminfo/mggiinf to obtain information such as the number of images and attributes in an HDF file and the characteristics of a raster image in the file.

In this example, the program gets the number of images in the file using the routine GRfileinfo/mgfinfo. For each image, the program then obtains and displays its name, number of components, data type, interlace mode, dimension sizes, and number of attributes using the routine GRgetiminfo/mggiinf.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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