-
Notifications
You must be signed in to change notification settings - Fork 157
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Closes #908 With all of the development on cuSpatial, it's time for a new README that is both more up-to-date, and more aligned with other RAPIDS READMEs. ### Outstanding tasks - [x] Add function hyperlinks - [x] Move `build from source` instructions to developer docs - [x] Remove from readme - [x] #999 - [x] Consider adding visuals for things like distances using [GitHub topojson](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-geojson-and-topojson-maps) - [x] #987 Authors: - Ben Jarmak (https://github.com/jarmak-nv) Approvers: - H. Thomson Comer (https://github.com/thomcom) - Mark Harris (https://github.com/harrism) - Michael Wang (https://github.com/isVoid) URL: #977
- Loading branch information
Showing
1 changed file
with
117 additions
and
66 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,91 +1,142 @@ | ||
| # <div align="left"><img src="https://rapids.ai/assets/images/rapids_logo.png" width="90px"/> cuSpatial - GPU-Accelerated Spatial and Trajectory Data Management and Analytics Library</div> | ||
| # <div align="left"><img src="https://rapids.ai/assets/images/rapids_logo.png" width="90px"/> cuSpatial - GPU-Accelerated Vector Geospatial Data Analysis</div> | ||
|
|
||
| **NOTE:** cuSpatial depends on [cuDF](https://github.com/rapidsai/cudf) and | ||
| [RMM](https://github.com/rapidsai/rmm) from [RAPIDS](https://rapids.ai/). | ||
| > **Note** | ||
| > | ||
| > cuSpatial depends on [cuDF](https://github.com/rapidsai/cudf) and [RMM](https://github.com/rapidsai/rmm) from [RAPIDS](https://rapids.ai/). | ||
| ## Operations | ||
| ## Resources | ||
|
|
||
| cuSpatial supports the following operations on spatial and trajectory data: | ||
| - [cuSpatial User's Guide](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html): Python API reference and guides | ||
| - [cuSpatial Developer Documentation](https://docs.rapids.ai/api/cuspatial/stable/developer_guide/index.html): Understand cuSpatial's architecture | ||
| - [Getting Started](https://rapids.ai/start.html): Instructions for installing cuSpatial | ||
| - [cuSpatial Community](https://github.com/rapidsai/cuspatial/discussions): Get help, collaborate, and ask the team questions | ||
| - [cuSpatial Issues](https://github.com/rapidsai/cuspatial/issues/new/choose): Request a feature/documentation or report a bug | ||
| - [cuSpatial Roadmap](https://github.com/orgs/rapidsai/projects/41/views/5): Report issues or request features. | ||
|
|
||
| 1. Spatial window query | ||
| 2. Point-in-polygon test | ||
| 3. Haversine distance | ||
| 4. Hausdorff distance | ||
| 5. Deriving trajectories from point location data | ||
| 6. Computing distance/speed of trajectories | ||
| 7. Computing spatial bounding boxes of trajectories | ||
| 8. Quadtree-based indexing for large-scale point data | ||
| 9. Quadtree-based point-in-polygon spatial join | ||
| 10. Quadtree-based point-to-linestring nearest neighbor distance | ||
| 11. Distance computation (point-point, point-linestring, linestring-linestring) | ||
| 12. Finding nearest points between point and linestring | ||
| ## Overview | ||
| cuSpatial accelerates vector geospatial operations through GPU parallelization. As part of the RAPIDS libraries, cuSpatial is inherently connected to [cuDF](https://github.com/rapidsai/cudf), [cuML](https://github.com/rapidsai/cuml), and [cuGraph](https://github.com/rapidsai/cugraph), enabling GPU acceleration across entire workflows. | ||
|
|
||
| Future support is planned for the following operations: | ||
| cuSpatial represents data in [GeoArrow](https://github.com/geoarrow/geoarrow) format, which enables compatibility with the [Apache Arrow](https://arrow.apache.org) ecosystem. | ||
|
|
||
| 1. Temporal window query | ||
| 2. Temporal point query (year+month+day+hour+minute+second+millisecond) | ||
| 3. Grid-based indexing for points and polygons | ||
| 4. R-Tree-based indexing for Polygons/Polylines | ||
| cuSpatial's Python API is closely matched to GeoPandas and data can seamlessly transition between the two: | ||
| ```python | ||
| import geopandas | ||
| from shapely.geometry import Polygon | ||
| import cuspatial | ||
|
|
||
| ## Install from Conda | ||
| p1 = Polygon([(0, 0), (1, 0), (1, 1)]) | ||
| p2 = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)]) | ||
| geoseries = geopandas.GeoSeries([p1, p2]) | ||
|
|
||
| To install via conda: | ||
|
|
||
| ```shell | ||
| conda install -c conda-forge -c rapidsai-nightly cuspatial | ||
| 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)) | ||
| ``` | ||
|
|
||
| ## Install from Source | ||
|
|
||
| To build and install cuSpatial from source: | ||
| For additional examples, browse the complete [API documentation](https://docs.rapids.ai/api/cuspatial/stable/), or check out more detailed [notebooks](https://github.com/rapidsai/notebooks-contrib). the [NYC Taxi][1] and [Weather][2] notebooks make use of cuSpatial. | ||
|
|
||
| ## Supported Geospatial Operations | ||
|
|
||
| cuSpatial is constantly working on new features! Check out the [epics](https://github.com/orgs/rapidsai/projects/41/views/4) for a high-level view of our development, or the [roadmap](https://github.com/orgs/rapidsai/projects/41/views/5) for the details! | ||
|
|
||
| ### Core Spatial Functions | ||
| - Spatial relationship queries (DE-9IM) [Follow Development!](https://github.com/rapidsai/cuspatial/milestone/5) | ||
| - [Contains Properly](https://docs.rapids.ai/api/cuspatial/stable/api_docs/geopandas_compatibility.html#cuspatial.GeoSeries.contains_properly) | ||
| - https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#Linestring-Intersections | ||
| - Distance computations (ST_Distance) [Follow Development!](https://github.com/rapidsai/cuspatial/issues/767) | ||
| - [Pairwise Linestring Distance](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.pairwise_linestring_distance) | ||
| - [Pairwise Point-Linestring Distance](https://docs.rapids.ai/api/cuspatial/stable/api_docs/spatial.html#cuspatial.pairwise_point_linestring_distance) | ||
| - [Haversine distance](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.haversine_distance) | ||
| - [Hausdorff distance](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.directed_hausdorff_distance) | ||
| - [Spatial window filtering](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.points_in_spatial_window) | ||
|
|
||
| ### Indexing and Join Functions | ||
| - [Quadtree indexing](https://docs.rapids.ai/api/cuspatial/nightly/user_guide/cuspatial_api_examples.html#Quadtree-Indexing) | ||
| - [Spatial joins](https://docs.rapids.ai/api/cuspatial/nightly/user_guide/cuspatial_api_examples.html#Indexed-Spatial-Joins) | ||
| - [Quadtree-based point-in-polygon](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.quadtree_point_in_polygon) | ||
| - [Quadtree-based point-to-nearest-linestring](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.quadtree_point_to_nearest_linestring) | ||
|
|
||
| ### Trajectory Functions | ||
| - [Deriving trajectories from point location data](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.derive_trajectories) | ||
| - [Computing distance/speed of trajectories](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.trajectory_distances_and_speeds) | ||
| - [Computing spatial bounding boxes of trajectories](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples.html#cuspatial.trajectory_bounding_boxes) | ||
|
|
||
| ### 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. | ||
|
|
||
| ```mermaid | ||
| --- | ||
| 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" | ||
| ``` | ||
|
|
||
| ### Pre-requisite | ||
|
|
||
| - gcc >= 7.5 | ||
| - cmake >= 3.23 | ||
| - miniconda | ||
| ## Using cuSpatial | ||
| **CUDA/GPU requirements** | ||
| ``` | ||
| CUDA 11.2+ | ||
| NVIDIA driver 450.80.02+ | ||
| Pascal architecture or better (Compute Capability >=6.0) | ||
| ``` | ||
|
|
||
| ### Fetch cuSpatial repository | ||
| ### Quick start: Docker | ||
| Use the [RAPIDS Release Selector](https://rapids.ai/start.html#get-rapids), selecting `Docker` as the installation method. All RAPIDS Docker images contain cuSpatial. | ||
|
|
||
| An example command from the Release Selector: | ||
| ```shell | ||
| export `CUSPATIAL_HOME=$(pwd)/cuspatial` && \ | ||
| git clone https://github.com/rapidsai/cuspatial.git $CUSPATIAL_HOME | ||
| docker pull nvcr.io/nvidia/rapidsai/rapidsai-core:23.02-cuda11.8-runtime-ubuntu22.04-py3.10 | ||
| docker run --gpus all --rm -it \ | ||
| --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \ | ||
| -p 8888:8888 -p 8787:8787 -p 8786:8786 \ | ||
| nvcr.io/nvidia/rapidsai/rapidsai-core:23.02-cuda11.8-runtime-ubuntu22.04-py3.10 | ||
| ``` | ||
| ### Install dependencies | ||
|
|
||
| 1. `export CUSPATIAL_HOME=$(pwd)/cuspatial` | ||
| 2. clone the cuSpatial repo | ||
| ### Install from Conda | ||
|
|
||
| ```shell | ||
| conda env update --file conda/environments/all_cuda-115_arch-x86_64.yaml | ||
| ``` | ||
| To install via conda: | ||
| > **Note** cuSpatial is supported only on Linux or [through WSL](https://rapids.ai/wsl2.html), and with Python versions 3.8 and later | ||
| ### Build and install cuSpatial | ||
| cuSpatial can be installed with conda (miniconda, or the full Anaconda distribution) from the rapidsai channel: | ||
|
|
||
| 1. Compile and install | ||
| ```shell | ||
| cd $CUSPATIAL_HOME && \ | ||
| chmod +x ./build.sh && \ | ||
| ./build.sh | ||
| ``` | ||
| ```shell | ||
| conda install -c rapidsai -c conda-forge -c nvidia \ | ||
| cuspatial=23.04 python=3.10 cudatoolkit=11.8 | ||
| ``` | ||
| We also provide nightly Conda packages built from the HEAD of our latest development branch. | ||
|
|
||
| 2. Run C++/Python test code | ||
| See the [RAPIDS release selector](https://rapids.ai/start.html#get-rapids) for more OS and version info. | ||
|
|
||
| Some tests using inline data can be run directly, e.g.: | ||
| ### Install from Source | ||
|
|
||
| ```shell | ||
| $CUSPATIAL_HOME/cpp/build/gtests/LEGACY_HAUSDORFF_TEST | ||
| $CUSPATIAL_HOME/cpp/build/gtests/POINT_IN_POLYGON_TEST | ||
| python python/cuspatial/cuspatial/tests/legacy/test_hausdorff_distance.py | ||
| python python/cuspatial/cuspatial/tests/test_pip.py | ||
| ``` | ||
| To build and install cuSpatial from source please see the [build documentation](https://docs.rapids.ai/api/cuspatial/stable/developer_guide/build.html). | ||
|
|
||
| Some other tests involve I/O from data files under `$CUSPATIAL_HOME/test_fixtures`. | ||
| For example, `$CUSPATIAL_HOME/cpp/build/gtests/SHAPEFILE_READER_TEST` requires three | ||
| pre-generated polygon shapefiles that contain 0, 1 and 2 polygons, respectively. They are available at | ||
| `$CUSPATIAL_HOME/test_fixtures/shapefiles` <br> | ||
|
|
||
| Python users can read any point/polyline/polygon data using existing Python | ||
| packages, e.g., [Shapely](https://pypi.org/project/Shapely/) and | ||
| [Fiona](https://github.com/Toblerity/Fiona), to generate numpy arrays and feed | ||
| them to [cuSpatial Python APIs](https://docs.rapids.ai/api/cuspatial/stable/). | ||
| [1]:https://github.com/rapidsai-community/notebooks-contrib/blob/main/community_tutorials_and_guides/taxi/NYCTaxi-E2E.ipynb | ||
| [2]:https://github.com/rapidsai-community/notebooks-contrib/blob/main/community_tutorials_and_guides/weather.ipynb |