HDF-EOS2 Dumper

The HDF-EOS2 Dumper is a command-line program that dumps information of HDF-EOS2 file. It is mainly used for dumping latitude and longitude values of different grids and swaths. It can also dump the number of grids and swaths as well as their respective name. The main advantage of this program is that it can generate actual lat and lon values when different projections, like SNSOID and SOM, and swath dimension maps are used. (Download)

The HDF-EOS2 library uses the U.S. Geological Survey General Cartographic Transformation Package (GCTP) to define and subset grid structures. Thus, HDF-EOS2 data files that are created by the HDF-EOS2 library have one of the following GCTP projections:

• GEO: Geographic
• PS: Polar Stereographic
• LAMAZ: Lambert Azimuthal Equal Area
• SNSOID: Sinusoidal
• SOM:Space Oblique Mercator
• CEA:Cylindrical Equal-Area (for EASE grid with corners in meters)

The above list contains the most common projections used in HDF-EOS2 data. Please see 6.5.1 GCTP Projection Codes in [1] for the complete list of projections.

1. Installation

This program requires five libraries:

• HDF4
• HDF-EOS2
• zlib
• szlib
• jpeg

Makefile template is provided to generate binary named eos2dump. Users need to set paths to those libraries above in the Makefile template at the corresponding places.

With Makefile, one can build this program by issuing make command. The generated binary is named eos2dump. This software has an old version which was built by configure script. Since configure script might have installation problem in some users' machine, we provide the Makefile template for the new version.

2. How to use

This program takes several command-line arguments: options, filename and grid or swath name. It reads the input file and dumps all the latitude and/or longitude values for the specified grid/swath name. If there is only one grid or swath available, you don't need to specify its name. The program will use that name by default and dumps the corresponding lat and lon values. It will generate error message and terminate the program if no grid or swath name specified if more than one available.

When the desired grid contains SOM projection, you need to specify the block dimension number you want to dump as an additional argument after the grid name argument. The dimension number should be between 1 and 180. If you want to dump lat/lon for all block dimensions, specify all option after the grid name. When only one grid exists, you don't need to specify the grid name, but you are also required to give the block dimension number you want to dump.

In the shell, the command of using HDF-EOS2 Dumper is as following:

The names and functionalities of all the supported options are listed below.

• -V: prints the version number of the software and exits
• -c: calculate lon/lat values and print them
• -a: calculate adjusted lon/lat values and print them if swath dimension maps are used
• -1: (valid only when -c or -a is used) print lat data
• -2: (valid only when -c or -a is used) print lon data
• -v: (valid only when -c or -a is used) add explanatory information to the lat/lon data
• -m: (valid only when -c or -a is used) print five lat/lon data per line, default number is one
• -g: print all the grid and swath names
• -h: print help information
• -o: print number of grid, swath, and point objects, and file size

There are three other options -d, -r, -n. They are not fully tested for all the example files. So their functions are not listed here. Users can find the detailed information for those three options in the Readme.txt file.

3. Examples

To show the illustration, we use several examples to show how to use this program to dump lat and lon values for HDF-EOS2 files.

3.1. Example 1

The first example is to dump latitude values of a swath object called L2_Standard_cloud-cleared_radiance_product in an HDF-EOS2 file AIRS.2002.12.31.001.L2.CC_H.v4.0.21.0.G06100185050.hdf. This file doesn't contain swath dimension map. The latitude is 45-by-30 array, and its type is 64-bit floating-point.

In the shell, one can issue the following command:

The -c option tells the dumper to calculate latitude and longitude values. The -1 option determines if lat and/or lon should be printed on the screen. Here we only want dump lat data. The option -m specifies how many data are allowed to be shown per line. The second argument specifies the name of the HDF-EOS2 file. The third argument is omitted, since there is only one swath L2_Standard_cloud-cleared_radiance_product in this file. The program will use it as the default swath name and dump the corresponding lat data.

The output of this program is shown below:

There are five latitude data printed on each line. Since this data file contains data field Latitude, the dumper just reads the lat data from that field and prints them on the screen.

3.2. Example 2

The second example is to dump latitude values of a grid object called BlueBand in an HDF-EOS2 file MISR_AM1_GRP_ELLIPSOID_GM_P117_O058421_BA_F03_0024.hdf. This file contains SOM projection. Therefore, we need to specify the block dimension we want to dump. Here we choose the 20th dimension to dump. The latitude is 128-by-512 array.

In the shell, one can issue the following command:

The -v option tells the dumper to add explanatory information to the latitude data, like grid name and file name. The third argument specifies the name of grid whose latitude you want to print on the screen. It will generate error message and stop the program if you don't specify this argument since it contains more than one grid. The fourth argument specifies which block dimension you want to dump. Here we choose the 20th dimension. If you don't specify it, the program will also generate an error message and stop.

The output of this program is shown below:

If you want to dump latitude for all block dimensions, specify all option after the desired grid name. The command is:

The output of this program is shown below:

You can also check the projection information by using -o option. Type the following command:

The output of this command is shown below:

3.3. Example 3

The third example is to dump latitude values of a swath object containing dimension maps called MODIS_SWATH_Type_L1B in an HDF-EOS2 file MYD02HKM.A2010031.0035.005.2010031183706.hdf. This file contains two swath dimension maps. The latitude is a 4060-by-2708 array.

In the shell, if you want to print the unadjusted latitude, issue the following command:

The output of this program is shown below:

This data file contains data field Latitude and its type is 32-bit floating-point. The dumper just reads the lat data from that field and prints them on the screen.

If you want to print the adjusted latitude after using swath dimension map, type the following command:

The output of this program is shown below:

This is the actual latitude data which has the same dimension size as the field data. It's calculated by HDF-EOS2 Dumper internally.

3.4. Example 4

Dump the longitudinal geolocation coordinates of HDF file AMSR_E_L3_5DaySnow_V09_20050126.hdf for the Northern Hemisphere LAMAZ grid. The file contains grids in Lambert Azimuthal projection (GCTP_LAMAZ) for both the Northern and Southern hemispheres.

Note: EOS Dumper -m option produces short lines at the ends of grid rows which are not modulo-5 values in length. This is acceptable for IDL, but MATLAB cannot tolerate the irregular length lines. When using geolocation coordinate files in MATLAB, use only -a1, -a2, -c1, -c2 options. Do not use the -m option to produce geolocation coordinate files for use in MATLAB.

The output of this program is shown below:

4. Limitation

1. The program can't handle HDF-EOS2 file which contains 'DEFAULT' values for UpperLeft and LowerRight points. The example file is CER_ES4_TRMM-PFM_Edition1_009001.199808.hdf.

2. For LAMAZ projection, the previous version of the EOS2 Dumper produced erroneous output lat and lon values ("1e+51") near the corners of the grid. This was due to a bug in the GCTP library. The current version checks for undefined values and returns the nearest-neighbor value within the valid range.

3. The program can't handle HDF-EOS2 file MISR_AM1_CGAS_MAR_01_2006_SITE_INTEXB_F06_0021.hdf. It has problem when calling "GDij2ll" function. The problem might come from the HDF-EOS2 library.

4. If the HDF-EOS2 file contains swath dimension map, using option -c will read unadjusted lat and lon that the date file provides. If you want to read adjusted lat and lon, option -a should be used instead. When the unadjusted lat and lon data contains fill value, the adjusted lat and lon will also contain fill value.

5. Now the number of output data per line could be chosen as one or five for use in other softwares, like MATLAB and IDL, further options should be added to let users specify their own number of output data per line.

6. When the swath dimension maps are used, the adjusted lat and lon values may fall out of valid range due to their closeness to the boundary lat/lon data provided in the date file. Here we make those invalid values equal to the boundary points. Special cautions are needed when handling swath dimension map file.

5. Download

Download the HDF-EOS2 Dumper.

Reference

• [1] HDF-EOS Library User's Guide for EOSDIS Evolution and Development (EED) Contract, Volume 1: Overview and Examples http://newsroom.gsfc.nasa.gov/sdptoolkit/docs/HDF-EOS_UG.pdf

Last modified: 10/07/2011