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

details Import/Export of Images and Arrays in HDF5 Format VIGRA

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)