summaryrefslogtreecommitdiffstats
path: root/hl/src/H5IMpublic.h
blob: bccf3c4eed68ff96f62df43e4829f767b669b963 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * 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