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

details HDF5File Class Reference VIGRA

Access to HDF5 files. More...

#include <vigra/hdf5impex.hxx>

List of all members.

Public Types

enum  OpenMode
 Set how a file is opened. More...

Public Member Functions

void cd (std::string groupName)
 Change the current group. Both absolute and relative group names are allowed.
void cd_mk (std::string groupName)
 Change the current group; create it if necessary. If the first character is a "/", the path will be interpreted as absolute path, otherwise it will be interpreted as path relative to the current group.
bool cd_up ()
 Change the current group to its parent group. Returns true if successful, false otherwise. If unsuccessful, the group will not change.
bool cd_up (int levels)
 Change the current group to its parent group. Returns true if successful, false otherwise. If unsuccessful, the group will not change.
void close ()
 Close the current file.
template<unsigned int N, class T >
void createDataset (std::string datasetName, typename MultiArrayShape< N >::type shape, T init=T(), int iChunkSize=0, int compressionParameter=0)
 Create a new dataset. This function can be used to create a dataset filled with a default value, for example before writing data into it using writeBlock(). Attention: only atomic datatypes are provided. For spectral data, add an dimension (case RGB: add one dimension of size 3).
bool existsAttribute (std::string object_name, std::string attribute_name)
 Test if attribute exists.
std::string filename () const
 Get the name of the associated file.
void flushToDisk ()
 Immediately write all data to disk.
std::string get_absolute_path (std::string path) const
 takes any path and converts it into an absolute path in the current file.
HDF5Handle getAttributeHandle (std::string dataset_name, std::string attribute_name)
 Obtain the HDF5 handle of a attribute.
hssize_t getDatasetDimensions (std::string datasetName)
 Get the number of dimensions of a certain dataset If the first character is a "/", the path will be interpreted as absolute path, otherwise it will be interpreted as path relative to the current group.
HDF5Handle getDatasetHandle (std::string dataset_name)
 Obtain the HDF5 handle of a dataset.
ArrayVector< hsize_t > getDatasetShape (std::string datasetName)
 Get the shape of each dimension of a certain dataset.
HDF5Handle getGroupHandle (std::string group_name)
 Obtain the HDF5 handle of a group.
 HDF5File (int track_creation_times=0)
 Default constructor.
 HDF5File (std::string filename, OpenMode mode, int track_creation_times=0)
 Open or create an HDF5File object.
std::vector< std::string > ls () const
 List the contents of the current group. The function returns a vector of strings holding the entries of the current group. Only datasets and groups are listed, other objects (e.g. datatypes) are ignored. Group names always have a trailing "/".
template<class Container >
void ls (Container &cont) const
 List the contents of the current group into a container-like object via insert().
void mkdir (std::string groupName)
 Create a new group. If the first character is a "/", the path will be interpreted as absolute path, otherwise it will be interpreted as path relative to the current group.
void open (std::string filename, OpenMode mode)
 Open or create the given file in the given mode and set the group to "/". If another file is currently open, it is first closed.
std::string pwd () const
 Get the path of the current group.
template<unsigned int N, class T >
void read (std::string datasetName, MultiArrayView< N, T, UnstridedArrayTag > &array)
 Read data into a multi array. 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.
template<class T >
void read (const std::string &datasetName, ArrayVectorView< T > &array)
 Read data into an array vector. 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.
void read (std::string datasetName, char &data)
 Read a single value. Specialization of the read function for simple datatypes.
template<unsigned int N, class T >
void readAndResize (std::string datasetName, MultiArray< N, T > &array)
 Read data into a MultiArray. Resize MultiArray to the correct size. 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.
template<class T >
void readAndResize (std::string datasetName, ArrayVector< T > &array)
 Read data into an array vector. Resize the array vector to the correct size. 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.
template<unsigned int N, class T >
void readAttribute (std::string object_name, std::string attribute_name, const MultiArrayView< N, T, UnstridedArrayTag > &array)
 Read MultiArray Attributes. In contrast to datasets, subarray access is not available.
void readAttribute (std::string object_name, std::string attribute_name, char &data)
 Read a single value. Specialization of the read function for simple datatypes.
template<unsigned int N, class T >
void readBlock (std::string datasetName, typename MultiArrayShape< N >::type blockOffset, typename MultiArrayShape< N >::type blockShape, MultiArrayView< N, T, UnstridedArrayTag > &array)
 Read a block of data into a multi array. This function allows to read a small block out of a larger volume stored in an HDF5 dataset.
void root ()
 Change current group to "/".
template<unsigned int N, class T >
void write (std::string datasetName, const MultiArrayView< N, T, UnstridedArrayTag > &array, int iChunkSize=0, int compression=0)
 Write multi arrays.
template<unsigned int N, class T >
void write (std::string datasetName, const MultiArrayView< N, T, UnstridedArrayTag > &array, typename MultiArrayShape< N >::type chunkSize, int compression=0)
 Write multi arrays. Chunks can be activated by providing a MultiArrayShape as chunkSize. chunkSize must have equal dimension as array.
template<class T >
void write (const std::string &datasetName, const ArrayVectorView< T > &array, int compression=0)
 Write array vectors.
void write (std::string datasetName, char data)
 Write a single value. Specialization of the write function for simple datatypes.
template<unsigned int N, class T >
void writeAttribute (std::string object_name, std::string attribute_name, const MultiArrayView< N, T, UnstridedArrayTag > &array)
 Write MultiArray Attributes. In contrast to datasets, subarray access, chunks and compression are not available.
void writeAttribute (std::string object_name, std::string attribute_name, char data)
 Write a single value. Specialization of the write function for simple datatypes.
template<unsigned int N, class T >
void writeBlock (std::string datasetName, typename MultiArrayShape< N >::type blockOffset, const MultiArrayView< N, T, UnstridedArrayTag > &array)
 Write a multi array into a larger volume. blockOffset determines the position, where array is written.
 ~HDF5File ()
 The destructor flushes and closes the file.

Detailed Description

Access to HDF5 files.

HDF5File provides a convenient way of accessing data in HDF5 files. vigra::MultiArray structures of any dimension can be stored to / loaded from HDF5 files. Typical HDF5 features like subvolume access, chunks and data compression are available, string attributes can be attached to any dataset or group. Group- or dataset-handles are encapsulated in the class and managed automatically. The internal file-system like structure can be accessed by functions like "cd()" or "mkdir()".

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'. Likewise, the order is reversed upon reading.

Example: Write the MultiArray out_multi_array to file. Change the current directory to "/group" and read in the same MultiArray as in_multi_array.

HDF5File file("/path/to/file",HDF5File::New);
file.mkdir("group");
file.write("/group/dataset", out_multi_array);

file.cd("/group");
file.read("dataset", in_multi_array);

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


Member Enumeration Documentation

enum OpenMode

Set how a file is opened.

OpenMode::New creates a new file. If the file already exists, overwrite it.

OpenMode::Open opens a file for reading/writing. The file will be created, if necessary.


Constructor & Destructor Documentation

HDF5File ( int  track_creation_times = 0)

Default constructor.

A file can later be opened via the open() function.

If track_creation_times is non-zero, time tagging of datasets will be enabled (it is disabled by default).

HDF5File ( std::string  filename,
OpenMode  mode,
int  track_creation_times = 0 
)

Open or create an HDF5File object.

Creates or opens HDF5 file with given filename. The current group is set to "/".

Note that the HDF5File class is not copyable (the copy constructor is private to enforce this).


Member Function Documentation

void ls ( Container &  cont) const

List the contents of the current group into a container-like object via insert().

Only datasets and groups are inserted, other objects (e.g., datatypes) are ignored. Group names always have a trailing "/".

The argument cont is presumably an associative container, however, only its member function cont.insert(std::string) will be called.

Parameters:
contreference to a container supplying a member function insert(const i_type &), where i_type is convertible to std::string.
ArrayVector<hsize_t> getDatasetShape ( std::string  datasetName)

Get the shape of each dimension of a certain dataset.

Normally, this function is called after determining the dimension of the dataset using getDatasetDimensions(). If the first character 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 function therefore reverses the axis order relative to the file contents. That is, when the axes in the file are ordered as 'z', 'y', 'x', this function will return the shape in the order 'x', 'y', 'z'.

void write ( std::string  datasetName,
const MultiArrayView< N, T, UnstridedArrayTag > &  array,
int  iChunkSize = 0,
int  compression = 0 
)

Write multi arrays.

Chunks can be activated by setting

 iChunkSize = size; //size > 0 

. The chunks will be hypercubes with edge length size.

Compression can be activated by setting

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

where 0 stands for no compression and 9 for maximum compression.

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

void write ( std::string  datasetName,
const MultiArrayView< N, T, UnstridedArrayTag > &  array,
typename MultiArrayShape< N >::type  chunkSize,
int  compression = 0 
)

Write multi arrays. 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 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'.

void writeBlock ( std::string  datasetName,
typename MultiArrayShape< N >::type  blockOffset,
const MultiArrayView< N, T, UnstridedArrayTag > &  array 
)

Write a multi array into a larger volume. blockOffset determines the position, where array is written.

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

void write ( const std::string &  datasetName,
const ArrayVectorView< T > &  array,
int  compression = 0 
)

Write array vectors.

Compression can be activated by setting

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

where 0 stands for no compression and 9 for maximum compression.

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.

void read ( std::string  datasetName,
MultiArrayView< N, T, UnstridedArrayTag > &  array 
)

Read data into a multi array. 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 HDF5 dataset, whose indices represent the 'z'-, 'y'-, and 'x'-axis in that order, is reversed upon reading into a MultiArrayView, i.e. in the array axis order must be 'x', 'y', 'z'.

void readAndResize ( std::string  datasetName,
MultiArray< N, T > &  array 
)

Read data into a MultiArray. Resize MultiArray to the correct size. 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 HDF5 dataset, whose indices represent the 'z'-, 'y'-, and 'x'-axis in that order, is reversed upon reading into a MultiArray, i.e. in the array axis order will be 'x', 'y', 'z'.

void readBlock ( std::string  datasetName,
typename MultiArrayShape< N >::type  blockOffset,
typename MultiArrayShape< N >::type  blockShape,
MultiArrayView< N, T, UnstridedArrayTag > &  array 
)

Read a block of data into a multi array. This function allows to read a small block out of a larger volume stored in an HDF5 dataset.

blockOffset determines the position of the block. blockSize determines the size in each dimension of the block.

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 HDF5 dataset, whose indices represent the 'z'-, 'y'-, and 'x'-axis in that order, is reversed upon reading into a MultiArray, i.e. in the array axis order will be 'x', 'y', 'z'.

void createDataset ( std::string  datasetName,
typename MultiArrayShape< N >::type  shape,
init = T(),
int  iChunkSize = 0,
int  compressionParameter = 0 
)

Create a new dataset. This function can be used to create a dataset filled with a default value, for example before writing data into it using writeBlock(). Attention: only atomic datatypes are provided. For spectral data, add an dimension (case RGB: add one dimension of size 3).

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

std::string get_absolute_path ( std::string  path) const

takes any path and converts it into an absolute path in the current file.

Elements like "." and ".." are treated as expected. Links are not supported or resolved.


The documentation for this class was generated from the following file:

© 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.9.0 (Tue Nov 6 2012)