zarr-vectors-tools

File format workflows, algorithms, and multiresolution for Zarr Vectors.

zarr-vectors-tools is an extension of zarr-vectors-py. It is not a standalone library, and neither this README nor its documentation restates that package's.

zarr-vectors-py owns Zarr Vectors — the specification and the Python API over it: store layout, chunk and bin geometry, fragments, links, the object model, resolution-level metadata, validation, and the two supported surfaces zarr_vectors.api and zarr_vectors.building. Anything about the format or the core API is documented there and only there.

This package adds the layers built on top of it: format-conversion workflows wrapping third-party readers and writers, streaming graph and mesh algorithms, the rich multiresolution coarsening layer, and the zvtools CLI.

Zarr Vectors was originally specified by Forrest Collman, Allen Institute for Brain Sciences.

Install

pip install zarr-vectors-tools

Python ≥ 3.11. Every file format is gated behind an extra, so a base install stays slim:

pip install "zarr-vectors-tools[trk]"           # nibabel (TRK)
pip install "zarr-vectors-tools[streamlines]"   # nibabel + trx-python
pip install "zarr-vectors-tools[all]"           # everything except gpu

Extras: las, ply, trk, trx, streamlines, graph, points-enrichment, mesh, precomputed, parallel, gpu, all, dev.

Quick start

From the terminal:

zvtools convert cells.csv cells.zarrvectors --chunk-shape 100,100,100
zvtools pyramid cells.zarrvectors --coarsen 8,8 --sparsity 2,2
zvtools convert cells.zarrvectors cells.ply --level 1   # and back out again
zvtools merge cells.zarrvectors more_cells.csv       # append, don't replace
zvtools split cells.zarrvectors parts/ --by groups
zvtools info cells.zarrvectors
zvtools validate cells.zarrvectors --level 3

From Python — note that convert.ingest and convert.export have no re-exports, so import from the concrete module:

from zarr_vectors_tools.convert.ingest.csv_points import ingest_csv
from zarr_vectors_tools.multiresolution.coarsen import build_pyramid
from zarr_vectors_tools.algorithms import compute_connected_components

ingest_csv("cells.csv", "cells.zarrvectors", chunk_shape=(100.0, 100.0, 100.0))
build_pyramid("cells.zarrvectors", factors=[(8.0, 2.0), (8.0, 2.0)])

What's in it

Coarsening and sparsity are two orthogonal axes — coarsening reduces vertices within each object, sparsity drops whole objects while preserving the IDs of survivors. See Coarsening versus sparsity.

Development

git clone https://github.com/AllenInstitute/zarr-vectors-tools
cd zarr-vectors-tools
pip install -e ".[all,dev]"
pytest

Build the docs locally:

pip install -r docs/requirements-docs.txt
python -m sphinx -b html docs docs/_build/html

License

BSD-3-Clause.