Table of contents
HDF++ is a C++ API for HDF 5. The aim is to facilitate
HDF integration in C++ programs.
In this version (V 0.2), HDF++ only provides
services on the following HDF objects :
- files
- groups
- datasets
- attributes (scalar)
HDF++ is still under development.
The following figure shows the hierarchical relationship between the classes
which compose HDF++.
The classes which are directly manipulated by the user are :
- HDFfile,
- HDFgroup,
- HDFdataset,
- HDFattribute,
- HDFexplorer,
- HDFexception.
The remaining classes are base classes for commonalties of HDF objects :
- HDFobject : base class for commonalties of all HDF objects (HDFfile,HDFgroups,
HDFdataset, HDFattribute).
- HDFinternalObject : base class for commonalties of HDFfile, HDFgroup and HDFdataset.
- HDFcontainerObject : base class for commonalties of HDFfile, HDFgroup.
HDFfile class provides functions that access a HDF5 file. It inherits functions
about attributes from its parents classes (HDFobject, HDFinternalObject and
HDFcontainerObject).
The member functions of HDFfile class are the following :
- HDFfile : creates a HDFfile object in memory.
- CreateOnDisk : creates the HDF5 file.
- OpenOnDisk : opens the HDF5 file.
- CloseOnDisk : closes the HDF5 file.
- GetAccessMode : returns the access mode (read,write,read and write).
- GetObjectType : returns the object type (HDFfile).
- nInternalObjects : returns the number of first level HDF objects
that the HDF5 file contains.
- InternalObjectIndentify : returns the name of an internal object int the
HDF5 file.
- ExistInternalObject : indicates if an HDF object identified by its name
is in the HDF5 file.
- InternalObjectType : gives the type of an internal object (dataset,group)
in the HDF5 file.
HDFgroup class provides functions that access a HDF5 group. It inherits functions
about attributes from its parents classes (HDFobject, HDFinternalObject and
HDFcontainerObject).
The member functions of HDFgroup class are the following :
- HDFgroup : creates a HDFgroup object. A HDFgroup object is linked
to his father which is a HDFcontainerObject : i.e. either a HDFfile object or another
HDFgroup object.
- GetFather : returns a reference on the father object.
- GetObjectType : returns the type of the object : HDFgroup
- CreateOnDisk : creates the HDF5 group in the HDF5 file.
- OpenOnDisk : opens the HDF5 group in the HDF5 file.
- CloseOnDisk : closes the HDF5 group in the HDF5 file.
- FileMount : the HDFgroup becomes a mount point for a HDF5 file.
- FileUnMount : the file mounted at the HDFgroup object is unmounted.
- nInternalObjects : returns the number of objects (first level) that
contains the HDF5 group in the HDF5 file.
- InternalObjectIndentify : gives the name of HDF5 objects contained in
the HDF5 group.
- ExistInternalObject : indicates if a HDF5 object identified by its name
is in the HDF5 group.
- InternalObjectType : gives the type of HDF5 object
in the HDF5 group (group or dataset).
HDFdataset class provides functions that access a HDF5 dataset. It inherits functions
about attributes from its parents classes (HDFobject and HDFinternalObject).
The member functions of HDFdataset class are the following :
- HDFdataset : creates a HDFdataset object. A HDFdataset object is linked
to his father which is a HDFcontainerObject : i.e. either a HDFfile object or a
HDFgroup object.
- GetFather : returns a reference on the father object.
- GetType : returns the type of the object : HDFdataset
- CreateOnDisk : creates the HDF5 dataset in the HDF5 file.
- OpenOnDisk : opens the HDF5 dataset in the HDF5 file.
- CloseOnDisk : closes the HDF5 dataset in the HDF5 file.
- WriteOnDisk : writes an array values in the HDF5 dataset.
- ReadFromDisk : read an array values in the HDF5 dataset.
- nDim : returns the dimension number of the HDF5 dataset.
- GetDim : returns an array which gives the size of each dimension.
of the HDF5 dataset.
- GetSize : returns the storage size of the array in the HDF5 dataset.
- GetObjectType : returns the data type of the HDF5 dataset (float,int, string...).
HDFattribute class provides functions that access a HDF5 attribute. It inherits functions
about attributes from it parent class (HDFobject).
The member functions of HDFattribute class are the following :
- HDFattribute : creates a HDFattribute object in memory.
A HDFattribute object is linked to his father which is a HDFinternalObject :
i.e. a HDFfile object or a HDFgroup object or a HDFdataset object.
- GetFather : returns a reference on the father object.
- GetType : returns the type of the object : HDFattribute
- CreateOnDisk : creates the HDF5 attribute in the HDF5 file.
- OpenOnDisk : opens the HDF5 attribute in the HDF5 file.
- CloseOnDisk : closes the HDF5 attribute in the HDF5 file.
- WriteOnDisk : writes a scalar value in the HDF5 attribute.
- ReadFromDisk : read an scalar value in the HDF5 attribute.
HDFexplorer class provides the mecanism to explore following class intances :
- HDFcontainerObject,
- HDFfile,
- HDFgroup.
The member functions of HDFexplorer class are the following :
- HDFexplorer : creates a HDFexplorer object. An HDFexplorer object takes
in parameter a HDFcontainerObject (HDFfile or HDFgroup object).
- Init : The current pointer inside the HDFexplorer object is on
the first son (the list head) of the HDFcontainerObject.
- Next : Increments the current pointer.
- More : Tests if the current pointer is on the list queue.
- Value : Returns the current object reference inside the list.
- Reset : Gives a new HDFcontainerObject to the HDFexplorer.
HDFexception class provides the mecanism for handling errors returned by other classes.
The member functions of HDFfile class are the following :
- HDFexception : creates a HDFexception object.
The declarations and definitions which must be included with any code which
uses HDF++, are gathered in the HDFOI.hxx include file.
In this section, we describe how to program some operations to :
- Create a HDFfile object and use it to create a new HDF5 file or open an existing one.
- Get some informations about an existing HDF file.
- Create a HDFgroup object and use it to create a new HDF5 group or open an existing one.
- Get some informations about the HDF5 objects that contains an existing HDF5 group.
- Mount and unmount a HDF5 file at the HDFgroup object.
- Create a HDFdataset object and use it to create a new HDF5 dataset or open an
existing one.
- Get some informations about an existing HDF5 dataset.
- Read/write the values of a HDFdataset.
- Create a HDFattribute object and use it to create a new HDF5 attribute or open an
existing one.
- Read/write the value of a HDFattribute.
- Create and use an HDFexplorer object.
This programming model shows how to
- Create a HDFfile object.
- Create a HDF5 file.
- Close a HDF5 file.
- Open a HDF5 file with "Read Only" access mode.
HDFfile *hdf_file;
...
hdf_file = new HDFfile("titi.hdf");
hdf_file->CreateOnDisk();
...
hdf_file->CloseOnDisk();
...
hdf_file->OpenOnDisk(HDF_RDONLY);
hdf_file->CloseOnDisk();
delete hdf_file
This programming model shows how to
- Get the number of HDF5 entities in the file (at the first level).
- Get the name of each internal entities in the file.
n = hdf_file->nInternalObjects();
for (i=0;iInternalObjectIndentify(i,name);
cout << " First Level Internal Object Name : " << name << endl;
}
This programming model shows how to
- Ask if an object is in the file.
if (hdf_file->ExistInternalObject("MESH"))
cout << " The object 'MESH' is in the file " << endl;
This programming model shows how to
- Determine the type of an object
type = hdf_file->InternalObjectType("MESH");
switch (type)
{
case HDF_GROUP :
cout << " Its type is HDF_GROUP" << endl;
break;
case HDF_DATASET :
cout << " Its type is HDF_DATASET" << endl;
break;
}
This programming model shows how to
- Create a new HDFgroup object.
- Create a HDF5 group in the file.
- Close a HDF5 group.
- Open an existing HDF5 group.
HDFgroup *hdf_group;
...
// A new HDF group object
hdf_group = new HDFgroup("MESH",hdf_file);
cout << " A HDFgroup object 'MESH' is created" << endl;
hdf_group->CreateOnDisk();
cout << " The HDF group is created " << endl;
...
hdf_group->CloseOnDisk();
cout << " The HDF group is closed " << endl;
...
hdf_group->OpenOnDisk();
cout << " The group is opened" << endl;
...
hdf_group->CloseOnDisk();
cout << " The HDF group is closed " << endl;
delete hdf_group;
This programming model shows how to
- Get the number of HDF5 entities inside a HDF5 group.
- Get each entity name.
- Get each entity type.
n = hdf_group->nInternalObjects();
for (i=0;i < n; i++)
{
hdf_group->InternalObjectIndentify(i,name);
type = hdf_group->InternalObjectType(name);
cout << " First Level Internal Object Name : " << name << endl;
switch (type)
{
case HDF_GROUP :
cout << " Its type is HDF_GROUP" << endl;
break;
case HDF_DATASET :
cout << " Its type is HDF_DATASET" << endl;
break;
}
}
This programming model shows how to
- Mount and unmount a HDF5 file at a HDFgroup object.
study = new HDFfile("study.hdf");
cout << " The HDFfile object for 'study.hdf' is created" << endl;
study->OpenOnDisk(HDF_RDONLY);
cout << " The file is opened" << endl;
geom = new HDFgroup("GEOM",study);
cout << " The HDFgroup object for 'GEOM' is created" << endl;
geom->FileMount("geom.hdf",HDF_RDONLY);
cout << " 'GEOM' becomes a mounted point for the file 'geom.hdf'" << endl;
geom->OpenOnDisk();
cout << " The group is opened" << endl;
geom1 = new HDFgroup("GEOM_1",geom);
cout << " The HDF group object is created for 'GEOM_1' with 'GEOM' as father" << endl;
cout << " This group is in fact in the file 'geom.hdf'"<OpenOnDisk();
cout << " The group 'GEOM_1' is opened" << endl;
...
geom1->CloseOnDisk();
cout << " The group 'GEOM_1' is closed" << endl;
geom->FileUnMount();
cout << " The file 'geom.hdf' is unmounted from 'GEOM' " << endl;
geom->CloseOnDisk();
study->CloseOnDisk();
delete geom1;
delete geom;
delete study;
This programming model shows how to
- Create a HDFdataset object.
- Create a HDF5 dataset in a HDF5 file.
- Close a HDF5 dataset.
HDFdataset *hdf_dataset;
hdf_size size[1] = 3;
...
hdf_dataset = new HDFdataset("COORDINATES",hdf_group,HDF_FLOAT64,size,1);
cout << " A HDFdataset object 'COORDINATES' is created" << endl;
hdf_dataset->CreateOnDisk();
cout << " The HDF dataset is created" << endl;
...
hdf_dataset->CloseOnDisk();
cout << " The HDF dataset is closed" << endl;
...
delete hdf_dataset;
This programming model shows how to
- Create a HDFdataset object.
- Open an existing HDF5 dataset in a HDF5 file.
- Close a HDF5 dataset.
HDFdataset *hdf_dataset;
...
hdf_dataset = new HDFdataset("COORDINATES",hdf_group);
cout << " The dataset object 'COORDINATES' is created in memory " << endl;
hdf_dataset->OpenOnDisk();
cout << " The dataset 'COORDINATES' is opened " << endl; c
...
hdf_dataset->CloseOnDisk();
cout << " The dataset 'COORDINATES' is closed " << endl;
...
delete hdf_dataset;
This programming model shows how to
- Get the dataset data type.
hdf_type data_type;
...
data_type = hdf_dataset->GetType();
switch(data_type)
{
case HDF_INT32 :
cout << " Type of data : HDF_INT32 " << endl;
break;
case HDF_INT64 :
cout << " Type of data : HDF_INT64 " << endl;
break;
case HDF_FLOAT64 :
cout << " Type of data : HDF_FLOAT64 " << endl;
break;
default :
cout << " Type of data : HDF_STRING " << endl;
}
This programming model shows how to
- Get the dataset dimension number.
- Get each dimension size.
hdf_size *dim;
...
ndim = hdf_dataset->nDim();
cout << " Number of dimensions : " << ndim << endl;
dim = new hdf_size[ndim];
hdf_dataset->GetDim(dim);
for (i = 0;i < ndim;i++)
cout << " Dimension " << i+1 << " of size : " << dim[i] << endl;
...
delete dim;
This programming model shows how to
- Get the dataset storage size.
int size;
...
size = hdf_dataset->GetSize();
This programming model shows how to
- Write values in a dataset.
hdf_dataset->WriteOnDisk(coordinates);
cout << " The HDF dataset is written in the file " << endl;
This programming model shows how to
hdf_float64 *val;
int size;
...
size = hdf_dataset->GetSize();
val = new hdf_float64[size];
hdf_dataset1->ReadFromDisk(val);
delete val;
This programming model shows how to
- Create a HDFattribute object.
- Create a HDF5 attribute in a HDF5 file.
- Close a HDF5 attribute.
- Open an existing attribute in a file.
HDFattribute *hdf_attribute;
...
hdf_attribute = new HDFattribute("ATTRIBUTE",hdf_dataset,HDF_INT32);
cout << " A HDF attribute object is created for hdf_dataset " << endl;
...
hdf_attribute->CreateOnDisk();
cout << " The HDF attribute is created on Disk " << endl;
...
hdf_attribute->CloseOnDisk();
cout << " The HDF attribute closed on" << endl;
...
hdf_attribute->OpenOnDisk();
cout << " The HDF attribute is created on Disk " << endl;
...
hdf_attribute->CloseOnDisk();
cout << " The HDF attribute closed on" << endl;
...
delete hdf_attribute;
This programming model shows how to
- Write/Read a scalar value in a HDF5 attribute.
hdf_attribute->WriteOnDisk(&attribute);
cout << " The HDF attribute is written on Disk " << endl;
hdf_attribute->ReadFromDisk(&attribute);
cout << " The HDF attribute is written on Disk " << endl;
This programming model shows how to
- Create a HDFexplorer object on a HDFContainerObject object (HDFfile or HDFgroup).
- Explore the HDF objects in the HDFcontainerObject.
- Affect a new HDFcontainerObject object in the explorer.
HDFexplorer *explorer;
...
explorer = new HDFexplorer(hdf_file);
cout << " A HDF explorer object is created" << endl;
cout << " File Exploration " << endl;
for (explorer->Init();explorer->More();explorer->Next())
{
object = explorer->Value();
cout << " Name of the object : " <<
object->GetName() << endl;
}
...
cout << " Group exploration" << endl;
explorer->Reset(hdf_group);
for (explorer->Init();explorer->More();explorer->Next())
{
object = explorer->Value();
cout << " Name of the object : " << object->GetName() << endl;
}
...
delete explorer;