cuSpatial - GPU-Accelerated Vector Geospatial Data Analysis

Note

cuSpatial depends on cuDF and RMM from RAPIDS.

cuProj - GPU-accelerated Coordinate Reference System (CRS) Transformations

cuProj is a new RAPIDS library housed within the cuSpatial repo that provides GPU-accelerated transformations of coordinates between coordinate reference systems (CRS). cuProj is available as of release 23.10 with support for transformations of WGS84 coordinates to and from Universal Transverse Mercator (UTM) 🌐.

To learn more about cuProj, see the Python cuProj README or the c++ libcuproj README.

Resources

cuSpatial User's Guide: Python API reference and guides
cuSpatial Developer Documentation: Understand cuSpatial's architecture
Getting Started: Installation options for cuSpatial
cuSpatial Community: Get help, collaborate, and ask the team questions
cuSpatial Issues: Request a feature/documentation or report a bug

Overview

cuSpatial accelerates vector geospatial operations through GPU parallelization. As part of the RAPIDS libraries, cuSpatial is inherently connected to cuDF, cuML, and cuGraph, enabling GPU acceleration across entire workflows.

cuSpatial represents data in GeoArrow format, which enables compatibility with the Apache Arrow ecosystem.

cuSpatial's Python API is closely matched to GeoPandas and data can seamlessly transition between the two:

import geopandas
from shapely.geometry import Polygon
import cuspatial

p1 = Polygon([(0, 0), (1, 0), (1, 1)])
p2 = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
geoseries = geopandas.GeoSeries([p1, p2])

cuspatial_geoseries = cuspatial.from_geopandas(geoseries)
print(cuspatial_geoseries)

Output:

0    POLYGON ((0 0, 1 0, 1 1, 0 0))
1    POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))

For additional examples, browse the complete API documentation, or check out more detailed notebooks. the NYC Taxi and Weather notebooks make use of cuSpatial.

Supported Geospatial Operations

cuSpatial is constantly working on new features! Check out the epics for a high-level view of our development, or the roadmap for the details!

Core Spatial Functions

Spatial relationship queries (DE-9IM)
Linestring-Linestring Intersections
Cartesian distance between any two geometries (ST_Distance)
Haversine distance
Hausdorff distance
Spatial window filtering

Indexing and Join Functions

Trajectory Functions

What if operations I need aren't supported?

Thanks to the from_geopandas and to_geopandas functions you can accelerate what cuSpatial supports, and leave the rest of the workflow in place.

---
title: Integrating into Existing Workflows
---
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': false},
            'themeVariables': {'commitLabelColor': '#000000',
            'commitLabelBackground': '#ffffff',
            'commitLabelFontSize': '14px'}} }%%
gitGraph
   commit id: "Existing Workflow Start"
   commit id: "GeoPandas IO"
   commit id: "Geospatial Analytics"
   branch a
   checkout a
   commit id: "from_geopandas"
   commit id: "cuSpatial GPU Acceleration"
   branch b
   checkout b
   commit id: "cuDF"
   commit id: "cuML"
   commit id: "cuGraph"
   checkout a
   merge b
   commit id: "to_geopandas"
   checkout main
   merge a
   commit id: "Continue Work"

Using cuSpatial

CUDA/GPU requirements

CUDA 11.2+ with a compatible, supported driver
Linux native: Pascal architecture or newer (Compute Capability >=6.0)
WSL2: Volta architecture or newer (Compute Capability >=7.0)

Quick start: Docker

Use the RAPIDS Release Selector, selecting Docker as the installation method. All RAPIDS Docker images contain cuSpatial.

An example command from the Release Selector:

docker run --gpus all --pull always --rm -it \
    --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \
    -p 8888:8888 -p 8787:8787 -p 8786:8786 \
    nvcr.io/nvidia/rapidsai/notebooks:24.08-cuda11.8-py3.10

Install with Conda

To install via conda:

Note cuSpatial is supported only on Linux or through WSL, and with Python versions 3.9, 3.10, and 3.11.

cuSpatial can be installed with conda (miniconda, or the full Anaconda distribution) from the rapidsai channel:

conda install -c rapidsai -c conda-forge -c nvidia \
    cuspatial=24.08 python=3.11 cudatoolkit=11.8

We also provide nightly Conda packages built from the HEAD of our latest development branch.

See the RAPIDS installation documentation for more OS and version info.

Install with pip

To install via pip:

Note cuSpatial is supported only on Linux or through WSL, and with Python versions 3.9, 3.10, and 3.11.

The cuSpatial pip packages can be installed from NVIDIA's PyPI index. pip installations require using the matching wheel to the system's installed CUDA toolkit.

For CUDA 11 toolkits, install the -cu11 wheels
For CUDA 12 toolkits install the -cu12 wheels
If your installation has a CUDA 12 driver but a CUDA 11 toolkit, use the -cu11 wheels.

pip install cuspatial-cu12 --extra-index-url=https://pypi.nvidia.com
pip install cuspatial-cu11 --extra-index-url=https://pypi.nvidia.com

Troubleshooting Fiona/GDAL versions

cuSpatial depends on geopandas, which uses fiona >= 1.8.19, to read common GIS formats with GDAL.

Fiona requires GDAL is already present on your system, but its minimum required version may be newer than the version of GDAL in your OS's package manager.

Fiona checks the GDAL version at install time and fails with an error like this if a compatible version of GDAL isn't installed:

ERROR: GDAL >= 3.2 is required for fiona. Please upgrade GDAL.

There are two ways to fix this:

Install a version of GDAL that meets fiona's minimum required version

Ubuntu users can install a newer GDAL with the UbuntuGIS PPA:

sudo -y add-apt-repository ppa:ubuntugis/ppa
sudo apt install libgdal-dev

Pin fiona's version to a range that's compatible with your version of libgdal-dev

For Ubuntu20.04 (GDAL v3.0.4):

pip install --no-binary fiona --extra-index-url=https://pypi.nvidia.com cuspatial-cu12 'fiona>=1.8.19,<1.9'

For Ubuntu22.04 (GDAL v3.4.1):

pip install --no-binary fiona --extra-index-url=https://pypi.nvidia.com cuspatial-cu12 'fiona>=1.9'

Build/Install from source

To build and install cuSpatial from source please see the build documentation.

Citing cuSpatial

If you find cuSpatial useful in your published work, please consider citing the repository.

@misc{cuspatial:24.08,
    author = {{NVIDIA Corporation}},
    title = {cuSpatial: GPU-Accelerated Geospatial and Spatiotemporal Algorithms},
    year = {2023},
    publisher = {NVIDIA},
    howpublished = {\url{https://github.com/rapidsai/cuspatial}},
    note = {Software available from github.com},
}

jakirkham/cuspatial