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
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); }
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.
#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); }
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.
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.
TABLE 8G GRreftoindex and GRnametoindex Parameter List
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); }
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.
|
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.
TABLE 8I GRsetexternalfile Parameter List
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.
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.
|