neu_vol.ops.occupancy

Where a sparse volume’s data actually is: occupied chunks, covered by maximal boxes.

Analysis, not presentation: boxes in level-0 voxels, zyx. neu-glance bboxes turns them into a layer; ops.relabel, ops.maskvalue and --sparse use them directly. The boxes come from the volume itself, in three steps, cheapest first:

1. Which chunk objects exist. TensorStore never persists an all-fill chunk, so the present keys are the occupied footprint. No voxel reads.

2. Cover the occupied cells with maximal boxes. Connected components would merge two regions written face to face.

3. Tighten each box to its nonzero voxels at a coarse level, nearly free, quantized to one coarse voxel. Raise tighten_level for cheaper, 0 for exact.

Attributes

ZARR_METADATA

Exceptions

NoOccupancy

No chunk key under the level's prefix could be read as a chunk index.

Functions

labeled_regions(volume, *[, level, tighten_level, fmt]) → tuple[list[dict], dict]	Occupied boxes of volume, in level-0 voxels, zyx, plus a context dict.
maximal_boxes(cells) → list[tuple[tuple, tuple]]	Cover a set of grid cells with axis-aligned boxes, as (lo, hi) cell ranges.
occupied_cells(volume, fmt, level, cell) → set[tuple[int, ...]]	The zyx chunk-grid cells that have a stored object at level.

Module Contents

exception neu_vol.ops.occupancy.NoOccupancy

Bases: RuntimeError

No chunk key under the level’s prefix could be read as a chunk index.

Initialize self. See help(type(self)) for accurate signature.

neu_vol.ops.occupancy.labeled_regions(volume: str, *, level: int = 0, tighten_level: int | None = 2, fmt: str | None = None) → tuple[list[dict], dict]

Occupied boxes of volume, in level-0 voxels, zyx, plus a context dict.

Each region is {"lo", "hi", "cells", "n_labels"}; n_labels is the number of distinct nonzero values seen at tighten_level and is None when tightening is off. It is a floor: a label too small to survive to that level is invisible there.

neu_vol.ops.occupancy.maximal_boxes(cells: set[tuple[int, ...]]) → list[tuple[tuple, tuple]]

Cover a set of grid cells with axis-aligned boxes, as (lo, hi) cell ranges.

Each pass takes the smallest remaining cell and grows it along each axis in turn while every cell of the box is present. For a union of a few written blocks this recovers the blocks; at worst it is one box per cell. It never emits a box containing an absent cell.

neu_vol.ops.occupancy.occupied_cells(volume: str, fmt: str, level: int, cell: tuple[int, ...]) → set[tuple[int, ...]]

The zyx chunk-grid cells that have a stored object at level.

One listing; an all-fill chunk is never written, so presence is occupancy.

neu_vol.ops.occupancy.ZARR_METADATA