API Reference¶

NPZ files¶

Defined in xtensor-io/xnpz.hpp

inline 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>();)

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

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.

Parameters

filename – The npz filename
search_varname – The array name to be loaded

Returns

xarray with the contents of the loaded array

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.

Parameters: filename – The path of the file to load
Returns: 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).

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.

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

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> inline 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.

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)

Returns

dataset the newly created HighFive::DataSet (e.g. to add an attribute)

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

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

Parameters

file – opened HighFive::File (has to be writeable)
path – path of the DataSet

Returns

data the read data

Warning

doxygenfunction: Unable to resolve function “xt::dump” with arguments (HighFive::File&, const std::string&, const xt::xarray<T>&, xt::dump_mode) in doxygen xml output for project “xtensor-io” from directory: ../xml. Potential matches:

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

Warning

doxygenfunction: Unable to resolve function “xt::dump” with arguments (HighFive::File&, const std::string&, const xt::xtensor<T, rank>&, xt::dump_mode) in doxygen xml output for project “xtensor-io” from directory: ../xml. Potential matches:

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

Warning

doxygenfunction: Unable to resolve function “xt::dump” with arguments (HighFive::File&, const std::string&, const std::vector<T>&, xt::dump_mode) in doxygen xml output for project “xtensor-io” from directory: ../xml. Potential matches:

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

template<class T> inline 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.

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)

Returns

dataset the newly created HighFive::DataSet (e.g. to add an attribute)

template<class T> inline 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.

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

Returns

dataset the (newly created) HighFive::DataSet (e.g. to add an attribute)

template<class T> inline 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.

Parameters

file – opened HighFive::File (has to be writeable)
idx – the indices to load
path – path of the DataSet

Returns

data the read data

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

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

Parameters

file – opened HighFive::File (has to be writeable)
path – path of the DataSet

Returns

data the read data

inline 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

Warning

doxygenfunction: Unable to resolve function “xt::extensions::create_group” with arguments (const HighFive::File&, const std::string&) in doxygen xml output for project “xtensor-io” from directory: ../xml. Potential matches:

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

inline 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.

Parameters

file – opened HighFive::File
path – path of the DataSet

Returns

size the size of the HighFive::DataSet

inline 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.

Parameters

file – opened HighFive::File
path – path of the DataSet

Returns

shape the shape of the HighFive::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.

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.

Returns

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

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

Load pixels from an opened GDAL dataset.

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.

Returns

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

struct xt::load_gdal_options¶

Options for loading a GDAL dataset.

Public Functions

inline 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.

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.

Returns

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

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

tparam E: The type of the container holding the elements
tparam 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.

tparam EC: The type of a chunk (e.g. xfile_array)
tparam 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 function “xt::chunked_file_array” with arguments None 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 E, class S> xchunked_array<xchunk_store_manager<xfile_array<typename E::value_type, IOH, L>, IP>> 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 E> xchunked_array<xchunk_store_manager<xfile_array<typename E::value_type, IOH, L>, IP>> 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 S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>> 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 S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>> 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)
- template<class T, class IOH, layout_type L = XTENSOR_DEFAULT_LAYOUT, class IP = xindex_path, class S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>> chunked_file_array(std::initializer_list<S> shape, std::initializer_list<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 S> xchunked_array<xchunk_store_manager<xfile_array<T, IOH, L>, IP>> chunked_file_array(std::initializer_list<S> shape, std::initializer_list<S> chunk_shape, const std::string &path, std::size_t pool_size = 1, layout_type chunk_memory_layout = XTENSOR_DEFAULT_LAYOUT)