vibespatial.io.shp_gpu

GPU-native Shapefile (.shp) binary decoder.

Reads geometry directly from the SHP binary format, bypassing the pyogrio -> WKB -> GPU WKB decode roundtrip. The SHP binary stores coordinates as little-endian float64, and CUDA is always little-endian, so coordinate extraction is a pure gather operation with zero byte-swapping.

Architecture

  1. SHX index parsing (CPU) – The .shx file is tiny (100-byte header + 8 bytes per record). Parsing it on CPU gives exact byte offsets for every record in the .shp file.

  2. Bulk file transfer (GPU) – The entire .shp file is read to device memory via kvikio (parallel POSIX reads) or CuPy fallback.

  3. NVRTC kernel decode (GPU) – Per-record coordinate extraction runs as one NVRTC kernel launch per geometry type. Variable-length types (PolyLine, Polygon, MultiPoint) use a two-pass count-scatter pattern: pass 1 counts parts/points per record, CCCL exclusive_sum builds offsets, pass 2 gathers coordinates to flat output arrays.

  4. Offset assembly (GPU) – geometry_offsets, part_offsets, ring_offsets built via CuPy cumsum / CCCL exclusive_sum. Everything stays device- resident.

  5. OwnedGeometryArray construction – Uses _build_device_single_family_owned to produce a fully device-resident geometry array.

SHP binary format reference:

  • All coordinates are little-endian float64 (no byte-swap on CUDA)

  • Record headers are big-endian (parsed from SHX, not re-read on GPU)

  • Shape types: 0=Null, 1=Point, 3=PolyLine, 5=Polygon, 8=MultiPoint

Tier classification (ADR-0033):

  • SHX/SHP header parsing: CPU (small data, one-time)

  • Coordinate gather from SHP binary: Tier 1 (custom NVRTC – binary offset gather)

  • Offset assembly: Tier 2 (CuPy cumsum) + CCCL exclusive_sum

  • No PrecisionPlan needed: this is I/O parsing producing fp64 storage. Same rationale as dbf_gpu.py and csv_gpu.py.

Attributes

cp

SHP_NULL

SHP_POINT

SHP_POLYLINE

SHP_POLYGON

SHP_MULTIPOINT

Classes

ShpHeader

Parsed SHP/SHX file header.

Functions

read_shp_gpu(...)

Read an SHP file directly on GPU -- no WKB intermediate.

Module Contents

vibespatial.io.shp_gpu.cp = None
vibespatial.io.shp_gpu.SHP_NULL = 0
vibespatial.io.shp_gpu.SHP_POINT = 1
vibespatial.io.shp_gpu.SHP_POLYLINE = 3
vibespatial.io.shp_gpu.SHP_POLYGON = 5
vibespatial.io.shp_gpu.SHP_MULTIPOINT = 8
class vibespatial.io.shp_gpu.ShpHeader

Parsed SHP/SHX file header.

shape_type: int
bbox: tuple
n_records: int
vibespatial.io.shp_gpu.read_shp_gpu(shp_path: pathlib.Path | str) → vibespatial.geometry.owned.OwnedGeometryArray

Read an SHP file directly on GPU – no WKB intermediate.

Requires both .shp and .shx files. The .shx index is parsed on CPU (tiny: 8 bytes per record), the .shp binary is bulk-transferred to device memory, and NVRTC kernels extract coordinates directly from the SHP binary format.

Parameters

shp_pathPath or str

Path to the .shp file. The corresponding .shx file must exist at the same location with the same stem.

Returns

OwnedGeometryArray

Device-resident geometry array.

Raises

ImportError

If CuPy is not available.

FileNotFoundError

If the .shx file does not exist.

ValueError

If the SHP file contains an unsupported shape type.