Specialised imaging and tracing
These operations encode acquisition-specific physics or shape assumptions. Their presence does not make those assumptions appropriate for every microscopy modality. Start from the runnable example closest to the experiment.
Available operations
dic
Entry points: DicNormaliseOp, DicIntegrateOp, DicTextureOp, CentreSurroundOp.
DIC normalization, shear-direction Tikhonov integration, texture/center-surround cues and shear calibration from gradient moments or a cosine fit. The shear direction is a calibration parameter, not an arbitrary image rotation.
Execution: Local filtering mixed with whole-plane Fourier inversion; DIC integration reaches all y/x and no neighboring z planes.
The inverse has a different support from its forward cues. Local normalization/texture filters can have finite radii, but Fourier inversion of a DIC shear derivative mixes the complete in-plane spectrum. DicIntegrateOp therefore declares all y/x and independent z slices. A finite physical shear is not a proof that its regularized inverse has finite image support.
The Tikhonov term stabilizes weakly observed frequencies and changes the reconstructed phase. Calibrating the shear direction from gradient moments or a fitted shell is a separate estimation task. Preserve its angular convention and frame before running the inverse; a wrong shear direction can give structured yet incorrect phase contrast.
eggshell
Entry points: fit_shell_plane, fit_ellipse_ransac, fit_ellipsoid, ellipsoid_mask.
Estimate embryo-shell geometry from texture rays and edge contrast; combine plane ellipses into an ellipsoid. RANSAC and fitting diagnostics determine which calibration points support the result.
Execution: Resident calibration geometry and mask helpers; no standalone planned shell-fit phase.
Calibration reduces selected image evidence to a small model. Texture rays find candidate shell points, robust conic fitting rejects inconsistent samples, and plane fits are combined into an ellipsoid when that model is appropriate. The calibrated geometry can then define masks or the directions used by later DIC analysis.
RANSAC seed, inlier tolerances and coverage of the shell matter. A good algebraic fit to a small arc does not establish the position of the unseen opposite wall. The helpers expect resident selected planes/crops, so choose a calibration subset whose memory is known rather than passing a whole acquisition under the assumption that every module is planned.
destripe
Entry points: DestripeParams, Destriper, DestripeOp.
Suppress a wedge of each plane spectrum to remove directional stripes. Set stripe angle, wedge/taper, minimum frequency and mirror padding; biological structure in that spectral wedge is also attenuated.
Execution: Whole-plane FFT operation: all y/x and independent z slices, not a finite local stencil.
Why a spectral wedge requires a whole plane. Directional stripes concentrate energy in selected Fourier directions, but removing those coefficients is a convolution with broadly supported spatial behavior. Exact evaluation of the stated plane-spectrum filter therefore reads the complete y/x plane; a few-pixel halo would define a different approximation.
Angle, excluded low frequencies, taper and mirror padding control which structures are attenuated and how plane edges behave. Compare line profiles and biological structures aligned with the stripe direction, not only the apparent cleanliness of the result. Independent z planes can be processed separately, but each plane’s transform buffers and padding still need to fit.
vessel_trace
Entry points: TraceConfig, TraceResult, trace, wall_supported_mask.
Trace image-supported paths from source candidates to target groups with explicit voxel/expansion caps, clearance/image costs and refinement bounds. Paths are constrained by the provided crop and geometry.
Execution: Resident image/crop tracing, not a globally scheduled tracing phase. trace_with_required_points, fit_paths_with_required_points and candidate_branches add constrained fitting through direct re-exports.
A path search is bounded by the crop and search budget. Image appearance, clearance and route costs guide candidate paths to target groups. Voxel and expansion limits protect the search from exploring an arbitrarily large region. Required-point variants impose geometric waypoints rather than treating every bright branch as an equivalent destination.
The crop defines what the algorithm can know. A vessel leaving that crop and returning elsewhere cannot be recovered merely by increasing a local smoothing radius. Retain path quality and termination diagnostics, and distinguish a search exhausted by its budget from evidence that no valid anatomical connection exists.
cost
Entry points: measure, report.
Run the operation cost-measurement harness and report coefficients used as planning seeds. This is developer tooling, not an image transformation or a universal performance guarantee.
Execution: Measurements must use release builds; machine, shape, dtype and workload affect their interpretation.
A measured coefficient is a planning seed. The harness supplies repeatable operation workloads, measures their execution and reports cost coefficients. Those coefficients help compare candidate partitions, but cache sizes, compiler choices, dtype and shape can change their relevance on another machine.
Run measurements in release mode on controlled workloads and check that their outputs exercise the intended computation. A thinning pass on an almost empty image can report a low cost because it does little work, not because a dense thinning workload is intrinsically cheap. Keep these measurements separate from correctness assertions and from an application’s end-to-end I/O timing.