diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2001-07-03 22:10:19 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2001-07-03 22:10:19 (GMT) |
| commit | 5fae2e9cb6d0ffffbcc2250dbeb70c8ae159ed29 (patch) | |
| tree | 1980ef8b2010843b054730b8ccb2abaf4bab5e12 | |
| parent | 2457f15317b0a1968944b1d4ed0c29bbca5b3823 (diff) | |
| download | hdf5-5fae2e9cb6d0ffffbcc2250dbeb70c8ae159ed29.zip hdf5-5fae2e9cb6d0ffffbcc2250dbeb70c8ae159ed29.tar.gz hdf5-5fae2e9cb6d0ffffbcc2250dbeb70c8ae159ed29.tar.bz2 | |
[svn-r4104]
Purpose:
Version 1.2 of "HDF5 Image and Palette Spec." (Replaces v1.1)
Platforms tested:
IE 5
| -rwxr-xr-x | doc/html/ADGuide/ImageSpec.html | 885 |
1 files changed, 706 insertions, 179 deletions
diff --git a/doc/html/ADGuide/ImageSpec.html b/doc/html/ADGuide/ImageSpec.html index 13466dd..8dea86a 100755 --- a/doc/html/ADGuide/ImageSpec.html +++ b/doc/html/ADGuide/ImageSpec.html @@ -1,131 +1,205 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> - <head> - <title>Image Specification</title> - </head> - - <body bgcolor="#FFFFFF"> - +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.72 [en] (WinNT; U) [Netscape]"> + <title>Image Specification</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000"> <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> - <!-- +<center><table BORDER=0 WIDTH="98%" > +<tr> +<td ALIGN=LEFT VALIGN=TOP><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> - - - - - - - - + --></td> +<td ALIGN=RIGHT VALIGN=TOP> +<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> +<h1> +HDF5 Image and Palette Specification</h1></center> +<center> +<h3> +<i>Version 1.2</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 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. <p>This specification defines: <ul> <li> -Standard attributes for an Image dataset</li> +Standard storage and attributes for an Image dataset (<a href="#Sect1">Section +1</a>)</li> <li> -Standard storage and attributes for Palettes</li> +Standard storage and attributes for Palettes (<a href="#sect2">Section +2</a>)</li> <li> -Standard for associating Palettes with Images.</li> +Standard for associating Palettes with Images. (<a href="#Sect3">Section +3</a>)</li> </ul> <h2> -1. HDF5 Image Specification</h2> +<a NAME="Sect1"></a>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. +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. <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. +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 <a href="#Sect1.2">Section 1.2</a>. +<p>A Palette is an HDF5 dataset which contains color map information. +A Pallet dataset has an attribute "CLASS=PALETTE" and other attributes +indicating the type and size of the palette, as defined in <a href="#sect2">Section +2.1</a>. A Palette is an independent object, which can be shared +among several Image datasets. <h3> -1.2 Image Attributes</h3> +<a NAME="Sect1.2"></a>1.2 Image Attributes</h3> +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. +<br> +<h4> +Attributes</h4> <dl> <dt> -Attribute name="<b>CLASS</b>"</dt> +Attribute name="<b>CLASS</b>" (Required)</dt> <dd> -This attribute is of type H5T_C_S1, with size 6.</dd> +This attribute is type H5T_C_S1, with size 5.</dd> <dd> For all Images, the value of this attribute is "IMAGE".</dd> -</dl> + +<dd> +</dd> <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>PALETTE</b>"</dt> <dl> +<dd> +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 +<a href="#sect2">section +2 below</a>. The first palette in this array will be the default palette +that the data may be viewed with.</dd> +</dl> + +<dl> +<dt> +</dt> + <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> +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:</dd> <dl> <dt> -"IMAGE_GRAYSCALE"</dt> +"IMAGE_GRAYSCALE" (length 15)</dt> <dd> A grayscale image, values 0-255 indicating brightness.</dd> <dt> -"IMAGE_BITMAP"</dt> +"IMAGE_BITMAP" (length 12)</dt> <dd> -A "bit map" image (???)</dd> +A bit map image</dd> <dt> -"IMAGE_TRUECOLOR"</dt> +"IMAGE_TRUECOLOR" (length 15)</dt> <dd> A truecolor image</dd> <dt> -"IMAGE_INDEXED"</dt> +"IMAGE_INDEXED" (length 13)</dt> <dd> An indexed image</dd> + +<dd> +</dd> </dl> + +<dt> +Attribute name="<b>INTERLACE_MODE</b>"</dt> + +<dd> +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 <a href="#Section1.3">section 1.3</a> for information about the +storage layout for data.</dd> + +<dd> +"INTERLACE_PIXEL" (default): the component value for a pixel are contiguous.</dd> + +<dd> +"INTERLACE_PLANE": each component is stored as a plane.</dd> + +<dt> +</dt> + +<dt> +Attribute name="<b>DISPLAY_ORIGIN</b>"</dt> + +<dd> +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.</dd> + +<dd> +"UL": (0,0) is at the upper left.</dd> + +<dd> +"LL": (0,0) is at the lower left.</dd> + +<dd> +"UR": (0,0) is at the upper right.</dd> + +<dd> +"LR": (0,0) is at the lower right.</dd> </dl> <dt> @@ -183,54 +257,46 @@ Attribute name="<b>IMAGE_COLORMODEL</b>"</dt> <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. +size 3, 4, or 5. The value is one of the color models described in +the Palette specification in <a href="#sect2.2">section 2.2 below</a>. This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or "IMAGE_INDEXED".</dd> </dl> <dt> -Attribute name="<b>PALETTE</b>"</dt> +Attribute name="<b>IMAGE_GAMMACORRECTION</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> +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".</dd> </dl> -Attribute name="<b>IMAGE_VERSION</b>" +Attribute name="<b>IMAGE_VERSION</b>" (Required) <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> +of this specification to which it conforms. The current version number +is "1.2".</dd> <br> <p> <br> <br> <center><table BORDER=2 BGCOLOR="#FFFFFF" > -<caption>Attributes of an Image Dataset</caption> +<caption><b>Table 1. Attributes of an Image Dataset</b></caption> <tr> <td><b>Attribute Name</b></td> -<td></td> +<td><b>(R = Required</b> +<br><b>O= Optional)</b></td> <td><b>Type</b></td> +<td><b>String Size</b></td> + <td><b>Value</b></td> </tr> @@ -241,6 +307,8 @@ is "1.0".</dd> <td>String</td> +<td>5</td> + <td>"IMAGE"</td> </tr> @@ -249,7 +317,9 @@ is "1.0".</dd> <td>O</td> -<td>Array of Object References</td> +<td>Array Object References</td> + +<td></td> <td><references to Palette datasets><sup>1</sup></td> </tr> @@ -261,6 +331,11 @@ is "1.0".</dd> <td>String</td> +<td>15, +<br>12, +<br>15, +<br>13</td> + <td> <dt> "IMAGE_GRAYSCALE",</dt> @@ -277,13 +352,27 @@ is "1.0".</dd> </tr> <tr> -<td>PALETTE</td> +<td>INTERLACE_MODE</td> + +<td>O<sup>3,6</sup></td> + +<td>String</td> + +<td>15</td> + +<td>The layout of components if more than one component per pixel.</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> <td>O</td> -<td>Array of Object Reference</td> +<td>String</td> + +<td>2</td> -<td><references to Palette datasets></td> +<td>If set, indicates the intended location of the pixel (0,0).</td> </tr> <tr> @@ -293,6 +382,8 @@ is "1.0".</dd> <td>Unsigned Integer</td> +<td></td> + <td>0 = false, 1 = true</td> </tr> @@ -301,7 +392,9 @@ is "1.0".</dd> <td>O<sup>3,5</sup></td> -<td>Unsigned Integer[2]</td> +<td>Array [2] <same datatype as data values></td> + +<td></td> <td>The (<minimum>, <maximum>) value of the data.</td> </tr> @@ -313,6 +406,8 @@ is "1.0".</dd> <td>Unsigned Integer</td> +<td></td> + <td>The index of the background color.</td> </tr> @@ -323,6 +418,8 @@ is "1.0".</dd> <td>Unsigned Integer</td> +<td></td> + <td>The index of the transparent color.</td> </tr> @@ -333,6 +430,8 @@ is "1.0".</dd> <td>Unsigned Integer</td> +<td></td> + <td>The aspect ratio.</td> </tr> @@ -343,6 +442,8 @@ is "1.0".</dd> <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> </tr> @@ -354,6 +455,8 @@ attribute <b>PAL_COLORMODEL</b>.</td> <td>Float</td> +<td></td> + <td>The gamma correction.</td> </tr> @@ -364,51 +467,333 @@ attribute <b>PAL_COLORMODEL</b>.</td> <td>String</td> -<td><specification version number></td> +<td>3</td> + +<td>"1.2"</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" +that use one of the standard color map types listed.</font> +<br><font size=-1>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.</font> +<br><font size=-1>4. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".</font> -<br><font size=-1>5. This applies to gray scale images: IMAGE_SUBCLASS="IMAGE_GRAYSCALE", +<br><font size=-1>5. This applies to: 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", +<br><font size=-1>6. This applies to: IMAGE_SUBCLASS="IMAGE_TRUECOLOR", or "IMAGE_INDEXED".</font></dl> </dl> +Table 2 summarizes the standard attributes for an Image datasets using +the common sub-classes. R means that the attribute listed on the leftmost +column is Required for the image subclass on the first row, O means that +the attribute is Optional for that subclass and N that the attribute cannot +be applied to that subclass. The two first rows show the only required +attributes +for all subclasses. +<br> +<table BORDER WIDTH="100%" > +<caption><b>Table 2a. Applicability of Attributes to IMAGE sub-classes</b></caption> + +<tr> +<td WIDTH="20%"><b>IMAGE_SUBCLASS</b><sup>1</sup></td> + +<td WIDTH="20%"><b>IMAGE_GRAYSCALE</b></td> + +<td WIDTH="20%"><b>IMAGE_BITMAP</b></td> +</tr> + +<tr> +<td WIDTH="20%">CLASS</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_VERSION</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td>INTERLACE_MODE</td> + +<td>N</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td> + +<td WIDTH="20%">R</td> + +<td WIDTH="20%">R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_MINMAXRANGE</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_TRANSPARENCY</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_ASPECTRATIO</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_COLORMODEL</td> + +<td WIDTH="20%">N</td> + +<td WIDTH="20%">N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_GAMMACORRECTION</td> + +<td WIDTH="20%">N</td> + +<td WIDTH="20%">N</td> +</tr> + +<tr> +<td WIDTH="20%">PALETTE</td> + +<td WIDTH="20%">O</td> + +<td WIDTH="20%">O</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> + +<td>O</td> + +<td>O</td> +</tr> +</table> + +<blockquote> </blockquote> + +<table BORDER WIDTH="100%" > +<caption><b>Table 2b. Applicability of Attributes to IMAGE sub-classes</b></caption> + +<tr> +<td WIDTH="20%"><b>IMAGE_SUBCLASS</b></td> + +<td WIDTH="20%"><b>IMAGE_TRUECOLOR</b></td> + +<td><b>IMAGE_INDEXED</b></td> +</tr> + +<tr> +<td WIDTH="20%">CLASS</td> + +<td WIDTH="20%">R</td> + +<td>R</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_VERSION</td> + +<td WIDTH="20%">R</td> + +<td>R</td> +</tr> + +<tr> +<td>INTERLACE_MODE</td> + +<td>R</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td> + +<td WIDTH="20%">N</td> + +<td>N</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_MINMAXRANGE</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_TRANSPARENCY</td> + +<td WIDTH="20%">N</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_ASPECTRATIO</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_COLORMODEL</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">IMAGE_GAMMACORRECTION</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td WIDTH="20%">PALETTE</td> + +<td WIDTH="20%">O</td> + +<td>O</td> +</tr> + +<tr> +<td>DISPLAY_ORIGIN</td> + +<td>O</td> + +<td>O</td> +</tr> +</table> <h3> -1.3 Storage Properties for Images</h3> -Image datasets may be stored with any chunking or compression properties +<a NAME="Section1.3"></a>1.3 Storage Layout and Properties for Images</h3> +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. +<br> +<table BORDER COLS=2 WIDTH="100%" > +<caption><b>Table 3. Storage of multiple component image data.</b></caption> + +<tr> +<td><b>Interlace Mode</b></td> + +<td><b>Dimensions in the Dataspace</b></td> +</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> + +<p>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]. +<p>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. +<p><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. +<p>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. +<br> <h2> -2. HDF5 Palette Specification</h2> +<a NAME="sect2"></a>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 +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 +<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 , +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 +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 @@ -417,13 +802,27 @@ may be specified as a color model attribute of the palette dataset. <i>(see <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. +<br> +<br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#666666" > +<tr> +<td><font color="#FFFFFF">Important Note: The specification of the Indexed +Palette will change substantially in the next version. The Palette +described here is <i>denigrated</i> and is not supported.</font></td> +</tr> +</table> + +<br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> <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". +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". <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 @@ -438,18 +837,24 @@ 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. +range index array attribute (100000) map to the last entry in the palette.</td> +</tr> +</table> + <h3> -2.2. Palette Attributes</h3> +<a NAME="sect2.2"></a>2.2. Palette Attributes</h3> A palette exists in an HDF file as an independent data set with accompanying -attributes. +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. <p>These attributes are defined as follows: <dl> <dt> -Attribute name="<b>CLASS</b>"</dt> +Attribute name="<b>CLASS</b>" (Required)</dt> <dd> -This attribute is of type H5T_C_S1, with size 8.</dd> +This attribute is of type H5T_C_S1, with size 7.</dd> <dd> For all palettes, the value of this attribute is "PALETTE". This attribute @@ -457,10 +862,10 @@ identifies this palette data set as a palette that conforms to the specification on this page.</dd> <dt> -Attribute name="<b>PAL_COLORMODEL</b>"</dt> +Attribute name="<b>PAL_COLORMODEL</b>" (Required)</dt> <dd> -This attribute is of type H5T_C_S1, with size 4, 5, or 6.</dd> +This attribute is of type H5T_C_S1, with size 3, 4, or 5.</dd> <dd> Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".</dd> @@ -520,30 +925,53 @@ 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> + +<dd> +</dd> </dl> <dt> -Attribute name="<b>PAL_TYPE</b>"</dt> +Attribute name="<b>PAL_TYPE</b>" (Required)</dt> + +<dd> +This attribute is of type H5T_C_S1, with size 9 or 10.</dd> <dd> -This attribute is of type H5T_C_S1, with size 10 or 11.</dd> +The current supported values for this attribute are : "STANDARD8" or "RANGEINDEX"</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 +<dd> +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. +indexes into the palette.</dd> +</dl> + +<dl> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> <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) +for more details)</td> +</tr> +</table> + +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td> <dt> -Attribute name="<b>PAL_RANGEINDEX</b>"</dt> +Attribute name="<b>PAL_RANGEINDEX</b>" <i>(Denigrated)</i></dt> +<dl> <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> +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> +</td> +</tr> +</table> <dt> Attribute name="<b>PAL_MINMAXNUMERIC</b>"</dt> @@ -558,22 +986,25 @@ 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>" +Attribute name="<b>PAL_VERSION</b>" (Required) <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> +number of this specification to which it conforms. The current version +is "1.2".</dl> <center><table BORDER=2 BGCOLOR="#FFFFFF" > -<caption><b>Attributes of a Palette Dataset</b></caption> +<caption><b>Table 4. Attributes of a Palette Dataset</b></caption> <tr> <td><b>Attribute Name</b></td> -<td></td> +<td><b>(R = Required,</b> +<br><b>O = Optional)</b></td> <td><b>Type</b></td> +<td><b>String Size</b></td> + <td><b>Value</b></td> </tr> @@ -584,6 +1015,10 @@ number is "1.0".</dl> <td>String</td> +<td> +<center>7</center> +</td> + <td>"PALETTE"</td> </tr> @@ -594,6 +1029,10 @@ number is "1.0".</dl> <td>String</td> +<td> +<center>3, 4, or 5</center> +</td> + <td>Color Model: "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"</td> </tr> @@ -604,18 +1043,56 @@ number is "1.0".</dl> <td>String</td> -<td>"STANDARD8" or "RANGEINDEX"</td> +<td> +<center>9</center> + +<p><br> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td>or 10</td> </tr> +</table> +</td> +<td>"STANDARD8" +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > <tr> -<td>RANGE_INDEX</td> +<td>or "RANGEINDEX" <i>(Denigrated)</i></td> +</tr> +</table> +</td> +</tr> + +<tr> +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><i>Denigrated</i> +<br>RANGE_INDEX</td> +</tr> +</table> +</td> -<td>R<sup>1</sup></td> +<td></td> +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> <td>Object Reference </td> +</tr> +</table> +</td> + +<td></td> +<td> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> <td><Object Reference to Dataset of range index values></td> </tr> +</table> +</td> +</tr> <tr> <td>PAL_MINMAXNUMERIC</td> @@ -624,6 +1101,8 @@ number is "1.0".</dl> <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> </tr> @@ -635,18 +1114,84 @@ value is <Maximum value for color values><sup>2</sup></td> <td>String</td> -<td><specification version number></td> +<td>4</td> + +<td>"1.2"</td> </tr> </table></center> -<dl><font size=-1>1. The RANGE_INDEX attribute is required if the +<dl> +<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" > +<tr> +<td><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. +be omitted. (Range index is denigrated.)</font></td> +</tr> +</table> +<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> +of the minimum must be less than or equal to the value of the maximum.</font></dl> </dl> +Table 5 summarized the uses of the standard attributes for a palette dataset. +R means that the attribute listed on the leftmost column is Required for +the palette type on the first row, O means that the attribute is Optional +for that type and N 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. +<br> +<br> +<table BORDER WIDTH="100%" > +<caption><b>Table 5. Applicability of Attributes</b></caption> + +<tr> +<td WIDTH="33%"><b>PAL_TYPE</b></td> + +<td WIDTH="33%"><b>STANDARD8</b></td> + +<td WIDTH="34%"><b>RANGEINDEX</b></td> +</tr> + +<tr> +<td WIDTH="33%">CLASS</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_VERSION</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_COLORMODEL</td> + +<td WIDTH="33%">R</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">RANGE_INDEX</td> + +<td WIDTH="33%">N</td> + +<td WIDTH="34%">R</td> +</tr> + +<tr> +<td WIDTH="33%">PAL_MINMAXNUMERIC</td> + +<td WIDTH="33%">O</td> + +<td WIDTH="34%">O</td> +</tr> +</table> <h3> 2.3. Storage Layout for Palettes</h3> @@ -657,18 +1202,19 @@ 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> +<a NAME="Sect3"></a>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>. +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. +<p>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 @@ -677,55 +1223,36 @@ 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. +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> -<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> - <!-- +<center><table BORDER=0 WIDTH="98%" > +<tr> +<td ALIGN=LEFT VALIGN=TOP><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> - + --></td> +<td ALIGN=RIGHT VALIGN=TOP> +<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> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a></address> +<br> <!-- Created: Spring 1999 --> <!-- hhmts start --> -Last modified: 2 June 2000 +Last modified: 3 July 2001 <!-- hhmts end --> <br> Describes HDF5 Release 1.5, Unreleased Development Branch - - - </body> +</body> </html> |