GDAL

1. Overview

Geospatial Data Abstraction Library (GDAL) is a translator library for raster geospatial data formats. As the name implies, GDAL has an abstraction layer that hides format-specific details, which means there is only one GDAL API regardless of file format. For example, one of the following - an HDF4 Vdata, an HDF4 SDS, an HDF4 Vgroup, an HDF5 dataset or an HDF5 group - is mapped to a GDALDataset object.

2. Installation

A compile error occurred while building GDAL 1.5.2, but this is a known problem. A patch^[1] is available. However, GDAL 1.6.1 does not have this problem.

GDAL 1.5.2 assumes HDF5 1.6 API; so, H5_USE_16_API should be defined if HDF5 1.8 or later is used.

3. How to Use

A GDALDataset object represents one HDF4 or HDF5 object. Although the term may cause confusion for HDF4 and HDF5 users, it represents HDF4 Vgroups and HDF5 groups as well as HDF4 Vdata, HDF4 SDS and HDF5 datasets.

Since GDAL is written in C++, information provided here will be explained in C++. This section explains how to call some important functions. In the example, we will use an HDF5 file converted from an HDF-EOS2 file from AE_RnGd data product of NSIDC. You can download the HDF5 file from here.

Although examples below show how to use GDAL to handle an HDF5 file, handling HDF4 files is very similar due to GDAL's abstraction layer.

3.1. Open a File or an Object

The GDALOpen() function opens a file as the following example shows.

The first argument specifies an HDF4 or HDF5 file, but it can also represent a specific dataset. For instance, if the following string is passed as the first argument, GDAL opens the HDF5 dataset RrLandRain in the HDF5 group MonthlyRainTotal_GeoGrid/Data_Fields in the HDF5 file AMSR_E_L3_RainGrid_B05_200707.h5. HDF5:\ specifies that this is an HDF5 file.

The above string can be fetched by calling the GetMetadata() method as Section 3.3 explains.

3.2. Retrieve Attributes

GDALDataset can have metadata as an HDF5 object can have attributes. The GetMetadata() method returns a list of metadata. Unlike HDF4 and HDF5, GDAL categorizes metadata, and GetMetadata() takes one argument that specifies the domain. Since all attributes in the file are stored in the default domain, an empty string can be passed as the argument.

Each string is formatted as Name=Value and null-terminated. If an attribute is not of string type, values are converted into a string.

3.3. Open Child Objects

In GDAL, the list of child objects is merely one category of metadata. GetMetadata(), introduced in Section 3.2, can be used to retrieve the list of child objects. The only difference is that the first argument should be SUBDATASETS. This is a predefined domain for child objects.

The HDF-EOS2 file we used has two datasets in the MonthlyRainTotal_GeoGrid/Data_Fields group. For this file, the above code returned the following. As explained in Section 3.1, GDALOpen() can open a specific object if the first argument indicates one dataset. A value whose name is SUBDATASET_*_NAME can be the first argument.

3.4. Read Data

A GDALDataset object corresponding to an HDF4 SDS or an HDF5 dataset contains one GDALRasterBand object. The GetRasterBand() method returns one GDALRasterBand object.

After getting a GDALRasterBand object, one can read or write values by using the RasterIO() method. The following is a routine that reads all values in the dataset given by the poDataset variable. After executing the following code, the buffer will obtain the data stored in the HDF file.

You can download a C++ program that reads the AE_RnGD HDF-EOS2 file from here. This program is composed of the above fragments.

Additionally, we wrote a dumper program. This program recursively dumps all datasets in a file. Although this program is not very practical, this sample shows how users can call GDAL APIs. You can download this file from here.

4. References

• [1] Ticket #2296. GDAL. http://trac.osgeo.org/gdal/attachment/ticket/2296/gdal-hdf4-UNKNOWN.diff

Last modified: 04/06/2010