How to Read HDF-EOS2 Swath Data in Fortran

This page explains how to read data fields and geolocation fields from HDF-EOS2 swath data using HDF-EOS2 Fortran APIs. The example will simply read the entire elements in one data field and two geolocation fields, and dump several elements.

First of all, we assume that you have installed the HDF-EOS2 Fortran library correctly. Please make sure that you included -Df2cFortran in the compiler option when you built it. You may want to review our How to build HDF-EOS page.

An HDF-EOS2 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 describe geolocation information where elements in 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 refer to HDF-EOS Library User's Guide.

We will use one AMSR-E AE_L2A file distributed by NSIDC. 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-EOS2 file
• Attach to the swath object
• Read data from the data field and the geolocation field
• Detach from the swath object
• Close the HDF-EOS2 file

For those who are familiar with the HDF-EOS2 grid interface, the above step is straightforward. All grid interfaces start with gd, and all swath interfaces start with sw.

The HDF-EOS2 API swopen function 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.

This HDF-EOS2 file has three swath objects. We will access one swath object Low_Res_Swath, which should be opened using the swattach function to access all data fields, dimensions, attributes and geolocation fields.

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

Low_Res_Swath has several data fields. Let's read data from 23.8H_Approx._Res.3_TB_(not-resampled) data field. One can find the datatype, the rank and dimension sizes using the HDF View Java browser or the hdp command-line tool. Assuming that we know the datatype, the rank and dimension sizes of this data field, data can be read using the swrdfld function.

The first argument is the descriptor returned by the 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. We specify the entire elements by setting starting point as (0, 0), stride as (1, 1), and edge (243, 1997). The last argument approxres is the buffer for the output; the value of the data field is saved in this buffer after the swrdfld function is called.

Note that passing insufficient buffer to the swrdfld function results in buffer-overrun. In this example, the data field is a 243-by-1997 array, and its datatype is the 16-bit integer.

On the other hand, Low_Res_Swath swath has three geolocation fields: Time, Longitude and Latitude. We will retrieve elements from Longitude and Latitude. The same API, swrdfld, can be used to read data in a geolocation field.

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

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

We have read one data field 23.8H_Approx._Res.3_TB_(not-resampled), and two geolocation fields, Longitude and Latitude, and stored them at approxres, longitude and latitude, respectively. One can print their values as follows:

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 latitude and longitude value where an element of data fields was measured.

Also, one need to note that data fields can have more dimensions than geolocation fields. For example, a data field Land/Ocean_Flag_for_6_10_18_23_36_50_89A is a 7-by-243-by-1997 array. Given that Longitude and Latitude are 243-by-1997 arrays, we can conclude that the last two dimensions of the data field are related to both Longitude and Latitude, and the first dimension is related to something else. This implies that seven elements are measured at the same location.

As the above code omits some parts, see here to get the full source code. For information on how to build the code, click here. For more Fortran examples of accessing HDF-EOS2 swath files, click here.

Last modified: 11/11/2020