pyrametric

Lazy, memory-bounded connected-components labeling and per-object measurement for OME-Zarr pyramids, with OME-NGFF label-image output.

pyrametric is the OME-Zarr-aware layer over tilewise-ccl: it labels the level-0 binary mask of a Pyramid, propagates the labels down the resolution levels, measures per-object features, and writes the result as a spec-compliant NGFF label image (labels/<name>/ with image-label metadata). It works on already-segmented masks — thresholding/segmentation lives in pyrops. It provides:

• label_pyramid — label a mask Pyramid → a lazy, writable label Pyramid (optionally with a per-object properties table).
• extract_features / ObjectFeatures — regionprops-like per-object measurement (area, bbox, moments, physical units, ...) over a label pyramid, computed lazily and memory-bounded (validated against skimage in 2D and 3D).
• write_label_pyramid — write a label pyramid as an OME-Zarr label image (colors, properties, source back-reference; default labels/<name>/ location).
• label_array — re-exported from tilewise-ccl for array-level labeling.

The heavy lifting (fast tile-wise connected components, memory-bounded, exact, returning a lazy dask array) lives in tilewise-ccl; this package adds the pyramid, axis-handling, measurement, and NGFF I/O concerns on top.

Installation

pip install pyrametric
# or, from a checkout:
pip install -e .

Depends on tilewise-ccl, ome_zarr_pyramid, plus numpy/scipy/dask/zarr.

Quick start

The input's level 0 must already be a binary mask (background 0 + one foreground value) — there is no thresholding here (binarize beforehand).

from ome_zarr_pyramid.core.io import IO
from pyrametric import label_pyramid, write_label_pyramid

io = IO()
mask_pyr = io.read_pyramid("mask.zarr")           # level 0 = a binary mask

# label level 0 -> a lazy, writable label Pyramid
label_pyr = label_pyramid(mask_pyr, connectivity=2, n_workers=8)

# ...write it as a plain multiscale array
io.write_pyramid(label_pyr, "labels.zarr", overwrite=True)

The result mirrors mask.zarr's resolution levels — you do not ask for them, and nothing is downsampled until the write. See Downscaling to change the depth.

With properties + an OME-Zarr label image

# also measure per-object properties (area + bounding box) - FREE from the labeling
# metadata pass; they are stamped onto the returned pyramid's image-label metadata
label_pyr = label_pyramid(mask_pyr, properties=True, n_workers=8)

# write a spec-compliant label image under the source's labels/ group:
#   mask.zarr/labels/cells/   (multiscales + image-label: colors, properties, source)
write_label_pyramid(label_pyr, source="mask.zarr", name="cells")

Attaching labels to the source image, written together

Pyramid.add_image_label attaches a label pyramid to its source image pyramid, so the two travel together and a single write_pyramid emits the image plus its labels/<name>/ sub-group in one OME-Zarr store — the common "image + its segmentation, side by side" layout that viewers open as one dataset:

image_pyr = io.read_pyramid("image.zarr")     # the intensity image
mask_pyr  = io.read_pyramid("mask.zarr")       # its binary mask (segment/threshold upstream)

# label the mask, name it, then attach it to the image. The label pyramid mirrors
# the source's levels automatically - add `.downscale(n_layers=3)` to override.
label_pyr = label_pyramid(mask_pyr, properties=True).rename("cells")
combined  = image_pyr.add_image_label(label_pyr, name="cells")

io.write_pyramid(combined, "image_with_labels.zarr", overwrite=True)

Labeling a sub-region

To label only part of the image, select it first with Pyramid.isel (any axis, int/slice/list) — the label matches that sub-region's geometry:

label_pyr = label_pyramid(mask_pyr.isel(c=1, z=slice(100, 150)))

Downscaling

label_pyramid takes no downscaling parameters. A label pyramid is downsampled the same way a raw one is — with Pyramid.downscale() — so the two behave alike:

labels = label_pyramid(mask_pyr)                      # mirrors mask.zarr's levels
labels = label_pyramid(mask_pyr).downscale(n_layers=5)          # exactly 5 levels
labels = label_pyramid(mask_pyr).downscale(min_dimension_size=128)  # coarser stop

min_dimension_size stops once the largest dimension would fall below it, so a volume already smaller than the threshold stays single-level.

Three things are handled for you:

Levels mirror the source. With no .downscale() call, the label pyramid gets the same number of levels as the mask it came from, at the same shapes, so the two line up voxel-for-voxel in a viewer.

Per-axis factors are derived from the source's own levels, not assumed. If the mask was built plane-wise (z=1, y=2, x=2) or with an irregular progression (2x to level 1, 5x to level 2), the labels follow it exactly. Only when there is nothing to derive from — a single-level source — does the default apply: isotropic 2x on the spatial axes (z=2, y=2, x=2; t/c stay 1), the same default a raw pyramid uses. When the source's levels cannot be reproduced by any integer factor, pyrametric warns and builds a fresh plan rather than silently shifting a level by a voxel.

Downsampling is nearest-neighbour (downscale_method="simple", the default for both label_pyramid and .downscale()), so a coarse level only ever contains ids that are really present at level 0. Do not override it on a label pyramid: averaging label ids invents objects that do not exist — the mean of ids 4 and 8 is 6, a different object — so downscale_method="mean"/"median" will corrupt the labels. It is accepted, not blocked; the correctness is on you if you change it.

Nothing is computed until the write: .downscale() records a plan, and the writer expands it progressively from disk. Level 0 is labelled exactly once, however many levels you ask for — so labels.nlayers reads 1 until it is written.

API

label_pyramid(pyramid, tile_shape=None, connectivity=2, n_workers=1, properties=False, verbose=False, backend="auto")

Label a binary-mask Pyramid's level 0. The result mirrors the source's resolution levels — it takes no downscaling parameters. To choose a different depth, call .downscale() on the result, exactly as you would for a raw pyramid (see Downscaling).

The coarser levels are recorded as a deferred plan, not built here: the writer expands them progressively from disk, so level 0 is labelled exactly once. Building them eagerly cost one additional full re-labelling of level 0 per level (measured 1x / 2x / 3x / 4x for 1..4 levels). Downsampling is nearest-neighbour (stride), the only correct choice for categorical labels, and the per-axis factors are derived from the source pyramid's own levels so the labels stay aligned with their image.

Because the levels are a plan, label_pyr.nlayers reads 1 until the pyramid is written; the store then contains the planned levels.

To label a sub-region, select it first with Pyramid.isel (e.g. mask.isel(c=1, z=slice(100, 150))).

Returns a lazy label Pyramid (dtype int32 unless the object count exceeds int32), mirroring the source's axes, units, per-level shapes and scales. With properties=True the same pyramid additionally carries its OME image-label metadata (per-object colors + an area/bbox properties table), so it is write-ready.

When properties=True, label_pyramid measures each object's area (voxel count) and bbox (half-open bounding box, per axis, in the label's own coordinates) and stamps them onto the returned pyramid's image-label metadata (alongside deterministic per-object colors), so it is write-ready. For richer per-object measurement (intensity / physical / shape features, filtering) pass the label pyramid to extract_features(...).

write_label_pyramid(label_pyramid, source=None, name="labels_0", output=None, write_colors=True, write_props=True, overwrite=False, **write_kwargs)

Write a label pyramid as an OME-Zarr label image, serialising the image-label metadata already on the pyramid (built by label_pyramid(..., properties=True) or Pyramid.set_image_label). This writer only persists it — it does not measure. Returns the path written.

The emitted image-label metadata (OME-NGFF labels spec) contains version, colors ({label-value, rgba}), properties ({label-value, "area (pixels)", "object-coordinates": {axis: [start, stop]}}), and source. Both NGFF 0.4 and 0.5 layouts are written correctly.

Notes

• Binary mask required, not validated. The level-0 array must be a binary mask; this is the caller's responsibility. Validating it would force a full scan of a potentially huge array, so it is deliberately skipped. (Re-labeling an already-labeled dataset will be possible later, once tilewise-ccl grows a relabel function.)
• Downsampling is nearest-neighbour (stride), and deferred. Categorical labels must not be averaged, so coarser levels are produced by striding, with the per-axis factor taken from the source pyramid. They are RECORDED as a plan and expanded by the writer from disk, so level 0 is labelled once no matter how many levels you ask for.
• Batch axes give globally-unique ids. When multiple (t, c) volumes are labeled, each is labeled independently and its ids are offset so the whole output is a single, globally-unique label image.
• Colors/properties at scale. For very large object counts, writing explicit per-object colors and properties bloats the metadata (pyrametric warns) — pass write_colors=False / write_props=False to write_label_pyramid to drop them. Viewers such as napari auto-randomise label colors when no colors list is present, so skipping them is usually fine.
• Memory. Labeling and property computation are memory-bounded by tile size (see tilewise-ccl); the only object-count-proportional cost is the in-memory properties table.
• Backends. label_pyramid and extract_features both take backend="auto"|"dask"|"dyna". "auto" prefers dyna when the pyramid's layers are zarr-backed and falls back to dask silently; a dask-backed pyramid is dask-only, and asking for "dyna" there raises rather than guessing. The results are identical - it is purely an execution choice.

See also

• tilewise-ccl — the storage-agnostic array-level engine (label_array), with its own README and benchmarks.