Filters, derivatives and feature images
Choose a filter by its spatial support and output meaning. A Gaussian, rank filter and Hessian feature can all be block-local, but their radii and scratch requirements differ. The support declared by the operation determines the halo; changing block size does not change the intended filter.
Available operations
smooth
Entry points: Gaussian, SmoothOp.
Separable Gaussian smoothing with explicit sigma, truncation and boundary convention. Scale is in voxel units unless the caller converts from physical spacing.
Execution: Planned blocks; finite support from the truncated kernels.
Support and parameter choice. Each axis reads ceil(truncate × sigma[axis]) voxels on both sides. Thus sigma [0, 1, 2] with truncation three needs [0, 3, 6], not a single isotropic radius. The zero z scale leaves slices independent. The three separable one-dimensional passes compute the Gaussian with a sum of kernel lengths rather than a full three-dimensional product. The wrapper accepts supported numeric carriers and writes f64 so that smoothing an integer image does not silently round its weighted averages.
For a physically isotropic blur on anisotropic data, first divide the desired physical sigma by each voxel pitch. Changing the edge convention changes the samples invented beyond a true image boundary; it does not reduce the internal halo. Use explicit narrowing afterward only if its loss of precision is intended.
convolve
Entry points: Kernel, ConvolveOp, TransformConvolveOp.
Direct convolution/correlation with explicit kernel sense and origin; FFT acceleration for finite kernels. Transform tiles are anchored globally to retain a consistent answer across compute grids.
Execution: Planned finite-footprint operations and resident kernels. FFT scratch can dominate a small output tile.
Why there are two dependency forms. A direct finite kernel reads the offsets from its chosen origin. An off-center kernel therefore needs different lower and upper halos; convolution also reverses the correlation offsets. Derive those sides from Kernel::reach_spec rather than assuming half the array width. Kernel coefficients, origin and sense together specify the operation.
TransformConvolveOp adds a different requirement: its FFT tiles are anchored to the image, so a compute block beginning inside a tile must fetch enough data to finish that tile. AxisReach::Aligned stores the kernel-only reach for tile-divisible block edges and a conservative wider reach otherwise. With tile edge 32 and kernel radius 4, the per-side bounds are 4 when aligned and 35 otherwise. This extra 31 comes from computation-tile alignment, not a wider PSF. FFT acceleration still implements a finite kernel; it does not make the whole image a single Fourier-periodic domain.
transform_bank
Entry points: BankGroup, TransformBankOp.
Evaluate several correlations, optionally over pointwise-mapped inputs, then combine and reduce responses. Reuse input transforms across kernels instead of independently transforming the same tile for each filter.
Execution: Planned finite-support transform tiles; kernel-bank size influences scratch and work.
When sharing helps. Suppose ten template correlations use the same input tile. Running ten separate transform convolutions repeats the input FFT ten times. A bank transforms its distinct mapped inputs once, applies the prepared kernel spectra, and computes the requested group combinations. The saved transforms can matter more than avoiding small pointwise arithmetic.
The largest kernel support and the anchored tile geometry still determine which image samples must be fetched. Group definitions also determine how many spectra, inverse transforms and response buffers are live. Choose the bank for a family of related responses, such as normalized template correlations, and inspect scratch rather than estimating memory from the final maximum-response image alone.
rank
Entry points: RankFilterOp, MaskedRankFilterOp.
Minimum, maximum, median and other order statistics under an explicit structuring element. Masked variants define which neighbors are eligible, including exclusion of the center. Floating-point selection uses its stated ordering.
Execution: Planned bounded windows and resident kernels; element size controls cost.
The window is the dependency. The structuring element supplies exact lower/upper sides, including asymmetric even extents and omitted offsets. A median over an x window of length 10 can need five samples below and four above its anchor; granting four on both sides is incorrect. A masked filter additionally reads the population mask over the same neighborhood. Excluding the center changes the selected population, not the maximum geometric footprint.
Rank selection preserves an input value rather than computing a weighted mean, making it useful for impulse rejection while keeping the intensity carrier. It is more expensive as eligible population grows; use a sliding histogram when its discrete-domain or quantization contract matches the data. Do not silently substitute binned ranks for exact floating-point selection.
sliding
Entry points: SlidingHistogramOp, Domain, HistogramQuery, RankQuery.
Carry a binned histogram along a scan line. State the value domain and binning explicitly: a quantized query is not automatically an exact floating-point rank statistic.
Execution: Planned finite windows, including masked populations; histogram state replaces repeated window rebuilding.
Why the kernel carries state. Adjacent windows overlap. The histogram removes samples that leave the window and adds those that enter, then answers a count, quantile or rank query. This reduces repeated work for large windows but introduces a scan-state dependency inside the implementation. A finite external halo does not alone prove that an arbitrary internal slab cut preserves that state.
The external image and optional mask reach follow the structuring element, including its asymmetric anchor. Select Domain so that the supported intensity interval and bin mapping are explicit. For an exact integer-domain histogram, a median is a rank over exact bins; coarsening the domain trades memory and work for quantization error. Empty masked windows and excluded center samples require the chosen query’s defined behavior.
ridge
Entry points: ScaleSpace, HessianEigenvalueOp, RidgeFilterOp.
Gaussian Hessian features, eigenvalues, ridge/plate/ratio responses and polarity selection for bright or dark structures. Parameters select smoothing scale and response model.
Execution: Planned finite Gaussian-plus-derivative support and resident kernels.
Where the halo comes from. A Hessian response first smooths at the requested scale and then evaluates derivative stencils. Both supports matter: the scale-space implementation derives Gaussian support and its derivative margin rather than using the final eigenvalue calculation as the reach. A pointwise eigenvalue solve adds work and scratch but no further spatial neighborhood.
Select bright/dark polarity before interpreting signs and choose ridge, plate or other response according to the expected structure. A thin membrane and a vessel do not have the same Hessian signature. When comparing several scales, preserve the module’s scale normalization rather than treating raw derivatives from differently blurred images as directly comparable.
structure_tensor
Entry points: StructureTensorOp, CornerResponseOp, GradientMagnitudeOp.
Smoothed gradient outer products, selected tensor eigenvalues, corner responses and gradient magnitude. psd_eigensystem, tensor_axis_into and support_weighted_components also expose calibrated tensor axes and support-weighted components.
Execution: Planned feature images plus resident eigensystem helpers. Derivative and integration smoothing supports both matter.
Two smoothing scales have different roles. Derivative smoothing controls the scale at which gradients are measured. Integration smoothing pools their outer products into a neighborhood orientation estimate. Consequently the input dependency includes the derivative and integration supports; the eigensystem is evaluated locally after those component images exist. A wider integration scale improves directional stability while mixing structures that lie close together.
The tensor describes unoriented axes: opposite eigenvectors represent the same axis. Physical-gradient calibration and eigenvalue/anisotropy checks are therefore necessary before using an axis for measurement. Support-weighted components also retain a support mass; missing observations must not be interpreted as invented zero-valued image evidence. These helpers complement the planned tensor feature images rather than changing the numerical contract of every existing tensor op.
features
Entry points: FeatureStack, FeatureChannel, Family, Geometry.
Describe a named bank of intensity, Gaussian derivative, Hessian and structure-tensor features for pixel classification. Keep channel order and geometry consistent between training and prediction.
Execution: Composes feature operations; feature count increases both work and live buffers.
A feature bank is an algorithm input. Channel names encode what was measured, while scale, axis and normalization determine its meaning. A classifier trained on intensity, a Gaussian response and one Hessian eigenvalue expects that same channel order and parameterization at inference. Reordering numerically plausible channels produces a valid-shaped but scientifically different input.
The effective input halo is the union of the requested features’ supports, including any composed derivative/integration margins. Memory grows with the simultaneous feature channels even when every feature has bounded support. Inspect whether the workflow streams channels or retains their stack; a three-channel raw image does not imply a three-array working set for a rich feature model.
edges
Entry points: CannyResponseOp, append_canny_edges_phases, append_hysteresis_threshold_phases.
Canny-style response, nonmaximum suppression and hysteresis. Linking weak edges to strong ones is a connected-component decision, not merely an independent threshold in each tile.
Execution: Local response followed by planned component facts and global seam merge; resident reference helpers also exist.
Local evidence versus connected decisions. Smoothing, gradient formation and nonmaximum suppression use finite windows. Hysteresis then retains weak edge responses only if they connect to a strong response. That connection can extend across arbitrarily many blocks, so a fixed-width image halo cannot decide the complete edge component.
The planned route emits component and seam facts, merges the connected identities, and paints the retained edges by block. The merge stores connectivity state, not the entire intensity image, but the number of components is data-dependent. Use consistent low/high thresholds and connectivity; independently applying a low threshold in each tile will either retain noise or break a long edge when its strong seed is elsewhere.
diffuse
Entry points: DiffusionStepOp, append_diffusion_phases, TvParams, tv_denoise_into.
Anisotropic diffusion with selectable diffusivity/model and explicit stable timestep; TV denoising has separate resident helpers and energy evaluation. Iteration count is part of the numerical specification.
Execution: Planned diffusion steps with local support. Do not assume the resident TV helper is an out-of-core solver.
One step is local; many steps are not one step. A diffusion update reads neighboring state to estimate flux and writes the next state. Repeating it permits information to travel farther on every update. Store phase boundaries between updates to exchange current halos, or account for the full composed reach when deliberately grouping steps. Reading the original image halo repeatedly does not supply the neighboring updated values.
Timestep, conductance function, scale and iteration count control stability and the amount of smoothing. The TV helper solves a different regularized problem with its own energy/stopping interpretation. A local stencil in a resident iterative solver does not establish bounded storage for the complete solve.