vigra - Import/Export of Images and Arrays in HDF5 Format

[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

| Import/Export of Images and Arrays in HDF5 Format |

## Classes
class | HDF5DisableErrorOutput
| Temporarily disable HDF5's native error output. More...
class | HDF5File
| Access to HDF5 files. More...
class | HDF5Handle
| Wrapper for unique hid_t objects. More...
class | HDF5HandleShared
| Wrapper for shared hid_t objects. More...
class | HDF5ImportInfo
| Argument object for the function readHDF5(). More...

## Functions
herr_t | close ()
| Explicitly call the stored destructor (if one has been registered in the constructor) for the contained handle and set the wrapper to NULL. Returns a negative value when the destructor call for the handle fails, and a non-negative value otherwise.
herr_t | close ()
| Close the handle if this is the unique (i.e. last) owner. More...
template<int N, class T >
HDF5HandleShared | createDataset (std::string datasetName, TinyVector< MultiArrayIndex, N > const &shape, typename detail::HDF5TypeTraits< T >::value_type init=typename detail::HDF5TypeTraits< T >::value_type(), TinyVector< MultiArrayIndex, N > const &chunkSize=(TinyVector< MultiArrayIndex, N >()), int compressionParameter=0)
| Create a new dataset. This function can be used to create a dataset filled with a default value init, for example before writing data into it using writeBlock(). More...
hid_t | get () const
| Get a temporary hid_t object for the contained handle. Do not call a close function on the return value - a crash will be likely otherwise.
hid_t | get () const
| Get a temporary hid_t object for the contained handle. Do not call a close function on the return value - a crash will be likely otherwise.
| HDF5Handle ()
| Default constructor. Creates a NULL handle.
| HDF5Handle (hid_t h, Destructor destructor, const char *error_message)
| Create a wrapper for a hid_t object. More...
| HDF5Handle (HDF5Handle const &h)
| Copy constructor. More...
| HDF5HandleShared ()
| Default constructor. Creates a NULL handle.
| HDF5HandleShared (hid_t h, Destructor destructor, const char *error_message)
| Create a shared wrapper for a plain hid_t object. More...
| HDF5HandleShared (HDF5HandleShared const &h)
| Copy constructor. Shares ownership with the RHS handle (analogous to `std::shared_ptr`).
bool | isHDF5 (char const *filename)
| Check if given filename refers to a HDF5 file.
| operator hid_t () const
| Convert to a plain hid_t object. More...
| operator hid_t () const
| Convert to a plain hid_t object. More...
bool | operator!= (HDF5Handle const &h) const
| Inequality comparison of the contained handle.
bool | operator!= (hid_t h) const
| Inequality comparison of the contained handle.
bool | operator!= (HDF5HandleShared const &h) const
| Inequality comparison of the contained handle.
bool | operator!= (hid_t h) const
| Inequality comparison of the contained handle.
HDF5Handle & | operator= (HDF5Handle const &h)
| Assignment. Calls close() for the LHS handle and hands over ownership of the RHS handle (analogous to `std::unique_pt`).
HDF5HandleShared & | operator= (HDF5HandleShared const &h)
| Assignment. Call close() for the present LHS handle and share ownership with the RHS handle (analogous to `std::shared_ptr`).
bool | operator== (HDF5Handle const &h) const
| Equality comparison of the contained handle.
bool | operator== (hid_t h) const
| Equality comparison of the contained handle.
bool | operator== (HDF5HandleShared const &h) const
| Equality comparison of the contained handle.
bool | operator== (hid_t h) const
| Equality comparison of the contained handle.
template<... >
void | readHDF5 (...)
| Read the data specified by the given vigra::HDF5ImportInfo object and write the into the given 'array'. More...
hid_t | release ()
| Return the contained handle and set the wrapper to NULL without calling `close()`.
void | reset (hid_t h, Destructor destructor, const char *error_message)
| Reset the wrapper to a new handle. More...
void | reset (hid_t h, Destructor destructor, const char *error_message)
| Reset the handle to a new value. More...
void | swap (HDF5Handle &h)
| Swap the contents of two handle wrappers. More...
void | swap (HDF5HandleShared &h)
| Swap the contents of two handle wrappers. More...
bool | unique () const
| Check if this is the unique owner of the conatined handle. More...
size_t | use_count () const
| Get the number of owners of the contained handle.
template<... >
void | writeHDF5 (...)
| Store array data in an HDF5 file. More...
template<size_t N, class T , class C >
void | writeHDF5Attr (hid_t loc, const char *name, MultiArrayView< N, T, C > const &array)
template<size_t N, class C >
void | writeHDF5Attr (hid_t loc, const char *name, MultiArrayView< N, std::string, C > const &array)
template<class T >
void | writeHDF5Attr (hid_t loc, const char *name, ArrayVectorView< T > &array)
template<class Arr >
void | writeHDF5Attr (std::string filePath, std::string pathInFile, Arr &ar)
| ~HDF5Handle ()
| Destructor. Calls close() for the contained handle.
| ~HDF5HandleShared ()
| Destructor (calls close())

## Detailed Description

Supports arrays with arbitrary element types and arbitrary many dimensions. See the HDF5 Website for more information on the HDF5 file format.

## Function Documentation

HDF5Handle | ( | hid_t | h,
|  | Destructor | destructor,
|  | const char * | error_message
| ) |  |

Create a wrapper for a hid_t object.

The hid_t object h is assumed to be the return value of an open or create function. It will be closed with the given close function destructor as soon as this HDF5Handle is destructed, except when destructor is a NULL pointer (in which case nothing happens at destruction time). If h has a value that indicates failed opening or creation (by HDF5 convention, this means that h is negative), an exception is raised by calling `vigra_fail(error_message)`.

Usage:

HDF5Handle file_id(H5Fopen(filename, H5F_ACC_RDWR, H5P_DEFAULT),
&H5Fclose,
"Error message.");
... // use file_id in the same way

HDF5Handle | ( | HDF5Handle const & | h) |  |

Copy constructor.

Hands over ownership of the RHS handle (analogous to `std::unique_pt`).

void reset | ( | hid_t | h,
|  | Destructor | destructor,
|  | const char * | error_message
| ) |  |

Reset the wrapper to a new handle.

Equivalent to `handle = HDF5Handle(h, destructor, error_message)`.

void swap | ( | HDF5Handle & | h) |  |

Swap the contents of two handle wrappers.

Also available as `std::swap(handle1, handle2)`.

operator hid_t | ( | ) |  | const

Convert to a plain hid_t object.

This function ensures that hid_t objects can be transparently replaced with HDF5Handle objects in user code. Do not call a close function on the return value - a crash will be likely otherwise.

HDF5HandleShared | ( | hid_t | h,
|  | Destructor | destructor,
|  | const char * | error_message
| ) |  |

Create a shared wrapper for a plain hid_t object.

The hid_t object h is assumed to be the return value of an open or create function. It will be closed with the given close function destructor as soon as this HDF5HandleShared is destructed, except when destructor is a NULL pointer (in which case nothing happens at destruction time). If h has a value that indicates failed opening or creation (by HDF5 convention, this means that h is negative), an exception is raised by calling `vigra_fail(error_message)`.

Usage:

HDF5HandleShared file_id(H5Fopen(filename, H5F_ACC_RDWR, H5P_DEFAULT),
&H5Fclose,
"Error message.");
... // use file_id in the same way

herr_t close | ( | ) |  |

Close the handle if this is the unique (i.e. last) owner.

Decrements the reference counter and calls the destructor function of the handle (if one has been registered in the constructor) when the counter reaches zero. Sets this wrapper to NULL in any case. Returns a negative value when the destructor call for the handle fails, and a non-negative value otherwise.

void reset | ( | hid_t | h,
|  | Destructor | destructor,
|  | const char * | error_message
| ) |  |

Reset the handle to a new value.

Equivalent to `handle = HDF5HandleShared(h, destructor, error_message)`.

bool unique | ( | ) |  | const

Check if this is the unique owner of the conatined handle.

Equivalent to `handle.use_count() == 1`.

void swap | ( | HDF5HandleShared & | h) |  |

Swap the contents of two handle wrappers.

Also available as `std::swap(handle1, handle2)`.

operator hid_t | ( | ) |  | const

Convert to a plain hid_t object.

This function ensures that hid_t objects can be transparently replaced with HDF5HandleShared objects in user code. Do not call a close function on the return value - a crash will be likely otherwise.

void vigra::readHDF5 | ( |  | ...) |  |

Read the data specified by the given vigra::HDF5ImportInfo object and write the into the given 'array'.

The array must have the correct number of dimensions and shape for the dataset represented by 'info'. When the element type of 'array' differs from the stored element type, HDF5 will convert the type on the fly (except when the HDF5 version is 1.6 or below, in which case an error will result). Multi-channel element types (i.e. vigra::RGBValue, vigra::TinyVector, and vigra::FFTWComplex) are recognized and handled correctly.

Declaration:

namespace vigra {
template<unsigned int N, class T, class StrideTag>
void
readHDF5(const HDF5ImportInfo &info, MultiArrayView<N, T, StrideTag> array);
}

Usage:

#include <vigra/hdf5impex.hxx>
Namespace: vigra

HDF5ImportInfo info(filename, dataset_name);
vigra_precondition(info.numDimensions() == 3, "Dataset must be 3-dimensional.");
MultiArrayShape<3>::type shape(info.shape().begin());
MultiArray<3, int> array(shape);
readHDF5(info, array);

void vigra::writeHDF5 | ( |  | ...) |  |

Store array data in an HDF5 file.

The number of dimensions, shape and element type of the stored dataset is automatically determined from the properties of the given array. Strided arrays are stored in an unstrided way, i.e. in contiguous scan-order. Multi-channel element types (i.e. vigra::RGBValue, vigra::TinyVector and vigra::FFTWComplex) are recognized and handled correctly (in particular, the will form the innermost dimension of the stored dataset). pathInFile may contain '/'-separated group names, but must end with the name of the dataset to be created.

Declaration:

namespace vigra {
template<unsigned int N, class T, class StrideTag>
void
writeHDF5(const char* filePath, const char* pathInFile,
MultiArrayView<N, T, StrideTag>const & array);
}

Usage:

#include <vigra/hdf5impex.hxx>
Namespace: vigra

MultiArrayShape<3>::type shape(100, 200, 20);
MultiArray<3, int> array(shape);
... // fill array with data
writeHDF5("mydata.h5", "/group1/my_dataset", array);

void vigra::writeHDF5Attr | ( | hid_t | loc,
|  | const char * | name,
|  | MultiArrayView< N, T, C > const & | array
| ) |  |

Write a numeric MultiArray as an attribute with name name of the dataset specified by the handle loc.

#include <vigra/hdf5impex.hxx>
Namespace: vigra

void vigra::writeHDF5Attr | ( | hid_t | loc,
|  | const char * | name,
|  | MultiArrayView< N, std::string, C > const & | array
| ) |  |

Write a string MultiArray as an attribute with name name of the dataset specified by the handle loc.

#include <vigra/hdf5impex.hxx>
Namespace: vigra

void vigra::writeHDF5Attr | ( | hid_t | loc,
|  | const char * | name,
|  | ArrayVectorView< T > & | array
| ) |  |

Write a numeric ArrayVectorView as an attribute with name name of the dataset specified by the handle loc.

#include <vigra/hdf5impex.hxx>
Namespace: vigra

void vigra::writeHDF5Attr | ( | std::string | filePath,
|  | std::string | pathInFile,
|  | Arr & | ar
| ) |  |

write an Attribute given a file and a path in the file. the path in the file should have the format [attribute] or /[subgroups/]dataset.attribute or /[subgroups/]group.attribute. The attribute is written to the root group, a dataset or a subgroup respectively

HDF5HandleShared createDataset | ( | std::string | datasetName,
|  | TinyVector< MultiArrayIndex, N > const & | shape,
|  | typename detail::HDF5TypeTraits< T >::value_type | init = `typename detail::HDF5TypeTraits<T>::value_type()`,
|  | TinyVector< MultiArrayIndex, N > const & | chunkSize = `(TinyVector<MultiArrayIndex, N>())`,
|  | int | compressionParameter = `0`
| ) |  |

Create a new dataset. This function can be used to create a dataset filled with a default value init, for example before writing data into it using writeBlock().

shape determines the dimension and the size of the dataset.

Chunks can be activated by providing a MultiArrayShape as chunkSize. chunkSize must have equal dimension as array.

Compression can be activated by setting

compression = parameter; // 0 < parameter <= 9

where 0 stands for no compression and 9 for maximum compression. If a non-zero compression level is specified, but the chunk size is zero, a default chunk size will be chosen (compression always requires chunks).

If the first character of datasetName is a "/", the path will be interpreted as absolute path, otherwise it will be interpreted as path relative to the current group.

Note that the memory order between VIGRA and HDF5 files differs: VIGRA uses Fortran-order, while HDF5 uses C-order. This means that a VIGRA MultiArray, whose indices represent the 'x'-, 'y'-, and 'z'-axis in that order, is reversed upon writing to an HDF5 file, i.e. in the file the axis order is 'z', 'y', 'x'.

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python vigra 1.10.0 (Thu Jan 8 2015)