This page explains how to read data fields and geolocation fields from HDF-EOS5 swath data using HDF-EOS5 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-EOS5 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-EOS5 file consists of multiple grids, swaths and points. An 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. Geolocation fields provide spatial and/or temporal information of 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 locations where elements of 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.
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:
An 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.
OMI-Aura_L2-OMAERO_2004m1001t0003-o01132_v003.he5, not its original name. We renamed the file to avoid an extremely long string in the example code.
This HDF-EOS5 file has one swath object ColumnAmountAerosol.
This swath object should be opened using the
he5_swattach function to access
all data fields, dimensions, attributes and geolocation fields.
he5_swopenfunction. The second argument is the name of the 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 Java browser or
the h5dump command-line tool.
Assuming that we know the datatype, the rank and
dimension sizes of this data field, data can be read using the
he5_swattachfunction. The second argument specifies the name of the data field. The third, fourth and fifth arguments can specify a subset of the data field. Here, we specify the entire elements by setting starting point as (0, 0), stride as (1, 1), and edge (60, 1644). The last argument
indexuvis the buffer for the output; the value of the data field is saved in this buffer after the
he5_swrdfldfunction is called. This code assumes that the datatype of this field is the signed 16-bit integer.
If you use a 64-bit machine, you need to change the type of integer*4 to integer*8 for start, stride and edge variables.
Note that passing insufficient buffer to the
he5_swrdfld function results in buffer-overrun.
In this example, the data field is a 60-by-1644 array, and its datatype is the 16-bit integer.
On the other hand, ColumnAmountAerosol swath has several geolocation fields including Time,
Longitude and Latitude. We will retrieve elements from Longitude
and Latitude. The same API,
he5_swrdfld, can be used
to read data in a geolocation field.
After retrieving data, the swath object can be detached using the
Note that this function and the
he5_swattach function form a pair. The descriptor returned
he5_swattach function is the argument of the
Now that we get all necessary data from the file, we can close the file.
he5_swclose function closes the file. Its argument is the descriptor returned by
We have read one data field AerosolIndexUV, and two geolocation fields,
Longitude and Latitude, and stored them at
latitude, respectively. One can print their values as follows:
Also, one need to note that data fields can have more dimensions than geolocation fields. For example, a data field AerosolOpticalThicknessMW is a 14-by-60-by-1644 array. Given that Longitude and Latitude are 60-by-1644 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 14 elements of the data field are measured at the same location.