NCSA HDF Specification and DeveloperÕs Guide Tag Specifications 6-1 National Center for Supercomputing Applications November 8, 1993 6-1 November 8, 1993 6-1 Chapter 6 Tag Specifications Chapter Overview This chapter addresses issues related to HDF tags and the data they represent. The first section provides general information about tags and their interpretation. The remainder of the chapter contains a complete list of tags supported by NCSA HDF Version 3.3 and detailed tag specifications. The HDF Tag Space As discussed in Chapter 1, "The Basic Structure of HDF Files," 16 bits are allotted for an HDF tag number. This provides for 65535 possible tags, ranging from 1 to 65535; zero (0) is not used. This tag space is divided into three ranges: 1 Ð 32767 Reserved for NCSA-supported tags 32768 Ð 64999 Set aside as user-definable tags 65000 Ð 65535 Reserved for expansion of the format No restrictions are placed on the user-definable tags. Note that tags from this range are not expected to be unique across user-developed HDF applications. The rest of this chapter is devoted to the NCSA-supported tags in the range 1 to 32767. Extended Tags and Alternate Physical Storage Methods Prior to HDF Version 3.2, each data element had to be stored in one contiguous block in the basic HDF file. Version 3.2 introduced extended tags, a mechanism supporting alternate physical data element storage structures. All NCSA- supported tags with variable-sized data elements can take advantage of the extended tag features. Extended Tag Implementation Extended tags are automatically recognized by current versions of the HDF library and interpreted according to a description record. The description record, a complete data element, identifies the type of extended element and provides the relevant parameters for data retrieval. Extended tags currently support two styles of alternate physical storage: Linked block elements are stored in several non- contiguous blocks within the basic HDF file. External elements are stored in a separate file, external to the basic HDF file. Every NCSA-supported tag is represented in HDF libraries and files by a tag number. NCSA-supported tags that take advantage of alternative physical storage features have an alternative tag number, called an extended tag number, that appears instead of the original tag number when an alternative physical storage method is in use. When NCSA determines that an extended tag should be defined for a given tag, the extended tag number is determined by performing an arithmetic OR with the original tag number and the hexadecimal number 0x4000. For example, the tag DFTAG_RI points to a data element containing a raster image. If the data element is stored contiguously in the same HDF file, the DD contains the tag number 302; if the data element is stored either in linked blocks or in an external file, the DD contains the extended tag number 16384. If a data object uses a regular tag number, its storage structure will be exactly as described in the ÒTag SpecificationsÓ section of this chapter. Figure 6.1 illustrates this general structure with the DD pointing directly to a single, contiguous data block. Figure 6.1 Regular Data Object regular_tag Tag number ref_no Reference number data_element The data element If a data object uses an extended tag, the storage structure will appear generally as illustrated in Figure 6.2. The DD will point to an extended tag description record which in turn will point to the data. Figure 6.2 Data Object with Extended Tag extended_tag Extended tag number ref_no Reference number ext_tag_desc A 32-bit constant defined in Hdfi.h that identifies the type of alternative storage involved. Current definitions include EXT_LINKED for linked block elements or EXT_EXTERN for external elements. data_location_information Information identifying and describing the linked blocks or external file data The data, stored either in linked blocks or in an external file Since the HDF tools were modified for HDF Version 3.2 to handle extended tags automatically, the only thing the user ever has to do is specify the use of either the linked blocks mechanism or an external file. Once that has been specified, the user can forget about extended tags entirely; the HDF library will manage everything correctly. There is only one circumstance under which an HDF user will need to be concerned with the difference between regular tag numbers and extended tag numbers. If a user bypasses the regular HDF interface to examine a raw HDF file, that user will have to know the extended tag numbers, their significance, and the alternative storage structures. Linked Block Elements As mentioned above, data elements had to be stored as single contiguous blocks within the basic HDF file prior to HDF Version 3.2. This meant that if a data element grew larger than the allotted space, the file had to be erased from its current location and rewritten at the end of the file. Linked blocks provide a convenient means of addressing this problem by linking new data blocks to a pre-existing data element. Linked block elements consist of a series of data blocks chained together in a linked list (similar to the DD list). The data blocks must be of uniform size, except for the first block, which is considered a special case. The linked block data element is a description record beginning with the constant EXT_LINKED, which identifies the linked block storage method. The rest of the record describes the organization of the data element stored as linked blocks. Figure 6.3 illustrates a linked block description record. Figure 6.3 Linked Block Description Record extended_tag The extended tag counterpart of any NCSA standard tag (16-bit integer) ref_no Reference number (16-bit integer) EXT_LINKED Constant identifying this as a linked block description record (32-bit integer) length Length of entire element (32-bit integer) first_len Length of the first data block (32-bit integer) blk_len Length of successive data blocks (32-bit integer) num_blk Number of blocks per block table (32-bit integer) link_ref Reference number of first block table (16-bit integer) The link_ref field of the description record gives the reference number of the first linked block table for the element. This table is identified by the tag/ref DFTAG_LINKED/link_ref and contains num_blk entries. There may be any number of linked block tables chained together to describe a linked block element. Figure 6.4 illustrates a linked block table. Figure 6.4 A Linked Block Table link_ref Reference number for this table (16-bit integer) next_ref Reference number for next table (16-bit integer) blk_ref_n Reference number for data block (16-bit integer) The next_ref field contains the reference number of the next linked block table. A value of zero (0) in this field indicates that there are no additional linked block tables associated with this element. The blk_ref_n fields of each linked block table contain reference numbers for the individual data blocks that make up the data portion of the linked block element. These data blocks are identified by the tag/ref DFTAG_LINKED/blk_ref_n as illustrated in Figure 6.5. Although it may seem ambiguous to use the same tag to refer to two different objects, this ambiguity is resolved by the context in which the tags appear. Figure 6.5 A Data Block blk_ref_n Reference number for this data block (16-bit integer) data_block Block of actual data (size specified by first_len or blk_len in the description record) Linked block elements can be created using the function HLcreate(), which is discussed in ChapterÊ3, ÒThe HDF General Purpose Interface.Ó External Elements External elements allow the data portion of an HDF element to reside in a separate file. The potential of external data elements is largely unexplored in the HDF context, although other file formats (most notably the Common Data Format, CDF, from NASA) have used external data elements to great advantage. Because there has been little discussion of external elements within the HDF user community, the structure of these elements is still not completely defined. Figure 6.6 shows a diagram of the suggested structure for an external element. Figure 6.6 External Element Description Record extended_tag The extended tag counterpart of any NCSA standard tag (16-bit integer) ref_no Reference number (16-bit integer) EXT_EXTERN Constant identifying this as an external element description record (16-bit integer) offset Location of the data within the external file (32-bit integer) length Length in bytes of the data in the external file (32-bit integer) filename Non-null terminated ASCII string naming the external file (any length) An external element description record begins with the constant EXT_EXTERN, which identifies the data object as having an externally stored data element. The rest of the description record consists of the specific information required to retrieve the data. External elements can be created using the function HXcreate(), which is discussed in ChapterÊ3, ÒThe HDF General Purpose Interface.Ó Tag Specifications The following pages contain the specifications of all the NCSA-supported tags in HDF Version 3.3. Each entry contains the following information: ¥ The tag (in capital letters in the left margin) ¥ The full name of the tag (on the first line to the right) ¥ The type and, where possible, the amount of data in the corresponding data element (on the second line to the right) When the data element is a variable-sized data structureÑsuch as text, a string, or a variable-sized arrayÑthe amount of data cannot be specified exactly. Where possible, a formula is provided to estimate the amount of data. The string ? bytes appears when neither the size nor the structure of the data element can be specified. ¥ The tag number in decimal/(hexadecimal) (on the third line to the right) ¥ A diagram illustrating the structure of the tag and its associated data Since all DDs that point to a data element contain data length and data offset fields, these fields are not included in the illustrations. ¥ A full specification of the tag, including a description of the data element and a discussion of its intended use. Tags are roughly grouped according to the roles they play: ¥ Utility tags ¥ Annotation tags ¥ Compression tags ¥ Raster Image tags ¥ Composite image tags ¥ Vector image tags ¥ Scientific data set tags ¥ Vset tags ¥ Obsolete tags These groupings imply a general context for the use of each tag; they are not meant to restrict their use. Please note the subsection ÒObsolete Tags.Ó These tags have fallen out of use with the continuing development of HDF. They are still recognized by the HDF library, but users should not write new objects using them; they may eventually be dropped from the HDF specification. In the following discussion, the ground symbol indicates that the DD for this tag includes no pointer to a data element. I.e., there is never a data element associated with the tag. Utility Tags DFTAG_NULL No data 0 bytes 1 (0x0001) ref_no Reference number (16-bit integer; alwaysÊ0) This tag is used for place holding and to fill empty portions of the data description block. The length and offset fields (not shown) of a DFTAG_NULL DD must be zero (0). DFTAG_VERSION Library version number 12 bytes plus the length of a string 30 (0x001E) ref_no Reference number (16-bit integer) majorv Major version number (32-bit integer) minorv Minor version number (32-bit integer) release Release number (32-bit integer) string Non-null terminated ASCII string (any length) The data portion of this tag contains the complete version number and a descriptive string for the latest version of the HDF library to write to the file. DFTAG_NT Number type 4 bytes 106 (0x006A) ref_no Reference number (16-bit integer) version Version number of NT information (8-bit integer) type Unsigned integer, signed integer, unsigned character, character, floating point, double precision floating point (8-bit code) width Number of bits, all of which are assumed to be significant (8-bit code) class A generic value, with different interpretations depending on type: floating point, integer, or character (8-bit code) Several values that may be used for each of the three types in the field CLASS are listed in Table 6.1. This is not an exhaustive list. Table 6.1 Number Type Values Type Mnemonic Value Floating point DFNTF_NONE 0 DFNTF_IEEE 1 DFNTF_VAX 2 DFNTF_CRAY 3 DFNTF_PC 4 DFNTF_CONVEX 5 Integer DFNTI_MBO 1 DFNTI_IBO 2 DFNTI_VBO 4 Character DFNTC_ASCII 1 DFNTC_EBCDOC 2 DFNTC_BYTE 0 The number type flag is used by any other element in the file to indicate specifically what a numeric value looks like. Other tag types should contain a reference number pointer to an DFTAG_NT instead of containing their own number type definitions. The version field allows expansion of the number type information, in case some future number types cannot be described using the fields currently defined. Successive versions of the DFTAG_NT may be substantially different from the current definition, but backward compatibility will be maintained. The current DFTAG_NT version number is 1. DFTAG_MT Machine type 0 bytes 107 (0x006B) double Specifies method of encoding double precision floating point (4-bit code) float Specifies method of encoding single precision floating point (4-bit code) int Specifies method of encoding integers (4-bit code) char Specifies method of encoding characters (4-bit code) DFTAG_MT specifies that all unconstrained or partially constrained values in this HDF file are of the default type for that hardware. When DFTAG_MT is set to VAX, for example, all integers will be assumed to be in VAX byte order unless specifically defined otherwise with a DFTAG_NT tag. Note that all of the headers and many tags, the whole raster image set for example, are defined with bit-wise precision and will not be overridden by the DFTAG_MT setting. For DFTAG_MT, the reference field itself is the encoding of the DFTAG_MT information. The reference field is 16 bits, taken as four groups of four bits, specifying the types for double- precision floating point, floating point, integer, and character respectively. This allows 16 generic specifications for each type. To the user, these will be defined constants in the header file hdf.h, specifying the proper descriptive numbers for Sun, VAX, Cray, Convex, and other computer systems. If there is no DFTAG_MT in a file, the application may assume that the data in the file has been written on the local machine; any portability problems must be addressed by the user. For this reason, we recommend that all HDF files contain a DFTAG_MT for maximum portability. Currently available data encodings are listed in Table 6.2. Table 6.2 Available Machine Types Type Available Encodings Double precision floating point IEEE64 VAX64 CRAY128 Floating point IEEE32 VAX32 CRAY64 Integers VAX32 Intel16 Intel32 Motorola32 CRAY64 Characters ASCII EBCDIC New encodings can be added for each data type as the need arises. Annotation Tags DFTAG_FID File identifier String 100 (0x0064) ref_no Reference number (16-bit integer) character_string Non-null terminated ASCII text (any length) This tag points to a string which the user wants to associate with this file. The string is not null terminated. The string is intended to be a user-supplied title for the file. DFTAG_FD File description Text 101 (0x0065) ref_no Reference number (16-bit integer) text_block Non-null terminated ASCII text (any length) This tag points to a block of text describing the overall file contents. The text can be any length. The block is not null terminated. The text is intended to be user-supplied comments about the file. DFTAG_TID Tag identifier String 102 (0x0066) tag Tag number to which this tag refers (16-bit integer) character_string Non-null terminated ASCII text (any length) The data for this tag is a string that identifies the functionality of the tag indicated in the space normally used for the reference number. For example, the tag identifier for DFTAG_TID might point to data that reads "tag identifier." Many tags are identified in the HDF specification, so it is usually unnecessary to include their identifiers in the HDF file. But with user-defined tags or special-purpose tags, the only way for a human reader to diagnose what kind of data is stored in a file is to read tag identifiers. Use tag descriptions to define even more detail about your user-defined tags. Note that with this tag you may make use of the user-defined tags to check for consistency. Although two persons may use the same user-defined tag, they probably will not use the same tag identifier. DFTAG_TD Tag description Text 103 (0x0067) tag Tag number to which this tag refers (16-bit integer) text_block Non-null terminated ASCII text (any length) The data for this tag is a text block which describes in relative detail the functionality and format of the tag which is indicated in the space normally occupied by the reference number. This tag is intended to be used with user-defined tags and provides a medium for users to exchange files that include human-readable descriptions of the data. It is important to provide everything that a programmer might need to know to read the data from your user-defined tag. At the minimum, you should specify everything you would need to know in order to retrieve your data at a later date if the original program were lost. DFTAG_DIL Data identifier label String 104 (0x0068) ref_no Reference number (16-bit integer) obj_tag Tag number of the data to which this label applies (16-bit integer) obj_ref_no Reference number of the data object to which this label applies (16-bit integer) character_string Non-null terminated ASCII text (any length) The DFTAG_DIL data object consists of a tag/ref followed by a string. The string serves as a label for the data identified by the tag/ref. By including DFTAG_DIL tags, you can give a data object a label for future reference. For example, DFTAG_DIL can be used to assign titles to images. DFTAG_DIA Data identifier annotation Text 105 (0x0069) ref_no Reference number (16-bit integer) obj_tag Tag number of the data to which this annotation applies (16-bit integer) obj_ref_no Reference number of the data object to which this annotation applies (16-bit integer) text_block Non-null terminated ASCII text (any length) The DFTAG_DIA data object consists of a tag/ref followed by a text block. The text block serves as an annotation of the data identified by the tag/ref. With a DFTAG_DIA tag, any data object can have a lengthy, user-written description. This can be used to include comments about images, data sets, source code, and so forth. Compression Tags DFTAG_RLE Run length encoded data 0 bytes 11 (0x000B) ref_no Reference number (16-bit integer) This tag is used in the DFTAG_ID compression field and in other places to indicate that an image or section of data is encoded with a run-length encoding scheme. The RLE method used is byte-wise. Each run is preceded by a count byte. The low seven bits of the count byte indicate the number of bytes (n). The high bit of the count byte indicates whether the next byte should be replicated n times (high bit = 1), or whether the next n bytes should be included as is (high bit = 0). See also: DFTAG_ID in ÒRaster Image TagsÓ DFTAG_NDG in ÒScientific Data Set TagsÓ DFTAG_IMC IMCOMP compressed data 0 bytes 12 (0x000C) ref_no Reference number (16-bit integer) This tag is used in the DFTAG_ID compression field and in other places to indicate that an image or section of data is encoded with an IMCOMP encoding scheme. This scheme is a 4:1 aerial averaging method which is easy to decompress. It counts color frequencies in 4x4 squares to optimize color sampling. See also: DFTAG_ID in ÒRaster Image TagsÓ DFTAG_NDG in ÒScientific Data Set TagsÓ DFTAG_JPEG 24-bit JPEG compression information ? bytes 13 (0x000D) ref_no Reference number (16-bit integer) This tag points to header information for 24-bit JPEG compressed images. The data in this tag is identical to the header data stored in a JFIF (JPEG File Interchange Format) file up to the start-of-frame parameter. The start-of- frame parameter and all further data for the JPEG image is stored in the associated DFTAG_CI data element which is the companion to the DFTAG_JPEG element. (See the document JPEG File Interchange Format* for a detailed description of the file format.) DFTAG_GREYJPEG 8-bit JPEG compression information ? bytes 14 (0x000E) ref_no Reference number (16-bit integer) This tag points to header information for 8-bit JPEG compressed images. The data in this tag is identical to the header data stored in a JFIF (JPEG File Interchange Format) file up to the start-of-frame parameter (see the JFIF format document for further details). The start-of-frame parameter and all further data for the JPEG image is stored in the associated DFTAG_CI data element which is the companion to the DFTAG_JPEG element. DFTAG_CI Compressed raster image ? bytes 303 (0x012F ref_no Reference number (16-bit integer) This tag points to a stream of bytes that make up a compressed image. The type of compression, together with any necessary parameters, are stored as a separate data object. For example, if DFTAG_JPEG is contained in the same raster image group, the stream of bytes contains the sratt-of- frame parameter and all further data for the JPEG image. Other parameters are stored in the DFTAG_JPEG object. Raster Image Tags DFTAG_RIG Raster image group n*4 bytes (where n is the number of data objects in the group) 306 (0x0132) ref_no Reference number (16-bit integer) tag_n Tag number for nth member of the group (16-bit integer) ref_n Reference number for nth member of the group (16- bit integer) The RIG data element contains the tag/refs of all the data objects required to display a raster image correctly. Application programs that deal with RIGs should read all the elements of a RIG and process those identifiers which it can display correctly. Even if the application cannot process all of the objects, the objects that it can process will be usable. Table 6.3 lists the tags that may appear in an RIG. Table 6.3 Available RIG Tags Tag Description DFTAG_ID Image dimension record DFTAG_RI Raster image DFTAG_XYP X-Y position DFTAG_LD LUT dimension DFTAG_LUT Color lookup table DFTAG_MD Matte channel dimension DFTAG_MA Matte channel DFTAG_CCN Color correction DFTAG_CFM Color format DFTAG_AR Aspect ratio Example DFTAG_ID, DFTAG_RI, DFTAG_LD, DFTAG_LUT Assume that an image dimension record, a raster image, an LUT dimension record, and an LUT are all required to display a particular raster image correctly. These data objects can be associated in an RIG so that an application can read the image dimensions then the image. It will then read the lookup table and display the image. DFTAG_ID DFTAG_LD DFTAG_MD DFTAG_ID Image dimension 20 bytes 300 (0x012C) DFTAG_LD LUT dimension 20 bytes 307 (0x0133) DFTAG_MD Matte dimension 20 bytes 308 (0x0134) ref_no Reference number (16-bit integer) x_dim Length of x (horizontal) dimension (32-bit integer) y_dim Length of y (vertical) dimension (32-bit integer) NT_ref Reference number for number type information elements Number of elements that make up one entry (16-bit integer) interlace Type of interlacing used (16-bit integer) 0 The components of each pixel are together. 1 Color elements are grouped by scan lines. 2 Color elements are grouped by planes. comp_tag Tag which tells the type of compression used and any associated parameters (16-bit integer) comp_ref Reference number of compression tag (16-bit integer) These three dimension records have exactly the same format; they specify the dimensions of the 2-dimensional arrays after which they are named and provide information regarding other attributes of the data in the array: DFTAG_ID specifies the dimensions of a DFTAG_RI. DFTAG_LD specifies the dimensions of a DFTAG_LUT. DFTAG_MD specifies the dimensions of a DFTAG_MA. Other attributes described in the image dimension record include the number type of the elements, the number of elements per pixel, the interlace scheme used, and the compression scheme used (if any). For example, a 512x256 row-wise 24-bit raster image with each pixel stored as RGB bytes would have the following values: x_dim 512 y_dim 256 NT_ref UINT8 elements 3 (3 elements per pixel: e.g., R, G, and B) interlace 0 (RGB values not separated) comp_tag 0 (no compression is used) The diagram above illustrates the tag DFTAG_ID. The DFTAG_LD and DFTAG_MD diagrams would be identical except for the tag name in the fist cell, whch would be DFTAG_LD and DFTAG_MD, respectively. DFTAG_RI Raster image xdim*ydim*elements*NTsize bytes (xdim, ydim, elements, and NTsize are specified in the corresponding DFTAG_ID) 302 (0x012E) ref_no Reference number (16-bit integer) This tag points to raster image data. It is stored in row- major order and must be interpreted as specified by interlace in the related DFTAG_ID. DFTAG_LUT Lookup table xdim*ydim*elements*NTsize bytes (xdim, ydim, elements, and NTsize are specified in the corresponding DFTAG_ID) 301 (0x012D) ref_no Reference number (16-bit integer) Pn_m mth value of parameter n (size is specified by the DFTAG_NT in the corresponding DFTAG_LD) The DFTAG_LUT, sometimes called a palette, is used to assign colors to data values. When a raster image consists of data values which are going to be interpreted through an LUT capability, the DFTAG_LUT should be loaded along with the image. The most common lookup table is the RGB lookup table which will have X dimensionÊ=Ê256 and Y dimensionÊ=Ê1 with three elements per entry, one each for red, green, and blue. The interlace will be either 0, where the LUT values are given RGB, RGB, RGB, ..., or 1, where the LUT values are given as 256 reds, 256 greens, 256 blues. DFTAG_MA Matte channel xdim*ydim*elements*NTsize bytes (xdim, ydim, elements, and NTsize are specified in the corresponding DFTAG_ID) 309 (0x0135) ref_no Reference number (16-bit integer) The DFTAG_MA data object contains transparency data which can be used to facilitate the overlaying of images. The data consists of a 2-dimensional array of unsigned 8-bit integers ranging from 0 to 255. Each point in a DFTAG_MA indicates the transparency of the corresponding point in a raster image of the same dimensions. A value of 0 indicates that the data at that point is to be considered totally transparent, while a value of 255 indicates that the data at that point is totally opaque. It is assumed that a linear scale applies to the transparency values, but users may opt to interpret the data in any way they wish. DFTAG_CCN Color correction 52 bytes (usually) 310 (0x0136) ref_no Reference number (16-bit integer) gamma Gamma parameter (32-bit IEEE floating point) red_x, red_y, and red_z Red x, y, and z correction factors (32-bit IEEE floating point) green_x, green_y, and green_z Green x, y, and z correction factors (32-bit IEEE floating point) blue_x, blue_y, and blue_z Blue x, y, and z correction factors (32-bit IEEE floating point) white_x, white_y, and white_z White x, y, and z correction factors (32-bit IEEE floating point) Color correction specifies the Gamma correction for the image and color primaries for the generation of the image. DFTAG_CFM Color format String 311 (0x0137) ref_no Reference number (16-bit integer) character_string Non-null terminated ASCII string (any length) The color format data element contains a string of uppercase characters that indicates how each element of each pixel in a raster image is to be interpreted. Table 6.4 lists the available color format strings. Table 6.4 Color Format String Values String Description VALUE Pseudo-color, or just a value associated with the pixel RGB Red, green, blue model XYZ Color-space model HSV Hue, saturation, value model HSI Hue, saturation, intensity SPECTRAL Spectral sampling method DFTAG_AR Aspect ratio 4 bytes 312 (0x0138) ref_no Reference number (16-bit integer) ratio Ratio of width to height (32-bit IEEE float) The data for this tag is the visual aspect ratio for this image. The image should be visually correct if displayed on a screen with this aspect ratio. The data consists of one floating-point number which represents width divided by height. An aspect ratio of 1.0 indicates a display with perfectly square pixels; 1.33 is a standard aspect ratio used by many monitors. Composite Image Tags DFTAG_DRAW Draw n*4 bytes (where n is the number of data objects that make up the composite image) 400 (0x0190) ref_no Reference number (16-bit integer) tag_n Tag number of the nth member of the draw list (16- bit integer) ref_n Reference number of the nth member of the draw list (16-bit integer) The DFTAG_DRAW data element consists of a list of tag/refs that define a composite image. The data objects indicated should be displayed in order. This can include several RIGs which are to be displayed simultaneously. It can also include vector overlays, like DFTAG_T14, which are to be placed on top of an RIG. Some of the elements in a DFTAG_DRAW list may be instructions about how images are to be composited (XOR, source put, anti-aliasing, etc.). These are defined as individual tags. DFTAG_XYP XY position 8 bytes 500 (0x01F4) ref_no Reference number (16-bit integer) x X-coordinate (32-bit integer) y Y-coordinate (32-bit integer) DFTAG_XYP is used in composites and other groups to indicate an XY position on the screen. For this, (0,0) is the lower left corner of the print area. X is the number of pixels to the right along the horizontal axis and Y is the number of pixels up on the vertical axis. The X and Y coordinates are two 32-bit integers. For example, if DFTAG_XYP is present in a DFTAG_RIG, the DFTAG_XYP specifies the position of the lower left corner of the raster image on the screen. See also: DFTAG_DRAW in this section Vector Image Tags DFTAG_T14 Tektronix 4014 ? bytes 602 (0x25A) ref_no Reference number (16-bit integer) This tag points to a Tektronix 4014 data stream. The bytes in the data field, when read and sent to a Tektronix 4014 terminal, will display a vector image. Only the lower seven bits of each byte are significant. There are no record markings or non-Tektronix codes in the data. DFTAG_T105 Tektronix 4105 ? bytes 603 (0x25B) ref_no Reference number (16-bit integer) This tag points to a Tektronix 4105 data stream. The bytes in the data field, when read and sent to a Tektronix 4105 terminal, will be displayed as a vector image. Only the lower seven bits of each byte are significant. Some terminal emulators will not correctly interpret every feature of the Tektronix 4105 terminal, so you may wish to use only a subset of the available Tektronix 4105 vector commands. Scientific Data Set Tags DFTAG_NDG Numeric data group n*4 bytes (where n is the number of data objects in the group.) 720 (0x02D0) ref_no Reference number (16-bit integer) tag_n Tag number of nth member of the group (16-bit integer) ref_n Reference number of nth member of the group (16-bit integer) The NDG data contains a list of tag/refs that define a scientific data set. DFTAG_NDG supersedes the old DFTAG_SDG, which became obsolete upon the release on HDF Version 3.2. A more complete explanation of the relationship between DFTAG_NDG and DFTAG_SDG can be found in Chapter 4, ÒSets and Groups.Ó All of the members of an NDG provide information for correctly interpreting and displaying the data. Application programs that deal with NDGs should read all of the elements of a NDG and process those data objects which it can use. Even if an application cannot process all of the objects, the objects that it can understand will be usable. TableÊ6.5 lists the tags that may appear in an NDG. Table 6.5 Available NDG Tags Tag Description DFTAG_SDD Scientific data dimension record (rank and dimensions) DFTAG_SD Scientific data DFTAG_SDS Scales DFTAG_SDL Labels DFTAG_SDU Units DFTAG_SDF Formats DFTAG_SDM Maximum and minimum values DFTAG_SDC Coordinate system DFTAG_CAL Calibration information DFTAG_FV Fill value DFTAG_LUT Color lookup table DFTAG_LD Lookup table dimension record DFTAG_SDLNK Link to old-style DFTAG_SDG Example DFTAG_SDD, DFTAG_SD, DFTAG_SDM Suppose that an NDG contains a dimension record, scientific data, and the maximum and minimum values of the data. These data objects can be associated in an NDG so that an application can read the rank and dimensions from the dimension record and then read the data array. If the application needs maximum and minimum values, it will read them as well. See also: Chapter 4, ÒSets and GroupsÓ DFTAG_SDD Scientific data dimension record 6 + 8*rank bytes 701 (0x02BD) ref_no Reference number (16-bit integer) rank Number of dimensions (16-bit integer) dim_n Number of values along the nth dimension (32-bit integer) data_NT_ref Reference number of DFTAG_NT for data (16-bit integer) scale_NT_ref_n Reference number for DFTAG_NT for the scale for the nth dimension (16-bit integer) This record defines the rank and dimensions of the array in the scientific data set. For example, a DFTAG_SDD for a 500x600x3 array of floating-point numbers would have the following values and components. Rank: 3 Dimensions: 500, 600, and 3. One data NT Three scale NTs DFTAG_SD Scientific data NTsize*x*y*z*... bytes (where NTsize is the size of the data NT specified in the corresponding DFTAG_SDD and x, y, z, etc. are the dimension sizes) 702 (0x02BE) ref_no Reference number (16-bit integer) This tag points to an array of scientific data. The type of the data may be specified by an DFTAG_NT included with the SDG. If there is no DFTAG_NT, the type of the data is floating-point in standard IEEE 32-bit format. The rank and dimensions must be stored as specified in the corresponding DFTAG_SDD. The diagram above shows a 3-dimensional data array. DFTAG_SDS Scientific data scales rank + NTsize0*x + NTsize1*y +NTsize2*z +... bytes (where rank is the number of dimensions, x, y, z, etc. are the dimension sizes, and NTsize# are the sizes of each scale NT from the corresponding DFTAG_SDD) 703 (0x02BF) ref_no Reference number (16-bit integer) is_n A flag indicating whether a scale exists for the nth dimension (8-bit integer; 0 or 1) scale_n List of scale values for the nth dimension (type specified in corresponding DFTAG_SDD) This tag points to the scales for the data set. The first n bytes indicate whether there is a scale for the corresponding dimension (1 = yes, 0 = no). This is followed by the scale values for each dimension. The scale consists of a simple series of values where the number of values and their types are specified in the corresponding DFTAG_SDD. DFTAG_SDL Scientific data labels ? bytes 704 (0x02C0) ref_no Reference number (16-bit integer) label_n Null terminated ASCII string (any length) This tag points to a list of labels for the data in each dimension of the data set. Each label is a string terminated by a null byte (0). DFTAG_SDU Scientific data units ? bytes 705 (0x02C1) ref_no Reference number (16-bit integer) unit_n Null terminated ASCII string (any length) This tag points to a list of strings specifying the units for the data and each dimension of the data set. Each unit's string is terminated by a null byte (0). DFTAG_SDF Scientific data format ? bytes 706 (0x02C2) ref_no Reference number (16-bit integer) format_n Null terminated ASCII string (any length) This tag points to a list of strings specifying an output format for the data and each dimension of the data set. Each format string is terminated by a null byte (0). DFTAG_SDM Scientific data max/min 8 bytes 707 (0x02C3) ref_no Reference number (16-bit integer) max Maximum value (type is specified by the data NT in the corresponding DFTAG_SDD) min Minimum value (type is specified by the data NT in the corresponding DFTAG_SDD) This record contains the maximum and minimum data values in the data set. The type of max and min are specified by the data NT of the corresponding DFTAG_SDD. DFTAG_SDC Scientific data coordinates ? bytes 708 (0x02C4) ref_no Reference number (16-bit integer) string Null terminated ASCII string (any length) This tag points to a string specifying the coordinate system for the data set. The string is terminated by a null byte. DFTAG_SDLNK Scientific data set link 8 bytes 710 (0x02C6) ref_no Reference number (16-bit integer) DFTAG_NDG NDG tag (16-bit integer) NDG_ref NDG reference number (16-bit integer) DFTAG_SDG SDG tag (16-bit integer) SDG_ref SDG reference number (16-bit integer) The purpose of this tag is to link together an old-style DFTAG_SDG and a DFTAG_NDG in cases where the NDG contains 32-bit floating point data and is, therefore, equivalent to an old SDG. See also: Chapter 4, ÒSets and GroupsÓ DFTAG_CAL Calibration information 36 bytes 731 (0x02DB) ref_no Reference number (16-bit integer) cal Calibration factor (64-bit IEEE float) cal_err Error in calibration factor (64-bit IEEE float) off Calibration offset (64-bit IEEE float) off_err Error in calibration offset (64-bit IEEE float) data_type Constant representing the effective data type of the calibrated data (32-bit integer) This tag points to a calibration record for the associated DFTAG_SD. The data can be calibrated by first multiplying by the cal factor, then adding the off value. Also included in the record are errors for the calibration factor and offset and a constant indicating the effective data type of the calibrated data. Table 6.6 lists the available data_type values. Table 6.6 Available Calibrated Data Types Data Type Description DFTNT_INT8 Signed 8-bit integer DFTNT_UINT8 Unsigned 8-bit integer DFTNT_INT16 Signed 16-bit integer DFTNT_UINT16 Unsigned 16-bit integer DFTNT_INT32 Signed 32-bit integer DFTNT_UINT32 Unsigned 32-bit integer DFTNT_FLOAT32 32-bit floating point DFTNT_FLOAT64 64-bit floating point DFTAG_FV Fill value ? bytes (size determined by size of data NT in corresponding DFTAG_SDD) 732 (0x02DC) ref_no Reference number (16-bit integer) fill_value Value representing unset data in the corresponding DFTAG_SD (size determined by size of data NT in corresponding DFTAG_SDD) This tag points to a value which has been used to indicate unset values in the associated DFTAG_SD. The number type of the value (and, therefore, its size) is given in the corresponding DFTAG_SDD. Vset Tags DFTAG_VG Vgroup 14 + 4*nelt + namelen + classlen bytes 1965 (0x07AD) ref_no Reference number (16-bit integer) nelt Number of elements in the Vgroup (16-bit integer) tag_n Tag of the nth member of the Vgroup (16-bit integer) ref_n Reference number of the nth member of the Vgroup (16-bit integer) namelen Length of the name field (16-bit integer) name Non-null terminated ASCII string (length given by namelen) classlen Length of the class field (16-bit integer) class Non-null terminated ASCII string (length given by classlen) extag Extension tag (16-bit integer) exref Extension reference number (16-bit integer) version Version number of DFTAG_VG information (16-bit integer) more Unused (2 zero bytes) DFTAG_VG provides a general-purpose grouping structure which can be used to impose a hierarchical structure on the tags in the group. Any HDF tag may be incorporated into a Vgroup, including other DFTAG_VG tags. See also: ÒVsets, Vdatas, and VgroupsÓ in Chapter 4, ÒSets and GroupsÓ NCSA HDF Vsets, Version 2.0 for HDF VersionÊ3.2 and earlier NCSA HDF UserÕs Guide and NCSA HDF Reference Manual for HDF Version 3.3 DFTAG_VH Vdata description 22 + 10*nfields + Sfldnmlen n + namelen + classlen bytes 1962 (0x07AA) ref_no Reference number (16-bit integer) interlace Constant indicating interlace scheme used (16- bit integer) nvert Number of entries in Vdata (32-bit integer) ivsize Size of one Vdata entry (16-bit integer) nfields Number of fields per entry in the Vdata (16-bit integer) type_n Constant indicating the data type of the nth field of the Vdata (16-bit integer) isize_n Size in bytes of the nth field of the Vdata (16-bit integer) offset_n Offset of the nth field within the Vdata (16-bit integer) order_n Order of the nth field of the Vdata (16-bit integer) fldnmlen_n Length of the nth field name string (16-bit integer) fldnm_n Non-null terminated ASCII string (length given by corresponding fldnmlen_n) namelen Length of the name field (16-bit integer) name Non-null terminated ASCII string (length given by namelen) classlen Length of the class field (16-bit integer) class Non-null terminated ASCII string (length given by classlen) extag Extension tag (16-bit integer) exref Extension reference number (16-bit integer) version Version number of DFTAG_VH information (16-bit integer) more Unused (2 zero bytes) DFTAG_VH provides all the information necessary to process a DFTAG_VS. See also: DFTAG_VS (this section) ÒVsets, Vdatas, and VgroupsÓ in Chapter 4, ÒSets and GroupsÓ NCSA HDF Vsets, Version 2.0 for HDF VersionÊ3.2 and earlier NCSA HDF UserÕs Guide and NCSA HDF Reference Manual for HDF Version 3.3 DFTAG_VS Vdata bytes, where nvert, isize_n, and order_n are specified in the corresponding DFTAG_VH 1963 (0x07AB) ref_no Reference number (16-bit integer) vdata Data block interpreted according to the corresponding DFTAG_VH ( bytes, where nvert, isize_n, and order_n are specified in the corresponding DFTAG_VH) DFTAG_VS contains a block of data which is to be interpreted according to the information in the corresponding DFTAG_VH. See also: DFTAG_VH (this section) ÒVsets, Vdatas, and VgroupsÓ in Chapter 4, ÒSets and GroupsÓ NCSA HDF Vsets, Version 2.0 for HDF VersionÊ3.2 and earlier NCSA HDF UserÕs Guide and NCSA HDF Reference Manual for HDF Version 3.3 Obsolete Tags DFTAG_ID8 Image dimension-8 4 bytes 200 (0x00C8) ref_no Reference number (16-bit integer) x_dim Length of x dimension (16-bit integer) y_dim Length of y dimension (16-bit integer) The data for this tag consists of two 16-bit integers representing the width and height of an 8-bit raster image in bytes. This tag has been superseded by DFTAG_ID. DFTAG_IP8 Image palette-8 768 bytes 201 (0x00C9) ref_no Reference number (16-bit integer) Table entries 256 triples of 8-bit integers The data for this tag can be thought of as a table of 256 entries, each containing one value for red, green, and blue. The first triple is palette entry 0 and the last is palette entry 255. This tag has been superseded by DFTAG_LUT. DFTAG_RI8 Raster image-8 xdim*ydim bytes (where xdim and ydim are the dimensions specified in the corresponding DFTAG_ID8) 202 (0x00CA) ref_no Reference number (16-bit integer) Image data 2-dimensional array of 8-bit integers The data for this tag is a row-wise representation of the elementary 8-bit image data. The data is stored width-first (i.e., row-wise) and is 8 bits per pixel. The first byte of data represents the pixel in the upper-left hand corner of the image. This tag has been superseded by DFTAG_RI. DFTAG_CI8 Compressed image-8 ? bytes 203 (0x00CB) ref_no Reference number (16-bit integer) compressed_image Series of run-length encoded bytes The data for this tag is a row-wise representation of the elementary 8-bit image data. Each row is compressed using the following run-length encoding where n is the lower seven bits of the byte. The high bit indicates whether the following n bytes will be reproduced exactly (high bit = 0) or whether the following byte will be reproduced n times (high bitÊ= 1). Since DFTAG_CI8 and DFTAG_RI8 are basically interchangeable, it is suggested that you not have a DFTAG_CI8 and a DFTAG_RI8 with the same reference number. This tag has been superseded by DFTAG_RLE. DFTAG_II8 IMCOMP image-8 ? bytes 204 (0x00CC) ref_no Reference number (16-bit integer) compressed_image Compressed image data The data for this tag is a 4:1 compressed 8-bit image, using the IMCOMP compression scheme. This tag has been superseded by DFTAG_IMC. DFTAG_SDG Scientific data group n*4 bytes (where n is the number of data objects in the group) 700 (0x02BC) ref_no Reference number (16-bit integer) tag_n Tag number of nth member of the group (16-bit integer) ref_n Reference number of nth member of the group (16- bit integer) The SDG data element contains a list of tag/refs that define a scientific data set. All of the members of the group provide information required to correctly interpret and display the data. Application programs that deal with SDGs should read all of the elements of an SDG and process those which it can use. Even if an application cannot process all of the objects, the objects that it can understand will be usable. Table 6.7 lists the tags that may appear in an SDG. Table 6.7 Available SDG Tags Tag Description DFTAG_SDD Scientific data dimension record (rank and dimensions) DFTAG_SD Scientific data DFTAG_SDS Scales DFTAG_SDL Labels DFTAG_SDU Units DFTAG_SDF Formats DFTAG_SDM Maximum and minimum values DFTAG_SDC Coordinate system DFTAG_SDT Transposition (obsolete) DFTAG_SDLNK Link to new DFTAG_NDG Example DFTAG_SDD, DFTAG_SD, DFTAG_SDM Assume that a dimension record, scientific data, and the maximum and minimum values of the data are required to read and interpret a particular data set. These data objects can be associated in an SDG so that an application can read the rank and dimensions from the dimension record and then read the data array. If the application needs the maximum and minimum values, it will read them as well. This tag has been superseded by DFTAG_NDG. See also: Chapter 4, ÒSets and GroupsÓ DFTAG_SDT Scientific data transpose 0 bytes 709 (0x02C5) ref_no Reference number (16-bit integer) The presence of this tag in a group indicates that the data pointed to by the corresponding DFTAG_SD is in column-major order, instead of the default row-major order. No data is associated with this tag. This tag is no longer written by the HDF library. When it is encountered in an old file, it is interpreted as originally intended. * The document JPEG File Interchange Format has not been published in a regular periodical. An electronic copy is available as a Postscript file from NCSAÕs FTP server ftp.ncsa.uiuc.edu in the same directory as this document, NCSA HDF Specification and DeveloperÕs Guide. Printed copies are available from C-Cube Microsystems, 1778 McCarthy Boulevard, Milpitas, CA 95035 (phone: 408-944-6300. Fax: 408-944-6314. Current email contact: eric@c3.pla.ca.us).