H5IM: Image functions
HDF5 Image API Reference
The HDF5 Image API defines a standard
storage for HDF5 datasets that are indented 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. Currently
we only provide a C interface for the library.
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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
HDF Help Desk
Last modified: November 14, 2002