How to Read HDF-EOS2 Grid data in C

This page explains how to read HDF-EOS2 grid data using HDF-EOS2 C API. This example is very simple. It shows how to access one data field in an HDF-EOS2 file. Please see the complete C source file here.

We will use one AMSR-E AE_RnGd external file from NSIDC. Download the file explained in this page here.

An HDF-EOS2 file consists of multiple grids, swaths and points. An HDF-EOS2 grid object consists of dimensions, data fields and attributes. Assuming that we know the name of the grid object and the name of the data field, we can access the data field through the following steps:

Open the HDF-EOS2 file
Attach to the grid object
Read data from the data field
Detach from the grid object
Close the HDF-EOS2 file

The following files contain the declarations of the library functions used in this example.

Figure 1 Required Header files to include

#include <mfhdf.h>

#include <hdf.h>

#include <HdfEosDef.h>

An HDF-EOS2 API function GDopen opens an existing HDF-EOS2 file. The first argument is the file name, and the second argument specifies the mode to access the file. In our example, we just want to read the data. So the mode is the read-only mode.

Figure 2 Opening an HDF-EOS2 grid file

int32 gridfileid;

gridfileid = GDopen("AMSR_E_L3_RainGrid_B05_200707.hdf", DFACC_RDONLY);

This HDF-EOS2 file has the grid object MonthlyRainTotal_GeoGrid, which should be opened using the GDattach function to access all data fields, dimensions and attributes of the grid object.

Figure 3 Attaching to a grid object

int32 gridid;

gridid = GDattach(gridfileid, "MonthlyRainTotal_GeoGrid");

The first argument is the descriptor returned by the GDopen function. The second argument is the name of the grid object.

MonthlyRainTotal_GeoGrid has two data fields: TbOceanRain and RrLandRain. Let's read data from TbOceanRain data field. One can find the datatype, rank and dimension sizes from the HDF View external Java browser or the hdp command-line tool. Assuming that we know the datatype, rank and dimension sizes of TbOceanRain, data can be read using the GDreadfield function(Figure 3).

Figure 4 Reading data from a data field

float32 tbocean[28][72];

GDreadfield(gridid, "TbOceanRain", NULL, NULL, NULL, tbocean);

The first argument is the descriptor returned by the GDattach function. The second argument specifies the name of the data field. The third, fourth and fifth arguments can specify a subset of the data field. Filling them with NULL implies reading the entire elements of the data field. The last argument tbocean is the buffer for the output; the value of the data field is saved in this buffer after the GDreadfield function is called.

Note that passing insufficient buffer to the GDreadfield function results in buffer-overrun. In this example, the data field is a 28-by-72 array, and the datatype is 32-bit floating point.

After retrieving data, the grid object can be detached using the GDdetach function. Note that this function and the GDattach function form a pair. The descriptor returned by the GDattach function is the argument of the GDdetach function.

Figure 5 Detaching from the grid object

GDdetach(gridid);

Now that we got all necessary data from the file, we can close the file. The GDclose function closes the file. Its argument is the descriptor returned by the GDopen function.

Figure 6 Closing the file

GDclose(gridfileid);

Previously, all elements of TbOceanRain data field were stored at a variable called tbocean. One can perform desired operations on this variable. Let's print a few elements to check if the retrieved data looks correct.

Figure 7 Using retrieved data

int32 i, j;

for (i = 0; i < 5; ++i) {
for (j = 0; j < 5; ++j) {
printf("%f ", tbocean[i][j]);
}
printf("\n");

}

To get the full source code, see here. To build this program, users can use Makefile like the following:

Figure 8 A skeleton of Makefile

HDF4_DIR=<hdf4_path>

HDFEOS2_DIR=<hdfeos2_path>

CC=$(HDF4_DIR)/bin/h4cc

CFLAGS=-I$(HDFEOS2_DIR)/include

LDFLAGS=-L$(HDFEOS2_DIR)/lib

LIBS=-lhdfeos -lGctp -lm

read_grid: read_grid.c
$(CC) $(CFLAGS) $(LDFLAGS) $< $(LIBS) -o $@

Users need to adjust this file to provide proper paths. For more information about this Makefile, check here.

For more C examples of accessing HDF-EOS2 grid data distributed by GES DISC, NSIDC, LP DAAC and LaRC, check here.

Last modified: 08/20/2021