HDF4CPP

HDF4CPP

Introduction

The HDF4CPP library is a wrapper library of the hdf4 C interfaces. The target was to create a common c++ api to read and write hdf scientific data. The library only supports reading of the data at the moment.

API overview

The idea

The idea is to use objects and their methods to do the operations. These classes are representing different kind of data, so the operation functions are separated. Only reading is supported right now.

Classes and objects

HdfObject - the base class of all the classes

HdfFile - represents an hdf file

HdfItem - represents an item (SData, VGroup, VData)

                - you can get from a file, calling its get function

HdfAttribute - represents an attribute of an item or of a file

                - you can get from a file or from an item, calling its getAttribute function

How does it work?

Include the library

You have to include a single file.

#include <hdf4cpp/hdf.h>

Open an file

hdf4cpp::HdfFile file("/path/to/the/file");

Get an item, an attribute

hdf4cpp::HdfAttribute fileAttr = file.getAttribute("file attribute name");
hdf4cpp::HdfItem item = file.get("item name");
hdf4cpp::HdfAttribute itemAttr = item.getAttribute("item attribute name");

Get all the items with a specific name

std::vector<hdf4cpp::HdfItem> items = file.getAll("items name");

Object type

Every kind of hdf data (SData, Vgroup, Vdata) stores different structures. These information must be read in a different way, we have to call different methods.

So we get the type of the object just to be sure that we want to read the data in a correct way.

switch(item.getType()) {
    case hdf4cpp::SDATA:
        // reading the sdata
    case hdf4cpp::VDATA:
        // reading the vdata
    default:
        std::cerr << "data is not readable";
        // note: VGroup has no data to be read
}

Reading the data

The HdfItem objects have a read function but overridden for every reading procedure. The first parameter is a vector in every case, in which the data will be stored.

Reading SData

You have two possibilities.

1. You can read the entire data.

   std::vector<int> vec;
   item.read(vec);
   

2. You can read the data in a specific range.

   std::vector<int> vec;
   std::vector<hdf4cpp::Range> ranges;
   // We have to specify the range for every dimension
   for(size_t i = 0; i < number_of_dimensions; ++i) {
   ranges.push_back(hdf4cpp::Range(begin, quantity, stride));
   // begin - the first index which is included in the range
   // quantity - the number of value to be read
   // stride - reading pattern (1 : every element, 2 : every second element, ...)
   // stride has a default value (1 : every element)
   }
   item.read(vec, ranges);
   

Reading VData

You have to specify:

• which field do you want to read
• how many records do you want to read

1. Reading scalar data

The data can be scalar: a field has only one value for every record.

std::vector<int> vec;
item.read(vec, "field_name", number_of_records);

1. Reading array data

The data can be array: a field has multiple values for every record. For example: if a field's type is string, it is considered that every record has multiple character values (character array).

// Reading string field
std::vector<std::vector<char> > vec;
item.read(vec, "field_name"); // the number_of_records it can be eliminated if I want to read all the records
// Getting the string vector
std::vector<std::string> string_vec;
for(const auto& char_vec : vec) {
    string_vec.push_back(char_vec.data());
}

Note: The library does a type size check, and throws an exception in case of mismatch.

Reading attribute data

The HdfAttribute objects have a read function which receives a vector reference. Here will be the data stored.

std::vector<short> vec;
attribute.get(vec);

Note: The library does a type size check, and throws an exception in case of mismatch.

Exception mechanism

The library throws an HdfException on any errors. This specific exception has getType and getClassType methods, just to get information about the thrower object. Has a getExceptionType which returns information about the type of the exception, and a getMessage method which returns a message as string.

Supported compilers

g++
clang++
msvc

Build instructions

The hdf4 C library is needed to build this project.

mkdir build
cd build
cmake ..
cmake --build .

Note: on windows you need to point cmake to your hdf4-C installation. This can be done using -DCMAKE_PREFIX_PATH=<path/to/hdf4>.

Install

First build as above, then run:

cmake --build . --target install

Note: you can use -DCMAKE_INSTALL_PREFIX=<path> in the previous cmake call to change the install location.

Generating documentation

1. Generating the user documentation. It includes documentation which is necessary for using this library.

   cmake --build . --target docs_user
   

2. Generating the whole documentations.

   cmake --build . --target docs_all