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

HDF5File Class Reference

Access to HDF5 files. More...

`#include <vigra/hdf5impex.hxx>`

## 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<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().
bool | existsAttribute (std::string object_name, std::string attribute_name)
| Test if attribute exists.
bool | existsDataset (std::string datasetName) const
| Check if given datasetName 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) const
| Obtain the HDF5 handle of a attribute.
ArrayVector< hsize_t > | getChunkShape (std::string datasetName) const
| Get the shape of chunks along each dimension of a certain dataset.
hssize_t | getDatasetDimensions (std::string datasetName) const
| 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 const &datasetName) const
| Obtain the HDF5 handle of a dataset.
HDF5HandleShared | getDatasetHandleShared (std::string const &datasetName) const
| Obtain a shared HDF5 handle of a dataset.
ArrayVector< hsize_t > | getDatasetShape (std::string datasetName) const
| Get the shape of each dimension of a certain dataset.
std::string | getDatasetType (std::string const &datasetName) const
HDF5Handle | getGroupHandle (std::string group_name, std::string function_name="HDF5File::getGroupHandle()")
| Obtain the HDF5 handle of a group (create the group if it doesn't exist).
| HDF5File ()
| Default constructor.
| HDF5File (bool track_creation_times)
| Construct with time tagging of datasets enabled.
| HDF5File (char const *filePath, OpenMode mode=ReadOnly, bool track_creation_times=false)
| Open or create an HDF5File object.
| HDF5File (HDF5File const &other)
| Copy a HDF5File object.
| HDF5File (HDF5HandleShared const &fileHandle, const std::string &pathname="", bool read_only=false)
| Initialize an HDF5File object from HDF5 file handle.
| HDF5File (std::string filePath, OpenMode mode=ReadOnly, bool track_creation_times=false)
| Open or create an HDF5File object.
std::vector< std::string > | listAttributes (std::string const &group_or_dataset) const
| List the attribute names of the given group or dataset.
template<class Container >
void | listAttributes (std::string const &group_or_dataset, Container &container) const
| Insert the attribute names of the given group or dataset into the given container by calling `container.insert(std::string)`.
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 filePath, 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.
HDF5File & | operator= (HDF5File const &other)
| Assign a HDF5File object.
std::string | pwd () const
| Get the path of 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 , class Stride >
void | read (std::string datasetName, MultiArrayView< N, T, Stride > 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 | 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 , class Alloc >
void | readAndResize (std::string datasetName, MultiArray< N, T, Alloc > &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.
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 , class Stride >
void | readAttribute (std::string object_name, std::string attribute_name, MultiArrayView< N, T, Stride > array)
| Read MultiArray Attributes. In contrast to datasets, subarray access is not available.
template<unsigned int N, class T , class Stride >
void | readBlock (std::string datasetName, typename MultiArrayShape< N >::type blockOffset, typename MultiArrayShape< N >::type blockShape, MultiArrayView< N, T, Stride > 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<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 , class Stride >
void | write (std::string datasetName, const MultiArrayView< N, T, Stride > &array, int iChunkSize=0, int compression=0)
| Write multi arrays.
template<unsigned int N, class T , class Stride >
void | write (std::string datasetName, const MultiArrayView< N, T, Stride > &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.
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 , class Stride >
void | writeAttribute (std::string object_name, std::string attribute_name, const MultiArrayView< N, T, Stride > &array)
| Write MultiArray Attributes. In contrast to datasets, subarray access, chunks and compression are not available.
template<unsigned int N, class T , class Stride >
void | writeBlock (std::string datasetName, typename MultiArrayShape< N >::type blockOffset, const MultiArrayView< N, T, Stride > &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);
vigra::HDF5File
Access to HDF5 files.
Definition hdf5impex.hxx:975
vigra::RGBValue
Class for a single RGB value.
Definition rgbvalue.hxx:128

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

## Member Enumeration Documentation

## ◆ OpenMode

enum OpenMode

Set how a file is opened.

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

OpenMode::ReadWrite opens a file for reading/writing. The file will be created if it doesn't exist.

OpenMode::ReadOnly opens a file for reading. The file as well as any dataset to be accessed must already exist.

## Constructor & Destructor Documentation

## ◆ HDF5File() [1/6]

HDF5File | ( |  | ) |

Default constructor.

A file can later be opened via the open() function. Time tagging of datasets is disabled.

## ◆ HDF5File() [2/6]

HDF5File | ( | bool | track_creation_times | ) |

explicit

Construct with time tagging of datasets enabled.

If track_creation_times is 'true', time tagging of datasets will be enabled.

## ◆ HDF5File() [3/6]

HDF5File | ( | std::string | filePath,
|  | OpenMode | mode = `ReadOnly`,
|  | bool | track_creation_times = `false`
| ) |  |

explicit

Open or create an HDF5File object.

Creates or opens HDF5 file with given filename. The current group is set to "/". By default, the files is opened in read-only mode.

## ◆ HDF5File() [4/6]

HDF5File | ( | char const * | filePath,
|  | OpenMode | mode = `ReadOnly`,
|  | bool | track_creation_times = `false`
| ) |  |

explicit

Open or create an HDF5File object.

Creates or opens HDF5 file with given filename. The current group is set to "/". By default, the files is opened in read-only mode.

## ◆ HDF5File() [5/6]

HDF5File | ( | HDF5HandleShared const & | fileHandle,
|  | const std::string & | pathname = `""`,
|  | bool | read_only = `false`
| ) |  |

explicit

Initialize an HDF5File object from HDF5 file handle.

Initializes an HDF5File object corresponding to the HDF5 file opened elsewhere. If fileHandle is constructed with a `NULL` destructor, ownership is not transferred to the new HDF5File object, and you must ensure that the file is not closed while the new HDF5File object is in use. Otherwise, ownership will be shared.

The current group is set to the specified pathname. If read_only is 'true', you cannot create new datasets or overwrite data.

Warning
  When VIRA is linked against a different HDF5 library than the one used to open the file with the given id, this method will lead to crashes.

## ◆ HDF5File() [6/6]

HDF5File | ( | HDF5File const & | other | ) |

Copy a HDF5File object.

The new object will refer to the same file and group as other.

## Member Function Documentation

## ◆ operator=()

HDF5File & operator= | ( | HDF5File const & | other | ) |

Assign a HDF5File object.

Calls close() on the present file and refers to the same file and group as other afterwards.

## ◆ ls()

template<class Container >

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

  cont | reference to a container supplying a member function `insert(const i_type &)`, where `i_type` is convertible to `std::string`.

## ◆ getDatasetShape()

ArrayVector< hsize_t > getDatasetShape | ( | std::string | datasetName | ) | const

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

## ◆ getChunkShape()

ArrayVector< hsize_t > getChunkShape | ( | std::string | datasetName | ) | const

Get the shape of chunks along 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'.

## ◆ getDatasetType()

std::string getDatasetType | ( | std::string const & | datasetName | ) | const

Query the pixel type of the dataset.

Possible values are:

"INT8"
  8-bit signed integer (unsigned char)
"UINT8"
  8-bit unsigned integer (unsigned char)
"INT16"
  16-bit signed integer (short)
"UINT16"
  16-bit unsigned integer (unsigned short)
"INT32"
  32-bit signed integer (long)
"UINT32"
  32-bit unsigned integer (unsigned long)
"INT64"
  64-bit signed integer (long long)
"UINT64"
  64-bit unsigned integer (unsigned long long)
"FLOAT"
  32-bit floating point (float)
"DOUBLE"
  64-bit floating point (double)
"UNKNOWN"
  any other type

## ◆ listAttributes() [1/2]

std::vector< std::string > listAttributes | ( | std::string const & | group_or_dataset | ) | const

List the attribute names of the given group or dataset.

If group_or_dataset is empty or `"."` (a dot), the command refers to the current group of this file object.

## ◆ listAttributes() [2/2]

template<class Container >

void listAttributes | ( | std::string const & | group_or_dataset,
|  | Container & | container
| ) |  | const

Insert the attribute names of the given group or dataset into the given container by calling `container.insert(std::string)`.

If group_or_dataset is empty or `"."` (a dot), the command refers to the current group of this file object.

## ◆ write() [1/3]

template<unsigned int N, class T , class Stride >

void write | ( | std::string | datasetName,
|  | const MultiArrayView< N, T, Stride > & | 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. When `iChunkSize == 0` (default), the behavior depends on the `compression` setting: If no compression is requested, the data is written without chunking. Otherwise, chuning is required, and the chunk size is automatically selected such that each chunk contains about 300k pixels.

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

## ◆ write() [2/3]

template<unsigned int N, class T , class Stride >

void write | ( | std::string | datasetName,
|  | const MultiArrayView< N, T, Stride > & | 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'.

## ◆ writeBlock()

template<unsigned int N, class T , class Stride >

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

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

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

## ◆ write() [3/3]

template<class T >

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.

## ◆ read()

template<unsigned int N, class T , class Stride >

void read | ( | std::string | datasetName,
|  | MultiArrayView< N, T, Stride > | 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'.

## ◆ readAndResize()

template<unsigned int N, class T , class Alloc >

void readAndResize | ( | std::string | datasetName,
|  | MultiArray< N, T, Alloc > & | 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'.

## ◆ readBlock()

template<unsigned int N, class T , class Stride >

void readBlock | ( | std::string | datasetName,
|  | typename MultiArrayShape< N >::type | blockOffset,
|  | typename MultiArrayShape< N >::type | blockShape,
|  | MultiArrayView< N, T, Stride > | 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'.

## ◆ createDataset()

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().

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

## ◆ get_absolute_path()

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:

- vigra/hdf5impex.hxx

© 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.12.2