flowchart TB I["Input image 0"] --> A["Phase 0: smooth on grid A"] A --> S["Stored image 1"] S --> B["Phase 1: segment on grid B"] B --> L["Stored labels: image 2"] L --> C["Phase 2: measure each region"] S --> C C --> R["Measurement fragments"]
Images, phases and tasks
Blockflow’s public execution model separates the identity of an image from the blocks used to compute it. A block grid is an execution partition. An image’s coordinate domain, element type and scientific meaning survive a change of that partition.
Images and their identities
Voxels is the runtime-typed rank-three buffer passed to image kernels. Its Dtype determines element width and which typed view a kernel can request. The spatial order is z,y,x. A singleton axis can represent a plane when the chosen algorithm supports that case; rank three alone does not guarantee that a 3D algorithm has a meaningful 2D specialization.
ImageId names an array within a run. Image zero is the initial input. Phase p reserves output image p + 1, while ImageId::supplied(i) names an additional array attached by the caller. A phase that writes only fragments reserves its position but does not create a readable pixel image there. The plan checks that later pixel readers do not use an unwritten image.
The type of an image is not inferred from its eventual values. BlockOp::accepts and BlockOp::produces declare the type contract, and Decomposition carries that contract forward. For example, thresholding can consume floating-point intensity and produce an integer mask, while a later measurement deliberately reads both the mask and an earlier intensity image. Those are two named inputs, not one mutable image whose earlier meaning has been lost.
A phase is a materialisation boundary
A Phase is the handle returned during assembly; its recorded geometry lives in PhaseDecomposition. A pixel phase evaluates a Chain of operations for each block. Multiple operations within that chain share task-local intermediates; separate phases communicate through stored images.
This distinction matters for resource use. A phase boundary can eliminate recomputation of an expensive intermediate across halos, but it adds a stored array and its write/read traffic. It also gives a natural place to change the block grid. PlanBuilder::regrid states that choice explicitly; it does not resample the image or change its voxel coordinates.
From grids to tasks
BlockGrid partitions a phase’s output domain. Each BlockCore owns one region. BlockGeometry then records the read region, mapped source region and valid output for that core. The halo may overlap neighboring reads; ownership of committed output must not overlap or leave holes.
A Task is one block’s work in one phase. TaskGraph connects that task to the producer tasks whose valid regions cover its source reads. SourceDep keeps additional image dependencies separate because coverage must be checked one image at a time. Adding coverage from two different images would make a false proof: two arrays each covering half a requested region do not together provide one complete operand.
For example, changing a smoothing grid from 64-wide blocks to 96-wide blocks before segmentation does not establish a one-to-one correspondence between producer and consumer block numbers. A consumer can intersect several producer cores. The graph follows those intersections and the required halo; it does not assume equal grid shapes.
Fragment outputs are a different shape of work
FragmentOp supports image-to-fragment, fragment-to-fragment and fragment-to-image computations. FragmentInput identifies the source stream, producer phase and neighborhood to gather. FragmentOutput declares an output stream and its coverage/lifetime. BlockOutput carries the resulting pixels and/or byte fragments.
A fragment can encode histogram bins, seam equivalences, diagnostic rows or partial object measurements. Its meaning belongs to its producer and consumer; it is not automatically a globally assembled table. Explicit encodings and coverage contracts prevent a missing block contribution from being interpreted as a valid empty result.
BlockView gives an application the owned core, read geometry, image buffers and requested fragments. When a barrier reduction has produced shared state, that state is available on the same view. The view therefore says what data the task was granted without allowing the operation to invent an unplanned read.
Storage is injected
Environment supplies image reads, writes, temporary buffers and sidecars. ArrayEnvironment holds images in memory and is useful for small inputs and reference tests. ZarrEnvironment attaches chunk-backed arrays and work storage. Changing the environment does not remove an algorithm’s resident allocations; choose an execution route whose workspace is appropriate to the dataset.
Together these layers explain a run: operations define values, phases define boundaries, grids define ownership, tasks define scheduling units, and the environment provides storage. The halo page develops the geometry, and fusion explains when to remove a phase boundary.