You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
350 lines
12 KiB
C
350 lines
12 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* Copyright by The HDF Group. *
|
|
* All rights reserved. *
|
|
* *
|
|
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
|
* terms governing use, modification, and redistribution, is contained in *
|
|
* the COPYING file, which can be found at the root of the source code *
|
|
* distribution tree, or in https://www.hdfgroup.org/licenses. *
|
|
* If you do not have access to either file, you may request a copy from *
|
|
* help@hdfgroup.org. *
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
|
|
#ifndef H5IMpublic_H
|
|
#define H5IMpublic_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \page H5IM_UG The HDF5 High Level Images
|
|
* @todo Under Construction
|
|
*/
|
|
|
|
/**\defgroup H5IM HDF5 Images API (H5IM)
|
|
*
|
|
* <em>Creating and manipulating HDF5 datasets intended to be
|
|
* interpreted as images (H5IM)</em>
|
|
*
|
|
* The specification for the Images API is presented in another
|
|
* document: \ref IMG
|
|
* This version of the API is primarily concerned with two dimensional raster
|
|
* data similar to HDF4 Raster Images.
|
|
* The HDF5 Images API uses the \ref H5LT.
|
|
*
|
|
* \note \Bold{Programming hints:}
|
|
* \note To use any of these functions or subroutines,
|
|
* you must first include the relevant include file (C) or
|
|
* module (Fortran) in your application.
|
|
* \note The following line includes the HDF5 Images package, H5IM,
|
|
* in C applications:
|
|
* \code #include "hdf5_hl.h" \endcode
|
|
* \note This line includes the H5IM module in Fortran applications:
|
|
* \code use h5im \endcode
|
|
*
|
|
* - \ref H5IMget_image_info
|
|
* \n Gets information about an image dataset (dimensions,
|
|
* interlace mode and number of associated palettes).
|
|
* - \ref H5IMget_npalettes
|
|
* \n Gets the number of palettes associated to an image.
|
|
* - \ref H5IMget_palette
|
|
* \n Gets the palette dataset.
|
|
* - \ref H5IMget_palette_info
|
|
* \n Gets information about a palette dataset (dimensions).
|
|
* - \ref H5IMis_image
|
|
* \n Inquires if a dataset is an image
|
|
* - \ref H5IMis_palette
|
|
* \n Inquires if a dataset is a palette.
|
|
* - \ref H5IMlink_palette
|
|
* \n Attaches a palette to an image.
|
|
* - \ref H5IMmake_image_8bit
|
|
* \n Creates and writes an image.
|
|
* - \ref H5IMmake_image_24bit
|
|
* \n Creates and writes a true color image.
|
|
* - \ref H5IMmake_palette
|
|
* \n Creates and writes a palette.
|
|
* - \ref H5IMread_image
|
|
* \n Reads image data from disk.
|
|
* - \ref H5IMunlink_palette
|
|
* \n Dettaches a palette from an image.
|
|
*
|
|
*/
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Creates and writes an image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset to create
|
|
* \param[in] width The width of the image
|
|
* \param[in] height The height of the image
|
|
* \param[in] buffer Buffer with data to be written to the dataset
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMmake_image_8bit() creates and writes a dataset named
|
|
* \p dset_name attached to the file or group specified by the
|
|
* identifier \p 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.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMmake_image_8bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height,
|
|
const unsigned char *buffer);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Creates and writes a true color image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset to create
|
|
* \param[in] width The width of the image
|
|
* \param[in] height The height of the image
|
|
* \param[in] interlace String defining the interlace mode
|
|
* \param[in] buffer Buffer with data to be written to the dataset
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMmake_image_24bit() creates and writes a dataset named
|
|
* \p dset_name attached to the file or group specified by the
|
|
* identifier \p 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
|
|
* \p interlace, a string that can have the values INTERLACE_PIXEL
|
|
* or INTERLACE_PLANE.
|
|
*
|
|
*/
|
|
H5_HLDLL 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);
|
|
|
|
/**
|
|
*-------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Gets information about an image dataset
|
|
* (dimensions, interlace mode and number of associated palettes).
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset
|
|
* \param[out] width The width of the image
|
|
* \param[out] height The height of the image
|
|
* \param[out] planes The number of color planes of the image
|
|
* \param[out] interlace The interlace mode of the image
|
|
* \param[out] npals The number of palettes associated to the image
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMget_image_info() gets information about an image
|
|
* named \p dset_name attached to the file or group specified
|
|
* by the identifier \p loc_id.
|
|
*
|
|
*/
|
|
H5_HLDLL 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);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Reads image data from disk.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset to create
|
|
* \param[out] buffer Buffer with data to store the image
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMread_image() reads a dataset named \p dset_name
|
|
* attached to the file or group specified by the
|
|
* identifier \p loc_id.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMread_image(hid_t loc_id, const char *dset_name, unsigned char *buffer);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Creates and writes a palette.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] pal_name The name of the palette
|
|
* \param[in] pal_dims An array of the size of the palette dimensions
|
|
* \param[in] pal_data Buffer with data to be written to the dataset
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMmake_palette() creates and writes a dataset
|
|
* named \p 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.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMmake_palette(hid_t loc_id, const char *pal_name, const hsize_t *pal_dims,
|
|
const unsigned char *pal_data);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Attaches a palette to an image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] image_name The name of the dataset to attach the palette to
|
|
* \param[in] pal_name The name of the palette
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMlink_palette() attaches a palette named \p pal_name
|
|
* to an image specified by \p 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.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Dettaches a palette from an image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] image_name The name of the image dataset
|
|
* \param[in] pal_name The name of the palette
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMunlink_palette() dettaches a palette from an image
|
|
* specified by \p image_name.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMunlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Gets the number of palettes associated to an image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] image_name The name of the image dataset
|
|
* \param[out] npals The number of palettes
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMget_npalettes() gets the number of palettes associated to
|
|
* an image specified by \p image_name.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMget_npalettes(hid_t loc_id, const char *image_name, hssize_t *npals);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Gets information about a palette dataset (dimensions).
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] image_name The name of the image dataset
|
|
* \param[in] pal_number The zero based index that identifies
|
|
* the palette
|
|
* \param[out] pal_dims The dimensions of the palette dataset
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMget_palette_info() gets the dimensions of the palette
|
|
* dataset identified by \p pal_number (a zero based index)
|
|
* associated to an image specified by \p image_name.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMget_palette_info(hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Gets the palette dataset.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] image_name The name of the image dataset
|
|
* \param[in] pal_number The zero based index that identifies
|
|
* the palette
|
|
* \param[out] pal_data The palette dataset
|
|
*
|
|
* \return \herr_t
|
|
*
|
|
* \details H5IMget_palette() gets the palette dataset identified
|
|
* by \p pal_number (a zero based index) associated to an
|
|
* image specified by \p image_name.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMget_palette(hid_t loc_id, const char *image_name, int pal_number,
|
|
unsigned char *pal_data);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Inquires if a dataset is an image.
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset
|
|
*
|
|
* \return \htri_t
|
|
*
|
|
* \details H5IMis_image() inquires if a dataset named \p dset_name,
|
|
* attached to the file or group specified by the identifier
|
|
* \p loc_id, is an image based on the HDF5 Image and Palette
|
|
* Specification.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMis_image(hid_t loc_id, const char *dset_name);
|
|
|
|
/**
|
|
* --------------------------------------------------------------------------
|
|
* \ingroup H5IM
|
|
*
|
|
* \brief Inquires if a dataset is a palette
|
|
*
|
|
* \fg_loc_id
|
|
* \param[in] dset_name The name of the dataset
|
|
*
|
|
* \return \htri_t
|
|
*
|
|
* \details H5IMis_palette() inquires if a dataset named \p dset_name,
|
|
* attached to the file or group specified by the
|
|
* identifier \p loc_id, is a palette based on the HDF5
|
|
* Image and Palette Specification.
|
|
*
|
|
*/
|
|
H5_HLDLL herr_t H5IMis_palette(hid_t loc_id, const char *dset_name);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|