mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
05676d1abe
* Consolidate documentation under doc/ directory
Move user-facing guides from release_docs/ and doxygen/ into a single
doc/ root. release_docs/ now holds only release artifacts (changelogs,
history, release process, maintainer info).
- git mv release_docs/INSTALL*.md, USING_*.md, README_HPC.md,
BuildSystemNotes.md, AutotoolsToCMakeOptions.md,
HDF5_Library_2.0.0_Migration_Guide.md → doc/
- git mv doxygen/ → doc/doxygen/
- Update CMakeLists.txt: HDF5_DOXYGEN_DIR and add_subdirectory path
- Update CMakeInstallation.cmake: all install paths for moved files
- Update bin/make_vers: hardcoded doxygen/ path substitution
- Update doc/doxygen/CMakeLists.txt: EXAMPLES_DIRECTORY and comments
- Update README.md, CONTRIBUTING.md, SECURITY.md, config/README.md,
release_docs/RELEASE_PROCESS.md: links to moved files
- Update doxygen .dox files: release_docs/ URLs for moved guides
- Rewrite release_docs/README.md for narrowed scope
* Add HDF5_DOCS_DIR variable for doc/ root path
Introduce HDF5_DOCS_DIR = \${HDF5_SOURCE_DIR}/doc so that
CMakeInstallation.cmake and future callers reference the doc/
directory symbolically rather than by hardcoded path.
HDF5_DOXYGEN_DIR is now derived from HDF5_DOCS_DIR.
716 lines
27 KiB
Plaintext
716 lines
27 KiB
Plaintext
|
|
/** \page IMG HDF5 Image and Palette Specification Version 1.2
|
|
|
|
Navigate back: \ref index "Main" / \ref SPEC
|
|
<hr>
|
|
|
|
The HDF5 specification defines the standard objects and storage for the
|
|
standard HDF5 objects. (For information about the HDF5 library, model and
|
|
specification, see the HDF documentation.) This document is an additional
|
|
specification to define a standard profile for how to store image data
|
|
in HDF5. Image data in HDF5 is stored as HDF5 datasets with standard attributes
|
|
to define the properties of the image.
|
|
|
|
This specification is primarily concerned with two dimensional raster
|
|
data similar to HDF4 Raster Images. Specifications for storing other
|
|
types of imagery will be covered in other documents.
|
|
This specification defines:
|
|
/li Standard storage and attributes for an Image dataset (\ref subsec_image_spec_spec_over)
|
|
/li Standard storage and attributes for Palettes (\ref subsec_image_spec_spec_attr)
|
|
/li Standard for associating Palettes with Images. (\ref sec_tab_spec_sect3)
|
|
|
|
\section sec_image_spec_spec HDF5 Image Specification
|
|
|
|
\subsection subsec_image_spec_spec_over Overview
|
|
Image data is stored as an HDF5 dataset with values of HDF5 class Integer
|
|
or Float. A common example would be a two dimensional dataset, with
|
|
elements of class Integer, e.g., a two dimensional array of unsigned 8
|
|
bit integers. However, this specification does not limit the dimensions
|
|
or number type that may be used for an Image.
|
|
|
|
The dataset for an image is distinguished from other datasets by giving
|
|
it an attribute "CLASS=IMAGE". In addition, the Image dataset may
|
|
have an optional attribute "PALETTE" that is an array of object references
|
|
for zero or more palettes. The Image dataset may have additional attributes
|
|
to describe the image data, as defined in \ref subsec_image_spec_spec_attr.
|
|
|
|
A Palette is an HDF5 dataset which contains color map information.
|
|
A Palette dataset has an attribute "CLASS=PALETTE" and other attributes
|
|
indicating the type and size of the palette, as defined in \ref sec_tab_spec_sect2.
|
|
A Palette is an independent object, which can be shared
|
|
among several Image datasets.
|
|
|
|
\subsection subsec_image_spec_spec_attr Image Attributes
|
|
The attributes for the Image are scalars unless otherwise noted.
|
|
The length of String valued attributes should be at least the number of
|
|
characters. Optionally, String valued attributes may be stored in a String
|
|
longer than the minimum, in which case it must be zero terminated or null
|
|
padded. "Required" attributes must always be used. "Optional" attributes
|
|
must be used when required.
|
|
|
|
\subsection subsec_image_spec_spec_attr_attr Attributes
|
|
|
|
<table>
|
|
<caption><b>Table 1. Attributes of an Image Dataset</b></caption>
|
|
<tr>
|
|
<th><b>Attribute Name</b></th>
|
|
<th><b>Required</b> or <b>Optional</b></th>
|
|
<th><b>Type</b></th>
|
|
<th><b>String Size</b></th>
|
|
<th><b>Value</b></th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>CLASS</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>5</td>
|
|
<td>"IMAGE"</td>
|
|
<td>This attribute is type #H5T_C_S1, with size 5. For all Images, the value of
|
|
this attribute is "IMAGE". This attribute identifies this data set as intended
|
|
to be interpreted as an image that conforms to the specifications on this page.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PALETTE</td>
|
|
<td>Optional</td>
|
|
<td>Array Object References</td>
|
|
<td></td>
|
|
<td><references to Palette datasets><sup>1</sup></td>
|
|
<td>A Image dataset within an HDF5 file may optionally specify an array of
|
|
palettes to be viewed with. The dataset will have an attribute field called
|
|
"<b>PALETTE</b>" which contains a one-dimensional array of object reference
|
|
pointers (HDF5 datatype #H5T_STD_REF_OBJ) which refer to palettes in the
|
|
file. The palette datasets must conform to the Palette specification in
|
|
\ref sec_tab_spec_sect2. The first palette in this array will be the default palette
|
|
that the data may be viewed with.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_SUBCLASS</td>
|
|
<td>Optional<sup>2</sup></td>
|
|
<td>String</td>
|
|
<td>15,<br />12,<br />15,<br />13</td>
|
|
<td>"IMAGE_GRAYSCALE",<br />"IMAGE_BITMAP",<br />"IMAGE_TRUECOLOR",<br />"IMAGE_INDEXED"</td>
|
|
<td>If present, the value of this attribute indicates the type of Palette that
|
|
should be used with the Image. This attribute is a scalar of type
|
|
#H5T_C_S1, with size according to the string plus one. The values
|
|
are:<br />
|
|
<ul><li>IMAGE_GRAYSCALE (length 15) A grayscale image</li>
|
|
<li>IMAGE_BITMAP (length 12) A bit map image</li>
|
|
<li>IMAGE_TRUECOLOR (length 15) A truecolor image</li>
|
|
<li>IMAGE_INDEXED (length 13) An indexed image</li></ul></td>
|
|
</tr>
|
|
<tr>
|
|
<td>INTERLACE_MODE</td>
|
|
<td>Optional<sup>3,6</sup></td>
|
|
<td>String</td>
|
|
<td>15</td>
|
|
<td>The layout of components if more than one component per pixel.</td>
|
|
<td>For images with more than one component for each pixel, this optional attribute
|
|
specifies the layout of the data. The values are type #H5T_C_S1 of length
|
|
15. See \ref subsec_image_spec_spec_store for information about the
|
|
storage layout for data.<br />
|
|
<ul><li>INTERLACE_PIXEL (default): the component values for a pixel are contiguous.</li>
|
|
<li>INTERLACE_PLANE: each component is stored as a plane.</li></ul></td>
|
|
</tr>
|
|
<tr>
|
|
<td>DISPLAY_ORIGIN</td>
|
|
<td>Optional</td>
|
|
<td>String</td>
|
|
<td>2</td>
|
|
<td>If set, indicates the intended location of the pixel (0,0).</td>
|
|
<td>This optional attribute indicates the intended orientation of the data
|
|
on a two-dimensional raster display. The value indicates which corner
|
|
the pixel at (0, 0) should be viewed. The values are type #H5T_C_S1
|
|
of length 2. If DISPLAY_ORIGIN is not set, the orientation is undefined.<br />
|
|
<ul><li>UL: (0,0) is at the upper left.</li>
|
|
<li>LL: (0,0) is at the lower left.</li>
|
|
<li>UR: (0,0) is at the upper right.</li>
|
|
<li>LR: (0,0) is at the lower right.</li></ul></td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_WHITE_IS_ZERO</td>
|
|
<td>Optional<sup>3,4</sup></td>
|
|
<td>Unsigned Integer</td>
|
|
<td></td>
|
|
<td>0 = false, 1 = true</td>
|
|
<td>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".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_MINMAXRANGE</td>
|
|
<td>Optional<sup>3,5</sup></td>
|
|
<td>Array [2] <same datatype as data values></td>
|
|
<td></td>
|
|
<td>The (<minimum>, <maximum>) value of the data.</td>
|
|
<td>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".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_BACKGROUNDINDEX</td>
|
|
<td>Optional<sup>3</sup></td>
|
|
<td>Unsigned Integer</td>
|
|
<td></td>
|
|
<td>The index of the background color.</td>
|
|
<td>If set, this attribute indicates the index value that should be interpreted
|
|
as the "background color". This attribute is HDF5 type #H5T_NATIVE_UINT.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_TRANSPARENCY</td>
|
|
<td>Optional<sup>3,5</sup></td>
|
|
<td>Unsigned Integer</td>
|
|
<td></td>
|
|
<td>The index of the transparent color.</td>
|
|
<td>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_TRUECOLOR".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_ASPECTRATIO</td>
|
|
<td>Optional<sup>3,4</sup></td>
|
|
<td>Unsigned Integer</td>
|
|
<td></td>
|
|
<td>The aspect ratio.</td>
|
|
<td>If set, this attribute indicates the aspect ratio.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_COLORMODEL</td>
|
|
<td>Optional<sup>3,6</sup></td>
|
|
<td>String</td>
|
|
<td>3, 4, or 5</td>
|
|
<td>The color model, as defined below in the Palette specification for
|
|
attribute <b>PAL_COLORMODEL</b>.</td>
|
|
<td>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 3, 4, or 5. The value is one of the color models described in
|
|
the Palette specification in \ref subsec_tab_spec_sect2_22.
|
|
This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or
|
|
"IMAGE_INDEXED".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_GAMMACORRECTION</td>
|
|
<td>Optional<sup>3,6</sup></td>
|
|
<td>Float</td>
|
|
<td></td>
|
|
<td>The gamma correction.</td>
|
|
<td>If set, this attribute gives the Gamma correction. The attribute
|
|
is type #H5T_NATIVE_FLOAT. This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR"
|
|
or "IMAGE_INDEXED".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>IMAGE_VERSION</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>3</td>
|
|
<td>"1.2"</td>
|
|
<td>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 current version number
|
|
is "1.2".</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Notes</h4>
|
|
\li 1. The first element of the array is the defaultPalette.
|
|
\li 2. This attribute is <b>required</b> for images
|
|
that use one of the standard color map types listed.
|
|
\li 3. This attribute is <b>required</b> if set for the source
|
|
image, in the case that the image is translated from another file into
|
|
HDF5.
|
|
\li 4. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".
|
|
\li 5. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE", "IMAGE_BITMAP", or "IMAGE_INDEXED".
|
|
\li 6. This applies to: IMAGE_SUBCLASS="IMAGE_TRUECOLOR", or "IMAGE_INDEXED".
|
|
|
|
Table 2 summarizes the standard attributes for an Image dataset(s) using
|
|
the common sub-classes. Required means that the attribute listed on the leftmost
|
|
column is required for the image subclass on the first row, Optional means that
|
|
the attribute is optional for that subclass and NA that the attribute cannot
|
|
be applied to that subclass. The two first rows show the only required
|
|
attributes for all subclasses.
|
|
<br>
|
|
<table>
|
|
<caption><b>Table 2a. Applicability of Attributes to IMAGE sub-classes</b></caption>
|
|
<tr>
|
|
<th WIDTH="20%"><b>IMAGE_SUBCLASS</b><sup>1</sup></th>
|
|
<th WIDTH="20%"><b>IMAGE_GRAYSCALE</b></th>
|
|
<th WIDTH="20%"><b>IMAGE_BITMAP</b></th>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">CLASS</td>
|
|
<td WIDTH="20%">Required</td>
|
|
<td WIDTH="20%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_VERSION</td>
|
|
<td WIDTH="20%">Required</td>
|
|
<td WIDTH="20%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td>INTERLACE_MODE</td>
|
|
<td>NA</td>
|
|
<td>NA</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td>
|
|
<td WIDTH="20%">Required</td>
|
|
<td WIDTH="20%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_MINMAXRANGE</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_TRANSPARENCY</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_ASPECTRATIO</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_COLORMODEL</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td WIDTH="20%">NA</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_GAMMACORRECTION</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td WIDTH="20%">NA</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">PALETTE</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DISPLAY_ORIGIN</td>
|
|
<td>Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<table>
|
|
<caption><b>Table 2b. Applicability of Attributes to IMAGE sub-classes</b></caption>
|
|
<tr>
|
|
<th WIDTH="20%"><b>IMAGE_SUBCLASS</b></th>
|
|
<th WIDTH="20%"><b>IMAGE_TRUECOLOR</b></th>
|
|
<th><b>IMAGE_INDEXED</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">CLASS</td>
|
|
<td WIDTH="20%">Required</td>
|
|
<td>Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_VERSION</td>
|
|
<td WIDTH="20%">Required</td>
|
|
<td>Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td>INTERLACE_MODE</td>
|
|
<td>Required</td>
|
|
<td>NA</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td>NA</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_MINMAXRANGE</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_TRANSPARENCY</td>
|
|
<td WIDTH="20%">NA</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_ASPECTRATIO</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_COLORMODEL</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">IMAGE_GAMMACORRECTION</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="20%">PALETTE</td>
|
|
<td WIDTH="20%">Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DISPLAY_ORIGIN</td>
|
|
<td>Optional</td>
|
|
<td>Optional</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsection subsec_image_spec_spec_store Storage Layout and Properties for Images
|
|
In the case of an image with more than one component per pixel (e.g., Red,
|
|
Green, and Blue), the data may be arranged in one of two ways. Following
|
|
HDF4 terminology, the data may be interlaced by pixel or by plane, which
|
|
should be indicated by the INTERLACE_MODE attribute. In both
|
|
cases, the dataset will have a dataspace with three dimensions, height,
|
|
width, and components. The interlace modes specify different orders
|
|
for the dimensions.
|
|
<table>
|
|
<caption><b>Table 3. Storage of multiple component image data.</b></caption>
|
|
<tr>
|
|
<th><b>Interlace Mode</b></th>
|
|
<th><b>Dimensions in the Dataspace</b></th>
|
|
</tr>
|
|
<tr>
|
|
<td>INTERLACE_PIXEL</td>
|
|
<td>[height][width][pixel components]</td>
|
|
</tr>
|
|
<tr>
|
|
<td>INTERLACE_PLANE</td>
|
|
<td>[pixel components][height][width]</td>
|
|
</tr>
|
|
</table>
|
|
|
|
For example, consider a 5 (rows) by 10 (column) image, with Red, Green,
|
|
and Blue components. Each component is an unsigned byte. In HDF5,
|
|
the datatype would be declared as an unsigned 8 bit integer. For
|
|
pixel interlace, the dataspace would be a three dimensional array, with
|
|
dimensions: [10][5][3]. For plane interleave, the dataspace would
|
|
be three dimensions: [3][10][5].
|
|
|
|
In the case of images with only one component, the dataspace may be
|
|
either a two dimensional array, or a three dimensional array with the third
|
|
dimension of size 1. For example, a 5 by 10 image with 8 bit color
|
|
indexes would be an HDF5 dataset with type unsigned 8 bit integer.
|
|
The dataspace could be either a two dimensional array, with dimensions
|
|
[10][5], or three dimensions, with dimensions either [10][5][1] or [1][10][5].
|
|
<p>Image datasets may be stored with any chunking or compression properties
|
|
supported by HDF5.
|
|
|
|
<b>A note concerning compatibility with HDF5 GR interface: </b>An Image
|
|
dataset is stored as an HDF5 dataset. It is important to note that
|
|
the order of the dimensions is the same as for any other HDF5 dataset.
|
|
For a two dimensional image that is to be stored as a series of horizontal
|
|
scan lines, with the scan lines contiguous (i.e., the fastest changing
|
|
dimension is 'width'), the image will have a dataspace with <i>dim[0] =
|
|
height</i> and <i>dim[1]</i> = <i>width</i>. This is completely consistent
|
|
with all other HDF5 datasets.
|
|
|
|
Users familiar with HDF4 should be cautioned that <i>this is not the
|
|
same as HDF4</i>, and specifically is not consistent with what the HDF4
|
|
GR interface does.
|
|
|
|
\section sec_tab_spec_sect2 HDF5 Palette Specification
|
|
|
|
\subsection subsec_tab_spec_sect2_21 Overview
|
|
A palette is the means by which color is applied to an image and is also
|
|
referred to as a color lookup table. It is a table in which every row contains
|
|
the numerical representation of a particular color. In the example of an
|
|
8 bit standard RGB color model palette, this numerical representation of
|
|
a color is presented as a triplet specifying the intensity of red, green,
|
|
and blue components that make up each color.
|
|
<table>
|
|
<tr>
|
|
<td>
|
|
\image html Palettes_fm_anc.gif
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
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.
|
|
|
|
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. <i>(see
|
|
\ref subsec_tab_spec_sect2_22 for details)</i>.
|
|
|
|
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.
|
|
<table>
|
|
<tr>
|
|
<th>Important Note: The specification of the Indexed
|
|
Palette will change substantially in the next version. The Palette
|
|
described here is <i>deprecated</i> and is not supported.</th>
|
|
</tr>
|
|
<tr>
|
|
<td><i>DEPRECATED</i><br />
|
|
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 list 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.
|
|
|
|
<b>Example 2: A range index array of type floating point</b>
|
|
<center>
|
|
\image html PaletteExample1.gif
|
|
</center>
|
|
The range index array attribute defines the "<i>to</i>" 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.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsection subsec_tab_spec_sect2_22 Palette Attributes
|
|
A palette exists in an HDF file as an independent data set with accompanying
|
|
attributes. The Palette attributes are scalars except where noted
|
|
otherwise. String values should have size the length of the string
|
|
value plus one. "Required" attributes must be used. "Optional"
|
|
attributes must be used when required.
|
|
|
|
These attributes are defined as follows:
|
|
<table>
|
|
<caption><b>Table 4. Attributes of a Palette Dataset</b></caption>
|
|
<tr>
|
|
<th><b>Attribute Name</b></th>
|
|
<th><b>Required or Optional</b></th>
|
|
<th><b>Type</b></th>
|
|
<th><b>String Size</b></th>
|
|
<th><b>Value</b></th>
|
|
<th>Description</th></tr>
|
|
<tr>
|
|
<td>CLASS</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>7</td>
|
|
<td>"PALETTE"</td>
|
|
<td>This attribute is of type H5T_C_S1, with size 7.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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PAL_COLORMODEL</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>3, 4, or 5</td>
|
|
<td>Color Model: "RGB", "YUV", "CMY", "CMYK", "YCbCr", or "HSV"</td>
|
|
<td>This attribute is of type H5T_C_S1, with size 3, 4, or 5.
|
|
Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".<br />
|
|
This defines the color model that the entries in the palette data set represent.
|
|
<dl>
|
|
<dt>"RGB"</dt>
|
|
<dd>Each color index contains a triplet where the first value defines the
|
|
red component, second defines the green component, and the third the blue
|
|
component.</dd>
|
|
|
|
<dt>"CMY"</dt>
|
|
<dd>Each color index contains a triplet where the first value defines the
|
|
cyan component, second defines the magenta component, and the third the
|
|
yellow component.</dd>
|
|
|
|
<dt>"CMYK"</dt>
|
|
<dd>Each color index contains a quadruplet where the first value defines
|
|
the cyan component, second defines the magenta component, the third the
|
|
yellow component, and the forth the black component.</dd>
|
|
|
|
<dt>"YCbCr"</dt>
|
|
<dd>Class Y encoding model. Each color index contains a triplet where the
|
|
first value defines the luminance, second defines the Cb Chromonance, and
|
|
the third the Cr Chromonance.</dd>
|
|
|
|
<dt>"YUV"</dt>
|
|
<dd>Composite encoding color model. Each color index contains a triplet where
|
|
the first value defines the luminance component, second defines the
|
|
chromonance component, and the third the value component.</dd>
|
|
|
|
<dt>"HSV"</dt>
|
|
<dd>Each color index contains a triplet where 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 <i>value</i> will be darker than a high value.</dd>
|
|
</dl></td>
|
|
</tr>
|
|
<tr>
|
|
<td>PAL_TYPE</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>9<br /><table><tr><th>or 10</th></tr></table></td>
|
|
<td>"STANDARD8"<br /><table><tr><th>or "RANGEINDEX" <i>(Deprecated)</i></th></tr></table></td>
|
|
<td>This attribute is of type H5T_C_S1, with size 9 or 10.
|
|
The current supported values for this attribute are: "STANDARD8" or "RANGEINDEX".<br />
|
|
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.<br />
|
|
<table><tr><th><i>Deprecated</i> If the PAL_TYPE is set to "RANGEINDEX", there will
|
|
be an additional attribute with a name of <b>PAL_RANGEINDEX</b>, (See example 2
|
|
for more details)</th></tr>
|
|
</table><br />
|
|
<table><tr><th>
|
|
<dl>
|
|
<dt>Attribute name="<b>PAL_RANGEINDEX</b>" <i>(Deprecated)</i></dt>
|
|
<dd>The <b>PAL_RANGEINDEX</b> attribute contains an HDF object reference (HDF5
|
|
datatype H5T_STD_REF_OBJ) pointer which specifies a range index array in
|
|
the file to be used for color lookups for the palette. (Only for
|
|
PAL_TYPE="RANGEINDEX")</dd>
|
|
</dl></th></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><table><tr><th><i>Deprecated</i><br />RANGE_INDEX</th></tr></table></td>
|
|
<td><table><tr><th><i>Deprecated</i></th></tr></table></td>
|
|
<td><table><tr><th>Object Reference</th></tr></table></td>
|
|
<td><table><tr><th><i>Deprecated</i></th></tr></table></td>
|
|
<td><table><tr><th><Object Reference to Dataset of range index values></th></tr></table></td>
|
|
<td><table><tr><th><i>Deprecated</i></th></tr></table></td>
|
|
</tr>
|
|
<tr>
|
|
<td>PAL_MINMAXNUMERIC</td>
|
|
<td>Optional</td>
|
|
<td>Array[2] of <same datatype as palette></td>
|
|
<td></td>
|
|
<td>The first value is the <Minimum value for color values>, the second
|
|
value is <Maximum value for color values><sup>2</sup></td>
|
|
<td>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.</td></tr>
|
|
<tr>
|
|
<td>PAL_VERSION</td>
|
|
<td>Required</td>
|
|
<td>String</td>
|
|
<td>4</td>
|
|
<td>"1.2"</td>
|
|
<td>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 current version
|
|
is "1.2".</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Notes</h4>
|
|
\li 1. The RANGE_INDEX attribute is required if the
|
|
PAL_TYPE is "RANGEINDEX". Otherwise, the RANGE_INDEX attribute should
|
|
be omitted. (Range index is deprecated.)
|
|
\li 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 minimum must be less than or equal to the value of the maximum.
|
|
|
|
Table 5 summarized the uses of the standard attributes for a palette dataset.
|
|
Required means that the attribute listed on the leftmost column is required for
|
|
the palette type on the first row, Optional means that the attribute is optional
|
|
for that type and NA that the attribute cannot be applied to that type.
|
|
The four first rows show the attributes that are always required
|
|
for the two palette types.
|
|
|
|
|
|
<table>
|
|
<caption><b>Table 5. Applicability of Attributes</b></caption>
|
|
<tr>
|
|
<th WIDTH="33%"><b>PAL_TYPE</b></th>
|
|
<th WIDTH="33%"><b>STANDARD8</b></th>
|
|
<th WIDTH="34%"><b>RANGEINDEX</b></th>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="33%">CLASS</td>
|
|
<td WIDTH="33%">Required</td>
|
|
<td WIDTH="34%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="33%">PAL_VERSION</td>
|
|
<td WIDTH="33%">Required</td>
|
|
<td WIDTH="34%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="33%">PAL_COLORMODEL</td>
|
|
<td WIDTH="33%">Required</td>
|
|
<td WIDTH="34%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="33%">RANGE_INDEX</td>
|
|
<td WIDTH="33%">NA</td>
|
|
<td WIDTH="34%">Required</td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="33%">PAL_MINMAXNUMERIC</td>
|
|
<td WIDTH="33%">Optional</td>
|
|
<td WIDTH="34%">Optional</td>
|
|
</tr>
|
|
</table>
|
|
|
|
\subsection subsec_tab_spec_sect2_23 Storage Layout for Palettes
|
|
The values of the Palette are stored as a dataset. The datatype can
|
|
be any HDF5 atomic numeric type. The dataset will have dimensions
|
|
(<tt>nentries</tt> by <tt>ncomponents</tt>), where '<tt>nentries</tt>'
|
|
is the number of colors (usually 256) and '<tt>ncomponents'</tt> is the
|
|
number of values per color (3 for <b>RGB</b>, 4 for <b>CMYK</b>, etc.)
|
|
|
|
\section sec_tab_spec_sect3 Consistency and Correlation of Image and Palette Attributes
|
|
The objects in this specification are an extension to the base HDF5 specification
|
|
and library. They are accessible with the standard HDF5 library,
|
|
but the semantics of the objects are not enforced by the base library.
|
|
For example, it is perfectly possible to add an attribute called <b>IMAGE</b>
|
|
to <i>any</i> dataset, or to include an object reference to <i>any</i>
|
|
HDF5 dataset in a <b>PALETTE</b> attribute. This would be a valid
|
|
HDF5 file, but not conformant to this specification. The rules defined
|
|
in this specification must be implemented with appropriate software, and
|
|
applications must use conforming software to assure correctness.
|
|
|
|
The Image and Palette specifications include several redundant standard
|
|
attributes, such as the <b>IMAGE_COLORMODEL</b> and the <b>PAL_COLORMODEL</b>.
|
|
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 <b>PALETTE</b> attribute array. This
|
|
would be a legal HDF5 file and also conforms to this specification, although
|
|
it may or may not be correct for a given application.</p>
|
|
|
|
<hr>
|
|
Navigate back: \ref index "Main" / \ref SPEC
|
|
|
|
*/
|