Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-07-28 The HDF5 Field Guide

Loading...
Searching...
No Matches
HDF5 Images API (H5IM)

## Detailed Description

Creating and manipulating HDF5 datasets intended to be interpreted as images (H5IM)

The specification for the Images API is presented in another document: HDF5 Image and Palette Specification Version 1.2 This version of the API is primarily concerned with two dimensional raster data similar to HDF4 Raster Images. The HDF5 Images API uses the HDF5 Lite APIs (H5LT,H5LD).

Note
  Programming hints:
  To use any of these functions or subroutines, you must first include the relevant include file (C) or module (Fortran) in your application.
  The following line includes the HDF5 Images package, H5IM, in C applications:
  #include "hdf5_hl.h"
  This line includes the H5IM module in Fortran applications:
  use h5im
  h5im
  This module contains Fortran interfaces for H5IM.
  Definition H5IMff.F90:35

- H5IMget_image_info
  Gets information about an image dataset (dimensions, interlace mode and number of associated palettes).
- H5IMget_npalettes
  Gets the number of palettes associated to an image.
- H5IMget_palette
  Gets the palette dataset.
- H5IMget_palette_info
  Gets information about a palette dataset (dimensions).
- H5IMis_image
  Inquires if a dataset is an image
- H5IMis_palette
  Inquires if a dataset is a palette.
- H5IMlink_palette
  Attaches a palette to an image.
- H5IMmake_image_8bit
  Creates and writes an image.
- H5IMmake_image_24bit
  Creates and writes a true color image.
- H5IMmake_palette
  Creates and writes a palette.
- H5IMread_image
  Reads image data from disk.
- H5IMunlink_palette
  Detaches a palette from an image.

## Functions
H5HL_DLL herr_t | H5IMget_image_info (hid_t loc_id, const char *dset_name, hsize_t *width, hsize_t *height, hsize_t *planes, char *interlace, hssize_t *npals)
| Gets information about an image dataset (dimensions, interlace mode and number of associated palettes).
H5HL_DLL herr_t | H5IMget_npalettes (hid_t loc_id, const char *image_name, hssize_t *npals)
| Gets the number of palettes associated to an image.
H5HL_DLL herr_t | H5IMget_palette (hid_t loc_id, const char *image_name, int pal_number, unsigned char *pal_data)
| Gets the palette dataset.
H5HL_DLL herr_t | H5IMget_palette_info (hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims)
| Gets information about a palette dataset (dimensions).
H5HL_DLL herr_t | H5IMis_image (hid_t loc_id, const char *dset_name)
| Inquires if a dataset is an image.
H5HL_DLL herr_t | H5IMis_palette (hid_t loc_id, const char *dset_name)
| Inquires if a dataset is a palette.
H5HL_DLL herr_t | H5IMlink_palette (hid_t loc_id, const char *image_name, const char *pal_name)
| Attaches a palette to an image.
H5HL_DLL herr_t | H5IMmake_image_24bit (hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const char *interlace, const unsigned char *buffer)
| Creates and writes a true color image.
H5HL_DLL herr_t | H5IMmake_image_8bit (hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const unsigned char *buffer)
| Creates and writes an image.
H5HL_DLL herr_t | H5IMmake_palette (hid_t loc_id, const char *pal_name, const hsize_t *pal_dims, const unsigned char *pal_data)
| Creates and writes a palette.
H5HL_DLL herr_t | H5IMread_image (hid_t loc_id, const char *dset_name, unsigned char *buffer)
| Reads image data from disk.
H5HL_DLL herr_t | H5IMunlink_palette (hid_t loc_id, const char *image_name, const char *pal_name)
| Detaches a palette from an image.

## Function Documentation

## ◆ H5IMget_image_info()

H5HL_DLL herr_t H5IMget_image_info | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | hsize_t * | width,
|  | hsize_t * | height,
|  | hsize_t * | planes,
|  | char * | interlace,
|  | hssize_t * | npals )

Gets information about an image dataset (dimensions, interlace mode and number of associated palettes).

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset
  [out] | width | The width of the image
  [out] | height | The height of the image
  [out] | planes | The number of color planes of the image
  [out] | interlace | The interlace mode of the image
  [out] | npals | The number of palettes associated to the image

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMget_image_info() gets information about an image named `dset_name` attached to the file or group specified by the identifier `loc_id`.

## ◆ H5IMget_npalettes()

H5HL_DLL herr_t H5IMget_npalettes | ( | hid_t | loc_id,
|  | const char * | image_name,
|  | hssize_t * | npals )

Gets the number of palettes associated to an image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | image_name | The name of the image dataset
  [out] | npals | The number of palettes

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMget_npalettes() gets the number of palettes associated to an image specified by `image_name`.

## ◆ H5IMget_palette()

H5HL_DLL herr_t H5IMget_palette | ( | hid_t | loc_id,
|  | const char * | image_name,
|  | int | pal_number,
|  | unsigned char * | pal_data )

Gets the palette dataset.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | image_name | The name of the image dataset
  [in] | pal_number | The zero based index that identifies the palette
  [out] | pal_data | The palette dataset

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMget_palette() gets the palette dataset identified by `pal_number` (a zero based index) associated to an image specified by `image_name`.

## ◆ H5IMget_palette_info()

H5HL_DLL herr_t H5IMget_palette_info | ( | hid_t | loc_id,
|  | const char * | image_name,
|  | int | pal_number,
|  | hsize_t * | pal_dims )

Gets information about a palette dataset (dimensions).

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | image_name | The name of the image dataset
  [in] | pal_number | The zero based index that identifies the palette
  [out] | pal_dims | The dimensions of the palette dataset

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMget_palette_info() gets the dimensions of the palette dataset identified by `pal_number` (a zero based index) associated to an image specified by `image_name`.

## ◆ H5IMis_image()

H5HL_DLL herr_t H5IMis_image | ( | hid_t | loc_id,
|  | const char * | dset_name )

Inquires if a dataset is an image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5IMis_image() inquires if a dataset named `dset_name`, attached to the file or group specified by the identifier `loc_id`, is an image based on the HDF5 Image and Palette Specification.

## ◆ H5IMis_palette()

H5HL_DLL herr_t H5IMis_palette | ( | hid_t | loc_id,
|  | const char * | dset_name )

Inquires if a dataset is a palette.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5IMis_palette() inquires if a dataset named `dset_name`, attached to the file or group specified by the identifier `loc_id`, is a palette based on the HDF5 Image and Palette Specification.

## ◆ H5IMlink_palette()

H5HL_DLL herr_t H5IMlink_palette | ( | hid_t | loc_id,
|  | const char * | image_name,
|  | const char * | pal_name )

Attaches a palette to an image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | image_name | The name of the dataset to attach the palette to
  [in] | pal_name | The name of the palette

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMlink_palette() attaches a palette named `pal_name` to an image specified by `image_name`. The image dataset may or not already have an attached palette. If it has, the array of palette references is extended to hold the reference to the new palette.

## ◆ H5IMmake_image_24bit()

H5HL_DLL herr_t H5IMmake_image_24bit | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | hsize_t | width,
|  | hsize_t | height,
|  | const char * | interlace,
|  | const unsigned char * | buffer )

Creates and writes a true color image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset to create
  [in] | width | The width of the image
  [in] | height | The height of the image
  [in] | interlace | String defining the interlace mode
  [in] | buffer | Buffer with data to be written to the dataset

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMmake_image_24bit() creates and writes a dataset named `dset_name` attached to the file or group specified by the identifier `loc_id`. This function defines a true color image conforming to the HDF5 Image and Palette specification. The function assumes that the image data is of the type H5T_NATIVE_UCHAR.

A true color image is an image where the pixel storage contains several color planes. In a 24 bit RGB color model, these planes are red, green and blue. In a true color image the stream of bytes can be stored in several different ways, thus defining the interlace (or interleaving) mode. The 2 most used types of interlace mode are interlace by pixel and interlace by plane. In the 24 bit RGB color model example, interlace by plane means all the red components for the entire dataset are stored first, followed by all the green components, and then by all the blue components. Interlace by pixel in this example means that for each pixel the sequence red, green, blue is defined. In this function, the interlace mode is defined in the parameter `interlace`, a string that can have the values INTERLACE_PIXEL or INTERLACE_PLANE.

## ◆ H5IMmake_image_8bit()

H5HL_DLL herr_t H5IMmake_image_8bit | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | hsize_t | width,
|  | hsize_t | height,
|  | const unsigned char * | buffer )

Creates and writes an image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset to create
  [in] | width | The width of the image
  [in] | height | The height of the image
  [in] | buffer | Buffer with data to be written to the dataset

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMmake_image_8bit() creates and writes a dataset named `dset_name` attached to the file or group specified by the identifier `loc_id`. Attributes conforming to the HDF5 Image and Palette specification for an indexed image are attached to the dataset, thus identifying it as an image. The image data is of the type H5T_NATIVE_UCHAR. An indexed image is an image in which each each pixel information storage is an index to a table palette.

## ◆ H5IMmake_palette()

H5HL_DLL herr_t H5IMmake_palette | ( | hid_t | loc_id,
|  | const char * | pal_name,
|  | const hsize_t * | pal_dims,
|  | const unsigned char * | pal_data )

Creates and writes a palette.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | pal_name | The name of the palette
  [in] | pal_dims | An array of the size of the palette dimensions
  [in] | pal_data | Buffer with data to be written to the dataset

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMmake_palette() creates and writes a dataset named `pal_name`. Attributes conforming to the HDF5 Image and Palette specification are attached to the dataset, thus identifying it as a palette. The palette data is of the type H5T_NATIVE_UCHAR.

## ◆ H5IMread_image()

H5HL_DLL herr_t H5IMread_image | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | unsigned char * | buffer )

Reads image data from disk.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset to create
  [out] | buffer | Buffer with data to store the image

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMread_image() reads a dataset named `dset_name` attached to the file or group specified by the identifier `loc_id`.

## ◆ H5IMunlink_palette()

H5HL_DLL herr_t H5IMunlink_palette | ( | hid_t | loc_id,
|  | const char * | image_name,
|  | const char * | pal_name )

Detaches a palette from an image.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | image_name | The name of the image dataset
  [in] | pal_name | The name of the palette

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5IMunlink_palette() detaches a palette from an image specified by `image_name`.