Specification

This section is the authoritative reference for the Zarr Vector Format (ZVF) as implemented in zarr-vectors-py. It is written to serve two audiences simultaneously:

  • Users who want to understand precisely what the format does and why, so they can make informed decisions about chunk sizes, metadata, and resolution pyramids.

  • Contributors who want to implement new geometry types, extend the validation suite, or propose changes to the format itself.

Each page follows a consistent structure: a Terms section defining all vocabulary used on that page, a plain-English Introduction, and a detailed Technical reference section with schemas, pseudocode, and worked examples.

Design goals

ZVF was designed to satisfy the following constraints simultaneously:

Cloud-native random access. Spatial queries should require only the minimum number of I/O operations, whether the store is on a local file system or in an object store (S3, GCS). This is achieved through spatial chunking at the chunk level and sub-chunk indexing at the bin level.

Multi-resolution out of the box. Viewers that render large-scale 3-D data (Neuroglancer, napari, custom WebGL) need coarser representations for overview rendering. ZVF encodes resolution pyramids natively, with OME-Zarr-compatible metadata so any NGFF-aware viewer can discover them.

Geometry-type agnostic layout. Points, streamlines, graphs, and meshes all use the same spatial chunking layout. This means a single I/O layer handles all types; type-specific logic lives only in the arrays present within each chunk group (e.g. meshes have a links/<delta> array that point clouds do not).

Format transparency. A ZVF store is a plain Zarr v3 directory tree. No binary wrapper, no proprietary codec required for the base format. Every array can be opened with the standard zarr library.

Contributor-accessible. The format is fully documented in this spec so that an external contributor can implement a compliant reader, writer, or validator without access to the original authors.

Relationship to upstream specifications

Specification

Relationship

Zarr v3 core spec

ZVF stores are valid Zarr v3 stores. All array storage, codec, and metadata conventions are inherited from Zarr v3.

OME-Zarr NGFF

ZVF borrows the multiscales JSON block for resolution pyramid metadata. ZVF-specific keys are additive extensions.

Allen Institute ZVF spec

The original specification by Forest Collman. zarr-vectors-py implements and extends this spec.

Neuroglancer precomputed

A related format for static Neuroglancer hosting. See comparison.

TRX format

A streamline-specific format. See comparison.

Specification sections