How to read HDF-EOS5 Swath Data in C

This page explains how to read data fields and geolocation fields from HDF-EOS5 swath data using HDF-EOS5 C APIs. The example used below will simply read the entire elements in one data field and two geolocation fields, and dump several elements. To get the full source code, see here.

An HDF-EOS5 file consists of multiple grids, swaths and points. A swath object consists of dimensions, data fields, attributes, geolocation fields and dimension maps. Note that a swath object can have geolocation fields and dimension maps, which are not allowed in a grid object. Geo-location fields provide spatial and/or temporal information about data fields.

In most cases, a swath object has at least two geolocation fields: Longitude and Latitude. As their names indicate, both fields are about geolocations where physical data (represented by data fields) were measured.

Briefly speaking, dimension maps can be used to save space by keeping only small number of elements in geolocation fields. The trade-off is that associating geolocation fields with data fields is complicated. For more information about the dimension map, refer to HDF-EOS5 Data Model, File Format and Library external .

We will use one OMI Aura data. Download the file explained in this page here. This file does not use dimension maps.

Assuming that we know the swath object name, the data field name, and the geolocation field name, we can access the data field through the following steps:

Open the HDF-EOS5 file
Attach to the swath object
Read data from the data field and geolocation field
Detach from the swath object
Close the HDF-EOS5 file

For those who are familiar with the HDF-EOS5 grid interface, the above steps are straightforward. All grid interfaces start with HE5_GD, and all swath interfaces start with HE5_SW.

The following file contains the declarations of the API functions used in this example.

Figure 1 Required Header File to Include

#include <HE5_HdfEosDef.h>

The HDF-EOS5 API HE5_SWopen function opens an existing HDF-EOS5 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-EOS5 swath file

hid_t swathfileid;

swathfileid = HE5_SWopen("OMI-Aura_L2-OMAERO_2004m1001t0003-o01132_v003-2009m0108t180405.he5", H5F_ACC_RDONLY);

This HDF-EOS5 file has one swath object ColumnAmountAerosol. We open this swath object using the HE5_SWattach function to access all its data fields,attributes and geolocation fields.

Figure 3 Attaching to a swath object

hid_t swathid;

swathid = HE5_SWattach(swathfileid, "ColumnAmountAerosol");

The first argument is the descriptor returned by the HE5_SWopen function. The second argument is the name of swath object.

ColumnAmountAerosol has several data fields. Let's read data from AerosolIndexUV data field. One can find the datatype, rank and dimension sizes using the HDF View external Java browser or the h5dump command-line tool. Assuming that we know the datatype, rank and dimension sizes of this data field, data can be read using the HE5_SWreadfield function.

Figure 4 Reading data from a data field

short indexuv[1644][60];

SWreadfield(swathid, "AerosolIndexUV", NULL, NULL, NULL, indexuv);

The first argument is the descriptor returned by the HE5_SWattach 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 indexuv is the buffer for the output; the value of the data field is saved in this buffer after the HE5_SWreadfield function is called.

Note that passing insufficient buffer to the HE5_SWreadfield function results in buffer-overrun. In this example, the data field is a 1644-by-60 array, and its datatype is the short (16-bit in most systems) integer.

ColumnAmountAerosol swath has several geolocation fields including Time, Longitude and Latitude. We will retrieve elements from Longitude and Latitude. The same API, HE5_SWreadfield, can be used to read data in a geolocation field.

Figure 5 Reading data from geolocation fields

float longitude[1644][60];

HE5_SWreadfield(swathid, "Longitude", NULL, NULL, NULL, longitude);

float latitude[1644][60];

HE5_SWreadfield(swathid, "Latitude", NULL, NULL, NULL, latitude);

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

Figure 6 Detaching from the swath object

HE5_SWdetach(swathid);

Now that we get all necessary data from the file, we can close the file. The HE5_SWclose function closes the opened file. Its argument is the descriptor returned by the HE5_SWopen function.

Figure 7 Closing the file

HE5_SWclose(swathfileid);

We have read one data field AerosolIndexUV, and two geolocation fields, Longitude and Latitude, and stored them at indexuv, longitude and latitude, respectively. One can print their values as follows:

Figure 8 Using retrieved data

hsize_t i, j;

for (i = 0; i < 1644; ++i) {
for (j = 0; j < 60; ++j) {
printf("%d was measured at %f, %f\n", (int)indexuv[i][j], longitude[i][j], latitude[i][j]);
}

}

This code assumes that those three fields have the same rank and number of elements. Note that this is not the case if dimension maps are used. If dimension maps are used, users need to do interpolation or sampling to get the values of latitude and longitude where the value of an element of a data field was measured.

Also, one needs to note that data fields can have more dimensions than geolocation fields. For example, the data field AerosolOpticalThicknessMW is a 1644-by-60-by-14 array. Given that Longitude and Latitude are 1644-by-60 arrays, we can conclude that the first two dimensions of the data field are related to both Longitude and Latitude, and the third dimension is related to something else. This implies that 14 elements are measured at the same location.

To get the full source code, see here. For more C examples of accessing HDF-EOS5 swath data and how to build this code, check here.

Last modified: 11/11/2020