Intensity, background and thresholds
Local normalization and a global histogram answer different questions. Prefer a bounded histogram or a declared sample when the full intensity population is unnecessary. Record whether thresholds come from all voxels, a mask or a sample.
Available operations
background
Entry points: background_estimate, remove_background, DifferenceCombine.
Estimate background by grey morphological opening and subtract it as a top-hat. This module composes rank filters and a subtraction branch; it is not a separate rolling-ball fitting algorithm.
Execution: Planned chain composition, with the combined support of erosion and dilation.
Why background removal needs more than one radius. A grey opening first erodes and then dilates a neighborhood estimate. Both passes contribute to the source footprint; subtracting that estimate from the original is pointwise and adds no spatial support. The structuring element should be larger than bright objects that are intended to disappear from the estimated background.
This method encodes a size/shape assumption. A broad biological object can become part of the background estimate, and a highly varying background can survive an overly large element. Compare the estimated field as well as the corrected image. Calling this operation rolling-ball fitting would conceal that its implementation is rank-filter composition.
normalise
Entry points: LevelCorrectionOp, LocalContrastOp, LocalGainOp.
Subtract or divide by a supplied level estimate, normalize against local statistics, or apply a bounded gain. Supply the removal mode, denominator behavior and gain bounds explicitly.
Execution: Planned local/source-aware blocks and resident arithmetic; support depends on the estimator used.
The estimate determines the halo. Removing a precomputed level is pointwise with respect to that level and the original image. Estimating the level inside the operation can require a sampled statistic plus interpolation; both the statistic’s window and the distance to bracketing samples contribute to the source support.
Subtraction models additive offset; division models multiplicative gain. Near-zero denominators, invalid population estimates and gain clipping have different scientific interpretations, so choose the relevant mode rather than relying on a visually pleasing result. Local contrast correction can amplify low-signal noise unless spread and gain limits are explicit. Retain the estimated level/spread for diagnostics when developing a workflow.
local
Entry points: LocalStatisticOp, AdaptiveThresholdOp, Statistic, Population.
Neighborhood means, dispersions and rank-like summaries, with optional masks, sampled populations and explicit empty-population rules. Niblack, Sauvola and Isodata threshold models use those local summaries.
Execution: Planned finite windows; sampled windows retain a globally anchored lattice.
Dense and sampled neighborhoods are different algorithms. A dense local statistic reduces the selected element at each output coordinate. A lattice-sampled statistic reduces windows only at globally anchored sample centers and interpolates those values. The latter saves reductions but introduces dependence on bracketing samples beyond the output coordinate’s own window.
LocalStatistic::reach_spec expresses a conservative asymmetric bound from interpolation distance plus element sides; LocalStatistic::halo can grant a tighter AxisReach::PerBlock table for an actual grid. Sample positions and even-window anchoring can make different blocks require different margins. An empty masked population follows its declared fallback rather than becoming a manufactured ordinary zero. Keep sampling alignment and any narrowing stages fixed when checking decomposition invariance.
lattice
Entry points: LatticeStatisticOp, LatticeInterpolateOp.
Compute expensive statistics on a sparse global lattice and interpolate them into a dense estimate. The lattice spacing and window determine the approximation; they are not incidental compute-block parameters.
Execution: Planned statistic/interpolation phases with source-footprint declarations.
Why split a sampled statistic into two images. In the fused local route, interpolation forces a fine-resolution fetch that includes distant sample windows. Splitting computes a coarse statistic image first, then reads only neighboring coarse samples for dense interpolation. The interpolation halo is measured on the coarse source grid, not in the fine output grid’s voxels.
These phases use Space::source_index and explicit source regions: a nominal zero in the phase’s own halo is not a claim that the operation reads only one co-located voxel. The placed source/output mapping carries the real dependency. Keep sample-grid narrowing separate from post-interpolation narrowing; rounding before a blend and rounding afterward are not the same operation.
lattice_samples
Entry points: LatticeSamplesOp, GatherSamplesOp, InterpolateSamplesOp.
Separate sparse sample emission, gathering and interpolation. This supports reusable sampled statistics without recomputing every dense neighborhood.
Execution: Planned fragments plus interpolation; sample state and interpolation neighborhoods must be budgeted.
Why a third route exists. The fragment version assigns every lattice center to one owner core, evaluates its window once, gathers the nearby sample fragments needed by each consumer core, then interpolates. It avoids repeated window evaluation in overlapping image halos without requiring a full-resolution stored image for each statistic.
LatticeSamplesOp gives the image and optional mask the element’s source reach. GatherSamplesOp declares dependencies on the blocks owning the needed sample rows. InterpolateSamplesOp then consumes the gathered samples locally and can combine them with explicitly declared voxelwise sources. These are image-read and fragment-neighborhood dependencies with different units, not two spellings of the same halo. No global barrier is required merely to gather nearby samples.
threshold
Entry points: append_global_threshold_phases, append_bounded_otsu_threshold_phases, SampledValuesOp.
Global Otsu, Yen, Li, triangle, minimum, multi-Otsu, robust-sigma and log-Otsu helpers; threshold masks/classes and sampled threshold reduction. The bounded Otsu route uses fixed bins, whereas exact/sample-retaining routes have different memory costs.
Execution: Pointwise application after global reduction. Resident threshold functions and planned routes are distinct APIs.
Global estimation does not require a global image read in every task. Block partials can build a fixed-bin histogram, one reduction derives the threshold, and the application stage compares each voxel with that shared scalar. Only the histogram stage consumes the complete population across tasks; the mask application has zero spatial reach.
The chosen estimator changes both statistical assumptions and retained state. Fixed-bin Otsu is bounded in bin count and quantizes intensities; sample-retaining estimators retain values according to their sampling policy. For multimodal/background-skewed data, inspect the population and resulting threshold rather than assuming one global method separates the intended objects. Local adaptive thresholds are separate local-statistic operations.
exposure
Entry points: append_equalize_histogram_phases, append_equalize_adapthist_phases, match_histogram.
Global histogram equalization, CLAHE, histogram matching and low-contrast detection. CLAHE tile layout and clipping affect the image and must not follow arbitrary scheduler tiles.
Execution: Planned global/CLAHE pipelines plus resident helpers; histogram matching and low-contrast helpers are resident.
Histogram tiles are part of the algorithm. Global equalization derives one cumulative intensity mapping. CLAHE derives clipped mappings on a fixed intensity/spatial tile layout and blends them spatially. Its sample/tile layout must stay fixed when compute blocks change, or the resulting image would change with worker configuration.
The histogram and mapping state have different lifetimes from intensity buffers. The planned route communicates these small facts and applies the mapping rather than reading the entire image per output block. Set bins, clipping and range conventions explicitly when comparing to another package. Histogram matching additionally assumes the reference distribution is scientifically meaningful; it can suppress true differences in fluorescence intensity between samples.
slice_normalise
Entry points: slice_statistics, slice_mapping, SliceNormaliseOp.
Estimate intensity levels per slice, optionally smooth them along the stack, and apply a chosen target mapping. Estimate the small calibration state first, then pass it to the application op.
Execution: Resident slice-statistic estimation and planned zero-reach application with precomputed levels.
Small calibration state makes application local. A per-z mapping can be stored as a short vector of levels/gains. Once estimated, applying the mapping needs the current sample and the entry indexed by its true global slice coordinate, so SliceNormaliseOp has zero spatial reach. A block-local slice index is insufficient when the block begins partway through the stack.
Estimating levels and optionally smoothing them along z remains a separate pass with its own population/sampling choices. Use this workflow for systematic slice-dependent intensity drift. It can also remove genuine depth-dependent biology, so compare the estimated curve with acquisition expectations before applying it to quantitative measurements.
intensity_statistics
Entry points: IntensityStatistics, IntensityStatisticsPartial.
Accumulate and merge intensity summaries. Reuse the partial-state abstraction when a pipeline needs global diagnostics rather than a new image.
Execution: Mergeable summary helpers; their presence does not imply every exact distribution statistic has bounded storage.
Associativity determines what can be reduced cheaply. Counts, sums, extrema and suitable moment states can be merged from independent block partials. Their state need not retain every contributing voxel. Exact order statistics or an entire empirical distribution are different: a mergeable wrapper does not imply constant-size storage for every requested statistic.
Use these helpers when a workflow needs diagnostic numbers rather than another image, and define handling of invalid values and the population being summarized. Compare count and range fields as well as the mean: a numerical mean can look plausible when a mask or source selection accidentally discarded most observations.