API Reference¶

This page provides a categorized overview of the vibeSpatial public API. Every entry links to the full auto-generated documentation with parameters, return types, and docstrings.

For the complete module-by-module reference, see the full API docs.

Core Classes¶

Class	Description
`GeoDataFrame`	pandas DataFrame with a geometry column backed by GPU-resident storage
`GeoSeries`	pandas Series of geometries with the full set of spatial operations
`GeometryArray`	ExtensionArray wrapping Shapely geometry objects
`OwnedGeometryArray`	GPU-resident geometry array with zero-copy device access

Top-Level Functions¶

I/O¶

Function	Description
`read_vector_file()`	Read vector file (Shapefile, GeoPackage, GeoJSON, etc.) – aliased as `vibespatial.read_file()`
`read_geoparquet()`	Read GeoParquet file – aliased as `vibespatial.read_parquet()`
`_read_feather()`	Read Feather file – aliased as `vibespatial.read_feather()`
`_list_layers()`	List layers in a vector file – aliased as `vibespatial.list_layers()`
`_read_postgis()`	Read from PostGIS database – aliased as `vibespatial.read_postgis()`
`write_geoparquet()`	Write GeoParquet file
`write_vector_file()`	Write vector file

Spatial Operations¶

Function	Description
`sjoin()`	Spatial join of two GeoDataFrames
`sjoin_nearest()`	Nearest-neighbor spatial join
`overlay()`	Spatial overlay (intersection, union, difference, etc.)
`clip()`	Clip geometries to a mask extent
`points_from_xy()`	Create point geometries from x, y (and optional z) coordinates

Runtime¶

Function	Description
`select_runtime()`	Query current GPU/CPU runtime selection
`has_gpu_runtime()`	Check if a CUDA GPU is available
`set_execution_mode()`	Set the execution mode (AUTO, GPU, CPU)
`get_requested_mode()`	Get the currently requested execution mode
`get_dispatch_events()`	Retrieve the dispatch event log
`clear_dispatch_events()`	Clear the dispatch event log
`get_fallback_events()`	Retrieve the fallback event log
`clear_fallback_events()`	Clear the fallback event log
`show_versions()`	Print package version info

GeoDataFrame Methods¶

Full class documentation: GeoDataFrame

Constructors¶

Method	Description
`GeoDataFrame(data, geometry=, crs=)`	Standard constructor
`GeoDataFrame.from_dict()`	Construct from dictionary
`GeoDataFrame.from_file()`	Construct from vector file
`GeoDataFrame.from_features()`	Construct from GeoJSON features
`GeoDataFrame.from_postgis()`	Construct from PostGIS query
`GeoDataFrame.from_arrow()`	Construct from Arrow table

Geometry Management¶

Method	Description
`.set_geometry(col)`	Set the active geometry column
`.rename_geometry(col)`	Rename a geometry column
`.active_geometry_name`	Name of the active geometry column
`.geometry`	Access the active geometry as a GeoSeries
`.crs`	Coordinate reference system

Spatial Operations¶

Method	Description
`.dissolve(by=)`	Dissolve geometries by group with GPU-accelerated union
`.explode()`	Explode multi-part geometries to single parts
`.sjoin()`	Spatial join with another GeoDataFrame
`.sjoin_nearest()`	Nearest spatial join
`.clip(mask)`	Clip geometries by a mask
`.overlay(right, how=)`	Spatial overlay operation

Export¶

Method	Description
`.to_parquet(path)`	Write to GeoParquet
`.to_feather(path)`	Write to Feather
`.to_file(path)`	Write to vector file (Shapefile, GPKG, GeoJSON, etc.)
`.to_postgis(name, con)`	Write to PostGIS table
`.to_json()`	Export to GeoJSON string
`.to_wkb()`	Export geometries as WKB
`.to_wkt()`	Export geometries as WKT
`.to_arrow()`	Export to Arrow table
`.to_crs(crs)`	Reproject geometries to a different CRS
`.set_crs(crs)`	Assign or override CRS
`.to_geo_dict()`	Export as GeoJSON-compatible dict

GeoSeries Methods¶

Full class documentation: GeoSeries

Constructors¶

Method	Description
`GeoSeries(data, crs=)`	Standard constructor
`GeoSeries.from_wkb(data)`	Construct from WKB binary
`GeoSeries.from_wkt(data)`	Construct from WKT strings
`GeoSeries.from_xy(x, y)`	Construct points from coordinate arrays
`GeoSeries.from_file(path)`	Construct from vector file
`GeoSeries.from_arrow(arr)`	Construct from Arrow array

Coordinate Access¶

Property	Description
`.x`	X coordinate (points only)
`.y`	Y coordinate (points only)
`.z`	Z coordinate (if present)
`.m`	M coordinate (if present)

Geometry Operations¶

These methods are available on both GeoSeries and GeoDataFrame via the GeoPandasBase mixin. See the full class docs for parameter details.

Properties & Measurements¶

Member	Description
`area`	Area of each geometry
`length`	Length of each geometry
`bounds`	Bounding box (minx, miny, maxx, maxy) per geometry
`total_bounds`	Total bounding box of all geometries
`geom_type`	Geometry type string per geometry
`is_valid`	Validity check
`is_valid_reason()`	Reason for invalidity
`is_empty`	Empty check
`is_simple`	Simplicity check
`is_ring`	Ring check
`is_closed`	Closed check
`is_ccw`	Counter-clockwise winding check
`has_z`	Has Z coordinates
`has_m`	Has M coordinates
`count_coordinates()`	Total coordinate count
`count_geometries()`	Sub-geometry count
`count_interior_rings()`	Interior ring count
`get_precision()`	Grid precision

Binary Predicates¶

Method	Description
`contains()`	Contains test
`contains_properly()`	Contains properly (excludes boundary)
`covers()`	Covers test
`covered_by()`	Covered by test
`crosses()`	Crosses test
`disjoint()`	Disjoint test
`intersects()`	Intersects test
`overlaps()`	Overlaps test
`touches()`	Touches test
`within()`	Within test
`dwithin()`	Within distance threshold
`geom_equals()`	Geometry equality
`geom_equals_exact()`	Exact equality with tolerance
`geom_equals_identical()`	Identical equality
`relate()`	DE-9IM relationship string
`relate_pattern()`	Match a DE-9IM pattern

Constructive Operations¶

Method	Description
`buffer()`	Buffer geometries by distance
`centroid`	Centroid point
`convex_hull`	Convex hull
`concave_hull()`	Concave hull
`envelope`	Minimum bounding rectangle
`minimum_rotated_rectangle()`	Minimum rotated bounding rectangle
`minimum_bounding_circle()`	Minimum bounding circle
`maximum_inscribed_circle()`	Maximum inscribed circle
`minimum_bounding_radius()`	Minimum bounding radius
`boundary`	Geometry boundary
`exterior`	Exterior ring (polygons)
`interiors`	Interior rings (polygons)
`representative_point()`	Point guaranteed inside geometry
`extract_unique_points()`	All unique vertices
`simplify()`	Douglas-Peucker simplification
`simplify_coverage()`	Simplify preserving coverage topology
`make_valid()`	Repair invalid geometries
`normalize()`	Normalize ring direction
`orient_polygons()`	Orient polygon rings
`reverse()`	Reverse coordinate order
`segmentize()`	Densify by max segment length
`offset_curve()`	Offset a line by distance
`clip_by_rect()`	Clip to a rectangle
`line_merge()`	Merge connected line segments
`remove_repeated_points()`	Remove duplicate vertices
`set_precision()`	Set coordinate grid precision
`delaunay_triangles()`	Delaunay triangulation
`constrained_delaunay_triangles()`	Constrained Delaunay triangulation
`voronoi_polygons()`	Voronoi diagram
`build_area()`	Build polygonal area from linework
`polygonize()`	Polygonize line segments
`sample_points()`	Random point sampling

Set Operations¶

Method	Description
`difference()`	Set difference
`symmetric_difference()`	Symmetric difference
`union()`	Pairwise union
`intersection()`	Pairwise intersection
`union_all()`	Union all geometries in the series
`intersection_all()`	Intersect all geometries in the series

Distance & Relationships¶

Method	Description
`distance()`	Distance to another geometry
`hausdorff_distance()`	Hausdorff distance
`frechet_distance()`	Frechet distance
`shortest_line()`	Shortest line between geometries
`project()`	Project point onto line
`interpolate()`	Interpolate point along line
`snap()`	Snap to another geometry
`shared_paths()`	Shared path segments

Transformations¶

Method	Description
`affine_transform()`	Apply affine transformation matrix
`translate()`	Translate by x/y/z offsets
`rotate()`	Rotate by angle
`scale()`	Scale by x/y/z factors
`skew()`	Skew by x/y angles
`transform()`	Apply coordinate transformation function
`force_2d()`	Drop Z/M, force 2D
`force_3d()`	Add Z coordinate

Coordinate Access¶

Member	Description
`get_coordinates()`	Get coordinate arrays
`cx`	Coordinate-based indexer
`hilbert_distance()`	Hilbert curve distance for spatial ordering
`get_geometry()`	Get sub-geometry by index

Spatial Index¶

Member	Description
`sindex`	Spatial index (STRtree)
`has_sindex`	Whether spatial index is built
`.gpu_spatial_index`	GPU-resident Hilbert R-tree (built via `read_file(..., build_index=True)`)

GPU-Accelerated File Reading¶

read_file() automatically routes eligible requests to GPU-accelerated parsers when a GPU is available. No code changes are required; dispatch selection is transparent to user code and recorded as an observable event.

Supported Formats¶

Format	Extension	Native/GPU route	Compatibility boundary
GeoParquet	`.parquet`, `.geoparquet`	GeoArrow/WKB decode and GPU scan where available	pyarrow
Feather/Arrow	`.feather`, `.arrow`, `.ipc`	Native GeoArrow codec	pyarrow
GeoJSON	`.geojson`, `.json`	Eligible unfiltered reads use GPU byte-classify geometry parse	pyogrio / fast-json compatibility
Shapefile	`.shp`	Direct SHP/DBF native path or Arrow + GPU WKB bridge	pyogrio
GeoPackage	`.gpkg`	Shared Arrow + GPU WKB native boundary for supported requests	pyogrio
File Geodatabase	`.gdb`	Shared Arrow + GPU WKB native boundary for supported requests	pyogrio
FlatGeobuf	`.fgb`	Direct FlatBuffer GPU decoder for eligible reads	pyogrio
CSV/TSV	`.csv`, `.tsv`	GPU WKT/WKB decode for detected geometry columns	pyogrio / pandas
KML	`.kml`	Direct WKT/native boundary for supported requests	pyogrio
GML	`.gml`	Shared Arrow + GPU WKB native boundary for supported requests	pyogrio
GPX	`.gpx`	Shared Arrow + GPU WKB native boundary for supported requests	pyogrio
TopoJSON	`.topojson`	Shared Arrow + GPU WKB native boundary for supported requests	pyogrio
GeoJSON-Seq	`.geojsonl`, `.geojsonseq`	Rewrites eligible records to the GPU GeoJSON parser	pyogrio
WKT	`.wkt`	GPU WKT parser	none for supported 2D geometry
OSM PBF	`.pbf`, `.osm.pbf`	Native full-data path and parallel supported-layer public reads	pyogrio for unsupported relation leftovers
PostGIS	`read_postgis()`	ADBC/WKB bridge when available	Shapely WKB

CSV Spatial Column Auto-Detection¶

When reading CSV files, vibeSpatial auto-detects spatial columns by header name (case-insensitive). You can also specify columns explicitly.

Latitude columns (any of): latitude, lat, y, lat_y, point_y

Longitude columns (any of): longitude, lon, lng, x, long, lon_x, point_x

Geometry columns (WKT text or hex-encoded WKB, any of): geometry, geom, wkt, the_geom, shape, wkb

# Auto-detected from column names
gdf = gpd.read_file("data.csv")

# Explicit column override
gdf = gpd.read_file("data.csv", lat_col="custom_lat", lon_col="custom_lon")

When a geometry column is detected, vibeSpatial peeks at the first value to determine the encoding:

Hex WKB: starts with 00 or 01 (byte-order marker), even length, all hex digits → decoded via GPU WKB pipeline
WKT text: everything else → parsed via GPU WKT pipeline

Fused Pipelines¶

# Reproject during parse (zero extra passes over coordinate data)
gdf = gpd.read_file("data.geojson", target_crs="EPSG:3857")

# Build GPU Hilbert R-tree spatial index during parse
gdf = gpd.read_file("data.geojson", build_index=True)
gdf.gpu_spatial_index  # → GpuSpatialIndex or None

Parameters That Disable GPU¶

The GPU fast path is bypassed when any of these are specified: bbox, columns, rows, mask, or engine.

Direct GPU Reader Access¶

Power users can import GPU readers directly for fine-grained control:

from vibespatial.io import (
    read_wkt_gpu,        # WKT bytes → OwnedGeometryArray
    read_csv_gpu,        # CSV bytes → CsvGpuResult
    read_kml_gpu,        # KML bytes → KmlGpuResult
    read_osm_pbf_nodes,  # PBF path → OsmGpuResult
    build_spatial_index,  # Coordinates → GpuSpatialIndex
)

Execution Modes¶

from vibespatial import ExecutionMode, set_execution_mode

set_execution_mode(ExecutionMode.AUTO)  # Default: GPU when available
set_execution_mode(ExecutionMode.GPU)   # Force GPU (raises if unavailable)
set_execution_mode(ExecutionMode.CPU)   # Force CPU

Environment Variables¶

Variable	Default	Effect
`VIBESPATIAL_EXECUTION_MODE`	`auto`	Force execution mode (`auto`, `gpu`, `cpu`)
`VIBESPATIAL_STRICT_NATIVE`	disabled	Set `1` to error on any CPU fallback
`VIBESPATIAL_DETERMINISM`	disabled	Set `1` for deterministic (reproducible) results
`VIBESPATIAL_TRACE_WARNINGS`	disabled	Set `1` to emit warnings from execution traces
`VIBESPATIAL_EVENT_LOG`	disabled	Path to write structured dispatch event log
`VIBESPATIAL_GPU_POOL_LIMIT`	unset	Limit GPU memory pool size (bytes)
`VIBESPATIAL_GPU_OOM_SAFETY`	disabled	Set `1` to enable Tier B: RMM pool with GC retry on OOM. Zero overhead on the happy path; ~5-50ms recovery on OOM.
`VIBESPATIAL_GPU_MANAGED_MEMORY`	disabled	Set `1` to enable Tier C: CUDA managed memory. Datasets exceeding VRAM will run to completion (slowly) instead of crashing. Expect 2-10x slowdown when oversubscribed.
`VIBESPATIAL_PROVENANCE_REWRITES`	enabled	Set `0` to disable automatic query rewrites
`VIBESPATIAL_CCCL_CACHE`	enabled	Set `0` to disable CCCL CUBIN disk cache
`VIBESPATIAL_NVRTC_CACHE`	enabled	Set `0` to disable NVRTC CUBIN disk cache
`VIBESPATIAL_CCCL_CACHE_DIR`	`~/.cache/vibespatial/cccl`	Override CCCL cache directory
`VIBESPATIAL_NVRTC_CACHE_DIR`	`~/.cache/vibespatial/nvrtc`	Override NVRTC cache directory
`VIBESPATIAL_PRECOMPILE`	enabled	Set `0` to disable background kernel pre-compilation

Projection¶

GeoDataFrame.to_crs() reprojects geometries using vibeProj for GPU-accelerated coordinate transforms. See the vibeSpatial integration guide for the zero-copy transform_buffers() API.

Raster¶

Install for GPU raster operations under the vibespatial.raster namespace. See the for shared module details.