This page explains how to read data fields and geolocation fields from HDF-EOS2 swath data using HDF-EOS2 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-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 the 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 concept of the dimension map in swath, refer to HDF-EOS Library User's Guide.
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:
The following files contain the declarations of the library functions used in this example.
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 open the swath object
SWattach function to access
its data fields, attributes and geolocation fields.
SWopenfunction. The second argument is the name of swath object.
Low_Res_Swath has several data fields. Let's read data from the
23.8H_Approx._Res.3_TB_(not-resampled) data field.
One can find the datatype, rank and dimension sizes
using the HDF View Java browser or the hdp command-line tool.
Assuming that we know the datatype, rank and
dimension sizes of this data field, data can be read using the
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. Filling them with
NULLimplies reading the entire elements of the data field. The last argument
approxresis the buffer for the output; the value of the data field is saved in this buffer after the
GDreadfieldfunction is called.
Note that passing insufficient buffer to the
SWreadfield function results in buffer-overrun.
In this example, the data field is a 1997-by-243 array, and its datatype is the short(16-bit for most systems) integer.
The Low_Res_Swath swath has three geolocation fields: Time,
Longitude and Latitude. We will retrieve elements from Longitude
and Latitude. The same API,
SWreadfield, 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
SWattach function form a pair. The descriptor returned
SWattach function is the argument of the
Now that we get all necessary data from the file, we can close the file.
SWclose function closes the file. Its argument is the descriptor returned by
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
latitude, respectively. One can print their values as follows:
Also, one needs to know that data fields can have more dimensions than geolocation fields. For example, the data field Land/Ocean_Flag_for_6_10_18_23_36_50_89A is a 1997-by-243-by-7 array. Given that Longitude and Latitude are 1997-by-243 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 seven elements are measured at the same location.