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

 

Palette functions

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

Image functions

 

Palette functions

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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  

The HDF Group Help Desk:
Describes HDF5 Release 1.10.
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois