Bump for Python 0.2 (#105)

* Bump for Python 0.2

* Update changelog

Author: kylebarron

README.md

@@ -17,7 +17,7 @@ A Rust crate for packed, immutable, zero-copy spatial indexes.
 
 - **An R-tree and k-d tree written in safe rust.**
 - **Fast.** Because of optimizations available by using immutable indexes, tends to be faster than dynamic implementations like [`rstar`](https://github.com/georust/rstar).
-- **Memory efficient.** The index is fully _packed_, meaning that all nodes are at full capacity (except for the last node at each tree level). This means the RTree and k-d tree use less memory. And because the index is backed by a single buffer, it exhibits excellent memory locality. For any number of input geometries, the peak memory required both to build the index and to store the index can be pre-computed.
+- **Memory efficient.** The index is fully _packed_, meaning that all nodes are at full capacity (except for the last node at each tree level). This means the RTree and k-d tree use less memory. And because the index is backed by a single buffer, it exhibits excellent memory locality.
 - **Bounded memory**. For any given number of items and node size, you can infer the total memory used by the RTree or KDTree.
 - **Multiple R-tree sorting methods.** Currently, [hilbert](https://en.wikipedia.org/wiki/Hilbert_R-tree) and [sort-tile-recursive (STR)](https://ia600900.us.archive.org/27/items/nasa_techdoc_19970016975/19970016975.pdf) sorting methods are implemented, but it's extensible to other spatial sorting algorithms in the future, like [overlap-minimizing top-down (OMT)](https://ceur-ws.org/Vol-74/files/FORUM_18.pdf).
 - **ABI-stable:** the index is contained in a single `Vec<u8>`, compatible with the [`flatbush`](https://github.com/mourner/flatbush) and [`kdbush`](https://github.com/mourner/kdbush) JavaScript libraries. Being ABI-stable means that the spatial index can be persisted for later use or shared zero-copy between Rust and another program like Python.

python/CHANGELOG.md

@@ -1,14 +1,26 @@
 # Changelog
 
-## Unreleased
-
-- Raise runtime warning for debug builds by @kylebarron in https://github.com/kylebarron/geo-index/pull/63
-- RTree Buffer protocol, python binding tests by @H-Plus-Time in https://github.com/kylebarron/geo-index/pull/55
-- Python: Return boxes as arrow from RTree by @kylebarron in https://github.com/kylebarron/geo-index/pull/89
-- Update Python API & implement RTree partitions, nearest neighbor search by @kylebarron in https://github.com/kylebarron/geo-index/pull/87
-- Update python bindings by @kylebarron in https://github.com/kylebarron/geo-index/pull/78
-- Add `__repr__` to Python classes by @kylebarron in https://github.com/kylebarron/geo-index/pull/84
-- Python docs website & improved rtree & kdtree docs by @kylebarron in https://github.com/kylebarron/geo-index/pull/93
+## [0.2.0] - 2025-01-06
+
+### New Features
+
+- Support for nearest neighbor searching on RTrees with [`neighbors`](https://kylebarron.dev/geo-index/v0.2.0/api/rtree/#geoindex_rs.rtree.neighbors).
+- Join two RTrees together with [`tree_join`](https://kylebarron.dev/geo-index/v0.2.0/api/rtree/#geoindex_rs.rtree.tree_join), finding their overlapping elements. This is the first part of a spatial join: to find which elements from two different data sources potentially intersect.
+- Extract partitioning structure from the underlying RTree with [`partitions`](https://kylebarron.dev/geo-index/v0.2.0/api/rtree/#geoindex_rs.rtree.partitions) and see the partition geometries with [`partition_boxes`](https://kylebarron.dev/geo-index/v0.2.0/api/rtree/#geoindex_rs.rtree.partition_boxes).
+- Expose [`RTreeMetadata`](https://kylebarron.dev/geo-index/v0.2.0/api/rtree/#geoindex_rs.rtree.RTreeMetadata) and [`KDTreeMetadata`](https://kylebarron.dev/geo-index/v0.2.0/api/kdtree/#geoindex_rs.kdtree.KDTreeMetadata). These allow you to infer the memory usage a tree would incur.
+- Access the internal boxes within the RTree for inspecting the tree internals with `boxes_at_level`.
+- Implement the buffer protocol on `RTree` and `KDTree`. This means you can copy the underlying buffer to Python with `bytes(tree)`.
+
+### Breaking
+
+- **Move RTree and KDTree query functions to standalone global functions**. This
+  makes it easier to persist index buffers and reuse them later, because the
+  query functions work on any object supporting the buffer protocol.
+- **Create "builder" classes**: `RTreeBuilder` and `KDTreeBuilder`. Having these as separate classes allows for iteratively adding the coordinates for an RTree or KDTree. This is useful when the source geometries are larger than fits in memory.
+
+### Documentation
+
+- New documentation website for Python bindings.
 
 ## [0.1.0] - 2024-03-26
 

python/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "geoindex-rs"
-version = "0.2.0-beta.1"
+version = "0.2.0"
 authors = ["Kyle Barron <[email protected]>"]
 edition = "2021"
 description = "Fast, memory-efficient 2D spatial indexes for Python."

python/Cargo.toml

@@ -5,10 +5,20 @@
 [pypi_badge]: https://badge.fury.io/py/geoindex-rs.svg
 [pypi_link]: https://pypi.org/project/geoindex-rs/
 
-Fast, memory-efficient 2D spatial indexes for Python.
+Fast, memory-efficient, zero-copy spatial indexes for Python.
 
 This documentation is for the Python bindings. [Refer here for the Rust crate documentation](https://docs.rs/geo-index).
 
+## Features
+
+- **An R-tree and k-d tree written in Rust, compiled for Python.**
+- **Fast.** The Rust core and immutability lends the spatial indexes to be very fast. Additionally, building the indexes accepts vectorized Numpy or [Arrow](https://arrow.apache.org/) input.
+- **Memory efficient.** The index is fully _packed_, meaning that all nodes are at full capacity (except for the last node at each tree level). This means the RTree and k-d tree use less memory.
+- **Bounded memory**. For any given number of items and node size, you can infer the total memory used by the RTree or KDTree.
+- **Multiple R-tree sorting methods.** Currently, [hilbert](https://en.wikipedia.org/wiki/Hilbert_R-tree) and [sort-tile-recursive (STR)](https://ia600900.us.archive.org/27/items/nasa_techdoc_19970016975/19970016975.pdf) sorting methods are implemented.
+- **ABI-stable:** the index is contained in a single buffer, compatible with the [`flatbush`](https://github.com/mourner/flatbush) and [`kdbush`](https://github.com/mourner/kdbush) JavaScript libraries. Being ABI-stable means that the spatial index can be persisted for later use or shared zero-copy between Rust and Python.
+- **Supports float64 or float32 coordinates:** for 2x memory savings, use float32 coordinates in the spatial index.
+
 ## Install
 
 ```
@@ -20,3 +30,97 @@ or with Conda:
 ```
 conda install geoindex-rs
 ```
+
+## Examples
+
+Building an RTree and searching for nearest neighbors.
+
+```py
+import numpy as np
+from geoindex_rs import rtree as rt
+
+# Three bounding boxes
+min_x = np.arange(0, 3)
+min_y = np.arange(0, 3)
+max_x = np.arange(2, 5)
+max_y = np.arange(2, 5)
+
+# When creating the builder, the total number of items must be passed
+builder = rt.RTreeBuilder(num_items=3)
+
+# Add the bounding boxes to the builder
+builder.add(min_x, min_y, max_x, max_y)
+
+# Consume the builder (sorting the index) and create the RTree.
+tree = builder.finish()
+
+# Find the nearest neighbors in the RTree to the point (5, 5)
+results = rt.neighbors(tree, 5, 5)
+
+# For performance, results are returned as an Arrow array.
+assert results.to_pylist() == [2, 1, 0]
+```
+
+Building a KDTree and searching within a bounding box.
+
+```py
+import numpy as np
+from geoindex_rs import kdtree as kd
+
+# Three points: (0, 2), (1, 3), (2, 4)
+x = np.arange(0, 3)
+y = np.arange(2, 5)
+
+# When creating the builder, the total number of items must be passed
+builder = kd.KDTreeBuilder(3)
+
+# Add the points to the builder
+builder.add(x, y)
+
+# Consume the builder (sorting the index) and create the KDTree.
+tree = builder.finish()
+
+# Search within this bounding box:
+results = kd.range(tree, 2, 4, 7, 9)
+
+# For performance, results are returned as an Arrow array.
+assert results.to_pylist() == [2]
+```
+
+## Persisting the spatial index
+
+The `RTree` and `KDTree` classes implement the Python buffer protocol, so you
+can pass an instance of the index directly to `bytes` to copy the underlying
+spatial index into a buffer. Then you can save that buffer somewhere, load it
+again, and use it directly for queries!
+
+```py
+import numpy as np
+from geoindex_rs import rtree as rt
+
+min_x = np.arange(0, 3)
+min_y = np.arange(0, 3)
+max_x = np.arange(2, 5)
+max_y = np.arange(2, 5)
+
+builder = rt.RTreeBuilder(num_items=3)
+builder.add(min_x, min_y, max_x, max_y)
+tree = builder.finish()
+
+# Copy to a Python bytes object
+copied_tree = bytes(tree)
+
+# The entire RTree is contained within this 144 byte buffer
+assert len(copied_tree) == 144
+
+# We can use the bytes object (or anything else implementing the Python buffer
+# protocol) directly in searches
+results = rt.neighbors(copied_tree, 5, 5)
+assert results.to_pylist() == [2, 1, 0]
+```
+
+## Drawbacks
+
+- Trees are _immutable_. After creating the index, items can no longer be added or removed.
+- Only two-dimensional indexes is supported. This can still be used with higher-dimensional input data as long as it's fine to only index two of the dimensions.
+- Queries return insertion indexes into the input set, so you must manage your own collections.

python/README.md

@@ -0,0 +1 @@
+../CHANGELOG.md

python/docs/CHANGELOG.md

@@ -24,6 +24,7 @@ nav:
   - API Reference:
       - api/rtree.md
       - api/kdtree.md
+  - Changelog: CHANGELOG.md
 
 watch:
   - python
@@ -96,6 +97,7 @@ plugins:
               - griffe_inherited_docstrings
 
           import:
+            - https://arrow.apache.org/docs/objects.inv
             - https://docs.python.org/3/objects.inv
             - https://kylebarron.dev/arro3/latest/objects.inv
 

python/mkdocs.yml

@@ -34,6 +34,22 @@ def range(
 
     Results are the insertion indexes of items that match the query.
 
+    **Example:**
+
+    ```py
+    import numpy as np
+    from geoindex_rs import kdtree as kd
+
+    builder = kd.KDTreeBuilder(3)
+    x = np.arange(0, 3)
+    y = np.arange(2, 5)
+    builder.add(x, y)
+    tree = builder.finish()
+
+    results = kd.range(tree, 2, 4, 7, 9)
+    assert results.to_pylist() == [2]
+    ```
+
     Args:
         index: the KDTree to search.
         min_x: The `min_x` coordinate of the query bounding box.
@@ -79,6 +95,9 @@ class KDTreeBuilder:
     y = np.arange(2, 5)
     builder.add(x, y)
     tree = builder.finish()
+
+    results = kd.range(tree, 2, 4, 7, 9)
+    assert results.to_pylist() == [2]
     ```
     """
     def __init__(
@@ -127,6 +146,9 @@ class KDTreeBuilder:
 
         Returns:
             An Arrow array with the insertion index of each element, which provides a lookup back into the original data.
+
+                This can be converted to a [`pyarrow.Array`][] by passing to
+                [`pyarrow.array`][].
         """
     def finish(self) -> KDTree:
         """Sort the internal index and convert this class to a KDTree instance.

python/python/geoindex_rs/kdtree.pyi

@@ -365,6 +365,9 @@ class RTreeBuilder:
 
         Returns:
             An Arrow array with the insertion index of each element, which provides a lookup back into the original data.
+
+                This can be converted to a [`pyarrow.Array`][] by passing to
+                [`pyarrow.array`][].
         """
     def finish(self, method: Literal["hilbert", "str"] = "hilbert") -> RTree:
         """Sort the internal index and convert this class to an RTree instance.
@@ -392,6 +395,31 @@ class RTree(Buffer):
     This class implements the Python buffer protocol, so you can pass it to the Python
     `bytes` constructor to copy the underlying binary memory into a Python `bytes`
     object.
+
+    ```py
+    import numpy as np
+    from geoindex_rs import rtree as rt
+
+    min_x = np.arange(0, 3)
+    min_y = np.arange(0, 3)
+    max_x = np.arange(2, 5)
+    max_y = np.arange(2, 5)
+
+    builder = rt.RTreeBuilder(num_items=3)
+    builder.add(min_x, min_y, max_x, max_y)
+    tree = builder.finish()
+
+    # Copy to a Python bytes object
+    copied_tree = bytes(tree)
+
+    # The entire RTree is contained within this 144 byte buffer
+    assert len(copied_tree) == 144
+
+    # We can use the bytes object (or anything else implementing the Python buffer
+    protocol) directly in searches
+    results = rt.neighbors(copied_tree, 5, 5)
+    assert results.to_pylist() == [2, 1, 0]
+    ```
     """
     def __repr__(self) -> str: ...
     @property