vibespatial.kernels.constructive.polygon_difference¶

GPU-native element-wise polygon difference kernel.

Computes left - right for aligned polygon/multipolygon OwnedGeometryArrays entirely on the GPU, returning a device-resident OwnedGeometryArray with no D->H transfers on the critical path.

Algorithm: Reuses the overlay topology pipeline (ADR-0016):: extract_segments -> classify_segment_intersections -> build_gpu_split_events -> build_gpu_atomic_edges -> build_gpu_half_edge_graph -> build_gpu_overlay_faces -> face selection (left_covered & ~right_covered) -> face-to-polygon assembly
ADR-0033: Tier 3 pipeline orchestrating Tier 1 NVRTC kernels and: Tier 3a CCCL primitives.
ADR-0002: CONSTRUCTIVE class – stays fp64 per policy; precision plan: wired through for observability.

Attributes¶

logger

Functions¶

polygon_difference(...)

Element-wise polygon difference: left - right.

Module Contents¶

vibespatial.kernels.constructive.polygon_difference.logger¶

vibespatial.kernels.constructive.polygon_difference.polygon_difference(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO) → vibespatial.geometry.owned.OwnedGeometryArray¶

Element-wise polygon difference: left - right.

Computes the geometric difference of aligned polygon/multipolygon arrays. When both inputs are polygonal and GPU is available, executes the full overlay topology pipeline on GPU. Falls back to Shapely for non-polygonal inputs or when GPU is unavailable.

Parameters¶

leftOwnedGeometryArray: Left geometry array (the “base” polygons).
rightOwnedGeometryArray: Right geometry array (the polygons to subtract).
dispatch_modeExecutionMode or str, default AUTO: Execution mode hint.
precisionPrecisionMode or str, default AUTO: Precision mode. CONSTRUCTIVE kernels stay fp64 per ADR-0002; the plan is computed for observability only.

Returns¶

OwnedGeometryArray: Result geometries. May contain MultiPolygon when the difference splits a polygon. Empty geometry when left is fully inside right. Original left geometry when there is no overlap.

Raises¶

ValueError: If row counts do not match.