Reading and writing OME-Zarr

An OME-Zarr acquisition can contain multiple channels, time points and pyramid levels. Select those before building the plan. Blockflow’s ordinary spatial buffers are rank-three z,y,x arrays; the input adapter fixes nonspatial indices and exposes the selected spatial image to the executor.

Select an image and attach its storage

The following is an API sketch; root and work are caller-selected paths:

use blockflow::ome_zarr::OmeVolumePyramid;
use blockflow::zarr_env::ZarrEnvironment;

let pyramid = OmeVolumePyramid::open(root, 0, 0)?; // channel, time
let source = pyramid.attached_level(0)?;
let environment = ZarrEnvironment::attach(work, &[source])?;

OmeVolumePyramid::open reads the image metadata and level descriptions. OmeVolumePyramid::attached_level creates an AttachedImage selection for one level. ZarrEnvironment::attach binds those selections to image identities and creates the environment used during execution. None of these calls means “decode every image voxel now”; region reads happen as tasks require them.

The OME selector reads axis names and requires the spatial axes to occur in z,y,x order. Channel and time dimensions are selected explicitly; unsupported remaining nonspatial dimensions must have length one. Do not treat any array with five dimensions as though its order were automatically t,c,z,y,x.

Use the selected level’s shape and dtype when assembling the plan. Selecting a coarser level changes the spatial lattice and usually its physical spacing. The convenience OmeVolumePyramid::voxel_size describes level zero, so it is not a substitute for checking a selected coarse level’s complete transform.

flowchart TB
  A["OME image group and axes"] --> B["Fix channel and time indices"]
  B --> C["Choose pyramid level"]
  C --> D["Attached spatial image: shape and dtype"]
  D --> E["Requested block source region"]
  E --> F["Intersecting storage chunks decoded as needed"]
Figure 1: Selection removes nonspatial ambiguity before chunk-backed block reads begin.

Blocks are not storage chunks

A storage chunk is the unit fetched and decoded by the array backend. A compute block is the unit whose output core a task owns. A filter’s read region includes its halo and can intersect several chunks. Adjacent blocks may therefore need some of the same decoded chunks; a source cache can reuse them.

There is no requirement that a block equal one chunk. Choosing a block that is convenient for storage can still be expensive for a wide filter, while an algorithmically convenient block may touch many chunks. Consider both read amplification and active memory when choosing the grid. The cache is a performance mechanism; missing a cache entry must cause a real read rather than change the numerical answer.

Physical coordinates and windows

Voxel indices refer to voxel centers. A diagonal physical frame maps an index i to origin + spacing * i, with each component in the declared axis unit. For a cropped AttachedImage::window, distinguish its local indices from the original image indices. Preserve the corresponding translation when publishing or comparing it with another crop.

A scale transform, translation transform and axis unit all matter. Identical array shapes do not prove two channels are registered. The calibration examples compose supported dataset and global scale/translation metadata and reject unsupported transforms instead of dropping them. Applications need a similar explicit contract. Neither an absent unit nor a filename containing “um” is a conversion to micrometers.

For a centered resize, output sample zero can fall between source samples. Consequently the output origin can change as well as its spacing; see the higher-order resampling example.

Work arrays and their lifetimes

Phase p writes its primary image under work/level{p+1}. These arrays are execution intermediates. An intermediate may be released after its last reader, so retain it through Hints::keep_images if publication or diagnostics need it after execution. Prefer the returned Phase::image handle when naming what should remain, rather than copying a numeric phase index into several places.

A successful processing call and a successful publication are different steps. A work array can contain correct voxels while still lacking the metadata and registry entries that a viewer expects. Keep input data separate from scratch, and publish only after the processing run has completed.

Publish intensity and label images deliberately

Intensity outputs need axes, dtype, multiscale paths, physical scale and translation describing the output lattice. An oblique plane uses a separate plane frame: it must not be labeled as an ordinary axis-aligned global z,y,x image merely because its output buffer has three dimensions.

For labels, ome_zarr::publish_label accepts a LabelPublication. The completed level-zero array must be uint64. The helper stages the label group, constructs nearest-neighbor label pyramid levels matching the source, writes label metadata, installs the result and refreshes the labels registry. When a table is provided, its identity values must agree with raster labels. The helper checks replacement policy before and during publication; it does not silently interpret any existing directory as disposable scratch.

Nearest-label reduction preserves identities. Averaging labels such as 1 and 3 can invent label 2, which has no valid object meaning. Convert with the intended label-conversion operation when necessary and retain the result until the publication helper has consumed it. See the segmentation walkthrough.

Finally, distinguish an OME image-group path from a raw Zarr array path. The OME selector expects image metadata; some examples intentionally accept the directory containing one array’s zarr.json. Check the example’s input contract instead of adding or removing /0 until a path opens.

See multidimensional acquisitions for a worked time/channel selection, singleton 2D axes and series publication. The complete execution story follows that selection through storage chunks, compute blocks and publication.