vibespatial.spatial.segment_primitives¶

Classes¶

`SegmentIntersectionKind`	Enum where members are also (and must be) ints
`SegmentTable`
`DeviceSegmentTable`	GPU-resident segment table in SoA layout.
`DeviceBroadcastSegmentRelation`	One physical segment table related to many logical geometry rows.
`DeviceRingLocalSegmentRelation`	Complete mask rings related to only their local logical rows.
`SegmentIntersectionResult`	Segment intersection results with lazy host materialization.
`PagedSegmentIntersectionResult`	Device-classified intersection pages beyond one contiguous relation budget.
`SegmentIntersectionBenchmark`
`SegmentLocalEventSummary`	Per-row exact local-event summary derived from segment intersections.
`SegmentIntersectionDeviceState`
`SegmentIntersectionCandidates`
`DeviceSegmentIntersectionCandidates`	GPU-resident candidate pairs from sweep-based spatial join.
`DeviceSegmentIntersectionCandidatePages`	Marker for candidate pages consumed without contiguous concatenation.

Functions¶

`device_segment_table_as_linestrings`(...)	Expose segment rows as a compact fixed-width device geometry carrier.
`concatenate_paged_segment_intersections_device`(...)	Globally concatenate compact classified pages for ordered consumers.
`extract_segments`(→ SegmentTable)	Extract segments from geometry array on CPU (legacy path).
`generate_segment_candidates`(...)
`classify_segment_intersections`(...)	Classify all segment-segment intersections between two geometry arrays.
`summarize_exact_local_events`(→ SegmentLocalEventSummary)	Summarize per-row exact local-event counts for overlay-style workloads.
`benchmark_segment_intersections`(...)

Module Contents¶

class vibespatial.spatial.segment_primitives.SegmentIntersectionKind¶

Enum where members are also (and must be) ints

DISJOINT = 0¶

PROPER = 1¶

TOUCH = 2¶

OVERLAP = 3¶

class vibespatial.spatial.segment_primitives.SegmentTable¶

row_indices: numpy.ndarray¶

part_indices: numpy.ndarray¶

ring_indices: numpy.ndarray¶

segment_indices: numpy.ndarray¶

x0: numpy.ndarray¶

y0: numpy.ndarray¶

x1: numpy.ndarray¶

y1: numpy.ndarray¶

bounds: numpy.ndarray¶

property count: int¶

class vibespatial.spatial.segment_primitives.DeviceSegmentTable¶

GPU-resident segment table in SoA layout.

row_indices: vibespatial.cuda._runtime.DeviceArray¶

segment_indices: vibespatial.cuda._runtime.DeviceArray¶

x0: vibespatial.cuda._runtime.DeviceArray¶

y0: vibespatial.cuda._runtime.DeviceArray¶

x1: vibespatial.cuda._runtime.DeviceArray¶

y1: vibespatial.cuda._runtime.DeviceArray¶

count: int¶

max_segments_per_row: int | None = None¶

part_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

ring_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

free() → None¶

Release all device allocations held by this table.

Consolidates the 7–9 individual runtime.free() calls that previously had to be duplicated at every cleanup site.

vibespatial.spatial.segment_primitives.device_segment_table_as_linestrings(segments: DeviceSegmentTable) → vibespatial.geometry.owned.OwnedGeometryArray¶

Expose segment rows as a compact fixed-width device geometry carrier.

Segment coordinates remain device-only. The returned rows are independent two-coordinate LineStrings whose bounds can participate in the canonical native spatial-index relation without interpreting the source geometry’s nested offsets again.

class vibespatial.spatial.segment_primitives.DeviceBroadcastSegmentRelation¶

One physical segment table related to many logical geometry rows.

The segment coordinates and source metadata remain singular. Consumers derive a logical segment id from logical_row * physical_count + lookup instead of repeating the table for every row.

physical_segments: DeviceSegmentTable¶

logical_row_count: int¶

property physical_count: int¶

property logical_count: int¶

class vibespatial.spatial.segment_primitives.DeviceRingLocalSegmentRelation¶

Complete mask rings related to only their local logical rows.

ring_relation maps target geometry rows to source ring ids. Every source ring is represented by one contiguous span in source_segments. Hole candidates must be accompanied by their ancestor shell in the relation; that complete shell is the winding baseline consumed by the existing exact face walk. Materialization therefore scales with complete candidate-ring segments, never logical_rows * all_mask_segments.

source_segments: DeviceSegmentTable¶

ring_relation: object¶

ring_starts: vibespatial.cuda._runtime.DeviceArray¶

ring_ends: vibespatial.cuda._runtime.DeviceArray¶

ancestor_shell_ring_ids: vibespatial.cuda._runtime.DeviceArray¶

property candidate_ring_count: int¶

materialize_segments() → DeviceSegmentTable¶: Gather complete candidate rings into row-local topology storage.

class vibespatial.spatial.segment_primitives.SegmentIntersectionResult¶

Segment intersection results with lazy host materialization.

When produced by the GPU pipeline, all 14 result arrays live in device_state and host numpy arrays are lazily copied on first property access. GPU-only consumers (e.g. build_gpu_split_events) that read only device_state, candidate_pairs, count, runtime_selection, precision_plan, and robustness_plan never trigger device-to-host copies.

candidate_pairs: int¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

precision_plan: vibespatial.runtime.precision.PrecisionPlan¶

robustness_plan: vibespatial.runtime.robustness.RobustnessPlan¶

device_state: SegmentIntersectionDeviceState | None = None¶

property left_rows: numpy.ndarray¶

property left_segments: numpy.ndarray¶

property left_lookup: numpy.ndarray¶

property right_rows: numpy.ndarray¶

property right_segments: numpy.ndarray¶

property right_lookup: numpy.ndarray¶

property kinds: numpy.ndarray¶

property point_x: numpy.ndarray¶

property point_y: numpy.ndarray¶

property overlap_x0: numpy.ndarray¶

property overlap_y0: numpy.ndarray¶

property overlap_x1: numpy.ndarray¶

property overlap_y1: numpy.ndarray¶

property ambiguous_rows: numpy.ndarray¶

property count: int¶

kind_names() → list[str]¶

class vibespatial.spatial.segment_primitives.PagedSegmentIntersectionResult¶

Device-classified intersection pages beyond one contiguous relation budget.

pages: tuple[SegmentIntersectionResult, Ellipsis]¶

candidate_pairs: int¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

precision_plan: vibespatial.runtime.precision.PrecisionPlan¶

robustness_plan: vibespatial.runtime.robustness.RobustnessPlan¶

compact_non_disjoint: bool = False¶

classified_count: int | None = None¶

page_count: int | None = None¶

property count: int¶

kind_names() → list[str]¶

class vibespatial.spatial.segment_primitives.SegmentIntersectionBenchmark¶

rows_left: int¶

rows_right: int¶

candidate_pairs: int¶

disjoint_pairs: int¶

proper_pairs: int¶

touch_pairs: int¶

overlap_pairs: int¶

ambiguous_pairs: int¶

elapsed_seconds: float¶

class vibespatial.spatial.segment_primitives.SegmentLocalEventSummary¶

Per-row exact local-event summary derived from segment intersections.

runtime_selection: vibespatial.runtime.RuntimeSelection¶

precision_plan: vibespatial.runtime.precision.PrecisionPlan¶

robustness_plan: vibespatial.runtime.robustness.RobustnessPlan¶

candidate_pairs: int¶

point_intersection_count: int¶

parallel_or_colinear_candidate_count: int¶

row_point_intersection_counts: numpy.ndarray¶

exact_event_counts: numpy.ndarray¶

exact_interval_upper_bounds: numpy.ndarray¶

property max_exact_events: int¶

class vibespatial.spatial.segment_primitives.SegmentIntersectionDeviceState¶

left_rows: vibespatial.cuda._runtime.DeviceArray¶

left_segments: vibespatial.cuda._runtime.DeviceArray¶

left_lookup: vibespatial.cuda._runtime.DeviceArray¶

right_rows: vibespatial.cuda._runtime.DeviceArray¶

right_segments: vibespatial.cuda._runtime.DeviceArray¶

right_lookup: vibespatial.cuda._runtime.DeviceArray¶

kinds: vibespatial.cuda._runtime.DeviceArray¶

point_x: vibespatial.cuda._runtime.DeviceArray¶

point_y: vibespatial.cuda._runtime.DeviceArray¶

overlap_x0: vibespatial.cuda._runtime.DeviceArray¶

overlap_y0: vibespatial.cuda._runtime.DeviceArray¶

overlap_x1: vibespatial.cuda._runtime.DeviceArray¶

overlap_y1: vibespatial.cuda._runtime.DeviceArray¶

ambiguous_rows: vibespatial.cuda._runtime.DeviceArray¶

class vibespatial.spatial.segment_primitives.SegmentIntersectionCandidates¶

left_rows: numpy.ndarray¶

left_segments: numpy.ndarray¶

left_lookup: numpy.ndarray¶

right_rows: numpy.ndarray¶

right_segments: numpy.ndarray¶

right_lookup: numpy.ndarray¶

pairs_examined: int¶

tile_size: int¶

property count: int¶

class vibespatial.spatial.segment_primitives.DeviceSegmentIntersectionCandidates¶

GPU-resident candidate pairs from sweep-based spatial join.

left_rows: vibespatial.cuda._runtime.DeviceArray¶

left_segments: vibespatial.cuda._runtime.DeviceArray¶

left_lookup: vibespatial.cuda._runtime.DeviceArray¶

right_rows: vibespatial.cuda._runtime.DeviceArray¶

right_segments: vibespatial.cuda._runtime.DeviceArray¶

right_lookup: vibespatial.cuda._runtime.DeviceArray¶

count: int¶

class vibespatial.spatial.segment_primitives.DeviceSegmentIntersectionCandidatePages¶

Marker for candidate pages consumed without contiguous concatenation.

count: int¶

vibespatial.spatial.segment_primitives.concatenate_paged_segment_intersections_device(result: PagedSegmentIntersectionResult) → SegmentIntersectionResult¶: Globally concatenate compact classified pages for ordered consumers.

vibespatial.spatial.segment_primitives.extract_segments(geometry_array: vibespatial.geometry.owned.OwnedGeometryArray) → SegmentTable¶: Extract segments from geometry array on CPU (legacy path).

vibespatial.spatial.segment_primitives.generate_segment_candidates(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = SEGMENT_TILE_SIZE) → SegmentIntersectionCandidates¶

vibespatial.spatial.segment_primitives.classify_segment_intersections(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, candidate_pairs: SegmentIntersectionCandidates | None = None, tile_size: int = SEGMENT_TILE_SIZE, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, _cached_left_device_segments: DeviceSegmentTable | None = None, _cached_right_device_segments: DeviceSegmentTable | None = None, _require_same_row: bool = False, _use_same_row_fast_path: bool = True, _collect_ambiguous_rows: bool = True, _strict_upper_source_rows: tuple[vibespatial.cuda._runtime.DeviceArray, vibespatial.cuda._runtime.DeviceArray] | None = None, _same_row_single_group: bool = False, _same_row_span_summary: tuple[int, int, int] | None = None, _compact_paged_non_disjoint: bool = False, _candidate_page_budget: int | None = None, _classified_page_consumer: collections.abc.Callable[[SegmentIntersectionResult], None] | None = None) → SegmentIntersectionResult | PagedSegmentIntersectionResult¶

Classify all segment-segment intersections between two geometry arrays.

Parameters¶

left, rightOwnedGeometryArray: Input geometry arrays (linestring, polygon, or multi-variants).
candidate_pairsSegmentIntersectionCandidates, optional: Pre-computed candidate pairs. If None, candidates are generated internally (GPU-native O(n log n) when GPU mode, tiled CPU otherwise).
tile_sizeint: Tile size for CPU candidate generation (ignored in GPU mode).
dispatch_modeExecutionMode: Force GPU, CPU, or AUTO dispatch.
precisionPrecisionMode: Force fp32, fp64, or AUTO precision.
_cached_left_device_segmentsDeviceSegmentTable, optional: Pre-extracted left-side device segments for reuse.
_cached_right_device_segmentsDeviceSegmentTable, optional: Pre-extracted right-side device segments for reuse (lyy.15).

Returns¶

SegmentIntersectionResult: Classification of all candidate segment pairs.

vibespatial.spatial.segment_primitives.summarize_exact_local_events(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, candidate_pairs: SegmentIntersectionCandidates | None = None, tile_size: int = SEGMENT_TILE_SIZE, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, _cached_right_device_segments: DeviceSegmentTable | None = None, _require_same_row: bool = False) → SegmentLocalEventSummary¶

Summarize per-row exact local-event counts for overlay-style workloads.

This is a reusable bridge between segment intersection classification and later topology stages. It combines segment endpoints with exact point-intersection outputs to produce stable row-local exact-event counts and interval upper bounds without teaching that logic separately in each overlay consumer.

vibespatial.spatial.segment_primitives.benchmark_segment_intersections(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = SEGMENT_TILE_SIZE, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO) → SegmentIntersectionBenchmark¶