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

GDAL files

Defined in xtensor-io/xgdal.hpp

template<typename T>
xtensor<T, 3> xt::load_gdal(const std::string &file_path, load_gdal_options options = {})

Load pixels from a GDAL dataset.

Return

pixels; band sequential by default, but index order is controlled by options.

Template Parameters

  • T: the type of pixels to return. If it doesn’t match the content of the raster, GDAL will silently cast to this data type (which may cause loss of precision).

Parameters

  • file_path: the file to open.

  • options: options to use when loading.

template<typename T>
xtensor<T, 3> xt::load_gdal(GDALDatasetH dataset, load_gdal_options options = {})

Load pixels from an opened GDAL dataset.

Return

pixels; band sequential by default, but index order is controlled by options.

Template Parameters

  • T: in type of pixels to return. If this doesn’t match the content of the dataset, GDAL will silently cast to this data type (which may cause loss of precision).

Parameters

  • dataset: an opened GDAL dataset.

  • options: options to used when loading.

struct xt::load_gdal_options

Options for loading a GDAL dataset.

Public Functions

load_gdal_options()

Load every band and return band-sequential memory (index order = [band, row, column]).

Public Members

layout interleave

The desired layout of the returned tensor - defaults to band sequential([band, row, col]).

Arbitrary index order is supported, like band interleaved by pixel ([row, col, band]).

std::vector<int> bands_to_load

The indices of bands to read from the dataset.

All bands are read if empty.

Remark

Per GDAL convention, these indices start at one (not zero).

std::function<void(const std::string&)> error_handler

The error handler used to report errors (like file missing or a read fails).

By default, a std::runtime_error is thrown when an error is encountered

template<typename T>
GDALDatasetH xt::dump_gdal(const xexpression<T> &e, const std::string &path, dump_gdal_options options = {})

Dump a 2D or 3D xexpression to a GDALDataset.

Return

nullptr by default, or, an open dataset if dump_gdal_options.return_opened_dataset (user must close).

Parameters

  • e: data to dump; must evaluate to a 2D or 3D shape.

  • path: where to save the data.

  • options: options to use when dumping.

struct dump_gdal_options

Options for dumping a GDAL dataset.

xfile_array

Defined in xtensor-io/xfile_array.hpp

template<class E, class IOH>
class xfile_array_container : public xaccessible<xfile_array_container<E, IOH>>, public xiterable<xfile_array_container<E, IOH>>, public xcontainer_semantic<xfile_array_container<E, IOH>>

Dense multidimensional file-backed cached container with tensor semantic.

The xfile_array_container class implements a dense multidimensional container with tensor semantic, stored on a file system. It acts as a file-backed cached container, allowing for data persistence.

See

xchunk_store_manager

Template Parameters

  • E: The type of the container holding the elements

  • IOH: The type of the IO handler (e.g. xio_disk_handler)

using xt::xfile_array = xfile_array_container<xarray<T, L, A, SA>, IOH>

xchunk_store_manager

Defined in xtensor-io/xchunk_store_manager.hpp

template<class EC, class IP = xindex_path>
class xchunk_store_manager : public xaccessible<xchunk_store_manager<EC, IP>>, public xiterable<xchunk_store_manager<EC, IP>>

Multidimensional chunk container and manager.

The xchunk_store_manager class implements a multidimensional chunk container. Chunks are managed in a pool, allowing for a limited number of chunks that can simultaneously be hold in memory, by swapping chunks when the pool is full. Should not be used directly, instead use chunked_file_array factory functions.

Template Parameters

  • EC: The type of a chunk (e.g. xfile_array)

  • IP: The type of the index-to-path transformer (default: xindex_path)

chunked_file_array

Defined in xtensor-io/xchunk_store_manager.hpp

Warning

doxygenfunction: Unable to resolve multiple matches for function “xt::chunked_file_array” with arguments (()) in doxygen xml output for project “xtensor-io” from directory: ../xml. Potential matches: 

- template<class IOH, layout_type L = XTENSOR_DEFAULT_LAYOUT, class IP = xindex_path, class EXT = empty_extension, class E, class S> xchunked_array<xchunk_store_manager<xfile_array<typename E::value_type, IOH, L>, IP>, EXT> chunked_file_array(const xexpression<E> &e, S &&chunk_shape, const std::string &path, std::size_t pool_size = 1, layout_type chunk_memory_layout = XTENSOR_DEFAULT_LAYOUT)
- template<class IOH, layout_type L = XTENSOR_DEFAULT_LAYOUT, class IP = xindex_path, class EXT = empty_extension, class E> xchunked_array<xchunk_store_manager<xfile_array<typename E::value_type, IOH, L>, IP>, EXT> chunked_file_array(const xexpression<E> &e, const std::string &path, std::size_t pool_size = 1, layout_type chunk_memory_layout = XTENSOR_DEFAULT_LAYOUT)
- template<class T, class IOH, layout_type L = XTENSOR_DEFAULT_LAYOUT, class IP = xindex_path, class EXT = empty_extension, class S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>, EXT> chunked_file_array(S &&shape, S &&chunk_shape, const std::string &path, const T &init_value, std::size_t pool_size = 1, layout_type chunk_memory_layout = XTENSOR_DEFAULT_LAYOUT)
- template<class T, class IOH, layout_type L = XTENSOR_DEFAULT_LAYOUT, class IP = xindex_path, class EXT = empty_extension, class S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>, EXT> chunked_file_array(S &&shape, S &&chunk_shape, const std::string &path, std::size_t pool_size = 1, layout_type chunk_memory_layout = XTENSOR_DEFAULT_LAYOUT)