Constants

Geometry type string constants. Import these instead of using raw strings to ensure forward-compatibility if constant values change.

Format constants for the Zarr Vectors (ZV) format.

These are the canonical names, prefixes, and default values used throughout the specification. Changing a value here changes it everywhere in the package.

zarr_vectors.constants.CAP_FRAGMENT_INDEX: str = 'fragment_index'

The store uses the v0.6 fragment-index encoding for vertex_fragments and link_fragments (single uint8 blob per chunk; see zarr_vectors.encoding.fragments).

Store uses the 0.4 multiscale links layout (links/<delta>/, cross_chunk_links/<delta>/, link_attributes/<name>/<delta>/ and cross_chunk_link_attributes/<name>/<delta>/) and may contain cross-pyramid-level edges (delta != 0).

zarr_vectors.constants.CAP_PRESERVED_OBJECT_IDS: str = 'preserved_object_ids'

At least one resolution level was written with ID-preserving sparsification (preserves_object_ids=True on the level metadata). Dropped objects appear as empty manifest slots and zero present_mask bytes; parent_level carries semantic weight.

zarr_vectors.constants.CAP_SHARED_FRAGMENTS: str = 'shared_fragments'

At least one resolution level stores per-chunk fragments that may be referenced by multiple objects’ manifests (the v0.6 successor to shared_vertex_groups; the sharing primitive is now a fragment rather than a contiguous-byte vertex group).

zarr_vectors.constants.COARSEN_PER_OBJECT: str = 'per_object'

each surviving object’s vertices are aggregated into bin centroids (metavertices). Metavertices may be shared between objects; OIDs are preserved across levels.

Type:

Per-object pyramid

zarr_vectors.constants.DEFAULT_AXES_NAMES: tuple[str, ...] = ('x', 'y', 'z', 'w')

Default axis names used when create_store is called without an explicit axes kwarg. Indexed by sid_ndim (1 → ("x",), 2 → ("x", "y"), …). Stops at 4 dims; higher-dim stores must pass axes explicitly.

zarr_vectors.constants.DEFAULT_BIN_RATIO: tuple[int, ...] = (1, 1, 1)

Bin ratio at level 0 (no downsampling).

zarr_vectors.constants.DEFAULT_BOUNDS_SIDE: float = 128.0

Default per-dimension extent for a freshly-warmed store. When create_store(path) is called with no bounds kwarg, the store is created with bounds = ([0,...,0], [128,...,128]) for the resolved sid_ndim. Out-of-bounds writes raise unless an out_of_bounds= policy is supplied by the caller.

zarr_vectors.constants.DEFAULT_CROSS_LEVEL_DEPTH: int = 1

emit ±1 cross-level link arrays at every adjacent level pair. 0 disables, -1 means all available pyramid levels.

Type:

Default cross_level_depth

zarr_vectors.constants.DEFAULT_CROSS_LEVEL_STORAGE: str = 'explicit'

materialize both +N (at the finer level) and -N (at the coarser level).

Type:

Default cross_level_storage

zarr_vectors.constants.DEFAULT_OOB_POLICY: str = 'raise'

Default out_of_bounds policy applied by the top-level write functions when the caller does not specify one. Values: "raise" (reject the write), "ignore" (silently drop out-of-bounds vertices), "expand" (grow store bounds to include the new data).

zarr_vectors.constants.DEFAULT_REDUCTION_FACTOR: int = 8

only emit a new resolution level when vertex count drops by 8×.

Type:

Default

zarr_vectors.constants.FORMAT_VERSION: str = '0.7.0'

Current ZV specification version.

0.7.0: per-level chunk_shape. RootMetadata.chunk_shape remains the level-0 default; LevelMetadata gains an optional chunk_shape field that, when set, overrides root for that level. Required invariant: per-level chunk_shape must be a positive integer multiple of the root chunk_shape along every axis (nested chunk grids). This lets coarser pyramid levels use larger chunks the way OME-Zarr image pyramids grow physical chunk extent via voxel-size scaling. Cross-level link arrays keep the single-chunk-key convention; the differing level’s chunk coord is computed by integer division using the per-level chunk_shape ratio. Hard break: 0.6.x stores are not readable; rewrite from source.

0.6.0: fragment-index schema. Replaces vertex_group_offsets with vertex_fragments and splits the v0.5 inline-header link blob into a flat links/0/<chunk> payload plus a sibling link_fragments/<chunk> group. The fragment-index byte layout expresses each per-group boundary as either a contiguous index range [start, count) or an explicit list of row indices, supporting vertex re-use across fragments. object_index/data now uses a per-chunk manifest-block format with single / range / explicit modes; cross-level link arrays (cross_chunk_links, delta != 0) are unchanged. Hard break: 0.5.x stores are not readable; rewrite from source.

0.5.0: NGFF-alignment cleanup + format simplification. The 0.5 series went through several on-disk simplifications without a version bump (consumers should pin to a specific point release):

  • vertex_counts/ per-chunk sidecars removed; per-chunk vertex counts are derived from vertex_group_offsets and the vertices/<key> blob size.

  • vertex_group_offsets/<key> is a plain (K,) int64 array of vertex byte offsets (the legacy (K, 2) paired layout with a link-offset column is gone).

  • attributes/<name>/<key>_offsets sibling blobs removed. Attribute groups align 1:1 with vertex groups; per-group byte offsets are computed at read time.

  • metanode_children/ removed. Pyramid drill-down uses the links/<+1>/ + cross_chunk_links/<+1>/ arrays emitted inline during coarsening (mirrored as -1 on the coarse side under cross_level_storage="explicit").

  • cross_chunk_faces/ removed. Cross-chunk face identity uses cross_chunk_links/<delta>/ with link_width=3. The cross_chunk_links array carries a link_width metadata field (default 2 for edges).

  • object_index/pending/ staging tree removed. Incremental writes go directly into object_index/; transactional backends (icechunk) make this cheap.

Earlier 0.5 changes (now baseline): renamed format_version to zv_version, moved axes to multiscales[0].axes, dropped per-array dtype duplication.

0.4.1: bare-integer resolution-level group names (0/, 1/).

Per-chunk fragment-index group describing how rows of links/0/<chunk> group into fragments. Exists at delta == 0 only; cross-level link arrays keep their inline self-describing header.

zarr_vectors.constants.PARAMETRIC_GROUP: str = 'parametric'

Name of the root-level parametric objects group.

zarr_vectors.constants.RESOLUTION_PREFIX: str = ''

Empty under the 0.4.1 layout — resolution level groups are bare integer names (0, 1, …) to mirror OME-Zarr’s convention. Retained as a symbol so callers that build paths via f"{RESOLUTION_PREFIX}{n}" keep working without import churn.

zarr_vectors.constants.VERTEX_FRAGMENTS: str = 'vertex_fragments'

Per-chunk fragment-index group describing how rows of vertices/<chunk> group into fragments. See zarr_vectors.encoding.fragments.

Geometry type constant values

Constant

Value

Use

GEOM_POINT_CLOUD

"point_cloud"

Unconnected vertices

GEOM_LINE

"line"

Independent line segment pairs

GEOM_POLYLINE

"polyline"

Ordered vertex paths

GEOM_STREAMLINE

"streamline"

Tractography paths with metadata

GEOM_GRAPH

"graph"

Arbitrary vertex–edge graph

GEOM_SKELETON

"skeleton"

Tree-structured morphology (SWC-compatible)

GEOM_MESH

"mesh"

Triangulated surface mesh