Graph and iterative segmentation
These methods have nonlocal decisions even when their image evidence is computed locally. A bounded image read does not bound the size of the reduced graph or sparse solve. Account for those structures separately.
Available operations
rag
Entry points: Rag, RagOptions, rag_block.
Build region adjacency with node and boundary statistics from labels and optional evidence. Convert the result to a graph for agglomeration.
Execution: Resident construction kernels; graph size follows region/contact count.
The graph is a reduction of image evidence. Region nodes aggregate per-label facts, while edges aggregate contacts and optional boundary values between labels. Choose the statistic according to the later decision: boundary area, mean probability and extreme probability encode different evidence and need different merge rules.
A local construction kernel does not own the global partition. Merge repeated region IDs and repeated label-pair contacts before running agglomeration. The result can be much smaller than the image for a coarse oversegmentation, or very large when almost every voxel has a distinct label. Graph memory follows that region/contact population.
rag_phases
Entry points: append_rag_phases, RagBlockOp, append_relabel_phase.
Collect RAG facts in planned blocks, merge them and paint a resulting label lookup back onto the volume.
Execution: Planned fragment construction/relabeling around a caller-owned graph solve.
Why graph building and relabeling are separate. Image blocks can emit sparse node/edge partials with local boundary reads. After those facts are merged, a graph algorithm returns a region-to-segment mapping. Painting that mapping is a lookup on each exact integer label and needs no new image neighborhood.
Keep the graph’s key namespace tied to the segmentation that produced it. A lookup generated for a relabeled or independently tiled image cannot safely be reused just because its integer keys happen to overlap. The helper stages expose the data movement and block ownership while leaving the choice of graph solve to the application.
agglomerate
Entry points: mutex_watershed, gasp, gaec, multicut, lifted_gasp.
Partition signed affinity graphs; positive weights attract and negative weights repel. kernighan_lin refines partitions and lifted edges add nonlocal evidence. These are heuristics, not exact multicut solvers.
Execution: Resident reduced-graph algorithms plus relabel helpers, independent of voxel storage.
Choosing an objective. An attractive edge encourages its two nodes to share a segment; a repulsive edge discourages it. Greedy edge contraction, mutex rules, signed agglomeration and local partition refinements make different compromises between objective improvement, hard exclusions and runtime. None should be selected solely because all return a vector of labels.
Lifted edges encode relationships between nodes that do not directly touch in the image. They change the graph model, not the pixel halo. Store the weight transform and seed/tie choices alongside the graph. Assess splits and merges on held-out image examples, since an improved graph score does not by itself establish a biologically correct boundary.
segment_split
Entry points: split_segment, split_segment_k.
Split a selected region using user seeds and minimum cuts on its RAG. Edge capacities derive from boundary evidence and geometric area.
Execution: Resident graph editing for a selected segment; source-graph size controls memory.
An interactive edit can stay smaller than a whole image. The selected segment’s subgraph and seed constraints define the cut. Hard seed assignments specify which pieces must separate; edge capacities derived from membrane evidence and area specify which separation is inexpensive. The image need not be resegmented everywhere to change that grouping.
The memory benefit depends on the selected subgraph fitting the declared editing budget. A nearly whole-volume segment can still produce a large cut problem. Validate that seeds lie in the intended segment and inspect the resulting adjacency/label mapping before publishing the edit, especially when a region graph has been regenerated.
random_walker
Entry points: RandomWalkerRowsOp, RandomWalkerSolveOp, append_random_walker_binary_seed_image_phases.
Assemble edge weights and sparse rows from image blocks, solve seeded random-walker probabilities, then map values back through row IDs. Binary and resident multilabel helpers are distinct routes.
Execution: Planned row assembly plus barrier sparse solve. Global solve memory grows with the assembled unknowns.
Why a short-range graph produces a global solve. Neighboring voxels exchange edge weights derived from their intensity difference, but the probability at one unlabeled voxel depends on all connected seeded paths through the graph. The assembled Laplacian must therefore be solved with global boundary conditions; truncating the image to a small halo changes the problem.
The planned route gives unknowns row IDs, emits sparse rows from blocks and performs a barrier solve before painting probabilities. This bounds image reads without making the sparse system constant-size. State the intensity scale/edge-weight parameter, seeded classes and solver tolerances, and distinguish a probability image from the final discrete class decision.
level_set
Entry points: GeodesicLevelSetStepOp, append_geodesic_level_set_phases, ChanVeseLevelSetConfig.
Geodesic active contours and Chan–Vese region models evolve a signed field. Initialization, timestep, stopping and intensity means define the method.
Execution: Planned geodesic steps plus resident iterative helpers; inspect the chosen API before assuming a bounded iterative store.
The update unit explains the halo. GeodesicLevelSetStepOp reads a two-voxel margin from both the running signed field and its declared image evidence. Curvature and derivative calculations need more than a pointwise speed value. Repeating steps must exchange the latest field between updates; a fixed original-image crop alone cannot provide neighboring evolved state.
The level-set sign convention, initialization and timestep determine how fronts move. Chan–Vese additionally uses region statistics, so a resident helper with that name has a different execution contract from the planned geodesic step. Check convergence/energy diagnostics and image frame alignment rather than interpreting every zero contour as the same segmentation method.
label_energy
Entry points: LabelEnergySweepOp, append_label_energy_phases, refine_labels.
Refine multi-label volumes using neighborhood energy, image likelihood and annealing/acceptance policies. Topology-aware flips and deterministic counter-based draws make the update rule explicit.
Execution: Planned finite-support sweeps and resident refinement; update schedule and seed affect results.
A sweep has more support than one flip. Label changes occur in a prescribed colored/subfield order. Later substeps can read labels changed by earlier ones, so sweep_reach derives the whole sweep’s dependency rather than claiming the radius of one acceptance test. The appearance/boundary sources use matching source reaches.
Class likelihood, surface terms, topology checks, temperature and random seed are model parameters. Counter-based randomness makes draws a function of the intended update coordinates rather than incidental task order. This does not make annealing deterministic across different parameter schedules; it makes a stated schedule reproducible across execution cuts that satisfy the contract.
surfaces
Entry points: append_layered_surface_phases, SurfaceBandOp, SurfaceLinesOp.
Find constrained stacked height-field surfaces, paint intervening region labels and derive bands/lines. Pool columns, solve a smaller global graph, then paint by blocks.
Execution: Planned reduction/global solve/application; reduced state scales with columns and surface count, not merely block size.
Reduction replaces a huge dense solve with a smaller structured one. The algorithm assumes surfaces can be represented as constrained height fields. Blocks pool evidence into columns; a global cut chooses heights subject to ordering/slope or separation constraints; later blocks paint regions and bands from that shared result. A folded or overhanging object may violate the height-field model even if the optimization succeeds.
The reduced graph scales with sampled columns, allowed depths and surface count. Pooling stride trades geometric resolution against graph size and must remain fixed during a comparison. Bounds on graph nodes and sampling are meaningful failure controls; reducing compute block size cannot rescue an intrinsically oversized reduced graph.