Registration and geometry

Registration estimates a coordinate map; resampling evaluates image values through that map. Keeping these steps separate lets an application inspect, compose and reuse transforms before generating another image. It also prevents a common mistake: applying a transform in the forward direction when image sampling needs the inverse direction.

Understand the pull convention

The atlas-registration example estimates a map from fixed coordinates to moving coordinates. To compute an output voxel on the fixed lattice, map its location into the moving image and sample there. This is pull resampling: every output owns a value, while the source position can be fractional or outside the domain.

flowchart TB
  F["Output voxel on fixed frame"] --> T["Fixed-to-moving coordinate map"]
  T --> M["Continuous location on moving frame"]
  M --> W["Interpolation and true-boundary policy"]
  W --> O["Value at the owned output voxel"]
Figure 1: Pull resampling maps an output location to its required source location; it does not push moving voxels into potentially empty output bins.

An affine map, for example, can change scale and orientation as well as shift. A B-spline deformation adds local displacement. Filename phrases such as “sample to atlas” do not establish direction; read the source/target frame contract. Composing maps before resampling also avoids repeatedly interpolating and blurring an image at every registration stage.

Two registration fitting routes

ops::align provides block-reduced Gauss–Newton fitting and a stochastic elastix-style route. The example selects the route from explicit options or parameter-file optimizer settings. fit_stochastic includes sampled coordinates, mutual-information machinery, multiresolution smoothing and optimizer choices. It is not equivalent to fitting the same geometric model with a different loss and then comparing only the transform’s name.

Inspect the selected image levels, physical frames, initial map, optimizer, metric and resulting registration.json. A metric improvement alone does not establish anatomically correct alignment. Registration between different contrasts can require a different similarity measure from registration of two same-channel acquisitions. The detailed README documents its transform export and reference comparisons.

Stitch tiles before treating them as one image

The tile-stitching example starts from a tile layout and nominal overlap. Neighbor-pair evidence gives relative shifts; a graph placement solves positions consistently instead of independently accepting mutually incompatible pairwise offsets. A slice-wise alignment then follows in-plane drift along the stack, and weighted fusion combines covering tiles.

Alignment and fusion have different read patterns. Neighbor alignment reads overlap regions; output fusion reads the tiles covering each slab. The stored tile route keeps tiles on disk and reads bounded boxes, whereas a resident helper expects already supplied arrays. A public function taking a complete collection of tile arrays is not evidence that the CLI loads every tile at once.

Inspect disconnected tile components, overlap evidence and fused seams. Missing measurements can be interpolated in the documented drift model; interpolation must not be mistaken for an independently measured displacement at every slice.

Resampling

The higher-order example compares linear, Keys cubic, Lanczos-3 and interpolating cubic B-spline sampling. For a centered resize, it uses

\[ x_s = (x_o + 0.5)\frac{N_s}{N_o}-0.5. \]

Thus output spacing is source spacing times N_s/N_o, while the output origin also shifts by half of (N_s/N_o - 1) source spacings. Preserving only spacing would move the represented voxel centers. WarpOp declares the actual mapped source footprint for each output region; a constant symmetric halo is not a complete description of a general warp.

SplineCoefficientsOp prepares cubic B-spline coefficients with a whole-line solve along each axis. The evaluator has a finite local basis, but those coefficients depend on the complete line. The example therefore runs bounded transverse strips that leave the active solve axis whole. This is a concrete case where local-looking interpolation needs more than a four-tap input halo.

Use nearest sampling for labels. Cubic and Lanczos intensity weights can overshoot, so preserving their answer can require allowing values outside the input range. Before downsampling substantially, add an explicit anti-aliasing filter; a wider interpolation kernel is not itself an anti-aliasing policy.

Sample a physical plane

The plane-sampling example uses PlaneGrid and PhysicalGrid to describe an oriented plane in physical space, including signed depth and anisotropic sampling. PlaneSampleOp reuses bounded affine source footprints. It samples intensity and support independently and writes a separate frame describing the oblique embedding.

Out-of-domain locations and nonfinite contributing samples yield NaN. A support threshold, support normalization or depth average is a later application choice. A three-dimensional buffer shaped [1,row,column] does not by itself make the plane an axis-aligned z/y/x image.