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
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...
bool	isHDF5 (char const *filename)
	Check if given filename refers to a HDF5 file.
template<... >
void	readHDF5 (...)
	Read the data specified by the given vigra::HDF5ImportInfo object and write the into the given 'array'. More...
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)

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

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'.