Resampling, warps and sampling
Intensity interpolation, label interpolation and anti-aliasing are separate choices. Compose coordinate maps before resampling where possible. A wider interpolation kernel alone does not supply the low-pass filter needed before minification.
Available operations
resample
Entry points: ResampleOp, Ratio, append_resample_phase, append_block_mean_phases.
Rational-grid nearest/linear resampling with explicit output extent. Block means are a separate downsampling route. Output voxel-center placement needs to be reflected in metadata.
Execution: Planned shape-changing phases with mapped source footprints; resident nearest/linear kernels.
Why output and source grids must both be named. A fine output voxel can map between coarse source samples, and a coarse output voxel can skip many fine input samples. The required source interval is derived from the rational map plus the nearest/linear interpolation footprint, rather than by applying one output-grid radius to the input.
Voxel-center placement determines origin as well as spacing. Mean downsampling integrates a defined source block and differs from point interpolation; use it or an explicit low-pass when suppressing aliasing is required. Label downsampling must preserve the intended identity policy rather than averaging IDs. Inspect edge windows when the source extent is not an exact multiple of the requested ratio.
transform
Entry points: CoordinateMap, WarpOp, append_warp_phase, TransformInterpolation.
Affine/projective transforms, rotations, polar/log-polar maps and remapping. Nearest/linear plus Keys cubic, Lanczos-3 and cubic B-spline evaluation have explicit boundary policies. Higher-order intensity interpolation accepts f32/f64; use nearest for label identities.
Execution: Planned mapped finite source footprints, not a single constant halo for every map. Extreme transforms can request very large source regions.
A warped core generally has a displaced source footprint. An affine map sends its corners to a source bounding region, then the interpolation taps widen that region. Projective and nonlinear maps need their supported footprint policy rather than a constant displacement guessed from the output block edge. A far-off source request is not a symmetric halo around the same-index core.
Choose interpolation by data meaning: nearest preserves label names; higher-order intensity kernels can overshoot below zero or above local extrema. Cubic B-spline evaluation requires coefficient preparation for interpolation, whereas Keys cubic and Lanczos sample intensities directly. Compose transforms first to avoid repeated resampling blur, and supply anti-aliasing separately for minification.
spline
Entry points: coefficients_axis, SplineCoefficientsOp.
Prepare interpolating cubic B-spline coefficients by a tridiagonal solve along each axis. Evaluating the B-spline basis on raw intensities is a different smoothing operation.
Execution: f64 whole-axis line dependency; bounded transverse strips and line scratch. Run all spatial-axis passes before spline interpolation.
Why coefficient preparation is nonlocal. Interpolating cubic B-spline coefficients solve a tridiagonal relation along an entire axis. The coefficients near one output position depend on the line solve and its boundary condition, so a fixed local image halo cannot reproduce the exact prepared field on arbitrary cuts.
SplineCoefficientsOp declares whole-axis reach on its selected axis, zero on transverse axes and line scratch. Process bounded strips of complete lines, then repeat for the remaining spatial axes. A one-voxel axis is handled as an identity case. After coefficients exist, the B-spline evaluator has a small finite tap footprint; the global preparation and local evaluation are separate operations with different dependency kinds.
plane_sample
Entry points: PhysicalGrid, PlaneGrid, PlaneSampleOp, append_plane_sample_phase.
Sample oriented physical planes with explicit z/y/x origin, spacing and voxel-center domain. Output is f64 with NaN for unsupported/nonfinite contributing samples; masks can be sampled as support separately.
Execution: Planned affine footprint sampling and resident getter-based kernels; intensity/support normalization belongs to the caller.
Physical coordinates explain the footprint. A requested plane defines an origin, basis/directions and output sampling pitch in calibrated coordinates. Converting its bounded output patch into source voxel coordinates gives the affine source footprint plus interpolation neighbors. Tilt can make a seemingly small plane patch cover many z slices.
The strict voxel-center domain and invalid-sample rules prevent extrapolated values from looking like observed signal. When sampling a support mask, keep the interpolated support separate from the intensity numerator and apply the chosen normalization explicitly. The planned sampler is useful for oblique sections and local profiles, but does not correct an erroneous origin or registration between sources.
fft
Entry points: RealTransform2, RealTransform3, Correlation2, SquaredDifference.
Real Fourier transforms, prepared correlation spectra and squared-difference shift landscapes. Set padding/shift bounds; a circular transform without enough padding is not a linear correlation.
Execution: Resident FFT/landscape helpers, not BlockOps. Optional fftw adds a selectable system FFT backend.
Transform extent is an algorithm choice. Multiplying Fourier spectra represents circular convolution unless the padding/embedding makes the desired linear operation valid. Prepared spectra can be reused only when shape, padding, kernel and transform convention match. A correlation landscape indexed by displacement is also not an image region indexed by world position.
These distinctions explain why the low-level transform helpers are not forced into a generic region-in/region-out operation. Use planned finite-kernel wrappers when computing image convolutions and the resident helpers when explicitly managing a transform-sized problem. Optional FFTW selects a backend; it does not change the mathematical padding or reduce every FFT to finite image support.
Sampling outside ops
sampling::sample_points reads intensities and gradients at physical points from chunk-backed SampleSources under explicit work/read budgets. Its current SourceLayout uses a positive diagonal spacing/origin map. It is a bounded sampler, not a generic interpolating label lookup.
pyramid, intensity_pyramid and label_pyramid provide multiscale construction; the OME-Zarr builders require zarr. Mean/max intensity reduction and nearest label reduction have different semantics. Preserve each writer’s documented edge-window and voxel-center convention when comparing levels.