HDF5 Image and Palette Specification

This specification defines:

• Standard attributes for an Image dataset
• Standard storage and attributes for Palettes
• Standard for associating Palettes with Images.

1. HDF5 Image Specification

1.1 Overview

The dataset for an image is distinguished from other datasets by giving it an attribute "CLASS=IMAGE".  In addition, the Image dataset has an attribute "PALETTE" that points to one or more palettes.

A Palette is ha HDF5 dataset.  A Pallet dataset has an attribute "an" and other attributes indicating the type and size of the palette.  A Palette is an independent object, which can be shared among several Image datasets.

1.2  Image Attributes

Attribute name="CLASS"

This attribute is of type H5T_C_S1, with size 6.

For all Images, the value of this attribute is "IMAGE".

Attribute name="IMAGE_SUBCLASS"

If present, the value of this attribute indicates the type of Palette that should be used with the Image.  This attribute is of type H5T_C_S1, with size according to the string.  The values are:

"IMAGE_GRAYSCALE"

A grayscale image, values 0-255 indicating brightness.

"IMAGE_BITMAP"

A "bit map" image (???)

"IMAGE_TRUECOLOR"

A truecolor image

"IMAGE_INDEXED"

An indexed image

This attribute is of type H5T_NATIVE_UCHAR.  0 = false, 1 = true .  This is used for images with IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".

Attribute name="IMAGE_MINMAXRANGE"

If present, this attribute is an array of two numbers, of the same HDF5 datatype as the data.  The first element is the minimum value of the data, and the second is the maximum.  This is used for images with IMAGE_SUBCLASS="IMAGE_GRAYSCALE", "IMAGE_BITMAP" or "IMAGE_INDEXED".

If set, this attribute indicates the index value that should be interpreted as the "background color".  This attribute is HDF5 type H5T_NATIVE_UINT.

If set, this attribute indicates the index value that should be interpreted as the "transparent color".  This attribute is HDF5 type H5T_NATIVE_UINT.  This attribute may not be used for IMAGE_SUBCLASS="IMAGE_TRUE_COLOR".

If set, this attribute indicates the aspect ratio.  This attribute is HDF5 type H5T_NATIVE_UINT.

If set, this attribute indicates the color model of Palette that should be used with the Image.  This attribute is of type H5T_C_S1, with size 4,5, or 6.  The value is one of the color models described in the Palette specification below.  This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or "IMAGE_INDEXED".

If set, this attribute gives the Gamma correction.  The type is H5T_NATIVE_FLOAT.  This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or "IMAGE_INDEXED".

A dataset within an HDF5 file may optionally specify an array of palettes to be viewed with. The dataset will have an attribute field called "PALETTE" which contains an array of object reference pointers which refer to palettes in the file. The first palette in this array will be the default palette that the data may be viewed with.

This attribute is of type H5T_C_S1, with size corresponding to the length of the version string.  This attribute identifies the version number of this specification to which it conforms.  The initial version number is "1.0".

 

 
 
 

Attributes of an Image Dataset

Attribute Name		Type	Value
CLASS	R	String	"IMAGE"
PALETTE	O	Array of Object References	<references to Palette datasets>1
IMAGE_SUBCLASS	O2	String	"IMAGE_GRAYSCALE", "IMAGE_BITMAP", "IMAGE_TRUECOLOR", "IMAGE_INDEXED"
PALETTE	O	Array of Object Reference	<references to Palette datasets>
IMAGE_WHITE_IS_ZERO	O3,4	Unsigned Integer	0 = false, 1 = true
IMAGE_MINMAXRANGE	O3,5	Unsigned Integer[2]	The (<minimum>, <maximum>) value of the data.
IMAGE_BACKGROUNDINDEX	O3	Unsigned Integer	The index of the background color.
IMAGE_TRANSPARENCY	O3,5	Unsigned Integer	The index of the transparent color.
IMAGE_ASPECTRATIO	O3,4	Unsigned Integer	The aspect ratio.
IMAGE_COLORMODEL	O3,6	String	The color model, as defined below in the Palette specification for attribute PAL_COLORMODEL.
IMAGE_GAMMACORRECTION	O3,6	Float	The gamma correction.
IMAGE_VERSION	R	String	<specification version number>

1.  The first element of the array is the default Palette.
2.  This attribute is required for images that are converted from one of the standard types listed.
3. This attribute is required if set for images converted from the applicable standard type.
4.  This applies to gray scale images:  IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".
5.  This applies to gray scale images:  IMAGE_SUBCLASS="IMAGE_GRAYSCALE", "IMAGE_BITMAP", or "IMAGE_INDEXED".
5.  This applies to gray scale images:  IMAGE_SUBCLASS="IMAGE_TRUECOLOR", or "IMAGE_INDEXED".

1.3 Storage Properties for Images

2.  HDF5 Palette Specification

2.1 Overview

In this example, the color component numeric type is an 8-bit unsigned integer. While this is most common and recommended for general use, other component color numeric datatypes, such as a 16-bit unsigned integer , may be used. This type is specified as the type attribute of the palette dataset. (see H5Tget_type(), H5Tset_type())

The minimum and maximum values of the component color numeric are specified as attribute of the palette dataset. See below (attribute PAL_MINMAXNUMERIC). If these attributes do not exist, it is assumed that the range of values will fill the space of the color numeric type. i.e. with an 8-bit unsigned integer, the valid range would be 0 to 255 for each color component.

The HDF5 palette specification additionally allows for color models beyond RGB. YUV, HSV, CMY, CMYK, YCbCr color models are supported, and may be specified as a color model attribute of the palette dataset. (see "Palette Attributes" for details).

In HDF 4 and earlier, palettes were limited to 256 colors. The HDF5 palette specification allows for palettes of varying length. The length is specified as the number of rows of the palette dataset.

In a standard palette, the color entries are indexed directly. HDF5 supports the notion of a range index table. Such a table defines an ascending ordered of ranges that map dataset values to the palette. If a range index table exists for the palette, the PAL_TYPE attribute will be set to "RANGEINDEX", and the PAL_RANGEINDEX attribute will contain an object reference to a range index table array. If not, the PAL_TYPE attribute either does not exist, or will be set to "STANDARD".

The range index table array consists of a one dimensional array with the same length as the palette dataset - 1. Ideally, the range index would be of the same type as the dataset it refers to, however this is not a requirement.

Example 2: A range index array of type floating point

The range index array attribute defines the "to" of the range. Notice that the range index array attribute is one less entry in size than the palette. The first entry of 0.1259, specifies that all values below and up to 0.1259 inclusive, will map to the first palette entry. The second entry signifies that all values greater than 0.1259 up to 0.3278 inclusive, will map to the second palette entry, etc. All value greater than the last range index array attribute (100000) map to the last entry in the palette.

2.2. Palette Attributes

These attributes are defined as follows:

Attribute name="CLASS"

This attribute is of type H5T_C_S1, with size 8.

For all palettes, the value of this attribute is "PALETTE". This attribute identifies this palette data set as a palette that conforms to the specifications on this page.

Attribute name="PAL_COLORMODEL"

This attribute is of type H5T_C_S1, with size 4, 5, or 6.

Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".

This defines the color model that the entries in the palette data set represent.

"RGB"

Each color index contains a triplet where the the first value defines the red component, second defines the green component, and the third the blue component.

"CMY"

Each color index contains a triplet where the the first value defines the cyan component, second defines the magenta component, and the third the yellow component.

"CMYK"

Each color index contains a quadruplet where the the first value defines the cyan component, second defines the magenta component, the third the yellow component, and the forth the black component.

"YCbCr"

Class Y encoding model. Each color index contains a triplet where the the first value defines the luminance, second defines the Cb Chromonance, and the third the Cr Chromonance.

"YUV"

Composite encoding color model. Each color index contains a triplet where the the first value defines the luminance component, second defines the chromonance component, and the third the value component.

"HSV"

Each color index contains a triplet where the the first value defines the hue component, second defines the saturation component, and the third the value component. The hue component defines the hue spectrum with a low value representing magenta/red progressing to a high value which would represent blue/magenta, passing through yellow, green, cyan. A low value for the saturation component means less color saturation than a high value. A low value for value will be darker than a high value.

Attribute name="PAL_TYPE"

This attribute is of type H5T_C_S1, with size 10 or 11.

The current supported values for this attribute are : "STANDARD8" or "RANGEINDEX"

A PAL_TYPE of "STANDARD8" defines a palette dataset such that the first entry defines index 0, the second entry defines index 1, etc. up until the length of the palette - 1. This assumes an image dataset with direct indexes into the palette.

If the PAL_TYPE is set to "RANGEINDEX", there will be an additional attribute with a name of "PAL_RANGEINDEX",  (See example 2 for more details)

Attribute name="PAL_RANGEINDEX"

The PAL_RANGEINDEX attribute contains an HDF object reference pointer which specifies a range index array in the file to be used for color lookups for the palette.  (Only for PAL_TYPE="RANGEINDEX"

Attribute name="PAL_MINMAXNUMERIC"

If present, this attribute is an array of two numbers, of the same HDF5 datatype as the palette elements or color numerics.

They specify the minimum and maximum values of the color numeric components. For example, if the palette was an RGB of type Float, the color numeric range for Red, Green, and Blue could be set to be between 0.0 and 1.0. The intensity of the color guns would then be scaled accordingly to be between this minimum and maximum attribute.

Attribute name="PAL_VERSION"

This attribute is of type H5T_C_S1, with size corresponding to the length of the version string.  This attribute identifies the version number of this specification to which it conforms.  The initial version number is "1.0".

Attributes of a Palette Dataset

Attribute Name		Type	Value
CLASS	R	String	"PALETTE"
PAL_COLORMODEL	R	String	Color Model:  "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"
PAL_TYPE	R	String	"STANDARD8" or "RANGEINDEX"
RANGE_INDEX	R1	Object Reference	<Object Reference to Dataset of range index values>
PAL_MINMAXNUMERIC	O	Array[2] of <same datatype as palette>	The first value is the <Minimum value for color values>, the second value is <Maximum value for color values>2
PAL_VERSION	R	String	<specification version number>

1.  The RANGE_INDEX attribute is required if the PAL_TYPE is "RANGEINDEX".  Otherwise, the RANGE_INDEX attribute should be omitted.
2.  The minimum and maximum are optional.  If not set, the range is assumed to the maximum range of the number type.  If one of these attributes is set, then both should be set.  The value of the minumum must be less than or equal to the value of the maximum.

2.3. Storage Layout for Palettes

3.  Consistency and Correlation of Image and Palette Attributes

The Image and Palette specifications include several mutually redundant standard attributes, such as the IMAGE_COLORMODEL and the PAL_COLORMODEL.  These attributes are informative not normative, in that it is acceptable to attach a Palette to an Image dataset even if their attributes do not match.  Software is not required to enforce consistency, and files may contain mismatched associations of Images and Palettes.  In all cases, it is up to applications to determine what kinds of images and color models can be supported.

For example, an Image that was created from a file with an "RGB" may have a "YUV" Palette in its PALETTE attribute array.  This would be a legal HDF5 file and also a conforms to this specification, although it may or may not be correct or useable for a given application.