/xtensor-io

xtensor plugin to read and write images, audio files, numpy (compressed) npz and HDF5

Primary LanguageC++BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

xtensor-io

Azure Pipelines ReadTheDocs Binder Join the Gitter Chat

Reading and writing image, sound and npz file formats to and from xtensor data structures.
Try it live in the browser!

Introduction

xtensor-io offers an API to read and write various file formats into xtensor data structures:

  • images,
  • audio files,
  • NumPy's compressed storage format (NPZ),
  • HDF5 files,
  • Blosc.

xtensor-io wraps the OpenImageIO, libsndfile, zlib, HighFive, and blosc libraries.

Installation

xtensor-io is a header-only library. We provide a package for the mamba (or conda) package manager.

mamba install xtensor-io -c conda-forge
  • xtensor-io depends on xtensor ^0.25.0.

  • OpenImageIO, libsndfile, zlib, HighFive, and blosc are optional dependencies to xtensor-io

    • OpenImageIO is required to read and write image files.
    • libsndfile is required to read and write sound files.
    • zlib is required to load NPZ files.
    • HighFive (and the HDF5 library) is required to read and write HDF5 files.
    • blosc is required to read and write Blosc files.

All five libraries are available for the conda package manager.

You can also install xtensor-io from source:

mkdir build
cd build
cmake ..
make
sudo make install

Trying it online

To try out xtensor-io interactively in your web browser, just click on the binder link:

Binder

Documentation

To get started with using xtensor-io, check out the full documentation

http://xtensor-io.readthedocs.io/

Usage

// loads png image into xarray with shape HEIGHT x WIDTH x CHANNELS
auto img_arr = xt::load_image("test.png");

// write xarray out to JPEG image
xt::dump_image("dumptest.jpg", img_arr + 5);

// load npz file containing multiple arrays
auto npy_map = xt::load_npz("test.npz");

auto arr_0 = npy_map["arr_0"].cast<double>();
auto arr_1 = npy_map["arr_1"].cast<unsigned long>();

// open a wav file
auto audio = xt::load_audio("files/xtensor.wav");
auto& audio_arr = std::get<1>(audio); // audio contents (like scipy.io.wavfile results)

// save a sine wave sound
int freq = 2000;
int sampling_freq = 44100;
double duration = 1.0;

auto t = xt::arange(0.0, duration, 1.0 / sampling_freq);
auto y = xt::sin(2.0 * xt::numeric_constants<double>::PI * freq * t);

xt::dump_audio("files/sine.wav", y, sampling_freq);

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the LICENSE file for details.