diff --git a/README.md b/README.md index 1f613974d..efd413aee 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A Rust implementation of the [GeoArrow](https://github.com/geoarrow/geoarrow) specification and bindings to [GeoRust algorithms](https://github.com/georust/geo) for efficient spatial operations on GeoArrow memory. -This repository also includes [JavaScript (WebAssembly) bindings](https://github.com/kylebarron/geoarrow-rs/blob/main/js/README.md), wrapping the GeoArrow memory layout and offering vectorized geometry operations. +This repository also includes [Python bindings](https://github.com/kylebarron/geoarrow-rs/blob/main/python/core/README.md) and [JavaScript (WebAssembly) bindings](https://github.com/kylebarron/geoarrow-rs/blob/main/js/README.md), wrapping the GeoArrow memory layout and offering vectorized geometry operations. ## Documentation diff --git a/python/README.md b/python/README.md new file mode 100644 index 000000000..df6d1f365 --- /dev/null +++ b/python/README.md @@ -0,0 +1,20 @@ +# `geoarrow.rust`: Python bindings to `geoarrow-rs` + +This folder contains Python bindings to the [GeoArrow Rust implementation](https://github.com/geoarrow/geoarrow-rs). + +`geoarrow.rust` is distributed with [namespace packaging](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/), meaning that each python package `geoarrow-rust-[submodule-name]` (imported as `geoarrow.rust.[submodule-name]`) can be published to PyPI independently. The benefit of this approach is that complex C dependencies can be built and packaged independently. + +Modules so far: + +- [`core`](./core/README.md): All algorithms and data structures implemented in pure Rust without any C dependencies. Having a pure Rust dependency tree means it's trivial to build binary wheels for many operating system architectures that might not be possible with C dependencies. + +Future modules: + +- `geos`: [GEOS](https://libgeos.org/)-based algorithms on GeoArrow memory. +- `proj`: [PROJ](https://proj.org/en/9.3/)-based coordinate reprojection on GeoArrow memory. + +In order to obtain relevant modules, you should install them from PyPI directly, e.g.: + +``` +pip install geoarrow-rust-core +``` diff --git a/python/core/README.md b/python/core/README.md index 206b43be0..0c1eff938 100644 --- a/python/core/README.md +++ b/python/core/README.md @@ -1,13 +1,25 @@ -# geoarrow.rust.core +# `geoarrow.rust.core`: Python bindings to `geoarrow-rs` -This library contains: +This library contains Python bindings to the [GeoArrow Rust implementation](https://github.com/geoarrow/geoarrow-rs). -- standalone classes to represent GeoArrow arrays in rust: `PointArray`, `LineStringArray`, etc -- pure-rust algorithms (from [`georust/geo`](https://github.com/georust/geo)) that don't require a C extension module and can statically link on every platform. +- **Fast**: Connects to algorithms implemented in [GeoRust](https://georust.org/), which compile to native code. +- **Parallel**: Multi-threading is enabled out-of-the-box for all operations on chunked data structures. +- **Self-contained**: Zero Python dependencies. +- **Easy to install**: Distributed as static binary wheels with zero C dependencies. +- **Strong, static typing**: geometry arrays have a known type +- **Interoperable ecosystem**: Data can be shared at zero cost with other libraries in the burgeoning [GeoArrow ecosystem](https://geoarrow.org/), such as [geoarrow-c](https://github.com/geoarrow/geoarrow-c/tree/main/python) or [lightning-fast map rendering](https://github.com/developmentseed/lonboard). -In the future, this will also contain: +More specifically, it contains: -- Chunked classes: `ChunkedPointArray`, `ChunkedLineStringArray`, etc -- Table representations: `GeoTable`, where one of the columns is a geospatial type. This will support e.g. geospatial joins using Arrow memory. +- Classes to represent GeoArrow arrays: `PointArray`, `LineStringArray`, etc. +- Classes to represent _chunked_ GeoArrow arrays: `ChunkedPointArray`, `ChunkedLineStringArray`, etc. +- A spatial table representation, `GeoTable`, where one column is a geospatial type, to enable future support for geospatial joins. +- Rust-based algorithms for computations on GeoArrow memory. +- Rust-based parsers for various geospatial file formats. -Refer to the [GeoArrow Python module proposal](https://github.com/geoarrow/geoarrow-python/issues/38) for more information. +Future work: + +- [ ] 3D coordinates. Only 2D geometries are supported at this time. +- [ ] CRS management. This currently loses the CRS information in the [GeoArrow metadata](https://geoarrow.org/extension-types#extension-metadata). + +Refer to the [GeoArrow Python module proposal](https://github.com/geoarrow/geoarrow-python/issues/38) for more background information.