[ HDF5 High Level Tutorial Top ] [ Next ] [ Prev ]

H5IM: HDF5 Image
Images

The HDF5 Image API defines a standard storage for HDF5 datasets that are indented to be interpreted as images. This version of the API is primarily concerned with two dimensional raster data similar to HDF4 Raster Images, which are indexed 8 bit images (an image in which each each pixel information storage is an index to a table palette), and 24 bit true color images (an image where the pixel storage contains 3 color planes, red , green , blue, in this case)

Writing indexed images and palettes

To write a HDF5 indexed images we use the H5IMmake_image_8bit function

H5IMmake_image_8bit( file_id, "Image1", width, height, data );

This function accepts a parameter file_id, obtained with the basic HDF5 library function H5Fcreate, a dataset name, the width and height of the dataset, and the data. This function is most useful when associated with a palette

The following table represents a palette with 9 entries

Index RGB components Color representation
0 0, 0, 168
1 0, 0, 252
2 0, 168, 252
3 84, 252, 252
4 168, 252, 168
5 0, 252, 168
6 252, 252, 84
7 252, 168, 0
8 252, 0, 0

 To create an HDF5 palette we use the H5IMmake_palette function

H5IMmake_palette( file_id, "Pallete", pal_dims, pal );

This function accepts a parameter file_id, obtained with the basic HDF5 library function H5Fcreate, a palette name, the dimensions of the palette, and the palette data. To associate a palette to any given image we use the function H5IMlink_palette

H5IMlink_palette( file_id, "Image1", "Pallete" );

This call associates the previously written "Image1" with the palette "Pallete".

Programming Example

The following example demonstrates how to create an indexed HDF5 image with an associated palette. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser that handles HDF5 images to access this file by clicking on the link below.

NOTE: To download a tar file of all of the examples, including a Makefile, please go to the Index page. The output image generated by this example is 

Writing true color images

To write an HDF5 true color image we use the H5IMmake_image_24bit function

H5IMmake_image_24bit( file_id, "Image1", width, height, interlace, data );

This function accepts a parameter file_id, obtained with the basic HDF5 library function H5Fcreate, a dataset name, the width and height of the dataset, a string with the interlace mode and the data.

Reading  images

To read an HDF5 image we use the H5IMread_image function

H5IMread_image( file_id, "Image1", data );

This function accepts a parameter file_id, obtained with the basic HDF5 library function H5Fopen, a dataset name, and the data. To obtain information about the image (for example to know the size of the buffer to allocate the image data), the H5IMget_image_info function is used

H5IMget_image_info( file_id, "Image1", &width, &height, &planes, interlace, &npals );

This function accepts a parameter file_id, obtained with the basic HDF5 library function H5Fopen, a dataset name, and returns the width and height of the dataset, , the number of color planes, the interlace mode, and the number of palettes. 


HDF Help Desk
Last modified: November 18, 2002