flowchart TB I["Input image 0"] --> F["Response phase"] F --> R["Response image 1"] R --> G["Candidate or fitting phase"] I -->|"Declared additional source"| G G --> O["Output image or diagnostics"]
Assembling pipelines
A pipeline assembly states both the computation and where intermediate results become named images. PlanBuilder keeps phase bookkeeping consistent while operations declare the neighborhoods, source images and output types they need. The distinction matters: two filters in one phase and two filters in separate phases can produce the same image while doing very different amounts of I/O.
Start from image identities
The run’s initial image is image zero. Appending a pixel phase returns a Phase; its Phase::image handle names the image written by that phase. Use the handle instead of calculating indices in application code:
let first = builder.pixels(Chain::op(first_op))?;
let second = builder.pixels(Chain::sequence(vec![
Chain::source(first.image()?, first_dtype),
Chain::op(second_op),
]))?;
let assembly = builder.finish()?;This is an assembly sketch, not a complete program: first_op, second_op and the dtype are application choices. The starter provides complete imports, storage and execution.
Chain::source explicitly selects an earlier image. Without a source leaf, an ordinary phase consumes the preceding image according to the assembled layout. Explicit sources are useful for branching: a later operation can combine a processed response with the original intensity, rather than mistakenly fitting a response image as though it were raw data.
Choose a phase boundary deliberately
A Chain::sequence within one pixel phase evaluates its kernels using local intermediate buffers. Required neighborhoods propagate backward through the sequence. For a radius-two smoothing followed by a radius-one derivative, the raw read needs radius three around the final owned core. The smoothing must be correct over the derivative’s required intermediate region.
Separate calls to PlanBuilder::pixels create separate phases. The first phase’s owned result is stored and can be shared by multiple later consumers; the next phase reads the region it needs from that image. This can save repeated upstream computation, but adds intermediate reads, writes and storage lifetime. The fusion page explains when that tradeoff matters. Changing scheduler priority does not merge the phases after assembly.
A branch whose outputs feed a combine belongs in Chain::parallel when its contracts fit that composition. The combine’s implementation determines whether branch outputs can be folded one at a time or must coexist. A branch is not free merely because it appears as one node in the application diagram.
Choose the appropriate phase kind
| Kind | Why use it | What to declare |
|---|---|---|
| Pixel chain | Local or explicitly mapped image-to-image computation | Accepted/produced dtype, reach, source operands and scratch |
| Fragment phase | Per-block evidence, rows, partial measurements or reconstruction from fragments | Input/output streams, coverage, ownership, lifecycle and any pixel reads |
| Barrier fragment phase | A result needs complete earlier evidence before block work starts | Barrier and reduction state, then blockwise application |
| Iterative image phase | A state image is repeatedly updated with substage dependencies | Running/fixed operands, per-substage reach and a finite guard |
The interfaces are BlockOp, FragmentOp and IterativeOp. A public numerical function does not automatically implement one of them. Registration fitting and the bounded-state deconvolution solver have their own documented execution routes. Choose an interface that can honestly express the algorithm rather than hiding a whole-volume load inside an apparently local operation.
Grids, finishing and execution
PlanBuilder::regrid changes the block lattice for subsequent phases. It does not change image resolution. Resampling needs an explicit operation with an output lattice and source footprint. Different block indices in two grids need not correspond; producer/consumer dependencies are determined from regions.
PlanBuilder::finish returns an Assembly, whose workflow, decomposition and phase work are kept together. Structural checks cover types, source images, phase work and supported geometry. The binding decomposition then goes to the executor with an environment and runtime hints. A hint can alter visit order or concurrency, but cannot remove a required source or change an output core.
For a small global calibration or threshold, either emit block evidence and reduce it at a barrier, or use two runs with the small result passed as a parameter to the second. A reduction is scalable only when its retained state is controlled; collecting every sample into one final vector still grows with the image.