datraw 1.1.0

datraw

This is a C++ header-only reimplementation of VIS's datraw library for volumetric data. The data sets are split in two files, the dat file containing a textual description of the data and the raw file which contains the actual volumetric data without any meta information.

The dat file

The dat file holds properties describing the raw data. Each property must be in a separate line. The name of the property and its value are separated by a colon (":").

In principle, arbitrary properties can be stored. However, some properties have special meaning and some are considered to be required. The well-known properties are:

The raw file

The raw file stores binary data as an M-dimensional array of N-dimensional tuples. All elements of the tuple need to have the same type.

Usage

In order to use the library in your project, add the datraw folder to the list of #include directories. Add #include "datraw.h". All other files are included via this file.

The library represents the dat file in the info class and provides access to the raw file(s) by means of the raw_reader class. The raw_reader can either be created from the path to a dat file or from an existing in-memory info instance. An info object can be parsed from the path to a dat file or from an in-memory string (e.g. if the data have been received from the network).

All classes are templated with the character type (char or wchar_t) and are located in the datraw namespace.

The following example shows the minimal example for iterating over all time steps in the data set described by "foot.dat":

#include "datraw.h"

typedef datraw::raw_reader<char> reader;

auto r = reader::open("foot.dat");
while (r) {
    std::vector<datraw::uint8> raw = r.read_current();
    r.move_next();
}

The variant with an explicit instance of the info class looks like:

#include "datraw.h"

typedef datraw::info<char> info;
typedef datraw::raw_reader<char> reader;

auto info = info::load("foot.dat");
reader r(info);
for (std::uint64_t i = 0; i < info.time_steps(); ++i) {
    r.move_to(i);
    assert(r);
    std::vector<datraw::uint8> raw = r.read_current();
}

There is a zero-copy overload of raw_reader::read_current which uses a user-provided buffer and returns the required buffer size. It can be used as follows:

#include "datraw.h"

typedef datraw::raw_reader<char> reader;

std::vector<datraw::uint8> frame;

auto r = reader::open("foot.dat");
while (r) {
    frame.resize(r.read_current(nullptr, 0));
    r.read_current(frame.data(), frame.size());
    r.move_next();
}