src.utils.curve.simple_crossing_handler

Classes

SimpleCrossingHandler([segment_grid_cell, sce])

class src.utils.curve.simple_crossing_handler.SimpleCrossingHandler(segment_grid_cell=5.0, sce=None)
Author:

Alberto M. Esmoris Pena

Cross-feature and cross-CID crossing resolver for the curves produced by SimpleCurveExtractor. Bundles the C++-backed bbox-grid crossing detection, truncation application, same-CID and cross-CID resolvers, the fixed-point driver and the coverage- refine drop dispatcher.

Instances are constructed once per consuming SCE pipeline phase from the private orchestrator helpers _step_merge_resolve_split_pipeline, _merge_resolve_sanitize_triplet, _step_overlap_and_cross_cid_cleanup and _step_adopt_short_cids; they take a snapshot of the relevant SCE attribute (_segment_grid_cell) plus a back-reference to the extractor for symmetry with R3/R4/R5. See SimpleCurveExtractor for the upstream pipeline that produces smooth_curves and metadata.

Six public methods are exposed: find_crossings() (the shared bbox-grid crossing-detection pipeline), apply_truncations() (the static truncation applier), resolve_cross_features() (same-CID resolver), resolve_cross_cid_crossings() (cross-CID resolver with the SKEL_MTH='coverage_refine' predicate), resolve_until_stable() (fixed-point driver over resolve_cross_features) and drop_cov_refine_by_predicate() (the instance-mode dispatcher that delegates to SimpleCurveExtractor._drop_coverage_crossing_features(), which intentionally stays on SCE as a unit-test public entry point).

Variables:

  • segment_grid_cell (float) – Bbox-grid cell size forwarded to the C++ curve_segments_cross_{f,d} binding and to the SimpleCurveExtractor._drop_coverage_crossing_features() helper. A floor of 1e-3 guards against degenerate zero/near-zero configurations.

  • _sce (SimpleCurveExtractor or None) – Back-reference to the consuming SimpleCurveExtractor instance, held for symmetry with R3/R4/R5 (no live back-calls in R6).

__init__(segment_grid_cell=5.0, sce=None)

Snapshot the SCE configuration relevant to the crossing-detection cascade.

find_crossings(smooth_curves, metadata, groups, predicate, pick_truncation, endpoint_touch_skip=False)

Common crossing-detection pipeline shared by resolve_cross_features() and resolve_cross_cid_crossings(). For each group of feature indices, invokes the C++ curve_segments_cross_{f,d} binding to enumerate cross-feature segment crossings (grid build + bbox indexing + geometry filter all in C++); for each returned pair calls predicate to confirm the pair must be processed, then pick_truncation to choose which feature to truncate and at which segment. Returns a {feature_idx: segment_idx} map with the EARLIEST truncation per feature.

The binding emits strict fa < fb pairs and a given (fa, fb) feature pair may appear with multiple (ia, ib) candidates; the first passing predicate wins per feature pair.

Parameters:

  • smooth_curves (list of dict) – Features (curve dicts).

  • metadata (list of dict) – Per-feature metadata dicts.

  • groups (dict) – Mapping {key: [feat_idx...]} used to scope the segment grid. A single global “all-features” group is supplied by resolve_cross_cid_crossings().

  • predicate (callable) – Callable (fa, fb, metadata) -> bool. False rejects the pair before geometry testing.

  • pick_truncation (callable) – Callable (fa, fb, ia, ib, pa, pb, metadata) -> (feat_to_trunc, segment_idx).

  • endpoint_touch_skip (bool) – If True, reject pairs whose endpoints touch within 1e-3 (used by the same-CID resolver; cross-CID resolver does not use this). Forwarded directly to the C++ binding.

Returns:

{feat_idx: earliest_si_t}.

Return type:

dict

static apply_truncations(smooth_curves, metadata, truncations)

Apply segment-index truncations to features. For each feature index present in truncations, slice points and slopes to si_t + 1; drop features that end up with fewer than 2 points; rebuild arc lengths through Polyline and refresh LENGTH_2D / LENGTH_3D on a copied metadata entry.

Parameters:

  • smooth_curves (list of dict) – Features (curve dicts).

  • metadata (list of dict) – Per-feature metadata dicts.

  • truncations (dict) – {feat_idx: si_t}.

Returns:

(out_curves, out_metadata).

Return type:

tuple

resolve_cross_features(smooth_curves, metadata)

Detect and resolve crossings between different features of the same CURVE_ID. When two features from the same curve cross, the shorter one is truncated at the crossing point.

First pass: detect all crossings (delegated to find_crossings()). Second pass: apply truncations (delegated to apply_truncations()).

Parameters:

  • smooth_curves (list of dict) – Chained curve segments.

  • metadata (list of dict) – Per-chain metadata dicts.

Returns:

Resolved (smooth_curves, metadata).

Return type:

tuple

resolve_cross_cid_crossings(smooth_curves, metadata)

Detect and resolve crossings between features from DIFFERENT CURVE_IDs where at least one has SKEL_MTH='coverage_refine'. The coverage_refine feature is always truncated; if both are refine, the shorter one is truncated.

Uses the same spatial-grid and two-pass pattern as resolve_cross_features(), through the shared helpers find_crossings() and apply_truncations().

Parameters:

  • smooth_curves (list of dict) – Chained curve segments.

  • metadata (list of dict) – Per-chain metadata dicts.

Returns:

Resolved (smooth_curves, metadata).

Return type:

tuple

resolve_until_stable(smooth_curves, metadata, max_passes=None)

Run resolve_cross_features() to fixed point via SimpleCurveExtractor._apply_until_stable(). Wraps the lambda boilerplate that was repeated at every cascade site. Extracted in iter4 (Phase 1, L-25).

Parameters:

  • smooth_curves (list of dict) – Curve segments.

  • metadata (list of dict) – Per-segment metadata dicts.

  • max_passes (int or None) – Optional iteration cap forwarded verbatim to SimpleCurveExtractor._apply_until_stable().

Returns:

Final (smooth_curves, metadata).

Return type:

tuple

drop_cov_refine_by_predicate(smooth_curves, metadata, predicate, log_suffix)

Run SimpleCurveExtractor._drop_coverage_crossing_features() with predicate and drop the resulting feature indices from smooth_curves and metadata. Used twice in _step_adopt_short_cids to collapse two near- identical predicate+drop blocks (L-15 in the Phase-1 ledger).

Mirrors the original inline pattern verbatim:

  • Cell size always self.segment_grid_cell (Phase-9 SR-2 per-instance scale-robust replacement of the legacy DEFAULT_SEGMENT_GRID_CELL).

  • Drop set is built once; surviving lists are re-materialised with i not in drop_set (the in predicate iterates over a set, so the mask preserves the original ordering).

  • Logs 'SimpleCrossingHandler: Dropped {N} ' + log_suffix only when drop_set is non-empty.

Parameters:

  • smooth_curves (list of dict) – Curve dicts.

  • metadata (list of dict) – Per-segment metadata dicts.

  • predicate (callable) – Crossing-pair predicate forwarded to SimpleCurveExtractor._drop_coverage_crossing_features().

  • log_suffix (str) – Suffix appended after 'Dropped {N} ' when emitting the debug log line.

Returns:

(smooth_curves, metadata).

Return type:

tuple