BES - Modules - The HDF5 Handler

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽

Kinds of files the handler will serve

This release of the server supports HDF5 files written using any version of the HDF5 API. The handler should be built/linked with version 1.8.x of the API.

Mappings between the HDF4 data model and DAP2 data types

The mapping between the HDF5 and HDF-EOS5 data model and DAP2 is documented in a NASA Technical Note (ESDS-RFC-017). This note is quite detailed; a summary from its appendix is provided below.

Special characters in HDF identifiers

A number of non-alphanumeric characters (e.g., space, #, +, -) used in HDF identifiers are not allowed in the names of DAP objects, object components or in URLs. The HDF5 data handler therefore deals internally with translated versions of these identifiers. To translate the WWW convention of escaping such characters by replacing them with "%" followed by the hexadecimal value of their ASCII code is used. For example, "Raster Image #1" becomes "Raster%20Image%20%231". These translations should be transparent to users of the server (but they will be visible in the DDS, DAS and in any applications which use a client that does not translate the identifiers back to their original form).

Known problems

Handling of floating point attributes

Because the DAP software encodes attribute values as ASCII strings there will be a loss of accuracy for floating point attributes. This loss of accuracy is dependent on the version of the C++ I/O library used in compiling/linking the software (i.e., the amount of floating point precision preserved when outputting to ASCII is dependent on the library). Typically it is very small (e.g., at least six decimal places are preserved).

Configuration parameters

H5.IgnoreUnknownTypes
Ignore variables that use data types the handler cannot process. In practice this means 64-bit integers. DAP2 does not support the 64-bit integer type; using this parameter (i.e., setting its value to yes or true) means that 64-bit integer variables are ignored and the rest of the variables in the file can be read. The default value of this parameter (no or false) configures the handler to return an error when a 64-bit integer variable is found.

Appendix

The complete set of mappings for the types in the HDF5 and HDF-EOS5 data model
HDF5 data type DAP2 data name Notes
8-bit unsigned integer Byte
8-bit signed integer Int16
16-bit unsigned integer UInt16
16-bit signed integer Int16
32-bit unsigned integer UInt32
32-bit signed integer Int32
32-bit floating point Float32
64-bit floating point Float64
String String
Object reference URL
Compound Structure HDF5 compound can be mapped to DAP2 under the condition that the base members (excluding object/region references) of compound can be mapped to DAP2.
Dataset Variable HDF5 dataset can be mapped to DAP2 under the condition that the datatype of the HDF5dataset can be mapped to DAP2.
Attribute Attribute HDF5 attribute can be mapped to DAP2 under the condition that the datatype of the HDF5 dataset can be mapped to DAP2, and the data is either scalar or one-dimensional array.
Group naming convention A special attribute HDF5_ROOT_GROUP is used to represent the HDF5 group structure; The absolute path of the HDF5 dataset as the DAP2 variable name; HDF5 group can be mapped to DAP2 under the condition that the file structure is a tree structure.
HDF-EOS5 grid w/1-D projection Grid The latitude and longitude are encoded according to CF
HDF-EOS5 grid w/2-D projection Arrays Map data variables to DAP2 Arrays; generate DAP2 Arrays for latitude and longitude (following CF); add a coordinates attribute for each variable providing the names of the coordinate variables (following CF).
HDF-EOS5 Swath Arrays Follow the same prescription as with HDF-EOS5 2-D grids

|