I was corresponding with Debbie Mao (NCAR) yesterday about how to write an image with a palette to an HDF5 file, when I realized I was doing it wrong. Here’s an example of a more correct way to do this, by attaching the palette as an attribute to the image.

Start by reading an image from the IDL distro:

infile = file_which('avhrr.png')
image = read_png(infile, r, g, b)
palette = transpose([[r],[g],[b]])

I want to save image and palette to an HDF5 file. Create an HDF5 file with:

file = 'image_and_palette_example.h5'
fid = h5f_create(file)

For convenience, create a group to hold the image and its palette:

group_id = h5g_create(fid, 'AVHRR image')

Next, define HDF5 datatypes and dataspaces for these two variables:

image_datatype_id = h5t_idl_create(image)
palette_datatype_id = h5t_idl_create(palette)
image_dataspace_id = h5s_create_simple(size(image, /dimensions))
palette_dataspace_id = h5s_create_simple(size(palette, /dimensions))

(Hopefully my verbose variable names are descriptive.) Now create datasets for image and palette and write them to the HDF5 file:

image_id = h5d_create(group_id, 'image data', image_datatype_id, image_dataspace_id)
palette_id = h5d_create(group_id, 'image palette', palette_datatype_id, palette_dataspace_id)
h5d_write, image_id, reverse(image,2)
h5d_write, palette_id, palette

I’ve chosen to flip the image (like using the ORDER keyword) so it previews nicely in the HDF5 file. The drawback of this choice is that the image will need to be flipped again when it’s read into IDL.

The datatype and dataspace identifiers are no longer needed, so close them:

h5s_close, image_dataspace_id
h5t_close, image_datatype_id
h5s_close, palette_dataspace_id
h5t_close, palette_datatype_id

Now comes the interesting part: we need to associate the palette with the image so it displays properly in HDFView and H5_BROWSER. The steps for doing this aren’t covered well in the IDL docs, but they are described in the HDF5 developer docs. (Aside: the IDL docs provide only a high-level overview of HDF5, HDF4 and HDF-EOS. I’ve always gone back to the documentation provided by The HDF Group (THG) for more detailed information on using these formats. The IDL API is very similar to the C API provided by THG, so it’s pretty straightforward to translate THG’s docs to IDL.)

Start by assigning the attribute “CLASS = PALETTE” to the image’s palette:

attribute_name = 'CLASS'
attribute_data = 'PALETTE'
attribute_datatype_id = h5t_idl_create(attribute_data)
attribute_dataspace_id = h5s_create_scalar()
attribute_id = h5a_create(palette_id, attribute_name, attribute_datatype_id, attribute_dataspace_id)
h5a_write, attribute_id, attribute_data
h5a_close, attribute_id

Next, assign the attribute “CLASS = IMAGE” to the image:

attribute_name = 'CLASS'
attribute_data = 'IMAGE'
attribute_datatype_id = h5t_idl_create(attribute_data)
attribute_dataspace_id = h5s_create_scalar()
attribute_id = h5a_create(image_id, attribute_name, attribute_datatype_id, attribute_dataspace_id)
h5a_write, attribute_id, attribute_data
h5a_close, attribute_id

Finally (and this is key), assign a reference to the palette as an attribute to the image, like this:

attribute_name = 'PALETTE'
attribute_data = h5r_create(group_id, 'image palette')
attribute_datatype_id = h5t_reference_create()
attribute_dataspace_id = h5s_create_scalar()
attribute_id = h5a_create(image_id, attribute_name, attribute_datatype_id, attribute_dataspace_id)
h5a_write, attribute_id, attribute_data
h5a_close, attribute_id

There are other HDF5 attributes that could be assigned to the image and to the palette (see the reference above), but I’m using the minimum number of attributes needed to make this work.

End by closing any open identifiers:

h5d_close, image_id
h5d_close, palette_id
h5g_close, group_id
h5f_close, fid

The code I’ve used is in hdf5_write_ex.pro; download it and run it:

IDL> hdf5_write_ex

The program produces an HDF5 file named image_and_palette_example.h5. Here’s a screenshot of the file displayed in HDFView:

Note how the palette is correctly associated with the image.