vibespatial.io.file

Classes

VectorFilePlan
ShapefileIngestPlan
ShapefileOwnedBatch
ShapefileIngestBenchmark

Functions

plan_shapefile_ingest(→ ShapefileIngestPlan)
read_geojson_native(source, *[, prefer, objective, ...])
read_shapefile_owned(→ ShapefileOwnedBatch)
read_shapefile_native(source, *[, bbox, columns, ...])
plan_vector_file_io(→ VectorFilePlan)
read_vector_file_native(filename[, bbox, mask, ...])	Read a spatial file into the shared native tabular boundary.
read_vector_file(filename[, bbox, mask, columns, ...])	Read a spatial file into a GeoDataFrame.
write_vector_file(df, filename[, driver, schema, index])
benchmark_shapefile_ingest(...)

Module Contents

class vibespatial.io.file.VectorFilePlan

format: vibespatial.io.support.IOFormat

operation: vibespatial.io.support.IOOperation

selected_path: vibespatial.io.support.IOPathKind

driver: str

implementation: str

reason: str

class vibespatial.io.file.ShapefileIngestPlan

implementation: str

selected_strategy: str

uses_pyogrio_container: bool

uses_arrow_batch: bool

uses_native_wkb_decode: bool

reason: str

class vibespatial.io.file.ShapefileOwnedBatch

geometry: vibespatial.geometry.owned.OwnedGeometryArray

attributes_table: object

metadata: dict[str, object]

class vibespatial.io.file.ShapefileIngestBenchmark

implementation: str

geometry_type: str

rows: int

elapsed_seconds: float

rows_per_second: float

vibespatial.io.file.plan_shapefile_ingest(*, prefer: str = 'auto') → ShapefileIngestPlan

vibespatial.io.file.read_geojson_native(source: str | pathlib.Path, *, prefer: str = 'auto', objective: str = 'pipeline', track_properties: bool = True, target_crs: str | None = None)

vibespatial.io.file.read_shapefile_owned(source: str | pathlib.Path, *, bbox=None, columns=None, rows=None, **kwargs) → ShapefileOwnedBatch

vibespatial.io.file.read_shapefile_native(source: str | pathlib.Path, *, bbox=None, columns=None, rows=None, target_crs: str | None = None, **kwargs)

vibespatial.io.file.plan_vector_file_io(filename, *, operation: vibespatial.io.support.IOOperation | str, driver: str | None = None) → VectorFilePlan

vibespatial.io.file.read_vector_file_native(filename, bbox=None, mask=None, columns=None, rows=None, engine=None, *, target_crs: str | None = None, **kwargs)

Read a spatial file into the shared native tabular boundary.

vibespatial.io.file.read_vector_file(filename, bbox=None, mask=None, columns=None, rows=None, engine=None, *, target_crs: str | None = None, build_index: bool = False, **kwargs)

Read a spatial file into a GeoDataFrame.

Supports GeoParquet, Feather/Arrow, Shapefile, GeoPackage, File Geodatabase, FlatGeobuf, GeoJSON, GeoJSON-Seq, GML, GPX, TopoJSON, WKT, CSV, KML, OSM PBF, and any format readable by pyogrio/fiona.

GPU acceleration is automatic for GeoJSON, Shapefile, FlatGeobuf, WKT, CSV, KML, and OSM PBF formats. GeoJSON and Shapefile auto-routing now optimize for pipeline shape rather than isolated read latency: eligible unfiltered reads prefer the repo-owned native ingest path so downstream GPU work does not immediately pay a host-to-device promotion. FlatGeobuf now follows the same policy for eligible local unfiltered reads, using the repo-owned direct FlatBuffer decoder by default. CSV and KML now try the repo-owned GPU parser for eligible local unfiltered reads instead of demoting solely because of a static file-size gate. WKT and full-data OSM PBF reads use the native GPU path. Standard OSM layers (points, lines, multipolygons) may use the pyogrio compatibility path when the native all-data parser is not required.

mask now also stays on the shared native Arrow/WKB boundary for the promoted pyogrio-backed vector containers when the request shape stays compatible. bbox, columns, and rows continue to work on that same boundary. Explicit engine="pyogrio" stays on the repo-owned native boundary for GeoJSON, Shapefile, and the promoted vector containers whose public semantics already match that boundary. Public automatic Shapefile reads prefer the direct SHP pipeline, while explicit engine="pyogrio" Shapefile reads stay on the shared Arrow/WKB bridge.

Aliased as vibespatial.read_file().

Parameters

filenamestr or Path

Path to the vector file.

bboxtuple of (minx, miny, maxx, maxy), optional

Spatial filter bounding box. Disables the GPU fast path.

maskGeometry or GeoDataFrame, optional

Spatial filter mask geometry. Promoted pyogrio-backed vector containers keep this on the shared native Arrow/WKB boundary when the request shape is compatible; other formats still use the compatibility path.

columnslist of str, optional

Subset of columns to read. Disables the GPU fast path.

rowsint or slice, optional

Subset of rows to read. Disables the GPU fast path.

enginestr, optional

Force a specific I/O engine ("pyogrio" or "fiona"). Disables GPU auto-routing.

target_crsstr, optional

Target CRS to reproject coordinates into (e.g. "EPSG:3857"). When the GPU path is used, the reprojection is fused with ingest via vibeProj GPU transform (no separate pass required). When the CPU path is used, the result is reprojected via gdf.to_crs() as a post-read step. For formats without an embedded CRS (WKT, CSV, KML, OSM PBF), the target CRS is set as a label without reprojection.

build_indexbool, default False

When True and the GPU path is used, build a GPU-resident packed Hilbert R-tree spatial index fused with ingest. The index is accessible via the GeoDataFrame.gpu_spatial_index property.

**kwargs

Passed through to the underlying engine. For OSM PBF GPU reads, the repo-owned path also accepts:

• tags: True, False, or "ways" to control tag decode

• geometry_only: skip tag and ID export for geometry-only reads

• layer: "points", "lines", "multipolygons", "ways", "relations", "multilinestrings", "other_relations", or "all"

Returns

GeoDataFrame

vibespatial.io.file.write_vector_file(df, filename, driver=None, schema=None, index=None, **kwargs)

vibespatial.io.file.benchmark_shapefile_ingest(*, geometry_type: str = 'point', rows: int = 100000, repeat: int = 5, seed: int = 0) → list[ShapefileIngestBenchmark]