Skip to content

Commit

Permalink
Next release prep (#768)
Browse files Browse the repository at this point in the history
### Change list

- Docs updates
- README updates
- Update `geometry_col` to work on RecordBatch as well
  • Loading branch information
kylebarron authored Sep 7, 2024
1 parent f3fec6b commit 826415b
Show file tree
Hide file tree
Showing 41 changed files with 285 additions and 246 deletions.
18 changes: 7 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,19 @@ This repository also includes [Python bindings](https://github.com/geoarrow/geoa

## Documentation

[**Documentation Website**](https://geoarrow.org/geoarrow-rs/)

<!--
- [Use from Rust](https://docs.rs/geoarrow/latest/geoarrow/)
- [Use from Python](https://geoarrow.github.io/geoarrow-rs/python)
- [Use from JavaScript](https://geoarrow.github.io/geoarrow-rs/js)
- [Create your own Rust-JavaScript library with `wasm-bindgen`](https://docs.rs/geoarrow-wasm/latest/geoarrow_wasm/)
- [Use from Python](https://geoarrow.org/geoarrow-rs/python)
- [Use from JavaScript](https://geoarrow.org/geoarrow-rs/js)
- [Create your own Rust-JavaScript library with `wasm-bindgen`](https://docs.rs/geoarrow-wasm/latest/geoarrow_wasm/) -->
<!-- - [Create your own Rust-Python library with `pyo3-geoarrow`](https://docs.rs/geoarrow-wasm/latest/geoarrow_wasm/) -->

## Examples

- [Rust examples](examples/README.md)

## Install

Add this to your `Cargo.toml`:

```toml
geoarrow = "0.2"
```

## References

- [Prototyping GeoRust + GeoArrow in WebAssembly](https://observablehq.com/@kylebarron/prototyping-georust-geoarrow-in-webassembly) gives an early preview of the JavaScript API.
Expand Down
38 changes: 28 additions & 10 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,42 @@

[![GitHub Workflow Status (Python)](https://img.shields.io/github/actions/workflow/status/geoarrow/geoarrow-rs/python.yml?branch=main)](https://github.com/geoarrow/geoarrow-rs/actions/workflows/python.yml)

This folder contains Python bindings to the [GeoArrow Rust implementation](https://github.com/geoarrow/geoarrow-rs).
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.
## Overview

Modules so far:
This library contains Python bindings to the [GeoArrow Rust implementation](https://github.com/geoarrow/geoarrow-rs).

- [`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.
- [`io`](./io/README.md): Pure-rust readers and writers for geospatial file formats.
- **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**: `pyproj` is the only Python dependency.
- **Easy to install**: Distributed as static binary wheels with zero C dependencies.
- **Static typing**: type hints for all operations.
- **Interoperable ecosystem**: Efficient data exchange with other libraries in the Python Arrow and GeoArrow ecosystems. , such as [geoarrow-c](https://github.com/geoarrow/geoarrow-c/tree/main/python) or [lightning-fast map rendering](https://github.com/developmentseed/lonboard).

Future potential modules:
## Documentation

Refer to the [documentation website](https://geoarrow.org/geoarrow-rs/python).

## Modules

`geoarrow.rust` is distributed with [namespace packaging](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/), meaning that each Python submodule is published to PyPI independently. This allows for separation of concerns and smaller environments when only some portion of functionality is necessary.

- `geos`: [GEOS](https://libgeos.org/)-based algorithms on GeoArrow memory.
- `proj`: [PROJ](https://proj.org/en/9.3/)-based coordinate reprojection on GeoArrow memory.
Existing modules:

- `geoarrow-rust-core`: Data structures to store and manage geometry data in GeoArrow format.
- `geoarrow-rust-compute`: Compute operations on GeoArrow data.
- `geoarrow-rust-io`: Pure-rust readers and writers for geospatial file formats.

In order to obtain relevant modules, you should install them from PyPI directly, e.g.:

```
pip install geoarrow-rust-core
pip install geoarrow-rust-core geoarrow-rust-compute geoarrow-rust-io
```

See [DEVELOP.md](docs/DEVELOP.md) in the `docs` folder for more information on developing and building the Python bindings.
Future potential modules:

- `geoarrow-rust-geos`: [GEOS](https://libgeos.org/)-based algorithms on GeoArrow memory.
- `geoarrow-rust-proj`: [PROJ](https://proj.org/en/9.3/)-based coordinate reprojection on GeoArrow memory.

See [DEVELOP.md](DEVELOP.md) for more information on developing and building the Python bindings.
3 changes: 3 additions & 0 deletions python/docs/api/compute/enums.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Enums

::: geoarrow.rust.compute.enums
40 changes: 40 additions & 0 deletions python/docs/api/compute/functions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Functions

## Array/Chunked Array functions

::: geoarrow.rust.compute
options:
filters:
- "!^_"
members:
- affine_transform
- area
- center
- centroid
- chaikin_smoothing
- convex_hull
- densify
- envelope
- frechet_distance
- geodesic_perimeter
- is_empty
- length
- line_interpolate_point
- line_locate_point
- polylabel
- rotate
- scale
- signed_area
- simplify
- skew
- total_bounds
- translate

## Table functions

::: geoarrow.rust.compute
options:
filters:
- "!^_"
members:
- explode
3 changes: 3 additions & 0 deletions python/docs/api/compute/types.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Types

::: geoarrow.rust.compute.types
36 changes: 11 additions & 25 deletions python/docs/api/core/functions.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,21 @@
# Top-level functions
# Functions

## Array/Chunked Array functions
Interoperability with other Python geospatial libraries (Shapely, GeoPandas) and in-memory geospatial formats (WKB, WKT).

::: geoarrow.rust.core
options:
filters:
- "!^_"
members:
- affine_transform
- area
- center
- centroid
- chaikin_smoothing
- convex_hull
- densify
- envelope
- frechet_distance
- geodesic_perimeter
- is_empty
- length
- line_interpolate_point
- line_locate_point
- polylabel
- rotate
- scale
- signed_area
- simplify
- skew
- total_bounds
- translate
- read_pyogrio
- from_ewkb
- from_geopandas
- from_shapely
- from_wkb
- from_wkt
- to_geopandas
- to_shapely
- to_wkb

## Table functions

Expand All @@ -37,5 +24,4 @@
filters:
- "!^_"
members:
- explode
- geometry_col
18 changes: 0 additions & 18 deletions python/docs/api/core/interop.md

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# I/O
# Functions

Read and write to and from geospatial file formats.

Expand Down
1 change: 0 additions & 1 deletion python/docs/ecosystem/pyogrio.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,4 @@ from geoarrow.rust.core import read_pyogrio, geometry_col
path = "path/to/file.shp"
table = read_pyogrio(path)
geometry = geometry_col(table)
# <geoarrow.rust.core._rust.ChunkedMultiLineStringArray at 0x13fb61e70>
```
41 changes: 0 additions & 41 deletions python/docs/index.md

This file was deleted.

1 change: 1 addition & 0 deletions python/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -655,8 +655,6 @@ def explode(input: ArrowStreamExportable) -> Table:
A new table with multi-part geometries exploded to separate rows.
"""

def geometry_col(table: ArrowStreamExportable) -> ChunkedGeometryArray: ...

# Interop

def read_pyogrio(
Expand Down
6 changes: 3 additions & 3 deletions python/geoarrow-compute/src/algorithm/geo/affine_ops.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
use crate::ffi::from_python::AnyGeometryInput;
use crate::ffi::to_python::{chunked_geometry_array_to_pyobject, geometry_array_to_pyobject};
use crate::util::{return_chunked_geometry_array, return_geometry_array};
use geoarrow::algorithm::geo::AffineOps;
use pyo3::exceptions::PyValueError;
use pyo3::prelude::*;
Expand Down Expand Up @@ -35,11 +35,11 @@ pub fn affine_transform(
match input {
AnyGeometryInput::Array(arr) => {
let out = arr.as_ref().affine_transform(&transform.0)?;
geometry_array_to_pyobject(py, out)
return_geometry_array(py, out)
}
AnyGeometryInput::Chunked(arr) => {
let out = arr.as_ref().affine_transform(&transform.0)?;
chunked_geometry_array_to_pyobject(py, out)
return_chunked_geometry_array(py, out)
}
}
}
9 changes: 5 additions & 4 deletions python/geoarrow-compute/src/algorithm/geo/area.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
use std::sync::Arc;

use crate::ffi::from_python::AnyGeometryInput;
use crate::util::{return_array, return_chunked_array};
use geoarrow::algorithm::geo::{Area, ChamberlainDuquetteArea, GeodesicArea};
use pyo3::exceptions::PyValueError;
use pyo3::prelude::*;
Expand Down Expand Up @@ -40,7 +41,7 @@ pub fn area(py: Python, input: AnyGeometryInput, method: AreaMethod) -> PyGeoArr
AreaMethod::Euclidean => arr.as_ref().unsigned_area()?,
AreaMethod::Geodesic => arr.as_ref().geodesic_area_unsigned()?,
};
Ok(PyArray::from_array_ref(Arc::new(out)).to_arro3(py)?)
return_array(py, PyArray::from_array_ref(Arc::new(out)))
}
AnyGeometryInput::Chunked(arr) => {
let out = match method {
Expand All @@ -50,7 +51,7 @@ pub fn area(py: Python, input: AnyGeometryInput, method: AreaMethod) -> PyGeoArr
AreaMethod::Euclidean => arr.as_ref().unsigned_area()?,
AreaMethod::Geodesic => arr.as_ref().geodesic_area_unsigned()?,
};
Ok(PyChunkedArray::from_array_refs(out.chunk_refs())?.to_arro3(py)?)
return_chunked_array(py, PyChunkedArray::from_array_refs(out.chunk_refs())?)
}
}
}
Expand All @@ -74,7 +75,7 @@ pub fn signed_area(
AreaMethod::Euclidean => arr.as_ref().signed_area()?,
AreaMethod::Geodesic => arr.as_ref().geodesic_area_signed()?,
};
Ok(PyArray::from_array_ref(Arc::new(out)).to_arro3(py)?)
return_array(py, PyArray::from_array_ref(Arc::new(out)))
}
AnyGeometryInput::Chunked(arr) => {
let out = match method {
Expand All @@ -84,7 +85,7 @@ pub fn signed_area(
AreaMethod::Euclidean => arr.as_ref().signed_area()?,
AreaMethod::Geodesic => arr.as_ref().geodesic_area_signed()?,
};
Ok(PyChunkedArray::from_array_refs(out.chunk_refs())?.to_arro3(py)?)
return_chunked_array(py, PyChunkedArray::from_array_refs(out.chunk_refs())?)
}
}
}
7 changes: 3 additions & 4 deletions python/geoarrow-compute/src/algorithm/geo/center.rs
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
use std::sync::Arc;

use crate::ffi::from_python::AnyGeometryInput;
use crate::util::{return_chunked_geometry_array, return_geometry_array};
use geoarrow::algorithm::geo::Center;
use geoarrow::array::GeometryArrayDyn;
use pyo3::prelude::*;
use pyo3_geoarrow::PyGeoArrowResult;
use pyo3_geoarrow::{PyChunkedGeometryArray, PyGeometryArray};

#[pyfunction]
pub fn center(py: Python, input: AnyGeometryInput) -> PyGeoArrowResult<PyObject> {
match input {
AnyGeometryInput::Array(arr) => {
let out = arr.as_ref().center()?;
Ok(PyGeometryArray::new(GeometryArrayDyn::new(Arc::new(out))).into_py(py))
return_geometry_array(py, Arc::new(out))
}
AnyGeometryInput::Chunked(arr) => {
let out = arr.as_ref().center()?;
Ok(PyChunkedGeometryArray::new(Arc::new(out)).into_py(py))
return_chunked_geometry_array(py, Arc::new(out))
}
}
}
7 changes: 3 additions & 4 deletions python/geoarrow-compute/src/algorithm/geo/centroid.rs
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
use std::sync::Arc;

use crate::ffi::from_python::AnyGeometryInput;
use crate::util::{return_chunked_geometry_array, return_geometry_array};
use geoarrow::algorithm::geo::Centroid;
use geoarrow::array::GeometryArrayDyn;
use pyo3::prelude::*;
use pyo3_geoarrow::PyGeoArrowResult;
use pyo3_geoarrow::{PyChunkedGeometryArray, PyGeometryArray};

#[pyfunction]
pub fn centroid(py: Python, input: AnyGeometryInput) -> PyGeoArrowResult<PyObject> {
match input {
AnyGeometryInput::Array(arr) => {
let out = arr.as_ref().centroid()?;
Ok(PyGeometryArray::new(GeometryArrayDyn::new(Arc::new(out))).into_py(py))
return_geometry_array(py, Arc::new(out))
}
AnyGeometryInput::Chunked(arr) => {
let out = arr.as_ref().centroid()?;
Ok(PyChunkedGeometryArray::new(Arc::new(out)).into_py(py))
return_chunked_geometry_array(py, Arc::new(out))
}
}
}
Loading

0 comments on commit 826415b

Please sign in to comment.