Awesome
zarrs_ffi
C/C++ bindings for the zarrs crate, a Rust library for the Zarr storage format for multidimensional arrays and metadata.
zarrs_ffi
is a single header library: zarrs.h
(docs).
Currently zarrs_ffi
only supports a small subset of the zarrs API.
A changelog can be found here.
Example
#include "zarrs.h"
void main() {
// Open a filesystem store pointing to a zarr hierarchy
ZarrsStorage storage = nullptr;
zarrs_assert(zarrsCreateStorageFilesystem("/path/to/hierarchy.zarr", &storage));
// Open an array in the hierarchy
ZarrsArray array = nullptr;
zarrsOpenArrayRW(storage, "/array", metadata, &array);
// Get the array dimensionality
size_t dimensionality;
zarrs_assert(zarrsArrayGetDimensionality(array, &dimensionality));
assert(dimensionality == 2);
// Retrieve the decoded bytes of the chunk at [0, 0]
size_t indices[] = {0, 0};
size_t chunk_size;
zarrs_assert(zarrsArrayGetChunkSize(array, 2, indices, &chunk_size));
std::unique_ptr<uint8_t[]> chunk_bytes(new uint8_t[chunk_size]);
zarrs_assert(zarrsArrayRetrieveChunk(array, 2, indices, chunk_size, chunk_bytes.get()));
}
See a more comprehensive example in the examples directory.
CMake Quickstart
- Install the Rust compiler (and cargo).
- Put Findzarrs.cmake in your
CMAKE_MODULE_PATH
find_package(zarrs <version> REQUIRED COMPONENTS zarrs/bz2)
- Replace
<version>
with the latest release: (e.g.,0.8
or0.8.4
) - zarrs is retrieved from
GitHub
using FetchContent and built using corrosion - Components are optional zarrs codecs
- Replace
- the
zarrs_ffi
library is available as thezarrs::zarrs
orzarrs::zarrs-static
target
A complete CMake
example can be found in examples/cmake_project.
Manual Build
Basic Build
Building generates a header, and a platform-dependent static and dynamic library.
cargo build --release --features cbindgen # -> zarrs.h and target/release/[lib]zarrs_ffi{.a,.so,.dll,.dylib}
zarrs.h
is only re-generated if the cbindgen
feature is enabled.
Enabling SIMD intrinsics
Encoding and decoding performance may be improved with avx2
/sse2
enabled (if supported).
Compile with either of:
RUSTFLAGS="-C target-cpu=native"
RUSTFLAGS="-C target-feature=+avx2,+sse2"
Enabling non-default zarrs codecs
Non-default zarrs
codecs (see zarrs
crate features) can be enabled with the all_codecs
feature.
Alternatively, individual codecs can be enabled by passing them as feature flags.
For example:
cargo build --release --features cbindgen --features zarrs/zstd,zarrs/bitround,zarrs/zfp,zarrs/bz2,zarrs/pcodec,zarrs/gdeflate
Licence
zarrs_ffi
is licensed under either of
- the Apache License, Version 2.0 LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0 or
- the MIT license LICENSE-MIT or http://opensource.org/licenses/MIT, at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.