The HDF Group

HDF User’s Guide

Version 4.2.6


[Top] [Prev][Next]


Appendices


Appendix A Reserved HDF Tags

A.1 Overview

This appendix includes tables containing brief descriptions of most of the tags that have been reserved for general use. This list will be expanded in future editions to include new tags as they are assigned. A more detailed description of the tags can be found in the HDF Specification and Developer's Guide. Also see the HDF Specification and Developer's Guide for a description of extended tags, which are not discussed in this appendix.

Each table contains a list of tags within one category. The titles of the tables, with a functional description of each table, are:

A.2 Tag Types and Descriptions

The following tables have five columns:

In the tables, the term String refers to a sequence of ASCII characters with the null byte possibly occurring at the end, but nowhere else. The term Text also refers to a sequence of ASCII characters, but it may contain null characters anywhere in the sequence. An n in the Data Size column describes a data unit of variable-length. For more detailed descriptions of these units of data, refer to the appropriate tag entry in the HDF Specification and Developer's Guide.

TABLE AA The HDF Utility Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_NULL
No Data
None
001
Used for place holding and filling up empty portions of the Data Descriptor Block.
DFTAG_VERSION
Library Version Number
4 bytes + string
030
Specifies the latest version of the HDF library used to write to the file.
DFTAG_NT
Number Type
4 bytes
106
Used by any other element in the file to specifically indicate what a numeric value looks like.
DFTAG_MT
Machine Type
0 bytes
107
Specifies that all unconstrained or partially constrained values in this HDF file are of the default type for that hardware.
DFTAG_FID
File Identifier
String
100
Points to a string that the user wants to associate with this file. This supports the inclusion of a user-supplied title for the file.
DFTAG_FD
File Descriptor
Text
101
Points to a block of text describing the overall file contents. It is intended to be user-supplied comments about the file.
DFTAG_TID
Tag Identifier
String
102
Provides a way to determine the meaning of a tag stored in the file.
DFTAG_TD
Tag Descriptor
Text
103
Similar to DFTAG_TD, but allows more text to be included.
DFTAG_DIL
Data Identifier Label
String
104
Associates the string with the Data Identifier as a label for whatever the identifier points to. By including DILs, any data element can be given a label for future reference. For example, this tag is often used to give titles to raster image data sets.
DFTAG_DIA
Data Identifier Annotation
Text
105
Associates the text block with the Data Identifier as an annotation for whatever that Data Identifier points to. With DIAs, and Data Identifier can have a lengthy, user-provided description of why that particular data element is in the file.
DFTAG_RLE
Run-length Encoding
0 bytes
011
Specifies that run-length encoding (RLE) is used to compress a raster image.
DFTAG_IMC
IMCOMP
Compression
0 bytes
012
Specifies that IMCOMP compression is used to compress a raster image.
DFTAG_JPEG
24-bit JPEG
Compression
n bytes
013
Provides header information for 24-bit JPEG-compressed raster images.
DFTAG_GREYPEG
8-bit JPEG
Compression
n bytes
014
Provides header information for 8-bit JPEG-compressed raster images.
TABLE AB The HDF General Raster Image Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_RIG
Raster Image Group
n*4 bytes
306
Lists the Data Identifiers (tag/reference number pairs) that uniquely describe a raster image set.
DFTAG_ID
Image Dimension
20 bytes
300
Defines the dimensions of the two-dimensional array the corresponding RI tag refers to.
DFTAG_LD
LUT Dimension
20 bytes
307
Defines the dimensions of the two-dimensional array the corresponding LUT tag refers to.
DFTAG_MD
Matte Dimension
20 bytes
308
Defines the dimensions of the two-dimensional array the corresponding MA tag refers to.
DFTAG_RI
Raster Image
x*y bytes
302
Points to a raster image data set.
DFTAG_CI
Compressed Image
n bytes
303
Points to a compressed raster image data set.
DFTAG_LUT
Lookup Table
n bytes
301
Table to be used by the hardware for the purpose of assigning RGB or HSV colors to data values.
DFTAG_MA
Matte Data
n bytes
309
Points to matte data.
DFTAG_CCN
Color Correction
n bytes
310
Specifies the gamma correction for the raster image and color primaries used in the generation of the image.
DFTAG_CFM
Color Format
String
311
Indicates the interpretation to be given to each element of each pixel in a raster image.
DFTAG_AR
Aspect Ratio
4 bytes
312
Indicates the aspect ratio of the image.
DFTAG_XYP
XY Position
8 bytes
500
Specifies the screen X-Y coordinate for raster image sets. (Also used for composite image sets - See the entry for DFTAG_XYP in Table 12.6)
TABLE AC The HDF Composite Image Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_DRAW
Draw
n*4 bytes
400
Specifies a list of Data Identifiers (tag/reference number pairs) which define a composite image.
DFTAG_XYP
XY Position
8 bytes
500
Specifies the screen X-Y coordinate for composite image sets. (Also used for raster image sets - See the entry for DFTAG_XYP in Table 12.5)
DFTAG_RUN
Run
n bytes
401
Identifies code that is to be executes as a program or script.
DFTAG_T14
Tektronix 4014
n bytes
602
Used as a vector image tag. Points to a Tektronix 4014 data. The bytes in the data field, when read and sent to a Tektronix 4014 terminal, will be displayed as a vector image.
DFTAG_T10S
Tektronix 4015
n bytes
603
Used as a vector image tag. Points to a Tektronix 4015 data. The bytes in the data field, when read and sent to a Tektronix 4015 terminal, will be displayed as a vector image.
TABLE AD The HDF Scientific Data Set Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_NDG
Numeric Data Group
n*4 bytes
720
Lists the Data Identifiers (tag/reference number pairs) that describe a scientific data set. Supersedes DFTAG_SDG.
DFTAG_SDD
SDS Dimension Record
n bytes
701
Defines the rank and dimensions of the array the corresponding SD refers to.
DFTAG_SD
Scientific Data
Real Number
702
Points to scientific data.
DFTAG_SDS
SCales
Real Number
703
Identifies the scales to be used when interpreting and displaying data.
DFTAG_SDL
Labels
String
704
Labels all dimensions and data.
DFTAG_SDU
Units
String
705
Displays units for all dimensions and data.
DFTAG_SDF
Formats
String
706
Displays formats for axes and data.
DFTAG_SDM
Maximum/minimum
2 Real Numbers
707
Displays the maximum and minimum values for the data.
DFTAG_SDC
Coordinate system
String
708
Displays the coordinate system to be used in interpreting data.
DFTAG_SDLNK
SDS Link
8 bytes
710
Links and old-style DFTAG_SDG and a DFTAG_NDG in cases where the DFTAG_NDG meets all criteria for a DFTAG_SDG.
DFTAG_CAL
Calibration Information
36 bytes
731
The calibration record for the corresponding DFTAG.SD.
DFTAG_FV
Fill Value
n bytes
732
The value which has been used to indicate unset values in the corresponding DFTAG_SD.
TABLE AE The HDF Vset Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_VG
Vgroup
14+n bytes
1965
Provides a general-purpose grouping structure.
DFTAG_VH
Vdata Description
22+n bytes
1962
Provides information necessary to process a DFTAG_VS.
DFTAG_VS
Vdata
n bytes
1963
Contains a block of data that is to be interpreted according to the information in the corresponding DFTAG_VH.
TABLE AF The Obsolete HDF Tags
Tag Name
Short Description
Data Size
Tag Value
Long Description
DFTAG_IDS
Image Dimension-8
4 bytes
200
Two 16-bit integers that represent the width and height of an 8-bit raster image in bytes.
DFTAG_IP8
Image Palette-8
768 bytes
201
A 256 x 3 byte array representing the red, green and blue elements of the 256-color palette respectively.
DFTAG_RI8
Raster Image-8
x*y bytes
202
A row-oriented representation of the elementary 8-bit image data.
DFTAG_CI8
Compressed Image-8
n bytes
203
A row-oriented representation of the elementary 8-bit raster image data, with each row compressed using a form of run-length encoding.
DFTAG_II8
IMCOMP Image-8
n bytes
204
A 4:1 8-bit raster image, compressed using the IMCOMP algorithm.
DFTAG_SDG
Scientific Data Group
n*4 bytes
700
List the Data Identifiers (tag/reference number pairs) that uniquely describe a scientific data set.
DFTAG_SDT
Transpose
0 bytes
709
Indicates that data is transposed in the file.

Appendix B HDF Installation Overview

B.1 General HDF Installation Overview

B.1.1 Acquiring the HDF Library Source

You may obtain the HDF source code and/or selected binaries at no charge from The HDF Group's server:

http://www.hdfgroup.org/products/hdf4

http://www.hdfgroup.org/release4/obtain.html

For reference, the unpacked HDF source code can be found at

ftp://ftp.hdfgroup.org/HDF/HDF_Current/src/unpacked/.

B.1.2 Building the HDF Library Source

For instructions on building HDF from the source code, please refer to the INSTALL file in the top directory of the unpacked HDF source tree.

Appendix C Attributes in HDF

C.1 Attribute Overview

Attributes are optional components in the HDF data model. They can be used to describe the nature and/or the intended usage of various HDF elements. This type of information is sometimes called user-created metadata because it is data about data. The HDF elements that can be assigned with attributes include:

At the creation, an HDF attribute requires a name, data values, number type, and number of values. The attribute name is an ASCII string of any length from 1 to H4_MAX_NC_NAME (or 256). The attribute data contains one or more values, in which case all the values must have the same number type as defined at the time the attribute is created. Attributes take the form label=value, where label is the attribute's name and value is the attribute's data. Number of values declares how many data entries the attribute has. The number type can be any type supported by the HDF library. These number types are listed in Table 1A, "Number Type Definitions" in Section I of the HDF4 Reference Manual.

For each attribute, an attribute count is maintained that identifies the number of values in the attribute. Each attribute has a unique attribute index, the value of which ranges from 0 to the total number of attributes minus 1. The attribute index is used to locate an attribute in the object which the attribute is attached to. Once the attribute is identified, its values and information can be retrieved.

There are two types of attributes in HDF: predefined attributes and user-defined attributes.

Predefined attributes have reserved names and, in some cases, predefined number types and/or number of data entries. Predefined attributes are useful because they establish conventions that applications can depend on. They were first introduced in DFSD interface and later in the SD interface. They are further described in Section 3.10, "Predefined Attributes," of the HDF User's Guide. The GR interface was added in 1995 and has only one predefined attribute: FILL_ATTR, which is described in Section 7.10.1, "Predefined GR Attributes," of the HDF User's Guide.

User-defined attributes are defined by the calling program and contain auxiliary information about the element to which the attributes attach. HDF library provides in each interface of SD, GR, V, and VS a set of functions to add and access attributes. They are fully described in the associated chapters.

C.2 Underlaying storage issues

In general, users should not need the details described in this section, unless one is working with older HDF files (circa prior to 1993) and with raw data which relies on the knowledge of data layout in the file. The inclusion of this section in this User's Guide was prompted by the HDF4 File Content Map Project because various API functions being added to support this project require explanation that involves the layout of attributes in the file.

In the early years of HDF, in addition to the predefined attributes such as label, unit, and format, annotations were used to attach metadata to an HDF element such as data set and raster image. When the library was expanded to include user-defined attributes to SD and GR interfaces, metadata once stored as an annotation could be more conveniently stored as an attribute. This expansion introduced the difference in the ways predefined attributes were stored in DFSD interface and in SD/GR interfaces. The user-defined attribute feature then extended into the V and VS interfaces. Along the way, an incompatibility was inadvertently produced in the storage of attributes and their information. The next sections briefly explains these issues and their effects.

C.2.1 Predefined Attributes in DFSD API

Beginning in 1993, when the SD interface and user-created attribute were introduced, an attribute has been stored in a vdata of class _HDF_ATTRIBUTE (or "Attr0.0",) regardless it is a predefined or user-created attribute. However, prior to this period, there were only predefined attributes in DFSD API and they can be assigned to a data set or a dimension. This early predefined attribute of the data set is stored using tag/ref approach, that is, a pair of tag and ref would point to a string containing the values of the data set's attribute and the dimensions' attributes. The dimension attributes are stored following the SDS attribute. All attributes are separated by null characters. For example, in file myfile, there is a two-dimensional data set. The SDS and its dimensions were assigned with pre-defined attributes as followed:

Data set: label = "SDS label", unit = "SDS unit", format = <no attribute assigned>

Dimension 1: label = "Dim1 label", unit = <no attribute assigned>, format = "Dim1 format"

Dimension 2: label = "Dim2 label", unit = "Dim2 unit", format = "Dim2 format"

In the file, the attributes' values are stored as followed:

Data set's label attribute tag/ref (DFTAG_SDL/<ref#>)

| (point to)

--> "SDS label<null>Dim1 label<null>Dim2 label<null>"

Data set's unit attribute tag/ref (DFTAG_SDU/<ref#>)

| (point to)

--> "SDS unit<null><null>Dim2 unit"

Data set's format attribute tag/ref (DFTAG_SDF/<ref#>)

| (point to)

--> "<null>Dim1 format<null>Dim2 format"

A complete list of pre-defined attribute tags are provided in Table AG below.

TABLE AG Pre-defined Attributes in the DFSD and SD APIs
Tag Name
Description
Data Size
Applicable to
DFTAG_SDL
Labels
String
SDS and dimensions
DFTAG_SDU
Units
String
SDS and dimensions
DFTAG_SDF
Formats
String
SDS and dimensions
DFTAG_SDM
Maximum/minimum
2 Real Numbers
Only SDS
DFTAG_SDC
Coordinate system
String
Only SDS
DFTAG_CAL
Calibration Information
36 bytes
Only SDS
DFTAG_FV
Fill Value
n bytes
Only SDS

The HDF library handles the situation properly, so the difference in storage approaches does not effect general applications, which simply read the values of these predefined attributes. It would only become significant when an application needs to get access to the raw data. The HDF4 File Content Map Project is an example. The raw data of this type of attribute is not accessible by the function SDgetattdatainfo, which was added to support the HDF4 File Content Map Project. Thus, when such an attribute is encountered, SDgetattdatainfo will return the error code DFE_NOVGREP to the caller, which will in turn call SDgetoldattdatainfo to get the data information of that attribute.

C.2.2 Vgroup Attribute Without Vsetattr

HDF Version 4.0.2, July 19, 1996, and prior did not support attributes in Vgroup and Vdata as for SD and GR interfaces. However, an application could simulate an attribute for a vgroup by creating and writing a vdata of class _HDF_ATTRIBUTE, and then adding that vdata to the vgroup via these calls:

vdata_ref = VHstoredatam(file_id, ATTR_FIELD_NAME, values, size, type,

attr_name, _HDF_ATTRIBUTE, order);

ret_value = Vaddtagref (vgroup_id, DFTAG_VH, vdata2_ref);

For simplicity, this type of attributes is referred to as old-style attributes in this document.

A vgroup and vdata were having version number as VSET_VERSION (3). Starting in version 4.1.1, HDF began to support attributes in Vgroup and Vdata interfaces. Applications were able to add and manipulate attributes via public functions such as Vsetattr/VSsetatt, Vgetattr/VSgetattr, Vattrinfo/VSattrinfo,... This type of attributes is referred to as new-style attributes in this document. The version number of a vgroup or a vdata that has new-style attributes got promoted from VSET_VERSION (3) to VSET_NEW_VERSION (4).

In addition, the file format was changed for the vgroup/vdata header to store the number of attributes and the tag/reference number of each attribute. The new attribute API functions use this new information to get access to the attributes, but they are not aware of the old-style attributes. Thus, Vnattrs misses counting them and other functions like Vattrinfo and Vgetattr are unable to get to them.

Starting in version 4.2.6, the library provides the updated functions Vnattrs2, Vattrinfo2, and Vgetattr2 for applications to get access to attributes that were not created by Vsetattr. These functions access both types of attributes. In addition, the HDF library provides the function Vnoldattrs to get the number of old-style attributes in a vgroup. The old-style attributes are likely to present in older files or files that were modified by older applications. Please refer to Section 5.8, "Vgroup Attributes," of the HDF User's Guide for details on these functions.


HDF 4.2.6 - August 2011
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group