How multidimensional acquisitions fit together

An acquisition can have time, channels, depth, positions and resolution levels without every one of those becoming an axis of a numerical kernel. Blockflow’s ordinary image operations work on one spatial z,y,x image. Storage adapters select that image from a higher-rank array, while application orchestration keeps track of which acquisition, channel, time and level it represents.

This distinction makes a three-dimensional filter reusable for a single volume, a time-lapse frame or one channel in a plate acquisition. It also sets a concrete limit: the executor is not a uniform six-dimensional scheduler that invents halos across arbitrary acquisition axes.

One acquisition through four coordinate systems

Consider an OME image with the following layout:

Property Value
Stored axes t,c,z,y,x
Stored shape [4,2,64,512,512]
Stored chunks [1,1,8,64,64]
Selection Time 1, channel 0, level 0
Exposed spatial shape [64,512,512]
Compute block shape [16,128,128]

The stored chunk describes five-dimensional I/O. The selection fixes two axes. The remaining three axes define the image seen by operations. Finally, the compute grid partitions that spatial image into owned cores. There are 4 × 4 × 4 = 64 compute cores in this example; neither the four time points nor the two channels multiply that one selected plan’s block-grid dimensions.

flowchart TB
  A["Stored acquisition: t,c,z,y,x<br/>shape 4,2,64,512,512"]
  A --> B["Fix time 1 and channel 0; choose level 0"]
  B --> C["Spatial image: z,y,x<br/>shape 64,512,512"]
  C --> D["Compute cores: 16,128,128<br/>64 spatial blocks"]
  D --> E["Read each core's required source region"]
  A -. "Storage chunks: 1,1,8,64,64" .-> E
Figure 1: Storage rank, acquisition selection and compute geometry are separate. The numerical operation receives one spatial image.

How source axes become spatial axes

OmeVolumePyramid::open(root, 0, 1) reads the OME axes and fixes channel zero and time one. OmeVolumePyramid::attached_level(0) yields an AttachedImage whose source spatial axes are [2,3,4], with fixed source indices [(0,1),(1,0)]. The equivalent lower-level selection is:

let selected = AttachedImage::at(level_zero_array)
    .volume([2, 3, 4], vec![(0, 1), (1, 0)]);

This is an API sketch: the path identifies the level array, not its OME group. VolumeSelection records the mapping. A selected voxel [z,y,x] = [3,10,20] means stored voxel [t,c,z,y,x] = [1,0,3,10,20].

Source spatial axes must be distinct and increasing. This allows the adapter to expose the selected C-order data without a whole-image transpose. Every other source axis must be fixed explicitly by the low-level selector; duplicate, out-of-range or missing selections are refused. The OME convenience selector recognizes channel/time names and accepts other nonspatial axes only when their length is one. It does not infer arbitrary experimental dimensions from a filename or silently select one of several positions.

The selected region can still require decoding a full physical storage chunk. With the example’s time/channel chunk extents of one, a decoded chunk contains only one time/channel pair. A store chunked across several channels can have a larger decode workspace even when the operation asks for one channel. Spatial buffer size alone does not describe that source cost.

Compute blocks and chunks answer different questions

BlockGrid divides the selected spatial output. Its core at block index [1,1,1] owns the half-open box [16,128,128] to [32,256,256]. Without a halo, this box aligns with 2 × 2 × 2 = 8 spatial chunks of the stored image. Their full stored chunk indices begin with the fixed pair [1,0].

Use the radius-three Gaussian from the execution story. Its read box is [13,125,125] to [35,259,259], with shape [22,134,134]. That box intersects four chunks on each spatial axis, or 64 chunks, before considering cache reuse. The logical read is about 1.507 times the core volume, but chunk boundaries can make cold decoded traffic much larger. Caching adjacent reads can recover some of this reuse. Neither effect changes which output core the task owns. The decision guide explains which of these values the caller sets and which follow from the selected computation.

The halo chapter explains why different operations need different source regions. Those spatial requirements do not automatically grow the fixed time/channel axes: an ordinary Gaussian of one selected frame is not a temporal Gaussian of the acquisition.

Channels and time are explicit orchestration

For a voxelwise two-channel calculation at time one, attach channel zero first and channel one second. The first is the run’s initial image; the second is named by ImageId::supplied(0). A SourceInput declares whether it is pointwise or needs an additional spatial window. Both inputs must satisfy the intended shape and physical registration contracts. Sharing z,y,x dimensions does not prove the channels are aligned.

To process four time points independently, the application selects four frames and runs the appropriate spatial computation for each. TimeSeriesImage::frame returns one selected AttachedImage; TimeSeriesImage::frame_shape and TimeSeriesImage::spacing describe the chosen level. The application can manage frame-level concurrency separately, while accounting for the memory consumed by all simultaneous spatial runs.

A temporal algorithm must explicitly request its neighboring frames as operands or implement a suitable frame orchestration. The spatial halo declaration does not establish temporal dependencies, choose missing-frame behavior or substitute elapsed time for a spatial distance. The acquired timeline is available through TimeSeriesImage::timeline, which can preserve timing information beyond a simple frame counter.

Plate, well and field identities sit one level higher. collection::open_plate and collection::open_manifest produce SeriesRef entries with a SeriesKey. These identify separate image series, not extra pixel axes. An application must not connect unrelated wells merely because their frame or voxel indices match.

Two-dimensional images use a real singleton

An operation that supports 2D images can receive shape [1,Y,X]. The leading one is not an acquired depth coordinate. SpatialAxis::Singleton represents a virtual axis with no stored source axis, so a stored t,c,y,x image can be selected as spatial z,y,x without pretending its channel axis is depth.

TimeSeriesImage supports an absent z axis and constructs that singleton in its frame selection. The lower-level AttachedImage::selected accepts the same mapping explicitly. In contrast, OmeVolumePyramid::open currently requires named z,y,x axes. Use the appropriate adapter or a stored singleton z; do not assume the two convenience readers have identical dimensional contracts.

A singleton does not make every 3D algorithm meaningful in 2D. A fitter requiring several depth samples, for example, can reject it. Check the operation’s own minimum shape and dimensional assumptions.

Levels and crops retain their own physical frames

A resolution level is a separate spatial lattice, not an extra block-grid axis. Selecting level one changes the image shape and generally its spacing and translation. OmeVolumeLevel records the level path, shape and projected transforms. Do not use a level number alone as a physical scale.

For a concrete crop, suppose level-zero origin is [10,20,30] µm and spacing is [1.5,0.4,0.4] µm in z,y,x order. A crop starting at [8,64,96] has origin [22,45.6,68.4] µm. Its local voxel [2,3,4] is original voxel [10,67,100] and physical point [25,46.8,70] µm. AttachedImage::window selects the voxels; the application must preserve the corresponding coordinate interpretation when publishing. It does not mutate the source acquisition metadata.

Pyramid construction also has a sample-placement convention. Mean pooling with factor [1,2,2] at the stated spacing places the nominal first pooled center at [10,20.2,30.2] µm, with spacing [1.5,0.8,0.8] µm. First-sample decimation uses a different origin. pyramid_axis_transform makes that distinction explicit. The n-dimensional storage-aware intensity_pyramid::plan_pyramid keeps nonspatial axes while planning spatial downsampling; PyramidRecipe is a different API for deriving ordinary spatial levels, and its PyramidRecipe::build_resident retains resident arrays.

Publication reconstructs acquisition meaning

An executor’s spatial result has no automatic channel/time interpretation. Publishing one selected intensity image can produce a standalone z,y,x group with its actual frame and provenance. Publishing a series requires a writer that deliberately restores the relevant nonspatial axes and metadata.

LabelStack is one concrete series writer. It stores uint64 labels as t[,z],y,x: the segmentation channel axis is dropped because it produced one label field, while time is retained. LabelStack::plane exposes a selected frame as a spatial output target for ZarrEnvironment::with_output_target. Its time chunks have extent one so concurrent frame outputs do not overwrite parts of the same compressed chunk. Metadata preserves level alignment and the acquired timeline according to the series writer’s contract.

This is not a universal inverse of selection. Combining several processed channels into a new t,c,z,y,x acquisition, choosing channel descriptions, or publishing an oblique plane requires an explicit output contract. Keep source axis mapping, output axes, scale/translation and units together; correct pixels with reconstructed axes that imply the wrong time, channel or position are not a correct multidimensional result.