vibespatial.constructive.linear_ref¶

GPU-accelerated linear referencing operations.

Provides interpolate (point at a distance along a line) and project (distance along a line to the nearest point) for LineString and MultiLineString geometries, operating directly on OwnedGeometryArray coordinate buffers.

ADR-0033: Tier 1 NVRTC kernels launched via CudaDriverRuntime with CPU fallback when GPU is unavailable. ADR-0002: CONSTRUCTIVE class — output coordinates are deterministic linear combinations of input coordinates.

CPU fallback works on coordinate buffers directly (no Shapely round-trip for the hot path).

Attributes¶

`cp`
`LINEAR_REF_GPU_THRESHOLD`

Functions¶

`interpolate_owned`(...)	Interpolate a point at distance along each geometry.
`project_owned`(→ numpy.ndarray)	Project each point onto the corresponding LineString.

Module Contents¶

vibespatial.constructive.linear_ref.cp = None¶

vibespatial.constructive.linear_ref.LINEAR_REF_GPU_THRESHOLD = 10000¶

vibespatial.constructive.linear_ref.interpolate_owned(owned: vibespatial.geometry.owned.OwnedGeometryArray, distance: float | numpy.ndarray, normalized: bool = False, *, dispatch_mode: vibespatial.runtime.ExecutionMode = ExecutionMode.AUTO) → vibespatial.geometry.owned.OwnedGeometryArray¶

Interpolate a point at distance along each geometry.

Parameters¶

ownedOwnedGeometryArray: Must contain only LineString and/or MultiLineString families.
distancefloat or array-like: Distance(s) along the line. Scalar is broadcast.
normalizedbool: If True, distance is a fraction of total line length [0, 1].
dispatch_modeExecutionMode: Execution mode selection (AUTO, GPU, CPU).

Returns¶

OwnedGeometryArray: Point-family OwnedGeometryArray with one point per input geometry.

Raises¶

ValueError: If owned contains non-line families (Point, Polygon, etc.).

vibespatial.constructive.linear_ref.project_owned(owned: vibespatial.geometry.owned.OwnedGeometryArray, point_owned: vibespatial.geometry.owned.OwnedGeometryArray, *, dispatch_mode: vibespatial.runtime.ExecutionMode = ExecutionMode.AUTO) → numpy.ndarray¶

Project each point onto the corresponding LineString.

Returns the cumulative distance along the LineString to the point on the line nearest to the query point.

Parameters¶

ownedOwnedGeometryArray: Must contain only LineString family (MultiLineString not supported for project).
point_ownedOwnedGeometryArray: Point-family OwnedGeometryArray, same row count as owned.
dispatch_modeExecutionMode: Execution mode selection (AUTO, GPU, CPU).

Returns¶

np.ndarray: float64 array of projected distances, one per row.

Raises¶

ValueError: If owned is not LineString-only or point_owned is not Point-only, or row counts do not match.