ENH: Segmentation Filters OoC Optimization

[joeykleingers]

Summary

• Optimizes 5 Group D filters (IdentifySample, ScalarSegmentFeatures, EBSDSegmentFeatures, CAxisSegmentFeatures, FillBadData) for out-of-core (ZarrStore) performance
• Adds chunk-sequential Connected Component Labeling (CCL) with Union-Find to SegmentFeatures base class, replacing DFS flood-fill for OOC paths
• Runtime dispatch selects BFS/DFS for in-core and CCL for OOC based on storage type
• Splits FillBadData and IdentifySample into separate BFS/CCL algorithm files
• Adds UnionFind.hpp utility class with path-halving compression and union-by-rank
• Adds 200x200x200 benchmark tests and ForceOocAlgorithmGuard correctness tests for all 5 filters

Algorithm Decision

Problem

The original DFS flood-fill in SegmentFeatures uses random data access — each stack pop reads an arbitrary voxel then checks 6 scattered neighbors. For in-core DataStore this is fast, but for ZarrStore-backed arrays every random access can trigger a chunk load/evict cycle, causing 50x–621x slowdowns.

Solution: Chunk-Sequential CCL with Union-Find

A two-phase scanline algorithm that processes the grid in strict Z-Y-X order:

Phase 1 — Forward Labeling: Iterate every voxel in scanline order. For each valid voxel, check only backward neighbors (-X, -Y, -Z). Assign provisional labels and union equivalences in a Union-Find structure. A 2-slice rolling buffer (current + previous Z-slice) keeps all neighbor reads in RAM.

Phase 2 — Resolution and Relabeling: Flatten the Union-Find, then two sequential passes remap provisional labels to final feature IDs (assigned in seed-discovery order for compatibility with the original DFS numbering).

Why This Algorithm

1. Eliminates random access entirely — every read is from the rolling buffer (RAM) or a sequential chunk load
2. Memory scales with slice size, not volume — O(dimX × dimY) for the buffer + O(num_features) for Union-Find
3. Preserves feature numbering order — Phase 2 remaps to match original DFS seed-discovery order
4. Shared base class — executeCCL() in SegmentFeatures serves all 4 subclasses via isValidVoxel() and areNeighborsSimilar() virtual methods

Dispatch

Each filter checks IsOutOfCore(*featureIdsArray) || ForceOocAlgorithm():

• True → executeCCL() (chunk-sequential CCL)
• False → execute() (original DFS flood-fill)

FillBadData (special case)

FillBadData uses its own 4-phase CCL (not the base class executeCCL()):

1. CCL with negative labels for bad-data regions
2. Flatten Union-Find and accumulate region sizes
3. Classify regions by size (small → fill, large → preserve as voids)
4. Iterative morphological dilation to fill marked regions

Split into FillBadDataBFS.cpp (in-core) and FillBadDataCCL.cpp (OOC) with dispatch in the main algorithm class.

Performance Results (200x200x200)

Filter	In-Core Speedup	OOC Speedup
IdentifySample	1.6x faster	>367x faster
ScalarSegmentFeatures	1.5x faster	>116x faster
EBSDSegmentFeatures	1.8x faster	>42x faster
CAxisSegmentFeatures	1.7x faster	>46x faster
FillBadData	3.2x faster	3.0x faster

OOC baselines for 4 of 5 filters timed out at 1500s (DFS on ZarrStore). FillBadData's baseline already had CCL from PR #1515; this PR refactored it into separate BFS/CCL dispatch files.

Test plan

• All existing IdentifySample, ScalarSegmentFeatures, EBSDSegmentFeatures, CAxisSegmentFeatures, and FillBadData unit tests pass with both in-core and OOC algorithm paths (GENERATE(false, true) + ForceOocAlgorithmGuard)
• New 200x200x200 benchmark tests pass for all 5 filters in both in-core and OOC configurations
• In-core benchmarks show no regression (all filters same speed or faster)
• Builds clean on both simplnx-Rel and simplnx-ooc-Rel presets