flowchart LR A[Fixed image pyramid] --> E[Fit transformation] B[Moving image pyramid] --> E E --> Q[Inspect diagnostics and overlap] Q --> W[Warp original image once]
Registration and alignment
An estimated transformation is small; the evidence used to estimate it may come from a very large image. Separate parameter fitting, transformation storage and image resampling. Registration metric interpolation is not automatically the same interpolation selected for the final output image.
Available operations
align
Entry points: VolumeFitParams, FittedTransform, run_with_diagnostics, fit_stochastic.
Fit translation, affine and B-spline deformation models with explicit physical frames, metrics, sampling and multiresolution schedules. Stochastic fitting exposes optimizer gains, scales, initialisation and relative stopping. Inspect convergence and sample diagnostics.
Execution: Block-reduced fitting plus resident and pyramid helpers. Zarr pyramid access requires zarr; reduced parameters do not imply every helper is out-of-core.
The reduction depends on the transform family. A translation or affine transform can be described by a small fixed parameter vector. A B-spline deformation stores a control grid whose size grows as control spacing becomes finer. Image blocks evaluate the current metric/derivatives, reduce their evidence, and update one shared parameter state; they must not each fit an unrelated local transform when the requested model is global.
Pyramid levels widen the capture range, while metric, overlap, interpolation and sampling affect which alignment is preferred. Physical frames connect voxel coordinates across levels. Check sample validity and convergence diagnostics: a stopped optimizer can have insufficient overlap or a flat metric rather than a correct transformation. Resample the native image afterward with the explicitly chosen output interpolation.
stack_align
Entry points: SliceShiftParams, estimate_slice_shifts, SliceShiftOp.
Estimate pairwise in-plane slice shifts, accumulate and optionally detrend the path, then resample slices using that path. This targets stack drift, not arbitrary 3D deformation.
Execution: Resident shift estimation with planned shift application. Estimate on representative/downsampled data when a full plane is too large.
Estimation and application need different data. Pairwise shift estimation compares slice content over a configured in-plane search/FFT extent. Accumulating those relative shifts gives a global path; optional detrending removes a modeled drift component. Once the path exists, applying a z slice’s translation reads its displaced in-plane source window and does not need a neighboring slice merely to know that shift.
Inspect accumulated drift as well as pairwise residuals. A repeated texture can make adjacent pairs choose a plausible wrong period, and those errors accumulate. A detrend can remove intentional sample motion or tilt, so it belongs to the registration model rather than an automatic cosmetic correction.
Practical sequence
Use physical units consistently across pyramid levels. A transformation fitted in voxel coordinates of a coarse image must be converted before applying it to the native grid. Existing tile-stitching examples show overlap alignment and image assembly; they are workflow compositions rather than a separate ops::stitch module. Heterogeneous stains can require a different metric from same-channel cycle drift, even though the final warp machinery is shared.