Reading a Raster Image from an HDF File
The following sections detail how a user may utilize the HDF library and the GR API within a computer program to read a raster image from an HDF file. In this section, the tutorial will concentrate on using the FORTRAN programming language and the GR API. However, examples of the appropriate C code will also be given for certain steps. For the purpose of this tutorial, we are choosing the example of reading an entire raster image that is the first and only data set in the HDF file. Similar to writing an HDF file, the user should follow these simple steps:
Does the current version of HDF support your computer platform and operating system?
As outlined in Section 4, the HDF library can not be run on just any available computer platform or operating system. Before downloading the HDF library software, the user should make sure that the current release of HDF supports his/her computer and operating system. Otherwise, the user will be unable to work with the HDF library and files. There is also a possibility that previous releases of HDF may support the Users computer platform while the latest version does not. In this event, the user may wish to obtain the earlier software.
Downloading and Installing the HDF library
The HDF library and software is public domain software and available free to all users. The library and code can be downloaded from the NCSA anonymous ftp server (ftp://ftp.ncsa.uiuc.edu/). Directions on how to install the HDF library can also be found at this location.
Are all libraries and programs properly linked and compiled?
In order to eventually run the HDF software, the library and the needed application routines and programs must first be properly compiled and linked. As of the current release of HDF (4.1r1), four separate libraries must be compiled and linked. These are the libmfhdf.a, libdf.a, libjpeg.a, and libz.a libraries. Provided below are examples of the command(s) that can be used for this action. It must be noted that the order in which the libraries are linked is important and should not vary from the order shown below:
For C programs:
cc -o <your program> <your program>.c \
-I<pathf for hdf include directory>\
-L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
For FORTRAN programs:
f77 -o <your program> <your program>.f \
-I<path for hdf include directory>\
-L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
For the various commands needed to link and compile the HDF library on each individual platform, please see Section 4:Compiling the HDF Library.
Writing a short program to read an HDF data set
As mentioned previously, the HDF library and programs can only be run by using either the C or FORTRAN programming language. This choice is up to the user depending on availability and the language he or she feels most familiar and comfortable with.
Make sure all include files are in place
Earlier, it was noted that a series of standard HDF definitions and declarations of file access codes (i.e. read, write, etc.) and data types (i.e. integer, character) must be included within the programs that the user writes to utilize the various application routines. In the C programs, this is accomplished simply by adding the line #include "hdf.h" at the beginning of the program. This line effectively includes all the needed constants and definitions from the HDF software. When writing FORTRAN programs, this may also be done by simply adding an include statement that brings in only the needed definitions and declarations (constants.f) from the hdf.h header file. This is done by the following code: "include constants.f". However, all FORTRAN compilers (particularly the older ones) do not support the use of include statements. In this event, the user must type in/declare all the constants and definitions found in the constants.f file. It is advised that all declarations, whether through Include statements or not, should be done at the beginning of the program.
Make all variables and parameter declarations
As with any program, the scientist/user should declare and initialize all variables and parameters at the beginning of the program. This includes all variables and arguments that will be used by the HDF commands to follow. The variable and parameter declarations needed for each call will be provided in the example boxes of the individual steps. These statements always belong at the top of the program.
Initialize access to the SD interface and open HDF file
The first real HDF programming step actually accomplishes two things:
This is done by the following code:
file_id = hopen(filename,access_mode,0) (FORTRAN)
gr_id = mgstart(file_id)
or
file_id = Hopen(filename, access_mode,0) ( C )
gr_id = GRstart(file_id)
where
file_id = HDF file id returned by the Hopen/hopen command
gr_id = the GR interface identifier
filename = the name of the existing HDF file (character string)
access_mode = Type of access required for this file
All available options for the access-mode argument are defined in the hdf.h header file mentioned previously and need only to be identified for all C and most FORTRAN operations. All options begin with the prefix "DFACC_" and include:
DFACC_CREATE (File Creation Access)
DFACC_RDONLY (Read Access)
DFACC_RDWR (Read and Write Access)
As mentioned previously, these definitions are stated in the hdf.h header file.
In the event that the user's FORTRAN compiler can not handle include statements with the header file (hdf.h), the DFACC_ variable must be defined, along with its assigned value, at the beginning of the program. This is done by a code line such as:
parameter (DFACC_RDONLY = 1) (For FORTRAN only)
Example:
FORTRAN:
integer*4 gr_id, file_id
integer mgstart
parameter(DFACC_RDONLY = 1)
file_id=hopen(image.hdf,DFACC_READ,0)
gr_id=mgstart(file_id)
C:
#includehdf.h"
int32 gr_id, file_id, GRstart;
file_id=Hopen(image.hdf,DFACC_READ,0);
gr_id=GRstart(file_id);
Select raster image to be read from the HDF file
After initializing the GR interface, the next step is to select the HDF raster image which will be read. This is done by the following code:
ri_id = mgselct (gr_id, ri_index) (FORTRAN)
or
ri_id = GRselect (gr_id, ri_index) ( C )
where
ri_id = HDF raster image id returned by the mgselct/GRselect command
gr_id = the GR interface identifier
ri_index = index number of data set within file
(i.e. 0 = first data set, 1 = second data set, etc.)
After initializing the API and selecting the HDF file and HDF raster image to be read to, the next step is to actually read the existing HDF data by using the GRreadimage (mgrdimg) command. This command is used to read either all or part of the existing image into the ri_id array with the same number of dimensions.
ret=mgrdimg (ri_id, start, stride, edge, data) (FORTRAN)
or
ret=GRreadimage (ri_id, start, stride, edge, data); ( C )
It should be noted that there are two versions of the read routine in FORTRAN. The mgrdimg routine reads numeric scientific data while mgrcimg reads character scientific data.
where
ri_id = raster image id returned by using GRselect or mgselct
start = An array which identifies where in the raster image that the reading will begin
stride = An array specifying the interval between written values in each dimension
edge = An array defining the number of data values in each dimension
A description and examples of how to use start, stride, and edge are provided in Section 8 - Writing a Raster Image to an HDF File
Example:
For reading the entire image from an HDF file which contains only one 2-D raster image
FORTRAN:
integer start(2), edge(2), stride(2)
integer retn mgrdimg
c Define the location, pattern + size of data to be read
YL = 10
XL = 10
start(1) = 0
start(2) = 0
stride(1) = 1
stride(2) = 1
edge(1) = XL
edge(2) = YL
retn = mgrdimg(ri_id, start,stride,edge,image)
C:
/* Define the location, pattern + size of data to be read */
YL = 10;
XL = 10;
dims[0] = YL;
dims[1] = XL;
start[0] = 0;
start[1] = 0;
stride[0] = 1;
stride[1] = 1;
edge[0] = dims[0];
edge[1] = dims[1];
retn = GRreadimage(ri_id, start,stride,edge,image);
Optional operation: Get and Read Metadata
After opening the HDF file, one possible step is to see if the file or images do indeed contain attributes. This is done by using the following code:
attr_index = GRfindattr (obj_id, attr_name); ( C )
attr_index = mgfattr (obj_id, attr_name) (FORTRAN)
where
attr_index = valid attribute index returned if attribute exists
obj_id = Interface or image identifier (gr_id or ri_id)
attr_name = name of attribute (i.e.,Contents of file")
If there is a attribute index, the name, data type (num_type), and count (number of characters) of the attribute can be obtained:
retn= GRattrinfo(obj_id, attr_index, attr_name, data, n_values); (C)
retn= mgatinf (obj_id, attr_index, attr_name, data, n_values) (FORTRAN)
where
data_type = data type of attribute
n_values = number of attribute values
After completing these operations, the attributes can be read using the following:
retn= GRgetattr (obj_id, attr_index, buffer); ( C )
retn= mggnatt (obj_id, attr_index, buffer) (FORTRAN)
where
buffer is allocated to hold the attribute data
The above steps can also be followed for each data set within the file by getting the image id (ri_id) of the data, finding a particular attribute (i.e.,"Units") and getting and reading the data.
Terminate/Close access to all files, data sets, and APIs
As in the writing of the image data, the raster imager, the GR interface, and the HDF file, in that order, must be closed/terminated in order to prevent any possible loss of data. This is done by the following:
retn = mgendac(ri_id) (FORTRAN)
retn = mgend(gr_id)
retn = hclose(file_id)
or
retn = GRendaccess(ri_id); ( C )
retn = GRend(gr_id)
retn = Hclose(file_id)
Execute like a standard FORTRAN or C program.