iRoCS Toolbox  1.1.0
Public Types | Public Member Functions | Static Public Member Functions
BlitzH5File Class Reference

#include <BlitzHdf5Light.hh>

Collaboration diagram for BlitzH5File:

Public Types

enum  FileMode {
  ReadOnly, Write, Replace, New,
  WriteOrNew
}
 

Public Member Functions

 BlitzH5File ()
 Creates a stub BlitzH5File object. More...
 
 BlitzH5File (std::string const &fileName, FileMode mode=ReadOnly)
 Opens/Creates an HDF5File, with the given file name. More...
 
 ~BlitzH5File ()
 
std::vector< std::string > allDatasets (std::string const &startGroup="/") const
 Returns the absolute paths of all datasets below the given group. More...
 
void copyObject (std::string const &objectName, BlitzH5File &outFile, int compression=-1)
 Recursively copy the given object to the given BlitzH5File. More...
 
void createGroup (std::string const &groupName)
 Create a group with specified name. More...
 
void deleteAttribute (std::string const &attName, std::string const &objectName="/")
 Deletes an attribute. More...
 
void deleteDataset (std::string const &name)
 Avoid using this function! If you really need to use it, your file may become severely fragmented. More...
 
void deleteGroup (std::string const &groupName)
 Delete the group specified by groupName. More...
 
bool existsAttribute (std::string const &attName, std::string const &objectName="/") const
 Checks if there is an attribute with the specified name in the specified group. More...
 
bool existsDataset (std::string const &name) const
 Checks if there is a dataset with the specified name. More...
 
bool existsGroup (std::string const &groupName) const
 Checks if there is a group with the specified name. More...
 
std::vector< std::string > getAttributes (std::string const &objectName="/") const
 Get all attributes of a group or dataset. More...
 
std::vector< hsize_t > getAttributeShape (std::string const &attName, std::string const &objectName="/") const
 Retrieve the shape of an attribute. More...
 
hid_t getAttributeType (const std::string &attName, const std::string &objectName="/") const
 Get the HDF5 type of the attribute. More...
 
std::vector< hsize_t > getDatasetShape (std::string const &name) const
 Returns the dimension extents of a dataset. More...
 
hid_t getDatasetType (std::string const &name) const
 Get the HDF5 type of the dataset. More...
 
std::vector< std::string > getGroups (std::string const &groupName="/") const
 Gets the list of all subgroups in the given group. More...
 
std::vector< std::string > getObjects (std::string const &groupName="/") const
 Gets the list of names of all objects in a group. More...
 
hid_t id ()
 Get HDF5 id for this file. More...
 
std::string const & name () const
 Get the file name. More...
 
template<typename DataT >
void readAttribute (DataT &data, std::string const &attName, std::string const &objectName="/") const
 Reads an attribute. More...
 
template<typename DataT , int Dim>
void readAttribute (blitz::TinyVector< DataT, Dim > &data, std::string const &attName, std::string const &objectName="/") const
 Reads an attribute. More...
 
template<typename DataT , int NRows, int NCols>
void readAttribute (blitz::TinyMatrix< DataT, NRows, NCols > &data, std::string const &attName, std::string const &objectName="/") const
 Reads an attribute. More...
 
template<typename DataT >
void readAttribute (std::vector< DataT > &data, std::string const &attName, std::string const &objectName="/") const
 Reads an attribute. More...
 
void readAttribute (std::string &data, std::string const &attName, std::string const &objectName="/") const
 Reads a string attribute. More...
 
template<typename FixedNumericT >
void readDataset (FixedNumericT &data, std::string const &name) const
 Reads a simple, fixed size numeric data set. More...
 
template<typename DataT >
void readDataset (std::vector< DataT > &data, std::string const &name) const
 Reads a simple, 1D vectorial numerical data set. More...
 
template<typename DataT , int Rank>
void readDataset (blitz::Array< DataT, Rank > &data, std::string const &name, iRoCS::ProgressReporter *pr=NULL) const
 Reads a simple, multi dimensional data set. More...
 
void readDataset (std::string &data, std::string const &name, iRoCS::ProgressReporter *pr=NULL) const
 Reads a simple, string data set. More...
 
template<typename DataT >
void writeAttribute (DataT const &in, std::string const &attName, std::string const &objectName="/")
 Writes an attribute. More...
 
void writeAttribute (std::string const &in, std::string const &attName, std::string const &objectName="/")
 Writes a string attribute. More...
 
template<typename DataT >
void writeDataset (DataT const &data, std::string const &name)
 Writes a simple data set without chunking or compression. More...
 
template<typename DataT , int Rank>
void writeDataset (blitz::Array< DataT, Rank > const &data, std::string const &name, int compression=1, iRoCS::ProgressReporter *pr=NULL)
 Writes a simple, multi dimensional data set, creating the data set if needed. More...
 
void writeDataset (std::string const &data, std::string const &name, iRoCS::ProgressReporter *pr=NULL)
 Writes a simple, string data set, creating the data set if needed. More...
 

Static Public Member Functions

static std::string simplifyGroupDescriptor (std::string const &group)
 Get a normalized version of the given h5 object path string. More...
 

Detailed Description

Definition at line 140 of file BlitzHdf5Light.hh.

Member Enumeration Documentation

◆ FileMode

Enumerator
ReadOnly 
Write 
Replace 
New 
WriteOrNew 

Definition at line 145 of file BlitzHdf5Light.hh.

Constructor & Destructor Documentation

◆ BlitzH5File() [1/2]

BlitzH5File::BlitzH5File ( )

Creates a stub BlitzH5File object.

◆ BlitzH5File() [2/2]

BlitzH5File::BlitzH5File ( std::string const &  fileName,
FileMode  mode = ReadOnly 
)

Opens/Creates an HDF5File, with the given file name.

When creating a new file, the mode will be automatically set to ReadWrite disregarding the given mode. When accessing an existing file it will be opened ReadOnly by default.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
fileNamefile to be opened
modefile mode to be used (default: ReadOnly),
See also
BlitzH5File::FileMode
Exceptions
BlitzH5Error

◆ ~BlitzH5File()

BlitzH5File::~BlitzH5File ( )

Member Function Documentation

◆ id()

hid_t BlitzH5File::id ( )
inline

Get HDF5 id for this file.

Exceptions
BlitzH5Error
Returns
The raw HDF5 file ID for direct access to the file using the HDF5 C interface.

Definition at line 188 of file BlitzHdf5Light.hh.

◆ name()

std::string const& BlitzH5File::name ( ) const
inline

Get the file name.

Returns
The name of this hdf5 file

Definition at line 202 of file BlitzHdf5Light.hh.

◆ simplifyGroupDescriptor()

static std::string BlitzH5File::simplifyGroupDescriptor ( std::string const &  group)
static

Get a normalized version of the given h5 object path string.

Extra '/' and './' will be removed. The resulting string is guaranteed to be the simplest possible equivalent version of the group string. The returned string always ends with a non-slash character. The input string may not contain any occurrence of '../'

e.g. the input bla/./blub//bleablub produces bla/blub/bleablub

Parameters
groupThe group string to simplify
Returns
The simplified group descriptor

◆ existsDataset()

bool BlitzH5File::existsDataset ( std::string const &  name) const

Checks if there is a dataset with the specified name.

Parameters
namedataset path descriptor
Returns
true if the dataset exists, false otherwise

◆ getDatasetShape()

std::vector<hsize_t> BlitzH5File::getDatasetShape ( std::string const &  name) const

Returns the dimension extents of a dataset.

For scalar datasets a zero length vector is returned!

Parameters
namedataset path descriptor
Returns
The dataset shape as vector of extents.

◆ allDatasets()

std::vector<std::string> BlitzH5File::allDatasets ( std::string const &  startGroup = "/") const

Returns the absolute paths of all datasets below the given group.

Parameters
startGroupThe names of all datasets in and below this group are returned
Returns
A vector containing the absolute dataset paths

◆ getDatasetType()

hid_t BlitzH5File::getDatasetType ( std::string const &  name) const

Get the HDF5 type of the dataset.

The returned hid_t must be released after usage with H5Tclose().

Parameters
namedataset path descriptor
Returns
An hid_t corresponding to the HDF5 data type of the dataset

◆ readDataset() [1/4]

template<typename FixedNumericT >
void BlitzH5File::readDataset ( FixedNumericT &  data,
std::string const &  name 
) const

Reads a simple, fixed size numeric data set.

This can be a simple scalar, a TinyVector or a TinyMatrix. Complex should also work but is not tested.

Parameters
dataoutput variable
namedataset path descriptor
Exceptions
BlitzH5ErrorIf the dataset can not be read this error is thrown
See also
existsDataset() to query the existence of a dataset before reading

Referenced by Marker::_loadFixedSize(), and segmentation::SegmentationModel< T >::load().

◆ readDataset() [2/4]

template<typename DataT >
void BlitzH5File::readDataset ( std::vector< DataT > &  data,
std::string const &  name 
) const

Reads a simple, 1D vectorial numerical data set.

The type is automatically converted to the vector type and the output vector will be resized to fit the dataset extents.

Parameters
dataoutput vector
namedataset path descriptor
Exceptions
BlitzH5ErrorIf the dataset can not be read this error is thrown
See also
existsDataset() to query the existence of a dataset before reading

◆ readDataset() [3/4]

template<typename DataT , int Rank>
void BlitzH5File::readDataset ( blitz::Array< DataT, Rank > &  data,
std::string const &  name,
iRoCS::ProgressReporter pr = NULL 
) const

Reads a simple, multi dimensional data set.

The type is automatically converted to the Array type and the output Array will be resized to fit the dataset extents.

Parameters
dataoutput array
namedataset path descriptor
prIf given progress will be reported to this ProgressReporter
Exceptions
BlitzH5ErrorIf the dataset can not be read this error is thrown
See also
existsDataset() to query the existence of a dataset before reading

◆ readDataset() [4/4]

void BlitzH5File::readDataset ( std::string &  data,
std::string const &  name,
iRoCS::ProgressReporter pr = NULL 
) const

Reads a simple, string data set.

Parameters
dataoutput string
namedataset path descriptor
prIf given progress will be reported to this PorgressReporter
Exceptions
BlitzH5ErrorIf the dataset can not be read this error is thrown
See also
existsDataset() to query the existence of a dataset before reading

◆ writeDataset() [1/3]

template<typename DataT >
void BlitzH5File::writeDataset ( DataT const &  data,
std::string const &  name 
)

Writes a simple data set without chunking or compression.

This should only be used for scalars or very small datasets.

Parameters
datavariable to write
namedataset path descriptor
Exceptions
BlitzH5ErrorIf the dataset can not be read this error is thrown
See also
existsDataset() to query the existence of a dataset before reading

Referenced by segmentation::SegmentationModel< T >::save().

◆ writeDataset() [2/3]

template<typename DataT , int Rank>
void BlitzH5File::writeDataset ( blitz::Array< DataT, Rank > const &  data,
std::string const &  name,
int  compression = 1,
iRoCS::ProgressReporter pr = NULL 
)

Writes a simple, multi dimensional data set, creating the data set if needed.

The datatype in the file is chosen according to the datatype of the blitz array. If a dataset with the given name already exists with different dimensionality, extents or data type it will be replaced.

Parameters
dataarray to be written into file
namedataset path descriptor
compressionlevel of compression = 0..9, default = 1 (low compression)
prIf given progress will be reported to this PorgressReporter
Exceptions
BlitzH5ErrorIf the dataset can not be written this error is thrown
See also
existsDataset() to query the existence of a dataset before writing

◆ writeDataset() [3/3]

void BlitzH5File::writeDataset ( std::string const &  data,
std::string const &  name,
iRoCS::ProgressReporter pr = NULL 
)

Writes a simple, string data set, creating the data set if needed.

If a dataset with the given name already exists with different dimensionality, extents or data type it will be replaced.

Parameters
datastring to be written into file
namedataset path descriptor
prIf given progress will be reported to this PorgressReporter
Exceptions
BlitzH5ErrorIf the dataset can not be written this error is thrown
See also
existsDataset() to query the existence of a dataset before writing

◆ deleteDataset()

void BlitzH5File::deleteDataset ( std::string const &  name)

Avoid using this function! If you really need to use it, your file may become severely fragmented.

Use some external tool to copy the contents if the file gets too bloated.

Remove association between dataset descriptor and dataset data. This will not actually release the file space used by the dataset but will mark the space as reusable until the file is closed. After closing the file free space information is lost!

Parameters
namedataset path descriptor
Exceptions
BlitzH5ErrorIf the dataset can not be deleted this error is thrown

◆ existsAttribute()

bool BlitzH5File::existsAttribute ( std::string const &  attName,
std::string const &  objectName = "/" 
) const

Checks if there is an attribute with the specified name in the specified group.

Parameters
attNamename of the attribute
objectNamepath to parent dataset or group
Returns
true if existing, false otherwise

◆ getAttributeShape()

std::vector<hsize_t> BlitzH5File::getAttributeShape ( std::string const &  attName,
std::string const &  objectName = "/" 
) const

Retrieve the shape of an attribute.

For scalars or C-Strings it will return 1, otherwise the extents of the (multidimensional) attribute

Parameters
attNamename of the attribute
objectNamepath to parent dataset or group
Returns
The attribute shape as vector of extents

◆ getAttributeType()

hid_t BlitzH5File::getAttributeType ( const std::string &  attName,
const std::string &  objectName = "/" 
) const

Get the HDF5 type of the attribute.

Parameters
attNamename of the attribute
objectNamepath to parent dataset or group
Returns
An hid_t corresponding to the HDF5 data type of the dataset

◆ readAttribute() [1/5]

template<typename DataT >
void BlitzH5File::readAttribute ( DataT &  data,
std::string const &  attName,
std::string const &  objectName = "/" 
) const

Reads an attribute.

Parameters
datavariable to store the attribute data to
attNamename of the attribute
objectNamepath to parent dataset or group

Referenced by segmentation::SegmentationModel< T >::load().

◆ readAttribute() [2/5]

template<typename DataT , int Dim>
void BlitzH5File::readAttribute ( blitz::TinyVector< DataT, Dim > &  data,
std::string const &  attName,
std::string const &  objectName = "/" 
) const

Reads an attribute.

Parameters
datavariable to store the attribute data to
attNamename of the attribute
objectNamepath to parent dataset or group

◆ readAttribute() [3/5]

template<typename DataT , int NRows, int NCols>
void BlitzH5File::readAttribute ( blitz::TinyMatrix< DataT, NRows, NCols > &  data,
std::string const &  attName,
std::string const &  objectName = "/" 
) const

Reads an attribute.

Parameters
datavariable to store the attribute data to
attNamename of the attribute
objectNamepath to parent dataset or group

◆ readAttribute() [4/5]

template<typename DataT >
void BlitzH5File::readAttribute ( std::vector< DataT > &  data,
std::string const &  attName,
std::string const &  objectName = "/" 
) const

Reads an attribute.

Parameters
datavariable to store the attribute data to
attNamename of the attribute
objectNamepath to parent dataset or group

◆ readAttribute() [5/5]

void BlitzH5File::readAttribute ( std::string &  data,
std::string const &  attName,
std::string const &  objectName = "/" 
) const

Reads a string attribute.

Parameters
datavariable to store the attribute data to
attNamename of the attribute
objectNamepath to parent dataset or group

◆ writeAttribute() [1/2]

template<typename DataT >
void BlitzH5File::writeAttribute ( DataT const &  in,
std::string const &  attName,
std::string const &  objectName = "/" 
)

Writes an attribute.

Parameters
invariable to be written to the file
attNamename of the attribute
objectNamepath to parent dataset or group

Referenced by segmentation::SegmentationModel< T >::save().

◆ writeAttribute() [2/2]

void BlitzH5File::writeAttribute ( std::string const &  in,
std::string const &  attName,
std::string const &  objectName = "/" 
)

Writes a string attribute.

Parameters
invariable to be written to the file
attNamename of the attribute
objectNamepath to parent dataset or group

◆ deleteAttribute()

void BlitzH5File::deleteAttribute ( std::string const &  attName,
std::string const &  objectName = "/" 
)

Deletes an attribute.

Parameters
attNamename of the attribute
objectNamepath to parent dataset or group

◆ getObjects()

std::vector<std::string> BlitzH5File::getObjects ( std::string const &  groupName = "/") const

Gets the list of names of all objects in a group.

Objects are datasets and groups.

Parameters
groupNamegroup name to be searched in; default is root '/'
Returns
The names of the objects in a std::vector

◆ getGroups()

std::vector<std::string> BlitzH5File::getGroups ( std::string const &  groupName = "/") const

Gets the list of all subgroups in the given group.

Parameters
groupNamegroup name to be searched in; default is root '/'
Returns
The names of the subgroups in a std::vector

◆ getAttributes()

std::vector<std::string> BlitzH5File::getAttributes ( std::string const &  objectName = "/") const

Get all attributes of a group or dataset.

Parameters
objectNamepath to group or dataset, if not specified, the global root attibutes are returned
Returns
The names of the attributes in a std::vector

◆ existsGroup()

bool BlitzH5File::existsGroup ( std::string const &  groupName) const

Checks if there is a group with the specified name.

Parameters
groupNameabsolute group path
Returns
true if group exists, false otherwise

◆ createGroup()

void BlitzH5File::createGroup ( std::string const &  groupName)

Create a group with specified name.

Parameters
groupNameabsolute group path
Exceptions
BlitzH5Error

◆ deleteGroup()

void BlitzH5File::deleteGroup ( std::string const &  groupName)

Delete the group specified by groupName.

All Objects within and below the group are recursively deleted.

Parameters
groupNameabsolute group path

◆ copyObject()

void BlitzH5File::copyObject ( std::string const &  objectName,
BlitzH5File outFile,
int  compression = -1 
)

Recursively copy the given object to the given BlitzH5File.

Object can be a dataset or a group.

Parameters
objectNameName of the dataset or group
outFileA reference to the output BlitzH5File
compressionCompression for the destination. Values in [0..9] change the compression. Value -1 (default) preserves the compression setting found in the original dataset.

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