|
|
|
The HDF-EOS2 Dumper is a command-line program that dumps information in an 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 names and data. The main advantage of this program is that it can generate the actual lat and lon values in ASCII when different projections, like Sinusoidal (SNSOID) and Space Oblique Mercator (SOM), and swath dimension maps are used. The plain text lat/lon values can be easily loaded into other software such as MATLAB and IDL that cannot resolve projection information from HDF-EOS2 file.
The HDF-EOS2 library uses the U.S. Geological Survey General Cartographic Transformation Package (GCTP) to define grid structures. Thus, HDF-EOS2 data files have one of the following GCTP projections:
| Code | Projection Description |
|---|---|
| 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 table contains the most common projections used in NASA HDF-EOS2 files. Please see 6.5.1 GCTP Projection Codes in [1] for the complete list of projections.
We provide the binaries on the following platforms.
| Platform | Binary | Checksum |
|---|---|---|
| Windows (7 or newer) | eos2dump.exe | SHA256 |
| Mac OS X (Mountain Lion or newer) | eos2dump | SHA256 |
| Linux 2.6 (i386) | eos2dump | SHA256 |
| Linux 2.6 (x86_64) | eos2dump | SHA256 |
If you want to build eos2dump from the source, please download the eos2dump-1.4.0.tar.gz (SHA256) source package.
To build eos2dump from the source, eos2dump requires the HDF-EOS2 library. The HDF-EOS2 library requires HDF4 library and the HDF4 library requires zlib and jpeg.
To build eos2dump on Unix systems, one needs to modify the Makefile template in the source distribution. The following library paths should be edited first:
With the edited Makefile, one can build eos2dump binary by issuing make command.
Please note that builiding with CMake on Windows may not work for the latest Visual Studio 2017. We recommend using MSYS2 for building HDF-EOS2 dumper.
To build eos2dump using CMake (on Windows), one needs to create include/
and lib/ sub-directories at the unpacked source directory and put all (zlib, szip, jpeg, hdf4, hdf-eos2)
dependency headers and libraries there. Then, run cmake . and cmake --build .
at the command line. The eos2dump(.exe) will be created under bin/(Debug/) directory.
On Windows, you will need depedent DLL files (e.g., hdf.dll, mfhdf.dll, jpeg.dll, etc.) under bin/Debug/ directory to test the newly-compiled bin/Debug/eos2dump.exe binary.
This program takes several command-line arguments: options, file name, grid or swath name, and SOM block number if SOM projection is used. It reads the input file and dumps all the latitude and/or longitude values for the specified grid/swath name in ASCII. If there is only one grid or swath available, you don't need to specify its name. If the file has multiple grids or swaths, a specific grid/swath name is expected as an argument. 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 is available.
When the desired grid contains SOM projection, you need to specify the
SOM block 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 SOM block number you want to
dump.
The HDF-EOS2 Dumper tool provides the following command line options:
The names and functions of all the supported options are listed below.
We provide several examples to show how to use this program to dump lat and lon values for various NASA HDF-EOS2 files.
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 45x30 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 values.
The -1 option determines latitude should be printed on the screen.
The option -m specifies 5 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.
The second example is to dump latitude values of a SOM grid object called BlueBand from an HDF-EOS2 file MISR_AM1_GRP_ELLIPSOID_GM_P117_O058421_BA_F03_0024.hdf. Since this file contains SOM projection, latitude and longitude datasets have 180 fixed blocks. For example, the latitude is represented as an 180 x 128 x 512 array in this file. Therefore, we need to specify a block number we want to dump unless you want to dump data from all 180 blocks.
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 you want to dump.
Here we choose the 20th block.
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 blocks, specify
all option after the desired grid name. The command is:
The output of the above command is shown below:
You can also check the projection information by using
-o option. Type the following command:
The output of the above command is shown below:
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 uses two dimension maps. The lat/lon fields are defined as 2030x1354 array while data fields are defined as either 5x4060x2708 or 2x4060x2708.
Please note that data field size 4050x2708 is twice the size of geo field 2030x1354 and that's why eos2dumper provides the -a option.
In the shell, if you want to print the unadjusted (i.e., 2030x1354) latitude, issue the following command:
The output of the above command 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 (i.e., 4060x2708) latitude using swath dimension map, type the following command:
The output of the above command is shown below:
In Figure 14., please note that the adjusted value -61.0949 is inserted between the first two data values (-61.0802, 61.1096) from Figure 12. It's calculated by the HDF-EOS2 Dumper internally. This will make latitude data have the exact same dimension size as the field data.
The fourth example is to dump the longitude values of the Northern Hemisphere LAMAZ grid from the AMSR_E_L3_5DaySnow_V09_20050126.hdf HDF-EOS2 file. The file contains two grids in Lambert Azimuthal (GCTP_LAMAZ) projection for both Northern and Southern hemispheres.
Please note that we did not use -m option
and each line contains only one data.
The -m option produces short lines at the
ends of grid rows that are not modulo-5 values in length.
For example, the last line may contain only 3 values at the end
with -m option instead of 5.
This is acceptable for IDL, but MATLAB cannot handle the
irregular length lines when the output is redirected to a text file
and the text file is later parsed by MATLAB.
Therefore, when you generate lat/lon dump output
files in MATLAB, use only -a1, -a2,
-c1, -c2 options. Do not use the
-m option to produce geo-location coordinate files
for use in MATLAB.
Please see our MATLAB AMSR_E comprehensive examples to check how lat/lon files generated from eos2dump are used.
The output of the above command is shown below:
The last example is to dump the multiple dimension map information of the VNIR swath from the AST_L1B_00301032001190431_20110121213613_30524.hdf HDF-EOS2 file. The file contains multiple swaths with multiple dimension map pairs. For example, VNIR swath has two dimension map pairs. The first pair of lat/lon can be retrieved using -a1 and -a2 as explained above. The second pair of lat/lon should be retrieved using -a3 and -a4. The HDF-EOS2 dumper can support up to 4 pairs. That is, you can use -a5/-a6 for the third pair and -a7/-a8 for the fourth pair. The dumper doesn't support beyond the fourth pair because we haven't seen such case. You can examine if there are more dimension map pairs using -0 and -9 options.
The output of the above command is shown below:
You can compare the above output against the first longitude information of VNIR Swath that can be generated with -a2i option. The difference is highlighted in Figure 20.
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 1.0.0 version produced erroneous lat and lon values ("1e+51") near the corners of the grid. This was due to a bug in the GCTP library. The newer (> 1.1.0) 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. The number of output data per line could be chosen either 1 or 5 only for the use in other software, like MATLAB and IDL. There's no option to let users specify the number of data per line.
6. When the swath dimension maps are used, the adjusted lat and lon values may fall out of the valid range due to their closeness to the boundary lat/lon data provided in the data file. Here, we make those invalid values equal to the boundary points. Special cautions are needed when handling swath dimension map file.
[1] HDF-EOS Library User's Guide for EOSDIS Evolution and Development (EED) Contract, Volume 1: Overview and Examples https://git.earthdata.nasa.gov/rest/git-lfs/storage/DAS/hdfeos/cea0af2253a6802bd1f320e8ce7f840b34d46f355fd14ccf9a57596dd932dbf3?response-content-disposition=attachment%3B%20filename%3D%22HDF-EOS_UG.pdf%22%3B%20filename*%3Dutf-8%27%27HDF-EOS_UG.pdf