rapidsai · rapids-bot · Mar 21, 2023 · Mar 7, 2023 · Mar 9, 2023 · Mar 17, 2023
diff --git a/README.md b/README.md
@@ -1,91 +1,142 @@
-# <div align="left"><img src="https://rapids.ai/assets/images/rapids_logo.png" width="90px"/>&nbsp;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"/>&nbsp;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