Complete inner grain boundaries with anchored shortest paths

[ralfHielscher]

Summary

• add an opt-in completeBoundaries flag to calcGrains
• represent Voronoi boundary segments as a compact grain-local dual graph
• extend every retained inner-boundary network until all of its free ends reach existing non-inner boundaries
• allow an augmentation to connect different boundary components, but never reconnect one component to itself
• ignore enclosed inner-boundary components shorter than three segments
• add bridge, noise-fragment, map-edge, minPixel, and isolated-pixel-loop regression cases

Motivation

Connected-component reconstruction can merge otherwise distinct grains when only one sub-threshold neighboring pixel pair bridges them. The detected interfaces then remain as self-boundaries inside the merged grain.

An unconstrained pixel minimum cut tends to isolate a single boundary pixel because that is often the cheapest cut. Boundary completion is therefore performed in the planar dual graph instead: retained boundary chains are extended along Voronoi segments until the resulting network is anchored at non-inner boundaries.

Loop prevention

For each free boundary endpoint, admissible targets are either:

• a vertex on an existing inter-grain or exterior map boundary, or
• a free endpoint belonging to a different boundary component

All other vertices of the active boundary network are blocked while finding the path. Consequently, an added path cannot connect a boundary component back to itself and cannot close a new loop around an isolated pixel. Once different components are joined, their remaining free ends are still extended until the complete network terminates at non-inner boundaries.

Performance

• replaces repeated grain-sized pixel max-flow problems with unweighted shortest paths in the boundary-segment dual
• processes only grains containing retained inner boundaries
• uses compact local vertex ids, avoiding graph objects with map-sized ranges of isolated vertices
• filters short enclosed noise fragments before constructing path problems
• keeps the conservative unsplit grain sizes in the preliminary minPixel pass, so completion is not run twice

The path sequence is greedy: every augmentation uses the smallest currently available number of new segments, but the complete result is not claimed to be a globally optimal Steiner forest.

Compatibility

Default reconstruction is unchanged unless completeBoundaries is supplied. One- and two-segment enclosed fragments are removed as noise; equally short fragments touching a pre-existing non-inner boundary are retained.

Validation

• connector branch contents verified byte-for-byte against the workspace
• function-signature JSON and Git whitespace/static checks pass
• equivalent square-grid graph simulations preserve the 50/50 bridge split and extend a three-segment U-shaped fragment to the exterior without producing a one-pixel grain
• MATLAB regression cases are included but could not be executed because this workspace has no MATLAB or Octave runtime