HDF5 Image Interface, H5IM

HDF5 documents and links Introduction to HDF5 HDF5 User’s Guide Other High-level API documents | In the HDF5 Reference Manual H5DS H5IM H5LT H5PT H5TB Optimized H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5PL H5R H5S H5T H5Z Tools Datatypes Fortran

# H5IM: HDF5 Image

## HDF5 Image API Reference

The HDF5 Image API defines a standard storage for HDF5 datasets that are intended to be interpreted as images. The specification for this API is presented in another document: HDF5 Image and Palette Specification. This version of the API is primarily concerned with two dimensional raster data similar to HDF4 Raster Images. The HDF5 image API uses the Lite HDF5 API.

The following functions are part of the HDF5 Image API version 1.0.

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 Image package, H5IM, in C applications:
`#include "hdf5_hl.h"`

This line includes the H5IM module in Fortran applications:
`use h5im`

The C Interfaces:

Image functions H5IMmake_image_8bit H5IMmake_image_24bit H5IMget_image_info H5IMread_image H5IMis_image | Palette functions H5IMmake_palette H5IMlink_palette H5IMunlink_palette H5IMget_npalettes H5IMget_palette_info H5IMget_palette H5IMis_palette

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function.

Image functions h5immake_image_8bit_f h5immake_image_24bit_f h5imget_image_info_f h5imread_image_f h5imis_image_f | Palette functions h5immake_palette_f h5imlink_palette_f h5imunlink_palette_f h5imget_npalettes_f h5imget_palette_info_f h5imget_palette_f h5imis_palette_f

Name: H5IMmake_image_8bit
Signature:
  herr_t H5IMmake_image_8bit ( hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const unsigned char *buffer)
Purpose:
  Creates and writes an image.
Description:
  `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.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group to create the dataset within.
const char *`dset_name` | IN: The name of the dataset to create.
hsize_t width | IN: The width of the image.
hsize_t height | IN: The height of the image.
const unsigned char *`buffer` | IN: Buffer with data to be written to the dataset.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5immake_image_8bit_f

      subroutine h5immake_image_8bit_f(loc_id, dset_name, width, height, buf, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id           ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name      ! name of the dataset
        integer(HSIZE_T), intent(IN) :: width          ! width of image
        integer(HSIZE_T), intent(IN) :: height         ! height of image
        integer*1, intent(IN), dimension(*) :: buf     ! 1 byte integer data buffer
        integer :: errcode                             ! error code
      end subroutine h5immake_image_8bit_f

Name: H5IMmake_image_24bit
Signature:
  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)
Purpose:
  Creates and writes a true color image.
Description:
  `H5Lmake_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.

Parameters:

hid_t `loc_id` | IN: Identifier of the file or group to create the dataset within.
const char *`dset_name` | IN: The name of the dataset to create.
hsize_t width | IN: The width of the image.
hsize_t height | IN: The height of the image.
const char * `interlace` | IN: String defining the interlace mode.
const unsigned char * `buffer` | IN: Buffer with data to be written to the dataset.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5immake_image_24bit_f

      subroutine h5immake_image_24bit_f(loc_id, dset_name, width, height, il, &
                                        buf, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id         ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name    ! name of the dataset
        integer(HSIZE_T), intent(IN) :: width        ! width of image
        integer(HSIZE_T), intent(IN) :: height       ! height of image
        character(LEN=*), intent(IN) :: il           ! interlace
        integer*1, intent(IN), dimension(*) :: buf   ! 1 byte integer data buffer
        integer :: errcode                           ! error code
      end subroutine h5immake_image_24bit_f

Name: H5IMget_image_info
Signature:
  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)
Purpose:
  Gets information about an image dataset (dimensions, interlace mode and number of associated palettes).
Description:
  `H5IMget_image_info` gets information about an image named `dset_name` attached to the file or group specified by the identifier `loc_id`. .
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the dataset is located.
const char *`dset_name` | IN: The name of the dataset.
hsize_t * `width` | OUT: The width of the image.
hsize_t * `height` | OUT: The height of the image.
hsize_t * `planes` | OUT: The number of color planes of the image.
char * `interlace` | OUT: The interlace mode of the image.
hssize_t * `npals` | OUT: The number of palettes associated to the image.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imget_image_info_f

      subroutine h5imget_image_info_f(loc_id, dset_name, width, height, planes, &
                                      interlace, npals, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id            ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name       ! name of the dataset
        integer(HSIZE_T), intent(INOUT) :: width        ! width of image
        integer(HSIZE_T), intent(INOUT) :: height       ! height of image
        integer(HSIZE_T), intent(INOUT) :: planes       ! color planes
        integer(HSIZE_T), intent(INOUT) :: npals        ! palettes
        character(LEN=*), intent(INOUT) :: interlace    ! interlace
        integer :: errcode                              ! error code
      end subroutine h5imget_image_info_f

Name: H5IMread_image
Signature:
  herr_t H5IMread_image ( hid_t loc_id, const char *dset_name, unsigned char *buffer )
Purpose:
  Reads image data from disk.
Description:
  `H5IMread_image` reads a dataset named `dset_name` attached to the file or group specified by the identifier `loc_id`.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group to read the dataset from.
const char *`dset_name` | IN: The name of the dataset.
unsigned char *`buffer` | OUT: Buffer with data to store the image.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imread_image_f

      subroutine h5imread_image_f(loc_id, dset_name, buf, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id             ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name        ! name of the dataset
        integer*1, intent(INOUT), dimension(*) :: buf    ! 1 byte integer data buffer
        integer :: errcode                               ! error code
      end subroutine h5imread_image_f

Name: H5IMis_image
Signature:
  herr_t H5IMis_image ( hid_t loc_id, const char *dset_name )
Purpose:
  Inquires if a dataset is an image.
Description:
  `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.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the dataset is located.
const char *`dset_name` | IN: The name of the dataset.

Returns:
  Returns true, false, fail.
Fortran90 Interface: h5imis_image_f

      integer function h5imis_image_f(loc_id, dset_name)
        implicit none
        integer(HID_T), intent(IN) :: loc_id         ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name    ! name of the dataset
        integer :: errcode                           ! error code
      end function h5imis_image_f

Name: H5IMmake_palette
Signature:
  herr_t H5IMmake_palette( hid_t loc_id, const char *pal_name, const hsize_t *pal_dims, const unsigned char *pal_data )
Purpose:
  Creates and writes a palette.
Description:
  `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.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group to create the dataset within.
const char *`pal_name` | IN: The name of the palette.
const hsize_t * `pal_dims` | IN: An array of the size of the palette dimensions.
const unsigned char *`pal_data` | IN: Buffer with data to be written to the dataset.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5immake_palette_f

      subroutine h5immake_palette_f(loc_id, dset_name, pal_dims, buf, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id           ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name      ! name of the dataset
        integer(HSIZE_T), intent(IN), dimension(*) :: pal_dims
                                                       ! dimensions
        integer*1, intent(IN), dimension(*) :: buf     ! 1 byte integer data buffer
        integer :: errcode                             ! error code
      end subroutine h5immake_palette_f

Name: H5IMlink_palette
Signature:
  herr_t H5IMlink_palette( hid_t loc_id, const char *image_name, const char *pal_name)
Purpose:
  Attaches a palette to an image.
Description:
  `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.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group.
const char *`image_name` | IN: The name of the dataset to attach the palette to.
const char *`pal_name` | IN: The name of the palette.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imlink_palette_f

      subroutine h5imlink_palette_f(loc_id, dset_name, pal_name, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id          ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name     ! name of the dataset
        character(LEN=*), intent(IN) :: pal_name      ! palette name
        integer :: errcode                            ! error code
      end subroutine h5imlink_palette_f

Name: H5IMunlink_palette
Signature:
  herr_t H5IMunlink_palette( hid_t loc_id, const char *image_name, const char *pal_name )
Purpose:
  Dettaches a palette from an image.
Description:
  `H5IMunlink_palette` dettaches a palette from an image specified by `image_name`.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group.
const char *`image_name` | IN: The name of the image dataset.
const char *`pal_name` | IN: The name of the palette.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imunlink_palette_f

      subroutine h5imunlink_palette_f(loc_id, dset_name, pal_name, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id          ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name     ! name of the dataset
        character(LEN=*), intent(IN) :: pal_name      ! palette name
        integer :: errcode                            ! error code
      end subroutine h5imunlink_palette_f

Name: H5IMget_npalettes
Signature:
  herr_t H5IMget_npalettes( hid_t loc_id, const char *image_name, hssize_t *npals )
Purpose:
  Gets the number of palettes associated to an image.
Description:
  `H5IMget_npalettes` gets the number of palettes associated to an image specified by `image_name`.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the image dataset is located.
const char *`image_name` | IN: The name of the image dataset.
hssize_t *`npals` | OUT: The number of palettes.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imget_npalettes_f

      subroutine h5imget_npalettes_f(loc_id, dset_name, npals, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id          ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name     ! name of the dataset
        integer(HSIZE_T), intent(INOUT) :: npals      ! palettes
        integer :: errcode                            ! error code
      end subroutine h5imget_npalettes_f

Name: H5IMget_palette_info
Signature:
  herr_t H5IMget_palette_info( hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims )
Purpose:
  Gets information about a palette dataset (dimensions).
Description:
  `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`.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the image dataset is located.
const char *`image_name` | IN: The name of the image dataset.
int `pal_number` | IN: The zero based index that identifies the palette.
hsize_t *`pal_dims` | OUT: The dimensions of the palette dataset.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imget_palette_info_f

      subroutine h5imget_palette_info_f(loc_id, dset_name, pal_number, dims, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id            ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name       ! name of the dataset
        integer, intent(IN) :: pal_number               ! palette number
        integer(HSIZE_T), dimension(*), intent(INOUT) :: dims
                                                        ! dimensions
        integer :: errcode                              ! error code
      end subroutine h5imget_palette_info_f

Name: H5IMget_palette
Signature:
  herr_t H5IMget_palette( hid_t loc_id, const char *image_name, int pal_number, unsigned char *pal_data )
Purpose:
  Gets the palette dataset.
Description:
  `H5IMget_palette` gets the palette dataset identified by `pal_number` (a zero based index) associated to an image specified by `image_name`.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the image dataset is located.
const char *`image_name` | IN: The name of the image dataset.
int `pal_number` | IN: The zero based index that identifies the palette.
unsigned char *`pal_data` | OUT: The palette dataset.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5imget_palette_f

      subroutine h5imget_palette_f(loc_id, dset_name, pal_number, buf, errcode)
        implicit none
        integer(HID_T), intent(IN) :: loc_id            ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name       ! name of the dataset
        integer, intent(IN) :: pal_number               ! palette number
        integer*1, intent(INOUT), dimension(*) :: buf   ! 1 byte integer data buffer
        integer :: errcode                              ! error code
      end subroutine h5imget_palette_f

Name: H5IMis_palette
Signature:
  herr_t H5IMis_palette ( hid_t loc_id, const char *dset_name )
Purpose:
  Inquires if a dataset is a palette.
Description:
  `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.
Parameters:

hid_t `loc_id` | IN: Identifier of the file or group in which the dataset is located.
const char *`dset_name` | IN: The name of the dataset.

Returns:
  Returns true, false, fail.
Fortran90 Interface: h5imis_palette_f

      integer function h5imis_palette_f(loc_id, dset_name)
        implicit none
        integer(HID_T), intent(IN) :: loc_id         ! file or group identifier
        character(LEN=*), intent(IN) :: dset_name    ! name of the dataset
        integer :: errcode                           ! error code
      end function h5imis_palette_f

HDF5 documents and links Introduction to HDF5 HDF5 User’s Guide Other High-level API documents | In the HDF5 Reference Manual H5DS H5IM H5LT H5PT H5TB Optimized H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5PL H5R H5S H5T H5Z Tools Datatypes Fortran