diff --git a/doc/html/ADGuide/H4toH5Mapping.pdf b/doc/html/ADGuide/H4toH5Mapping.pdf new file mode 100644 index 0000000000..edee66ab32 Binary files /dev/null and b/doc/html/ADGuide/H4toH5Mapping.pdf differ diff --git a/doc/html/ADGuide/ImageSpec.html b/doc/html/ADGuide/ImageSpec.html new file mode 100755 index 0000000000..4757b712bf --- /dev/null +++ b/doc/html/ADGuide/ImageSpec.html @@ -0,0 +1,731 @@ + + + Palettes + + + + + +
+
+ + + +
+ HDF5 documents and links 
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ +		 +
+ HDF5 User's Guide 
+ HDF5 Application Developer's Guide  +
+
+
+ + + + + + + + + + +
+

HDF5 Image and Palette Specification

+

(Major revision: designated Version 1.1 of the Image and Palette Specification)

+
+ +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 do 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 defines: +

+ +

+1. HDF5 Image Specification

+ +

+1.1 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 type Integer.  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 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".
+
+ +
+This attribute identifies this data set as intended to be interpreted as +an image that conforms to the specifications on this page.
+ +
+
+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
+
+
+ +
+Attribute name="IMAGE_WHITE_IS_ZERO"
+ +
+
+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".
+
+ +
+Attribute name="IMAGE_BACKGROUNDINDEX"
+ +
+
+If set, this attribute indicates the index value that should be interpreted +as the "background color".  This attribute is HDF5 type H5T_NATIVE_UINT.
+
+ +
+Attribute name="IMAGE_TRANSPARENCY"
+ +
+
+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".
+
+ +
+Attribute name="IMAGE_ASPECTRATIO"
+ +
+
+If set, this attribute indicates the aspect ratio.  This attribute +is HDF5 type H5T_NATIVE_UINT.
+
+ +
+Attribute name="IMAGE_COLORMODEL"
+ +
+
+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".
+
+ +
+Attribute name="IMAGE_GAMMACORRECTION"
+ +
+
+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".
+
+ +
+Attribute name="PALETTE"
+ +
+
+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.
+
+Attribute name="IMAGE_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 an Image Dataset
Attribute NameTypeValue
CLASSRString"IMAGE"
PALETTEOArray of Object References<references to Palette datasets>1
IMAGE_SUBCLASSO2String +
+"IMAGE_GRAYSCALE",
+ +
+"IMAGE_BITMAP",
+ +
+"IMAGE_TRUECOLOR",
+ +
+"IMAGE_INDEXED"
+
PALETTEOArray of Object Reference<references to Palette datasets>
IMAGE_WHITE_IS_ZEROO3,4Unsigned Integer0 = false, 1 = true
IMAGE_MINMAXRANGEO3,5Unsigned Integer[2]The (<minimum>, <maximum>) value of the data.
IMAGE_BACKGROUNDINDEXO3Unsigned IntegerThe index of the background color.
IMAGE_TRANSPARENCYO3,5Unsigned IntegerThe index of the transparent color.
IMAGE_ASPECTRATIOO3,4Unsigned IntegerThe aspect ratio.
IMAGE_COLORMODELO3,6StringThe color model, as defined below in the Palette specification for +attribute PAL_COLORMODEL.
IMAGE_GAMMACORRECTIONO3,6FloatThe gamma correction.
IMAGE_VERSIONRString<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

+Image datasets may be stored with any chunking or compression properties +supported by HDF5. +

+2.  HDF5 Palette Specification

+ +

+2.1 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. +
+

+ +

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

+A palette exists in an HDF file as an independent data set with accompanying +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 NameTypeValue
CLASSRString"PALETTE"
PAL_COLORMODELRStringColor Model:  "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"
PAL_TYPERString"STANDARD8" or "RANGEINDEX"
RANGE_INDEXR1Object Reference <Object Reference to Dataset of range index values>
PAL_MINMAXNUMERICOArray[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_VERSIONRString<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

+The values of the Palette are stored as a dataset.  The datatype can +be any HDF 5 atomic numeric type.  The dataset will have dimensions +(nentries  by  ncomponents), where 'nentries' +is the number of colors (usually 256) and 'ncomponents' is the +number of values per color (3 for RGB, 4 for CMYK, etc.) +
  +

+3.  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 IMAGE +to any dataset, or to include an object reference to any +HDF5 dataset as a "palette" in a PALETTE attribute.  this would +be a perfectly 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 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. +

+ + + + + + + + + + + + +

+
+ + + +
+ HDF5 documents and links 
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ +		 +
+ HDF5 User's Guide 
+ HDF5 Application Developer's Guide  +
+
+ + + +
+
+HDF Help Desk +
+ + + +Last modified: 2 June 2000 + + +
+Describes HDF5 Release 1.4 Beta, December 2000 + + + + diff --git a/doc/html/ADGuide/PaletteExample1.gif b/doc/html/ADGuide/PaletteExample1.gif new file mode 100755 index 0000000000..8694d9dfd3 Binary files /dev/null and b/doc/html/ADGuide/PaletteExample1.gif differ diff --git a/doc/html/ADGuide/Palettes.fm.anc.gif b/doc/html/ADGuide/Palettes.fm.anc.gif new file mode 100755 index 0000000000..d344c03ddf Binary files /dev/null and b/doc/html/ADGuide/Palettes.fm.anc.gif differ