The HDF_PARSE function recursively descends through an HDF4 file and creates an ordered hash containing object information and data.
Note: This function is not part of the standard HDF interface but is provided as a programming convenience. Its IDL source code is in the file hdf_parse.pro, located in the IDL lib directory.
Example
The following example shows how to parse a file and print the tags of the ordered hash:
File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])
Result = HDF_PARSE(File)
Result
IDL prints:
{
"_NAME": "C:\\<etc.>\\vattr_example.hdf",
"_TYPE": "GROUP",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/",
"MetObs": {
"_NAME": "MetObs",
"_TYPE": "VDATA",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/",
"_COUNT": 10,
"_NFIELDS": 1,
"_FIELD_NAMES": ["TempDP"],
"TempDP": {
"_NAME": "TempDP",
"_TYPE": "VDATA_FIELD",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/MetObs",
"_ORDER": 1,
"_IDL_DATATYPE": "INT",
"_DATA": "<unread>",
"field_contents": {
"_NAME": "field_contents",
"_TYPE": "ATTRIBUTE",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/MetObs/TempDP",
"_IDL_DATATYPE": "STRING",
"_DATA": "Dew point temperature in degrees Celsius."
}
},
"vdata_contents": {
"_NAME": "vdata_contents",
"_TYPE": "ATTRIBUTE",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/MetObs",
"_IDL_DATATYPE": "STRING",
"_DATA": "Ground station meteorological observations."
},
"num_stations": {
"_NAME": "num_stations",
"_TYPE": "ATTRIBUTE",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/MetObs",
"_IDL_DATATYPE": "INT",
"_DATA": [10]
}
},
"vdata_contents": {
"_NAME": "vdata_contents",
"_TYPE": "VDATA",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/",
"_COUNT": 1,
"_NFIELDS": 1,
"_FIELD_NAMES": ["VALUES"],
"VALUES": {
"_NAME": "VALUES",
"_TYPE": "VDATA_FIELD",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/vdata_contents",
"_ORDER": 43,
"_IDL_DATATYPE": "BYTE",
"_DATA": "<unread>
}
},
"num_stations": {
"_NAME": "num_stations",
"_TYPE": "VDATA",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/",
"_COUNT": 1,
"_NFIELDS": 1,
"_FIELD_NAMES": ["VALUES"],
"VALUES": {
"_NAME": "VALUES",
"_TYPE": "VDATA_FIELD",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/num_stations",
"_ORDER": 1,
"_IDL_DATATYPE": "INT",
"_DATA": "<unread>"
}
},
"field_contents": {
"_NAME": "field_contents",
"_TYPE": "VDATA",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/",
"_COUNT": 1,
"_NFIELDS": 1,
"_FIELD_NAMES": ["VALUES"],
"VALUES": {
"_NAME": "VALUES",
"_TYPE": "VDATA_FIELD",
"_FILE": "C:\\<etc.>\\vattr_example.hdf",
"_PATH": "/field_contents",
"_ORDER": 41,
"_IDL_DATATYPE": "BYTE",
"_DATA": "<unread>"
}
}
}
The next example uses the READ_DATA keyword and prints the contents of a VData field:
File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])
Result = HDF_PARSE(File, /READ_DATA)
Print, Result['num_stations', 'VALUES', '_DATA']
IDL prints:
10
Syntax
Result = HDF_PARSE(File, [/ READ_DATA])
Return Value
The Result is an ordered hash containing the parsed file. The tags in the hash depend upon the object type, as outlined in the tables below.
Tags common to all object types
|
Tag |
Description |
|
_NAME |
Object name (or filename if at top level)
|
|
_TYPE |
Object type, which can be any of the following: VGROUP, VDATA, VDATA_FIELD, SD,
IMAGE, ATTRIBUTE, ANNOTATION, or PALETTE
|
|
_FILE |
The filename to which the object belongs
|
|
_PATH |
The full path within the file to the object. If the object is at the root level of the file, then this field is set to '/'.
|
Tags associated with VGroups
All objects within the group will be added to the group's hash with their names as the keys.
Tags associated with VData
|
Tag |
Description |
|
_COUNT |
The number of records in the data
|
|
_NFIELDS |
The number of fields in the dataset
|
|
_FIELD_NAMES |
A string array with the names of all fields within the VData. If there are no fields, this value is set to !NULL.
|
Fields within the VData will be added as fields to the ordered hash with the field names as the hash key names. See the next table for a description of the fields.
If the VData contains attributes or annotations, they will be added to the Vdata hash with the attribute or annotation names for the keys.
Tags associated with VData fields
|
Tag |
Description |
|
_ORDER |
The number of entries (the order) of the field |
|
_IDL_DATATYPE |
String value corresponding to the IDL data type of the field values |
|
_DATA |
If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>.
|
If the field contains attributes, they will be added to the data field's hash with the attribute names for the keys.
Tags associated with Scientific Datasets (SDs)
|
Tag |
Description |
|
_NDIMENSIONS |
Number of dimensions
|
|
_DIMENSIONS |
Dimensions of the dataset
|
|
_IDL_DATATYPE |
A string corresponding to the IDL data type of the dataset
|
|
_DATA |
If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>. |
If the dataset contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.
Tags associated with images
|
Tag |
Description |
|
_RASTER_TYPE |
HDF4 contains three types of raster images:
- GR - General Raster
- 8BIT - 8-bit raster image (RIS8)
- 24BIT - 24-bit raster image (RIS24)
|
|
_NDIMENSIONS |
The number of dimensions in the image.
|
|
_DIMENSIONS |
The image dimensions
|
|
_IDL_DATATYPE |
String value corresponding to the IDL data type of the image.
|
|
_INTERLACE |
An integer corresponding to the interlace mode of the image data. Possible values are:
- 0: Pixel interlace
- 1: Line interlace
- 2: Component interlace
|
|
_DATA |
If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>. |
If the image contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.
Tags associated with attributes
|
Tag |
Description |
|
_IDL_DATATYPE |
A string corresponding to the IDL data type of the dataset |
|
_DATA |
The data from the attribute. The HDF_PARSE function always reads data from attributes, regardless of the READ_DATA keyword setting.
|
Tags associated with annotations
|
Tag |
Description |
|
_DATA |
The value stored in the annotation. The HDF_PARSE function always reads data from annotations, regardless of the READ_DATA keyword setting.
|
Tags associated with palettes
|
Tag |
Description |
|
_DATA |
The value stored in the annotation. The HDF_PARSE function always reads data frompalettes, regardless of the READ_DATA keyword setting. |
Arguments
File
A string that specifies the file to be parsed.
Keywords
READ_DATA
If you set this keyword, all data from scientific datasets, images, and VData fields will be read from the file. If you do not set this keyword, the _DATA field for these object types will be set to the string '<unread>'.
Version History
See Also
H5_PARSE