API Reference

NPZ files

Defined in xtensor-io/xnpz.hpp

auto xt::load_npz(std::string filename)

Loads a npz file.

This function returns a map. The individual arrays are not casted to a specific file format. This has to be done before they can be used as xarrays (e.g. auto arr_0 = npz_map["arr_0"].cast<double>();)

Return
returns a map with the stored arrays. Array names are the keys.
Parameters
  • filename: The filename of the npz file

template<class T>
xarray<T> xt::load_npz(std::string filename, std::string search_varname)

Loads a specific array indicated by search_varname from npz file.

All other data in the npz file is ignored.

Return
xarray with the contents of the loaded array
Parameters
  • filename: The npz filename
  • search_varname: The array name to be loaded

template<class E>
void xt::dump_npz(std::string filename, std::string varname, const xt::xexpression<E> &e, bool compression = false, bool append_to_existing_file = true)

Save a xarray or xtensor to a NPZ file.

If a npz file with filename exists already, the new data is appended to the existing file by default. Note: currently no checking of name-collision is performed!

Parameters
  • filename: filename to save to
  • varname: desired name of the variable
  • e: xexpression to save
  • compression: true enables compression, otherwise store uncompressed (default false)
  • append_to_existing_file: If true, appends new data to existing file

Images

Defined in xtensor-io/ximage.hpp

template<class T = unsigned char>
xarray<T> xt::load_image(std::string filename)

Load an image from file at filename.

Storage format is deduced from file ending.

Return
xarray with image contents. The shape of the xarray is HEIGHT x WIDTH x CHANNELS of the loaded image, where CHANNELS are ordered in standard R G B (A).
Parameters
  • filename: The path of the file to load

template<class E>
void xt::dump_image(std::string filename, const xexpression<E> &data, dump_image_options const &options = dump_image_options())

Save image to disk.

The desired image format is deduced from filename. Supported formats are those supported by OpenImageIO. Most common formats are supported (jpg, png, gif, bmp, tiff). The shape of the array must be HEIGHT x WIDTH or HEIGHT x WIDTH x CHANNELS.

Parameters
  • filename: The path to the desired file
  • data: Image data
  • options: Pass a dump_image_options object to fine-tune image export

Audio files

Defined in xtensor-io/xaudio.hpp

template<class T = short>
auto xt::load_audio(std::string filename)

Read a WAV or OGG file This function reads a WAV file at filename.

Return
tuple with (samplerate, xarray holding the data). The shape of the xarray is FRAMES x CHANNELS.
Parameters
  • filename: File to load.
Template Parameters
  • T: select type (default: short, 16bit)

template<class E>
void xt::dump_audio(std::string filename, const xexpression<E> &data, int samplerate, int format = SF_FORMAT_WAV | SF_FORMAT_PCM_16)

Save an xarray in WAV or OGG sound file format Please consult the libsndfile documentation for more format flags.

Parameters
  • filename: save under filename
  • data: xarray/xexpression data to save
  • samplerate: The samplerate of the data
  • format: select format (see sndfile documentation). Default is 16 bit PCM WAV format.

HDF5 files

Defined in xtensor-io/xhighfive.hpp

template<class T>
void xt::dump_hdf5(const std::string &fname, const std::string &path, const T &data, xt::file_mode fmode = xt::file_mode::create, xt::dump_mode dmode = xt::dump_mode::create)

Write field to a new DataSet in an HDF5 file.

Return
dataset the newly created HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • dmode: DataSet-write mode (xt::dump_mode::create | xt::dump_mode::overwrite)

template<class T>
auto xt::load_hdf5(const std::string &fname, const std::string &path)

Load a DataSet in an open HDF5 file to an object (templated).

Return
data the read data
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet

template<class T>
HighFive::DataSet xt::dump(HighFive::File &file, const std::string &path, const xt::xarray<T> &data, xt::dump_mode dmode = xt::dump_mode::create)

Write “xt::xarray<T>” to a new DataSet in an open HDF5 file.

Return
dataset the newly created HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • dmode: DataSet-write mode (xt::dump_mode::create | xt::dump_mode::overwrite)

template<class T, std::size_t rank>
HighFive::DataSet xt::dump(HighFive::File &file, const std::string &path, const xt::xtensor<T, rank> &data, xt::dump_mode dmode = xt::dump_mode::create)

Write “xt::xtensor<T,rank>” to a new DataSet in an open HDF5 file.

Return
dataset the newly created HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • dmode: DataSet-write mode (xt::dump_mode::create | xt::dump_mode::overwrite)

template<class T>
HighFive::DataSet xt::dump(HighFive::File &file, const std::string &path, const std::vector<T> &data, xt::dump_mode dmode = xt::dump_mode::create)

Write “std::vector<T>” to a new DataSet in an open HDF5 file.

Return
dataset the newly created HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • dmode: DataSet-write mode (xt::dump_mode::create | xt::dump_mode::overwrite)

template<class T>
HighFive::DataSet xt::dump(HighFive::File &file, const std::string &path, const T &data, xt::dump_mode dmode = xt::dump_mode::create)

Write scalar/string to a new DataSet in an open HDF5 file.

Return
dataset the newly created HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • dmode: DataSet-write mode (xt::dump_mode::create | xt::dump_mode::overwrite)

template<class T>
HighFive::DataSet xt::dump(HighFive::File &file, const std::string &path, const T &data, const std::vector<std::size_t> &idx)

Write a scalar to a (new, extendible) DataSet in an open HDF5 file.

Return
dataset the (newly created) HighFive::DataSet (e.g. to add an attribute)
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet
  • data: the data to write
  • idx: the indices to which to write

template<class T>
auto xt::load(const HighFive::File &file, const std::string &path, const std::vector<std::size_t> &idx)

Load entry “{i,…}” from a DataSet in an open HDF5 file to a scalar.

Return
data the read data
Parameters
  • file: opened HighFive::File (has to be writeable)
  • idx: the indices to load
  • path: path of the DataSet

template<class T>
auto xt::load(const HighFive::File &file, const std::string &path)

Load a DataSet in an open HDF5 file to an object (templated).

Return
data the read data
Parameters
  • file: opened HighFive::File (has to be writeable)
  • path: path of the DataSet

bool xt::extensions::exist(const HighFive::File &file, const std::string &path)

Check if a path exists (is a Group or DataSet) in an open HDF5 file.

Parameters
  • file: opened HighFive::File
  • path: path of the Group/DataSet

void xt::extensions::create_group(HighFive::File &file, const std::string &path)

Recursively create groups in an open HDF5 file such that a DataSet can be created.

For example if the path = “/path/to/dataset”, this function will create the groups “/path” and “/path/to”.

Parameters
  • file: opened HighFive::File
  • path: path of the DataSet

std::size_t xt::extensions::size(const HighFive::File &file, const std::string &path)

Get the size of an existing DataSet in an open HDF5 file.

Return
size the size of the HighFive::DataSet
Parameters
  • file: opened HighFive::File
  • path: path of the DataSet

std::vector<std::size_t> xt::extensions::shape(const HighFive::File &file, const std::string &path)

Get the shape of an existing DataSet in an open HDF5 file.

Return
shape the shape of the HighFive::DataSet
Parameters
  • file: opened HighFive::File
  • path: path of the DataSet