Morphology, topology and distance

Structuring elements describe the mathematical neighborhood. Connectivity describes which voxels belong to the same region. Keep these choices explicit, especially when foreground and background topology must agree.

Available operations

element

Source.

Entry points: StructuringElement, ElementShape, StepOrigin, Rank.

Define neighborhood geometry, even-sized anchor placement and selected ranks. Reflect an asymmetric element where the mathematical operation requires it.

Execution: Configuration shared by bounded morphology/rank kernels; no execution by itself.

Why origin placement matters. An odd centered width of seven has sides (3,3). A centered width of ten has no central voxel, so its chosen anchor can give (5,4). Reflection exchanges those sides; it is required when switching between gathering erosion and placing dilation in a mathematical opening. Element shape, step spacing and origin therefore affect both values and dependency geometry.

A box, ball and sparse custom neighborhood can share a bounding box while visiting different samples. The bounding halo guarantees availability; it is not the list of samples to include in a statistic. Keep the element object intact when constructing related operations instead of manually restating a radius in each one.

morphology

Source.

Entry points: MorphologyOp, GreyErodeOp, GreyDilateOp, HitOrMissOp.

Binary and grey erosion/dilation, opening/closing, top-hats, gradients and hit-or-miss. Composed opening/closing support includes both passes.

Execution: Planned bounded-support operations and resident kernels; boolean and grey-value APIs are separate.

Composition changes support. A primitive erosion/dilation reads the element’s own sides. An opening or closing composes a pass with the reflected element and reads (lo+hi, lo+hi) per axis. For the width-ten (5,4) element that is (9,9), not (10,8) and not (5,4). This is why the module uses reach_spec_reflected_pair for these compositions.

Use binary morphology for masks and grey morphology for extrema of intensity values. Hit-or-miss tests a joint foreground/background configuration, so the union of both required neighborhoods must be present. Changing the compute block grid must not alter these definitions; treating every tile boundary as background would manufacture object erosion along seams.

fill

Source.

Entry points: LabelBackgroundOp, FillHolesOp, append_open_on.

Fill enclosed background components. Select connectivity and which true volume faces count as open; opening only one side can define the region beneath a sheet.

Execution: Local component fragments plus global exterior merge, followed by blockwise painting.

Why a local window cannot prove a hole is enclosed. A dark component may connect to an open image face through a long narrow channel. No fixed halo can rule that connection out. The first stage labels local background components and records contacts; the global merge identifies which joined components reach the selected true faces. The painting stage fills only the remaining components.

Choose open faces to match the intended geometry. Opening all faces gives conventional enclosed-hole filling; opening a selected face can classify the space above or below a sheet. This is a topological convention, not an optimization. Its global component state can be large for salt-and-pepper masks even when the image reads stay blockwise.

reconstruct

Source.

Entry points: HExtremaOp, reconstruct, h_extrema_iterative.

Geodesic reconstruction and h-extrema suppression iterate local updates to stability under a fixed mask/constraint. A fixed number of updates and a converged reconstruction are different operations.

Execution: Resident helpers and planned iterative execution; one substage has bounded support, but propagation can travel globally.

Propagation needs synchronization. Geodesic reconstruction starts from a marker and repeatedly expands it subject to a mask. A voxel changed many iterations ago can eventually influence a distant region, although each individual update reads only nearby state. The iterative route declares the update’s operands and exchanges the required state between substages; it does not approximate convergence with a halo chosen from object size.

For h-maxima/h-minima, the marker offset and intensity convention determine which extrema survive. Set a convergence/iteration limit and inspect whether it was reached. A finite-step result is useful when deliberately requested, but should not be labeled a converged reconstruction solely because its local neighborhoods fit the block.

distance

Source.

Entry points: DistanceParams, DistanceSweepOp, DistanceFinishOp, distance_transform.

Exact anisotropic Euclidean distance to background via one-dimensional parabola-envelope sweeps. chamfer_distance is a separate approximate method. Set physical sampling and the unbounded-mask behavior.

Execution: Planned whole-axis line passes over transverse strips; not an arbitrary fixed-halo stencil.

Why the reach is a whole axis. During a one-dimensional Euclidean distance sweep, a background site anywhere on that line may be the nearest site for the current voxel. A finite radius cannot preserve the exact uncapped result. DistanceSweepOp therefore declares AxisReach::All on the swept axis and zero reach on the transverse axes; each task can hold a strip of complete lines instead of the complete volume.

The passes accumulate squared, physically weighted distances, and the finish stage converts to the requested form. A dense transform is appropriate when many later voxels need distances. For a sparse set of points and a declared cap, use the point-distance route instead. That route changes the requested result and dependency shape; it is not a faster exact replacement at unlimited radius.

envelope

Source.

Entry points: RollingBallEnvelope, append_rolling_ball_envelope_phases.

Construct a binary envelope using exterior rolling-ball accessibility at a physical radius. This is a geometric mask operation, distinct from intensity-background subtraction.

Execution: Composes exact distance sweeps and global exterior-component merging.

The radius has physical meaning. The envelope asks where a ball of the stated physical radius can move from exterior space. Narrow clefts inaccessible to that ball can be bridged without claiming that they contain measured tissue. Anisotropic voxel pitches matter because a physically round ball is not generally a voxel-index sphere.

The pipeline inherits two different dependency mechanisms: complete-line distance sweeps and global exterior-component classification. A single large local morphological radius cannot automatically replace that exterior accessibility decision. Use the resulting envelope as a geometric support model and retain the original mask for analyses that require measured rather than inferred material.

path_opening

Source.

Entry points: PathParams, PathOpeningOp, PathCones.

Grey path openings/closings retain sufficiently long structures along planar or volume adjacency cones. The robust variant allows a bounded run of gaps.

Execution: Planned finite reach derived from path length/cones/gaps, plus resident kernels.

A path-length bound gives a finite halo. A length L path with maximum gap allowance G can reach (L−1)(G+1) along axes used by its adjacency cones. Planar cones do not read neighboring z planes; volume cones do. For L=8 and G=1, the bound is 14, substantially wider than a one-step adjacency radius.

Length is a path criterion rather than a disk radius: a thin curving structure may survive even when a compact object of the same area does not. The cone set restricts admissible directions and robust gaps allow limited interruptions. Increase those parameters only when the changed structural definition is intended, since they alter both selectivity and halo work.

skeleton

Source.

Entry points: ThinningOp, thin, thin_to_fixed_point, betti_numbers.

Topology-preserving binary thinning, explicit subfields and pass limits. Additional resident helpers count components, Euler characteristic and Betti numbers.

Execution: Planned bounded-pass thinning; fixed-point helpers are separate. Repeated local deletions can require many passes.

The primitive pass and convergence have different dependencies. ThinningOp performs one subfield deletion decision using a 3×3×3 neighborhood, so its external radius is one. The global coordinate anchor determines the subfield phase. A complete thinning sequence must keep that phase consistent across seams; restarting parity relative to each buffer would change which voxels are considered together.

Repeated subfields can move the skeleton boundary over many updates. Use the stated pass sequence or fixed-point helper according to the desired result, and preserve the foreground/background connectivity convention when interpreting topology. The resident Betti-number helpers answer global questions and are not obtained by summing each block’s topology independently.

directional

Source.

Entry points: DirectionalPassOp, directional_thin, directional_to_fixed_point.

Directional template-based thinning using deletion tables and explicit border handling. Distinguish a single directional sweep from a full cycle or convergence.

Execution: Bounded-support planned passes and resident fixed-point helpers.

One named pass contains several local updates. DirectionalPassOp includes twelve sub-iterations, each capable of depending on a newly changed one-voxel neighbor. Its declared radius is therefore twelve on every axis, even though each individual lookup examines a 3×3×3 pattern. Using radius one for the whole pass would read stale information near its core boundary.

The deletion tables and border treatment specify the algorithm. A full fixed-point run can perform many such passes and has a separate stop/limit contract. This is a useful contrast with the single-subfield skeleton operation: similar-looking binary thinning kernels need different halos because their public execution units contain different amounts of sequential work.

configuration

Source.

Entry points: ConfigurationPassOp, ConfigurationFixedPointOp, ConfigurationTable.

Apply a caller-supplied 3×3×3 binary neighborhood lookup table. The table defines the rewrite rule; arbitrary rules do not automatically preserve topology or converge.

Execution: Planned finite passes or iterative fixed-point execution with a required limit.

A table specifies a rule, not its safety properties. The 27 bits of a 3×3×3 binary neighborhood select one entry from the supplied table. One synchronous table application has radius one. ConfigurationPassOp groups n applications and declares radius n, because the last update can depend transitively on a sample n voxels away.

Use the fixed-point interface when termination is defined by unchanged state, and supply a finite limit. An arbitrary table can oscillate or destroy topology; the framework checks declared execution geometry, not a mathematical proof that a caller-provided rewrite rule is sensible. Keep table version, pass order and limit with the pipeline’s recorded parameters.