vibespatial.io.fgb_gpu¶

GPU-native FlatGeobuf (.fgb) binary decoder.

Reads geometry directly from the FGB binary format, bypassing the pyogrio -> WKB -> GPU WKB decode roundtrip. FGB stores coordinates as flat xy: [double] arrays with separate ends: [uint32] arrays for ring/part boundaries – almost our OGA format already.

Architecture:

Phase 1 – Header + index parsing (CPU): Parse the FlatBuffer header to extract geometry type, CRS, column schema, and feature count. If a packed Hilbert R-tree index is present, parse it to get per-feature byte offsets into the data section.

Phase 2 – Feature offset scan (CPU): If no index is present, sequentially scan 4-byte feature-size prefixes to build feature byte offsets. This is O(n) but touches only 4 bytes per feature – fast even on CPU for millions of features.

Phase 3 – Bulk file-to-device transfer: Read the entire file to GPU memory via kvikio (or np.fromfile + cp.asarray fallback). Feature offsets go to device as well.

Phase 4 – GPU geometry decode (Tier 1 NVRTC): Custom NVRTC kernels navigate the FlatBuffer binary structure on GPU: each thread reads one feature’s geometry by following the FlatBuffer vtable/offset chain to the xy vector.

fgb_decode_points: Each thread reads xy[0], xy[1] for one Point.
fgb_count_coords: Count coordinate pairs per LineString/Polygon.
fgb_gather_coords: Copy coordinates from FGB to SoA output.

Phase 5 – Attribute extraction (CPU): FGB properties are binary-encoded per the column schema. Extract on CPU (same hybrid pattern as our other readers).

Phase 6 – Assembly: Build device-resident OwnedGeometryArray with SoA coordinate buffers.

Tier classification (ADR-0033):

Header/index parsing: CPU (small, sequential, one-time)
Feature offset scan: CPU (sequential 4-byte size reads)
File transfer: kvikio / CuPy (Tier 2)
Point decode: Tier 1 (custom NVRTC – FlatBuffer navigation)
Coord count/gather: Tier 1 (custom NVRTC – FlatBuffer navigation)
Offset construction: CCCL exclusive_sum (Tier 3a) + CuPy (Tier 2)
Attribute extraction: CPU (string data, hybrid pattern)

Precision (ADR-0002):

The decode kernels are integer-only byte navigation with fp64 coordinate storage. No floating-point computation that benefits from precision dispatch. Same rationale as csv_gpu.py, kml_gpu.py, osm_gpu.py, and all other IO readers.

Classes¶

`FgbColumnDef`	Column definition from the FGB header.
`FgbHeader`	Parsed FlatGeobuf header.
`FgbGpuResult`	Result of GPU FlatGeobuf decode.

Functions¶

read_fgb_gpu(→ FgbGpuResult)

Read a FlatGeobuf file with GPU geometry decode.

Module Contents¶

vibespatial.io.fgb_gpu.cp = None¶

vibespatial.io.fgb_gpu.logger¶

vibespatial.io.fgb_gpu.FGB_GEOM_UNKNOWN = 0¶

vibespatial.io.fgb_gpu.FGB_GEOM_POINT = 1¶

vibespatial.io.fgb_gpu.FGB_GEOM_LINESTRING = 2¶

vibespatial.io.fgb_gpu.FGB_GEOM_POLYGON = 3¶

vibespatial.io.fgb_gpu.FGB_GEOM_MULTIPOINT = 4¶

vibespatial.io.fgb_gpu.FGB_GEOM_MULTILINESTRING = 5¶

vibespatial.io.fgb_gpu.FGB_GEOM_MULTIPOLYGON = 6¶

vibespatial.io.fgb_gpu.FGB_COL_BYTE = 0¶

vibespatial.io.fgb_gpu.FGB_COL_UBYTE = 1¶

vibespatial.io.fgb_gpu.FGB_COL_BOOL = 2¶

vibespatial.io.fgb_gpu.FGB_COL_SHORT = 3¶

vibespatial.io.fgb_gpu.FGB_COL_USHORT = 4¶

vibespatial.io.fgb_gpu.FGB_COL_INT = 5¶

vibespatial.io.fgb_gpu.FGB_COL_UINT = 6¶

vibespatial.io.fgb_gpu.FGB_COL_LONG = 7¶

vibespatial.io.fgb_gpu.FGB_COL_ULONG = 8¶

vibespatial.io.fgb_gpu.FGB_COL_FLOAT = 9¶

vibespatial.io.fgb_gpu.FGB_COL_DOUBLE = 10¶

vibespatial.io.fgb_gpu.FGB_COL_STRING = 11¶

vibespatial.io.fgb_gpu.FGB_COL_JSON = 12¶

vibespatial.io.fgb_gpu.FGB_COL_DATETIME = 13¶

vibespatial.io.fgb_gpu.FGB_COL_BINARY = 14¶

class vibespatial.io.fgb_gpu.FgbColumnDef¶

Column definition from the FGB header.

name: str¶

type: int¶

class vibespatial.io.fgb_gpu.FgbHeader¶

Parsed FlatGeobuf header.

geometry_type: int¶

has_z: bool¶

has_m: bool¶

features_count: int¶

crs_wkt: str | None¶

columns: list[FgbColumnDef]¶

index_node_size: int¶

header_size: int¶

has_envelope: bool¶

envelope_dims: int¶

class vibespatial.io.fgb_gpu.FgbGpuResult¶

Result of GPU FlatGeobuf decode.

geometry: vibespatial.geometry.owned.OwnedGeometryArray¶

attributes: dict[str, object] | None¶

n_features: int¶

crs: str | None¶

vibespatial.io.fgb_gpu.read_fgb_gpu(path: pathlib.Path | str) → FgbGpuResult¶

Read a FlatGeobuf file with GPU geometry decode.

This is the direct decoder that bypasses the pyogrio -> WKB -> GPU WKB decode roundtrip. FGB coordinates are already flat arrays, so the GPU kernel just copies them to SoA output.

Parameters¶

pathPath or str: Path to the .fgb file.

Returns¶

FgbGpuResult: Result with device-resident geometry, host-resident attributes, feature count, and CRS.

`cp`
`logger`
`FGB_GEOM_UNKNOWN`
`FGB_GEOM_POINT`
`FGB_GEOM_LINESTRING`
`FGB_GEOM_POLYGON`
`FGB_GEOM_MULTIPOINT`
`FGB_GEOM_MULTILINESTRING`
`FGB_GEOM_MULTIPOLYGON`
`FGB_COL_BYTE`
`FGB_COL_UBYTE`
`FGB_COL_BOOL`
`FGB_COL_SHORT`
`FGB_COL_USHORT`
`FGB_COL_INT`
`FGB_COL_UINT`
`FGB_COL_LONG`
`FGB_COL_ULONG`
`FGB_COL_FLOAT`
`FGB_COL_DOUBLE`
`FGB_COL_STRING`
`FGB_COL_JSON`
`FGB_COL_DATETIME`
`FGB_COL_BINARY`