diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2000-12-21 20:29:37 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2000-12-21 20:29:37 (GMT) |
| commit | 38c0de50ba64eab99ef5a3499505ee39aca1362b (patch) | |
| tree | 75f8d2882d2856e2f96df877c1c746d3ed45fc9f /doc/html/ADGuide | |
| parent | d7fc23847c21874eb1ca54acf309dc0aeca778f2 (diff) | |
| download | hdf5-38c0de50ba64eab99ef5a3499505ee39aca1362b.zip hdf5-38c0de50ba64eab99ef5a3499505ee39aca1362b.tar.gz hdf5-38c0de50ba64eab99ef5a3499505ee39aca1362b.tar.bz2 | |
[svn-r3179]
Purpose:
Bringing the Application Developer's Guide into R1.4 (from R1.2)
Subdocuments:
HDF5 Image and Palette Specification
Mapping HDF4 Objects to HDF5 Objects
Platforms tested:
IE 5
Diffstat (limited to 'doc/html/ADGuide')
| -rw-r--r-- | doc/html/ADGuide/H4toH5Mapping.pdf | bin | 0 -> 50753 bytes | |||
| -rwxr-xr-x | doc/html/ADGuide/ImageSpec.html | 731 | ||||
| -rwxr-xr-x | doc/html/ADGuide/PaletteExample1.gif | bin | 0 -> 2731 bytes | |||
| -rwxr-xr-x | doc/html/ADGuide/Palettes.fm.anc.gif | bin | 0 -> 4748 bytes |
4 files changed, 731 insertions, 0 deletions
diff --git a/doc/html/ADGuide/H4toH5Mapping.pdf b/doc/html/ADGuide/H4toH5Mapping.pdf Binary files differnew file mode 100644 index 0000000..edee66a --- /dev/null +++ b/doc/html/ADGuide/H4toH5Mapping.pdf diff --git a/doc/html/ADGuide/ImageSpec.html b/doc/html/ADGuide/ImageSpec.html new file mode 100755 index 0000000..4757b71 --- /dev/null +++ b/doc/html/ADGuide/ImageSpec.html @@ -0,0 +1,731 @@ +<html> + <head> + <title>Palettes</title> + </head> + + <body bgcolor="#FFFFFF"> + + +<hr> +<center> +<table border=0 width=98%> +<tr><td valign=top align=left> + <a href="index.html">HDF5 documents and links</a> <br> + <a href="H5.intro.html">Introduction to HDF5</a> <br> + <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> + <!-- + <a href="Glossary.html">Glossary</a><br> + --> +</td> +<td valign=top align=right> + <br> + <a href="H5.user.html">HDF5 User's Guide</a> <br> + <a href="ADGuide.html">HDF5 Application Developer's Guide</a> +</td></tr> +</table> +</center> +<hr> + + + + + + + + + + +<center> +<h1>HDF5 Image and Palette Specification</h1> +<h3><i>(Major revision: designated Version 1.1 of the Image and Palette Specification)</i></h3> +</center> + +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. +<p>This specification defines: +<ul> +<li> +Standard attributes for an Image dataset</li> + +<li> +Standard storage and attributes for Palettes</li> + +<li> +Standard for associating Palettes with Images.</li> +</ul> + +<h2> +1. HDF5 Image Specification</h2> + +<h3> +1.1 Overview</h3> +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. +<p>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. +<p>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. +<h3> +1.2 Image Attributes</h3> + +<dl> +<dt> +Attribute name="<b>CLASS</b>"</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 6.</dd> + +<dd> +For all Images, the value of this attribute is "IMAGE".</dd> +</dl> + +<dd> +This attribute identifies this data set as intended to be interpreted as +an image that conforms to the specifications on this page.</dd> + +<dl> +<dt> +Attribute name="<b>IMAGE_SUBCLASS</b>"</dt> + +<dd> +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:</dd> + +<dl> +<dt> +"IMAGE_GRAYSCALE"</dt> + +<dd> +A grayscale image, values 0-255 indicating brightness.</dd> + +<dt> +"IMAGE_BITMAP"</dt> + +<dd> +A "bit map" image (???)</dd> + +<dt> +"IMAGE_TRUECOLOR"</dt> + +<dd> +A truecolor image</dd> + +<dt> +"IMAGE_INDEXED"</dt> + +<dd> +An indexed image</dd> +</dl> +</dl> + +<dt> +Attribute name="<b>IMAGE_WHITE_IS_ZERO</b>"</dt> + +<dl> +<dd> +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".</dd> +</dl> + +<dl> +<dt> +Attribute name="<b>IMAGE_MINMAXRANGE</b>"</dt> + +<dd> +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".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_BACKGROUNDINDEX</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the index value that should be interpreted +as the "background color". This attribute is HDF5 type H5T_NATIVE_UINT.</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_TRANSPARENCY</b>"</dt> + +<dl> +<dd> +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".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_ASPECTRATIO</b>"</dt> + +<dl> +<dd> +If set, this attribute indicates the aspect ratio. This attribute +is HDF5 type H5T_NATIVE_UINT.</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_COLORMODEL</b>"</dt> + +<dl> +<dd> +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".</dd> +</dl> + +<dt> +Attribute name="<b>IMAGE_GAMMACORRECTION</b>"</dt> + +<dl> +<dd> +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".</dd> +</dl> + +<dt> +Attribute name="<b>PALETTE</b>"</dt> + +<dl> +<dd> +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 "<b>PALETTE</b>" +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.</dd> +</dl> +Attribute name="<b>IMAGE_VERSION</b>" +<dl> +<dd> +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".</dd> + +<br> +<p> +<br> +<br> +<center><table BORDER=2 BGCOLOR="#FFFFFF" > +<caption>Attributes of an Image Dataset</caption> + +<tr> +<td><b>Attribute Name</b></td> + +<td></td> + +<td><b>Type</b></td> + +<td><b>Value</b></td> +</tr> + +<tr> +<td>CLASS</td> + +<td>R</td> + +<td>String</td> + +<td>"IMAGE"</td> +</tr> + +<tr> +<td>PALETTE</td> + +<td>O</td> + +<td>Array of Object References</td> + +<td><references to Palette datasets><sup>1</sup></td> +</tr> + +<tr> +<td>IMAGE_SUBCLASS</td> + +<td>O<sup>2</sup></td> + +<td>String</td> + +<td> +<dt> +"IMAGE_GRAYSCALE",</dt> + +<dt> +"IMAGE_BITMAP",</dt> + +<dt> +"IMAGE_TRUECOLOR",</dt> + +<dt> +"IMAGE_INDEXED"</dt> +</td> +</tr> + +<tr> +<td>PALETTE</td> + +<td>O</td> + +<td>Array of Object Reference</td> + +<td><references to Palette datasets></td> +</tr> + +<tr> +<td>IMAGE_WHITE_IS_ZERO</td> + +<td>O<sup>3,4</sup></td> + +<td>Unsigned Integer</td> + +<td>0 = false, 1 = true</td> +</tr> + +<tr> +<td>IMAGE_MINMAXRANGE</td> + +<td>O<sup>3,5</sup></td> + +<td>Unsigned Integer[2]</td> + +<td>The (<minimum>, <maximum>) value of the data.</td> +</tr> + +<tr> +<td>IMAGE_BACKGROUNDINDEX</td> + +<td>O<sup>3</sup></td> + +<td>Unsigned Integer</td> + +<td>The index of the background color.</td> +</tr> + +<tr> +<td>IMAGE_TRANSPARENCY</td> + +<td>O<sup>3,5</sup></td> + +<td>Unsigned Integer</td> + +<td>The index of the transparent color.</td> +</tr> + +<tr> +<td>IMAGE_ASPECTRATIO</td> + +<td>O<sup>3,4</sup></td> + +<td>Unsigned Integer</td> + +<td>The aspect ratio.</td> +</tr> + +<tr> +<td>IMAGE_COLORMODEL</td> + +<td>O<sup>3,6</sup></td> + +<td>String</td> + +<td>The color model, as defined below in the Palette specification for +attribute <b>PAL_COLORMODEL</b>.</td> +</tr> + +<tr> +<td>IMAGE_GAMMACORRECTION</td> + +<td>O<sup>3,6</sup></td> + +<td>Float</td> + +<td>The gamma correction.</td> +</tr> + +<tr> +<td>IMAGE_VERSION</td> + +<td>R</td> + +<td>String</td> + +<td><specification version number></td> +</tr> +</table></center> + +<dl><font size=-1>1. The first element of the array is the default +Palette.</font> +<br><font size=-1>2. This attribute is <b>required</b> for images +that are converted from one of the standard types listed.</font> +<br><font size=-1>3. This attribute is <b>required</b> if set for images +converted from the applicable standard type.</font> +<br><font size=-1>4. This applies to gray scale images: IMAGE_SUBCLASS="IMAGE_GRAYSCALE" +or "IMAGE_BITMAP".</font> +<br><font size=-1>5. This applies to gray scale images: IMAGE_SUBCLASS="IMAGE_GRAYSCALE", +"IMAGE_BITMAP", or "IMAGE_INDEXED".</font> +<br><font size=-1>5. This applies to gray scale images: IMAGE_SUBCLASS="IMAGE_TRUECOLOR", +or "IMAGE_INDEXED".</font></dl> +</dl> + +<h3> +1.3 Storage Properties for Images</h3> +Image datasets may be stored with any chunking or compression properties +supported by HDF5. +<h2> +2. HDF5 Palette Specification</h2> + +<h3> +2.1 Overview</h3> +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. +<center> +<p><img SRC="Palettes.fm.anc.gif" ></center> + +<p>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()) +<p>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. +<p>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 +"Palette Attributes" for details)</i>. +<p>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. +<p>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". +<p>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. +<p><b>Example 2: A range index array of type floating point</b> +<center> +<p><img SRC="PaletteExample1.gif" ></center> + +<p>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. +<h3> +2.2. Palette Attributes</h3> +A palette exists in an HDF file as an independent data set with accompanying +attributes. +<p>These attributes are defined as follows: +<dl> +<dt> +Attribute name="<b>CLASS</b>"</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 8.</dd> + +<dd> +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.</dd> + +<dt> +Attribute name="<b>PAL_COLORMODEL</b>"</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 4, 5, or 6.</dd> + +<dd> +Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".</dd> + +<dd> +This defines the color model that the entries in the palette data set represent.</dd> + +<dl> +<dt> +"RGB"</dt> + +<dd> +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.</dd> + +<dt> +"CMY"</dt> + +<dd> +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.</dd> + +<dt> +"CMYK"</dt> + +<dd> +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.</dd> + +<dt> +"YCbCr"</dt> + +<dd> +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.</dd> + +<dt> +"YUV"</dt> + +<dd> +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.</dd> + +<dt> +"HSV"</dt> + +<dd> +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 <i>value</i> will be darker than a high value.</dd> +</dl> + +<dt> +Attribute name="<b>PAL_TYPE</b>"</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 10 or 11.</dd> + +<br>The current supported values for this attribute are : "STANDARD8" or +"RANGEINDEX" +<p>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. +<p>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) +<dt> +Attribute name="<b>PAL_RANGEINDEX</b>"</dt> + +<dd> +The <b>PAL_RANGEINDEX</b> 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"</dd> + +<dt> +Attribute name="<b>PAL_MINMAXNUMERIC</b>"</dt> + +<dl> +<dt> +If present, this attribute is an array of two numbers, of the same HDF5 +datatype as the palette elements or color numerics.</dt> + +<br>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.</dl> +Attribute name="<b>PAL_VERSION</b>" +<dl>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".</dl> + +<center><table BORDER=2 BGCOLOR="#FFFFFF" > +<caption><b>Attributes of a Palette Dataset</b></caption> + +<tr> +<td><b>Attribute Name</b></td> + +<td></td> + +<td><b>Type</b></td> + +<td><b>Value</b></td> +</tr> + +<tr> +<td>CLASS</td> + +<td>R</td> + +<td>String</td> + +<td>"PALETTE"</td> +</tr> + +<tr> +<td>PAL_COLORMODEL</td> + +<td>R</td> + +<td>String</td> + +<td>Color Model: "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"</td> +</tr> + +<tr> +<td>PAL_TYPE</td> + +<td>R</td> + +<td>String</td> + +<td>"STANDARD8" or "RANGEINDEX"</td> +</tr> + +<tr> +<td>RANGE_INDEX</td> + +<td>R<sup>1</sup></td> + +<td>Object Reference </td> + +<td><Object Reference to Dataset of range index values></td> +</tr> + +<tr> +<td>PAL_MINMAXNUMERIC</td> + +<td>O</td> + +<td>Array[2] of <same datatype as palette></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> +</tr> + +<tr> +<td>PAL_VERSION</td> + +<td>R</td> + +<td>String</td> + +<td><specification version number></td> +</tr> +</table></center> + +<dl><font size=-1>1. The RANGE_INDEX attribute is required if the +PAL_TYPE is "RANGEINDEX". Otherwise, the RANGE_INDEX attribute should +be omitted.</font> +<br><font size=-1>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.</font></dl> +</dl> + +<h3> +2.3. Storage Layout for Palettes</h3> +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 +(<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.) +<br> +<h2> +3. Consistency and Correlation of Image and Palette Attributes</h2> +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 as a "palette" in a <b>PALETTE</b> 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. +<p>The Image and Palette specifications include several mutually 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. +<p>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 a conforms to this specification, although +it may or may not be correct or useable for a given application. +<p> + + + + + + + + + + + + +<hr> +<center> +<table border=0 width=98%> +<tr><td valign=top align=left> + <a href="index.html">HDF5 documents and links</a> <br> + <a href="H5.intro.html">Introduction to HDF5</a> <br> + <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> + <!-- + <a href="Glossary.html">Glossary</a><br> + --> +</td> +<td valign=top align=right> + <br> + <a href="H5.user.html">HDF5 User's Guide</a> <br> + <a href="ADGuide.html">HDF5 Application Developer's Guide</a> +</td></tr> +</table> +</center> + + + +<hr> +<address> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> +</address> + +<!-- Created: Spring 1999 --> +<!-- hhmts start --> +Last modified: 2 June 2000 +<!-- hhmts end --> + +<br> +Describes HDF5 Release 1.4 Beta, December 2000 + + + </body> +</html> diff --git a/doc/html/ADGuide/PaletteExample1.gif b/doc/html/ADGuide/PaletteExample1.gif Binary files differnew file mode 100755 index 0000000..8694d9d --- /dev/null +++ b/doc/html/ADGuide/PaletteExample1.gif diff --git a/doc/html/ADGuide/Palettes.fm.anc.gif b/doc/html/ADGuide/Palettes.fm.anc.gif Binary files differnew file mode 100755 index 0000000..d344c03 --- /dev/null +++ b/doc/html/ADGuide/Palettes.fm.anc.gif |
