flowchart LR M[Mask blocks] --> L[Local labels and face facts] L --> U[Merge seam equivalences] U --> R[Relabel or filter each block] R --> O[Consistent regions]
Components, watershed and region cleanup
Local connected-component labels are provisional. Components crossing block faces need a seam merge before their final identities, sizes or exterior status can be trusted. Watershed variants additionally differ in ordering and tile-grid semantics; choose one deliberately.
Available operations
components
Entry points: Connectivity, Union, LabelIndex, walk_seams.
Shared component labeling, connectivity steps, seam facts and union-find structures. These are building blocks for labeling, filling, hysteresis and region extraction.
Execution: Local kernels plus global component merging; merged component state can grow with object count.
What crosses a seam. A connected component can be arbitrarily long, but its communication across one block boundary consists of local label identities and the face/edge/corner contacts required by the selected connectivity. Union-find merges those equivalences transitively. A local label number is therefore meaningful only together with its producer block until the merge assigns global identities.
Choose 6-, 18- or 26-connectivity according to whether face, edge or corner touching joins foreground. The complement’s topology may need a different convention. Global component counts, sizes and exterior flags must be computed after transitive merging; adding local counts double-counts objects crossing seams.
label
Entry points: LabelComponentsOp, RelabelComponentsOp, LabelPointsOp.
Label connected masks, merge seam equivalences and relabel blocks. Also stamp weighted/named points into labels and widen label dtypes. Point painting is not connected-component labeling.
Execution: Planned component/relabel phases and point painting; label IDs must remain exact integers.
Why labeling can start with zero pixel halo. LabelComponentsOp labels its own core and emits the seam facts needed to join local components later. It need not discover the entire component in its image read. RelabelComponentsOp uses a barrier/reduction to obtain the mapping and then paints each block. This is fundamentally different from a filter that must fetch all input evidence before emitting a core value.
Use the complete label/merge/relabel route when object identities leave the pipeline. Stamping supplied points with LabelPointsOp instead draws names at positions; adjacent painted names are not automatically merged. Preserve integer label carriers when widening or publishing labels, especially when sparse IDs are large.
detect
Entry points: LabelRegionsOp, RegionPointsOp, detect_phases.
Extract connected regions and merge their moments into centroid/measurement rows. Connectivity, emission mode and core ownership determine which rows leave each block.
Execution: Planned fragments with seam merge; resident region and moment helpers also exist.
Why moments are merged after components. A region split between blocks contributes several provisional moment states. Counts, coordinate sums and intensity summaries can be merged after the seam equivalences identify the true region. The final centroid then reflects all pieces, rather than a collection of per-tile centroids.
Set connectivity and emission mode explicitly. A detection row’s ownership is anchored in the global volume so that it is emitted once even when its region spans several cores. The image extraction stages can be bounded while the component/moment map grows with the number of regions. Use filters on final merged measurements when a size or brightness threshold is intended to describe whole objects.
regional
Entry points: LabelPlateauxOp, RegionalMaximaOp, regional_maxima.
Identify connected flat plateaux and determine whether they have a higher neighbor. A plateau spanning blocks cannot be decided by testing each tile independently.
Execution: Planned plateau facts and global merge; resident helpers available. Plateau state is data-dependent.
A flat peak is a connected object. A regional maximum is a plateau for which no connected plateau voxel has a higher neighbor. Looking at only the center voxel or the interior of one block cannot settle that property: another piece of the same plateau can meet a higher value several blocks away.
The planned route emits plateau identities and comparisons, merges seam-connected plateaux, and derives final extrema flags. The output therefore has a global connectivity dependency even though each local comparison is short-range. Specify how a plateau becomes points or a mask before using it as a seed source; a plateau is not automatically one statistically fitted emitter.
watershed
Entry points: SeededWatershedOp, ScalableWatershedOp, blockwise_minimax_watershed.
Seeded flooding and alternative minimax/scalable routines over a cost image. Seed, separation and tie-order conventions influence labels; the APIs do not promise all variants give the same partition.
Execution: Resident/global and planned whole-volume routes exist. A planned wrapper alone does not establish bounded memory.
Why exact flooding requests global state. Queue order, ties, seed arrivals and competing paths can affect which basin claims a voxel. A seed can influence a distant part of the image through a low-cost path, so no fixed finite halo guarantees the same globally ordered watershed on arbitrary data. The whole-volume declarations make that constraint visible to planning instead of hiding a large allocation inside a local-looking wrapper.
Choose seed IDs, mask, separation and tie semantics as part of the result definition. The scalable/minimax alternatives have their own numerical contracts. If the purpose is only to form supervoxels for later graph merging, fixed-tile watershed offers a bounded but deliberately different starting partition.
tiled_watershed
Entry points: TiledWatershedConfig, TiledWatershedOp.
Produce supervoxels by independent watershed on globally fixed tiles with halos. The pinned tile grid is part of the algorithm, unlike a freely chosen compute grid.
Execution: Bounded tile buffers with explicit support; an oversegmentation, not exact global watershed.
Why its halo is an algorithm parameter. Independent tile floods do not reproduce an exact global queue. They produce a fixed oversegmentation whose tile/halo layout is part of the requested answer. The op checks the compute grid against its fixed tiles; merely changing a scheduler block edge is not an allowed numerical no-op for this algorithm.
Finding only global seeds inside each crop is unsafe: a crop can contain a basin tail but not its seed. The implementation uses buffer-edge minima where necessary so that an unreachable distant seed does not let another basin claim that tail. Optional global seeds retain their IDs where reached. Tile-specific fragments can later be rejoined using a region adjacency graph, but that later merge needs evidence rather than an assumption that every seam contact belongs together.
scikitimage_watershed
Entry points: watershed_raveled.
A flattened-array watershed helper with explicit queue semantics used for reference-compatible behavior. Callers supply shape/connectivity information in the raveled representation.
Execution: Resident helper; not a separate out-of-core planner phase.
Where the reference contract applies. This helper operates on flattened resident arrays and explicit neighbor offsets, so array order, connectivity and queue initialization must agree with the caller. Its purpose is a specific watershed queue behavior, not an automatic conversion from an arbitrary image source into a bounded plan.
Use it as a numerical reference or inside a crop whose memory is already budgeted. Passing the flattened form of a very large volume does not avoid the memory required by its queue and arrays. For a planned operation, select the global or fixed-tile route whose dependency contract matches the desired segmentation.
cleanup
Entry points: append_remove_small_objects_phases, append_remove_small_holes_phases, ExpandLabelsOp, RingLabelsOp.
Remove small components/holes; clear selected borders; filter label sizes; fill label holes in 2D; expand or ring labels; prune by object distance. Bounds, connectivity and label conflict rules are part of the configuration.
Execution: A mix of component/reduction pipelines and bounded neighborhood operations. Choose the named planned helper rather than assuming a resident helper scales.
The name does not imply one dependency shape. Removing small connected objects needs global component sizes; clearing a selected border needs globally merged exterior contacts. Those decisions use fragments and reductions. By contrast, expanding labels by a finite distance or extracting a local ring examines a bounded neighborhood around each output coordinate.
ExpandLabelsOp derives its integer search radius from the requested distance, and competing labels follow its deterministic distance/tie convention. Expansion does not estimate a cell membrane. Filtering by object size should happen after components have been merged, or one object crossing many blocks can be incorrectly discarded as several small pieces.
A global merge here can operate on component facts rather than retaining the whole intensity volume. Its own state still grows with the number of components.