The HDF-EOS library provides APIs and associated callable routines for all the three main data types supported by HDF-EOS. As mentioned in Volume 1 of the HDF-EOS Library Users Guide, the routines fro these APIs can be broken down into seceral categories:

1. Access - Initializing, opening, closing and terminating.
2. Definition - Sets or defines important features such as dimensions.
3. Input/Output - Reading and writing.
4. Index Input/Output - Reading and writing information which links data sets in the PT API.
5. Inquiry - Queries about the data and metadata.
6. Subsetting - Reads or writes from selected/defined geographical regions.

Complete detail of the various interfaces or APIs and their associated commands is provided in the HDF-EOS Users Guide, but some initial information for each API is provided below. Both the C and the FORTRAN (in parentheses) preface are given for each interface.

• SW API (SW/sw): The SW API is used for storing, retrieving, and manipulating time-ordered data sets such as satellite swath data.
• GD API (GD/gd): The GD API is used for storing, retrieving, and manipulating data that has been stored in a rectilinear array based on a defined map projection.
• PT API (PT/pt): The PT API is used for storing, retrieving, and manipulating data in point data sets. These data have associated geolocation information, but are not organized in a spatial or temporal fashion.

The above summaries provided an overview of the various HDF-EOS APIs and some of the most important information needed by an individual researcher and/or non-expert HDF/HDF-EOS user. The user is directed to the HDF-EOS Users Guide, Volume 1: Overview and Example and HDF-EOS Users Guide, Volume 2: Reference Guide for complete documentation on the HDF-EOS APIs and all possible commands and operations. A good source that provides links to these documents is the HDF-EOS Information Resources page.

Return to Main Topics

The Grid API or data model is most often used to read or write data on an ordered (i.e., latitude vs longitude) grid using an identified map projection selected by the data producer. An example of this might be meteorological output (temperature, as an example) from a global forecast model and represented on a geographic projection.

Similar to the SW API, th Grid API is also made up of several components with the main distinction being that the geolocation information for all points in a grid data set are provided by the definition of all projection parameters and a set of projection equations for the map projection.

The three main components of a Grid data set are:

• Data - 2-dimensional (or higher) array of scientific data
• Dimensions - Relates various data fields to the geolocation information by soecifying a "XDim" (longitude) and "YDim" (latitude)
• Projection - The choice of the map projection (see below) allows for the changing of geo-location Earth coordinates (latitude/longitude) to x/y coordinates for graphical representation.

Projections supported by HDF-EOS include the Geographic, Interrupted Goode's Homolosine, Polar Stereographic, UTM, Space Oblique, Albers Equal Area Conic, Mercator and Lambert Equal Area. Detailed inforamtion on the projections and HDF-EOS projection codes is provided in Ch. 6 of Volume 1 of the HDF-EOS User's Guide.

As mentioned previously, the routines within the GR API (and all HDF-EOS APIs) can be used to access the GR interface and GR data sets, define the data and metadata, read and write the data and metadata, subset the data, and obtain inforamtion on existing GR data sets. A listing of all the possible GR API commands is provided in Volume 1, Ch. 6 and Volume 2 of the HDF-EOS Users Guide. Presented below are just a few of the possible commands with both the C and FORTRAN (in paranthese) versions given:

• GDcreate (gdcreate) - creates a new grid data set
• GDopen (gdopen) - opens a new/existing HDF file and the GD API
• GDdefproj (gddefproj) - defines grid projection
• GDdefdim (gddefdim) - defines grid dimensions
• GDdeffield (gddeffld) - defines grid data fields
• GDattrinfo (gdattrinfo) - obtains names and number of grid attributes
• GDprojinfo (gdprojinfo) - obtains projection information
• GDinqfields (gdingflds) - obtains information on grid data fields
• GDinqattrs (gdinqattrs) - obtains information on grid attributes
• GDinqdims (gdinqdims) - obtains information on grid dimensions
• GDwritefield (gdwrfld) - writes data to a grid field
• GDreadfield (gdrdfld) - reads data from a grid field
• GDwriteattr (gdwrattr) - writes attributes in a grid
• GDreadattr (gdrdattr) - reads attributes from a grid
• GDwritefieldmeta (gdwrmet) - writes metadata for existing field
• GDdefboxregion (gddefboxreg) -defines a lat/long box for subsetting
• GDdetach (gddetach) - releases GR interface
• GDclose (gdclose) - closes HDF files

Examples of how to use many of the GD commands is provided in later sections.

Return to top

The Swath API or data model is mainly used to put satellite swath data from such instruments platforms as TRMM, Terra (e.g., MODIS) etc. in the form of scans (cross-track or along track ) into HDF-EOS. The data to be read/written in the Swath API has several components that are taken care of by differnt commands:

• Scientific Data - Such as counts, brightness temperature, etc.. Usually a 1- or 2-dimensional field
• Geolocation Fields - Fields such as latitude and longitude that allow the scientific data to be organized by its' location on earth
• Dimensions - Defines the names and sizes of the dimensions of each axix
• Dimension Maps - Defines the relationship between the scientific data and the geolocation field by defining the 1-to-1 relationship betweenthe dimensions of the data field and the geolocation fields. In addition, information fields such as "offset" and "increment"are provided to define the relationship when the dimensions of the two are staggered or of a different size.

As mentioned previously, the routines within the SW API (and all HDF-EOS APIs) can be used to access the SW interface and SW data sets, define the data and metadata, read and write the data and metadata, subset the data, and obtain inforamtion on existing SW data sets. A listing of all the possible SW API commands is provided in Volume 1, Ch. 5 and Volume 2 of the HDF-EOS Users Guide. Presented below are just a few of the possible commands with both the C and FORTRAN (in paranthese) versions given:

• SWcreate (swcreate) - creates a new swath data set
• SWopen (swopen) - opens or creats an HDF file with the Swath API
• SWattach (swattach) - Attachs to an existing swath in an HDF file
• SWinqdims (swinqdims) - obtains information (names, sizes) of dimesnisons
• SWinqmaps (swinqmaps) - obtains information on geolocation relationships
• SWinqattrs (swinqattrs) - obtains information (names, sizes) of attributes
• SWfieldinfo (swfldinfo) - obtains information on individual data or geolocation fields
• SWwritefield (swwrfld) - writes data to swath field
• SWreadfield (swrdfld) - reads data from a swath field
• SWwriteattr (swwrattr)- writes attributes in a swath
• SWreadattr (swrdattr) - reads attributes from a swath
• SWdefboxregion (defboxreg) - defines a latitude/longitud box of interest for subsetting
• SWdetach (swdetach) - detaches from SW API
• SWclose (swclose) - closes file

Examples of how to use many of the SW commands is provided in later sections.

Return to top

The Point API or Point data model is most commonly used for data or data records with no ordered spatial or temporal organization. A simple example of this would be meteorological observations (i.e., temperature, winds, etc.) from weather stations across the United States or ship/buoy reports over the oceans. In the example below for Alaskan surfaceweather reports, the scientific data would be the value for the wind speed, while the geolocation data might be latitude or longitude.

As mentioned previously, the routines within the PT API (and all HDF-EOS APIs) can be used to access the PT interface and PT data sets, define the data and metadata, read and write the data and metadata, subset the data, and obtain inforamtion on existing PT data sets. A listing of all the possible PT API commands is provided in Volume 1, Ch. 4 and Volume 2 of the HDF-EOS Users Guide. Presented below are just a few of the possible commands with both the C and FORTRAN (in paranthese) versions given:

• PTcreate (ptcreate) - creates a new point data set
• PTopen (ptopen) - opens PT API and existing HDF file
• PTdeflevel (ptdeflev) - defines a level within a point daya set
• PTattrinfo 9ptattrinfo) - obtains inforamtion on an individual attribute
• PTinqattrs (ptinqattrs) - obtains number and names of defined attributes
• PTwritelevel (ptwrlev) - writes records/data
• PTreadlevel (ptrdlev) - reads records/data
• PTwriteattr (ptwrattr) - writes a new or modified attribute
• PTreadattr (ptrdattr) - reads existing attribute
• PTdefboxregion (ptdefboxreg) - defines a latitude/longitude box of interest for subsetting
• PTdetach (ptdetach) - releases data set and frees memory
• PTclose (ptclose) - closes HDF-EOS file and frees PT API for further use

Return to top