fastquadtree 1.5.0__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

fastquadtree/rect_quadtree.py

@@ -0,0 +1,230 @@
+# rect_quadtree.py
+from __future__ import annotations
+
+from typing import Any, Literal, SupportsFloat, Tuple, overload
+
+from ._base_quadtree import Bounds, _BaseQuadTree
+from ._item import Point, RectItem
+from ._native import (
+    RectQuadTree as RectQuadTreeF32,
+    RectQuadTreeF64,
+    RectQuadTreeI32,
+    RectQuadTreeI64,
+)
+
+_IdRect = Tuple[int, SupportsFloat, SupportsFloat, SupportsFloat, SupportsFloat]
+
+DTYPE_MAP = {
+    "f32": RectQuadTreeF32,
+    "f64": RectQuadTreeF64,
+    "i32": RectQuadTreeI32,
+    "i64": RectQuadTreeI64,
+}
+
+
+class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
+    """
+    Rectangle version of the quadtree. All geometries are axis-aligned rectangles. (min_x, min_y, max_x, max_y)
+    High-level Python wrapper over the Rust quadtree engine.
+
+    Performance characteristics:
+        Inserts: average O(log n) <br>
+        Rect queries: average O(log n + k) where k is matches returned <br>
+        Nearest neighbor: average O(log n) <br>
+
+    Thread-safety:
+        Instances are not thread-safe. Use external synchronization if you
+        mutate the same tree from multiple threads.
+
+    Args:
+        bounds: World bounds as (min_x, min_y, max_x, max_y).
+        capacity: Max number of points per node before splitting.
+        max_depth: Optional max tree depth. If omitted, engine decides.
+        track_objects: Enable id <-> object mapping inside Python.
+        dtype: Data type for coordinates and ids in the native engine. Default is 'f32'. Options are 'f32', 'f64', 'i32', 'i64'.
+
+    Raises:
+        ValueError: If parameters are invalid or inserts are out of bounds.
+    """
+
+    def __init__(
+        self,
+        bounds: Bounds,
+        capacity: int,
+        *,
+        max_depth: int | None = None,
+        track_objects: bool = False,
+        dtype: str = "f32",
+    ):
+        super().__init__(
+            bounds,
+            capacity,
+            max_depth=max_depth,
+            track_objects=track_objects,
+            dtype=dtype,
+        )
+
+    @overload
+    def query(
+        self, rect: Bounds, *, as_items: Literal[False] = ...
+    ) -> list[_IdRect]: ...
+    @overload
+    def query(self, rect: Bounds, *, as_items: Literal[True]) -> list[RectItem]: ...
+    def query(
+        self, rect: Bounds, *, as_items: bool = False
+    ) -> list[_IdRect] | list[RectItem]:
+        """
+        Query the tree for all items that intersect the given rectangle.
+
+        Args:
+            rect: Query rectangle as (min_x, min_y, max_x, max_y).
+            as_items: If True, return Item wrappers. If False, return raw tuples.
+
+        Returns:
+            If as_items is False: list of (id, x0, y0, x1, y1) tuples.
+            If as_items is True: list of Item objects.
+
+        Example:
+            ```python
+            results = rqt.query((10.0, 10.0, 20.0, 20.0), as_items=True)
+            for item in results:
+                print(f"Found rect id={item.id_} at {item.geom} with obj={item.obj}")
+            ```
+        """
+        if not as_items:
+            return self._native.query(rect)
+        if self._store is None:
+            raise ValueError("Cannot return results as items with track_objects=False")
+        return self._store.get_many_by_ids(self._native.query_ids(rect))
+
+    def query_np(self, rect: Bounds) -> tuple[Any, Any]:
+        """
+        Return all points inside an axis-aligned rectangle as NumPy arrays.
+        The first array is an array of IDs, and the second is a corresponding array of rectangle coordinates.
+
+        Requirements:
+            NumPy must be installed to use this method.
+
+        Args:
+            rect: Query rectangle as (min_x, min_y, max_x, max_y).
+
+        Returns:
+            Tuple of (ids, locations) where:
+                ids:       NDArray[np.uint64] with shape (N,)
+                locations: NDArray[np.floating] with shape (N, 4)
+
+        Example:
+            ```python
+            ids, locations = rqt.query_np((10.0, 10.0, 20.0, 20.0))
+            for id_, (x0, y0, x1, y1) in zip(ids, locations):
+                print(f"Found rect id={id_} at ({x0}, {y0}, {x1}, {y1})")
+            ```
+        """
+
+        return self._native.query_np(rect)
+
+    @overload
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: Literal[False] = ...
+    ) -> _IdRect | None: ...
+    @overload
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: Literal[True]
+    ) -> RectItem | None: ...
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: bool = False
+    ) -> RectItem | _IdRect | None:
+        """
+        Return the single nearest neighbor to the query point.
+        Utilizes euclidean distance to the nearest edge of rectangles.
+
+        Args:
+            xy: Query point (x, y).
+            as_item: If True, return Item. If False, return (id, x0, y0, x1, y1).
+
+        Returns:
+            The nearest neighbor or None if the tree is empty.
+
+        Example:
+            ```python
+            nn = rqt.nearest_neighbor((15.0, 15.0), as_item=True)
+            if nn is not None:
+                print(f"Nearest rect id={nn.id_} at {nn.geom} with obj={nn.obj}")
+            else:
+                print("No rectangles in the tree.")
+            ```
+        """
+        t = self._native.nearest_neighbor(xy)
+        if t is None or not as_item:
+            return t
+        if self._store is None:
+            raise ValueError("Cannot return result as item with track_objects=False")
+        id_, _x0, _y0, _x1, _y1 = t
+        it = self._store.by_id(id_)
+        if it is None:
+            raise RuntimeError("Internal error: missing tracked item")
+        return it
+
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: Literal[False] = ...
+    ) -> list[_IdRect]: ...
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: Literal[True]
+    ) -> list[RectItem]: ...
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: bool = False
+    ) -> list[RectItem] | list[_IdRect]:
+        """
+        Return the k nearest neighbors to the query point in order of increasing distance.
+        Utilizes euclidean distance to the nearest edge of rectangles.
+
+        Args:
+            xy: Query point (x, y).
+            k: Number of neighbors to return.
+            as_items: If True, return Item wrappers. If False, return raw tuples.
+
+        Returns:
+            If as_items is False: list of (id, x0, y0, x1, y1) tuples. <br>
+            If as_items is True: list of Item objects. <br>
+
+        Example:
+            ```python
+            # Gets the 3 nearest rectangles to point (15.0, 15.0)
+            results = rqt.nearest_neighbors((15.0, 15.0), 3, as_items=True)
+            for item in results:
+                print(f"Found rect id={item.id_} at {item.geom} with obj={item.obj}")
+            ```
+        """
+        raw = self._native.nearest_neighbors(xy, k)
+        if not as_items:
+            return raw
+        if self._store is None:
+            raise ValueError("Cannot return results as items with track_objects=False")
+        out: list[RectItem] = []
+        for id_, _x0, _y0, _x1, _y1 in raw:
+            it = self._store.by_id(id_)
+            if it is None:
+                raise RuntimeError("Internal error: missing tracked item")
+            out.append(it)
+        return out
+
+    def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
+        """Create the native engine instance."""
+        rust_cls = DTYPE_MAP.get(self._dtype)
+        if rust_cls is None:
+            raise TypeError(f"Unsupported dtype: {self._dtype}")
+        return rust_cls(bounds, capacity, max_depth)
+
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes, dtype: str = "f32") -> Any:
+        """Create a new native engine instance from serialized bytes."""
+        rust_cls = DTYPE_MAP.get(dtype)
+        if rust_cls is None:
+            raise TypeError(f"Unsupported dtype: {dtype}")
+        return rust_cls.from_bytes(data)
+
+    @staticmethod
+    def _make_item(id_: int, geom: Bounds, obj: Any | None) -> RectItem:
+        return RectItem(id_, geom, obj)

fastquadtree-1.5.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: fastquadtree
+Version: 1.5.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: ruff>=0.6.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.4.2 ; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0 ; extra == 'dev'
+Requires-Dist: coverage>=7.5 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: build>=1.2.1 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.6 ; extra == 'dev'
+Requires-Dist: mkdocs-material ; extra == 'dev'
+Requires-Dist: mkdocstrings[python] ; extra == 'dev'
+Requires-Dist: mkdocs-autorefs ; extra == 'dev'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin ; extra == 'dev'
+Requires-Dist: mkdocs-minify-plugin ; extra == 'dev'
+Requires-Dist: maturin>=1.5 ; extra == 'dev'
+Requires-Dist: pyqtree==1.0.0 ; extra == 'dev'
+Requires-Dist: numpy ; extra == 'dev'
+Requires-Dist: pre-commit ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search.
+Keywords: quadtree,spatial-index,geometry,rust,pyo3,nearest-neighbor,k-nn
+Author: Ethan Anderson
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Project-URL: Homepage, https://github.com/Elan456/fastquadtree
+Project-URL: Repository, https://github.com/Elan456/fastquadtree
+Project-URL: Documentation, https://elan456.github.io/fastquadtree/
+Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
+
+# fastquadtree
+
+<img src="https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/interactive_v2_screenshot.png"
+     alt="Interactive Screenshot" align="right" width="420">
+
+Rust-optimized quadtree with a clean Python API
+
+👉 **Check out the Docs:** https://elan456.github.io/fastquadtree/
+
+[![PyPI](https://img.shields.io/pypi/v/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
+[![Downloads](https://static.pepy.tech/personalized-badge/fastquadtree?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Total%20Downloads)](https://pepy.tech/projects/fastquadtree)
+[![Build](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml/badge.svg)](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml)
+![No runtime deps](https://img.shields.io/badge/deps-none-success)
+
+[![PyO3](https://img.shields.io/badge/Rust-core%20via%20PyO3-orange)](https://pyo3.rs/)
+[![maturin](https://img.shields.io/badge/Built%20with-maturin-1f6feb)](https://www.maturin.rs/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://elan456.github.io/fastquadtree/)
+[![Wheels](https://img.shields.io/pypi/wheel/fastquadtree.svg)](https://pypi.org/project/fastquadtree/#files)
+[![Coverage](https://codecov.io/gh/Elan456/fastquadtree/branch/main/graph/badge.svg)](https://codecov.io/gh/Elan456/fastquadtree)
+[![License: MIT](https://img.shields.io/pypi/l/fastquadtree.svg)](LICENSE)
+
+<br clear="right"/>
+
+## Why use fastquadtree
+
+- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with **no external dependencies** and modern typing hints
+- The fastest quadtree Python package ([>10x faster](https://elan456.github.io/fastquadtree/benchmark/) than pyqtree)
+- Prebuilt wheels for Windows, macOS, and Linux
+- Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
+- Fast KNN and range queries
+- Optional object tracking for id ↔ object mapping
+- Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
+- Support for multiple data types (f32, f64, i32, i64) for coordinates
+- [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
+- Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
+
+----
+
+
+## Examples
+See examples of how fastquadtree can be used in the [runnables](https://elan456.github.io/fastquadtree/runnables/) section.
+
+
+## Install
+```bash
+pip install fastquadtree
+```
+
+```python
+from fastquadtree import QuadTree  # Point handling
+from fastquadtree import RectQuadTree  # Bounding box handling
+from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (6.567x faster while keeping the same API)
+```
+
+## Benchmarks
+
+fastquadtree **outperforms** all other quadtree Python packages, including the Rtree spatial index.
+
+### Library comparison
+
+![Total time](https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/quadtree_bench_time.png)
+![Throughput](https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/quadtree_bench_throughput.png)
+
+### Summary (largest dataset, PyQtree baseline)
+- Points: **250,000**, Queries: **500**
+- Fastest total: **fastquadtree** at **0.030 s**
+
+| Library | Build (s) | Query (s) | Total (s) | Speed vs PyQtree |
+|---|---:|---:|---:|---:|
+| fastquadtree | 0.023 | 0.007 | 0.030 | 41.31× |
+| Shapely STRtree | 0.094 | 0.049 | 0.143 | 8.67× |
+| nontree-QuadTree | 0.448 | 0.475 | 0.924 | 1.34× |
+| Rtree        | 0.801 | 0.225 | 1.025 | 1.21× |
+| e-pyquadtree | 0.666 | 0.451 | 1.117 | 1.11× |
+| PyQtree      | 1.066 | 0.175 | 1.241 | 1.00× |
+| quads        | 0.969 | 0.330 | 1.299 | 0.96× |
+
+See the [benchmark section](https://elan456.github.io/fastquadtree/benchmark/) for details, including configurations, system info, and native vs shim benchmarks.
+
+## Quickstart
+[See the quickstart guide](https://elan456.github.io/fastquadtree/quickstart/)
+
+## API
+
+[See the full API](https://elan456.github.io/fastquadtree/api/quadtree/)
+
+### `QuadTree(bounds, capacity, max_depth=None, track_objects=False, start_id=1)`
+
+* `bounds` — tuple `(min_x, min_y, max_x, max_y)` defines the 2D area covered by the quadtree
+* `capacity` — max number of points kept in a leaf before splitting
+* `max_depth` — optional depth cap. If omitted, the tree can keep splitting as needed
+* `track_objects` — if `True`, the wrapper maintains an id → object map for convenience.
+* `start_id` — starting value for auto-assigned ids
+
+### Key Methods
+
+- `insert(xy, *, id=None, obj=None) -> int`
+
+- `query(rect, *, as_items=False) -> list`
+
+- `nearest_neighbor(xy, *, as_item=False) -> (id, x, y) | Item | None`
+
+- `delete(id, xy) -> bool`
+
+There are more methods and object tracking versions in the [docs](https://elan456.github.io/fastquadtree/api/quadtree/).
+
+### Geometric conventions
+
+* Rectangles are `(min_x, min_y, max_x, max_y)`.
+* Containment rule is closed on the min edge and open on the max edge
+  `(x >= min_x and x < max_x and y >= min_y and y < max_y)`.
+  This only matters for points exactly on edges.
+
+## Performance tips
+
+* Choose `capacity` so that leaves keep a small batch of points. Typical values are 8 to 64.
+* If your data is very skewed, set a `max_depth` to prevent long chains.
+* For fastest local runs, use `maturin develop --release`.
+* The wrapper maintains an object map only if the quadtree was constructed with `track_objects=True`. If you don't need it, leave it off for best performance.
+* Refer to the [Native vs Shim Benchmark](https://elan456.github.io/fastquadtree/benchmark/#native-vs-shim-benchmark) for overhead details.
+
+### Pygame Ball Pit Demo
+
+![Ballpit_Demo_Screenshot](https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/ballpit.png)
+
+A simple demo of moving objects with collision detection using **fastquadtree**. 
+You can toggle between quadtree mode and brute-force mode to see the performance difference.
+
+See the [runnables guide](https://elan456.github.io/fastquadtree/runnables/) for setup instructions.
+
+## FAQ
+
+**Can I delete items from the quadtree?**
+Yes! Use `delete(id, xy)` to remove specific items. You must provide both the ID and exact location for precise deletion. This handles cases where multiple items exist at the same location. If you're using `track_objects=True`, you can also use `delete_by_object(obj)` for convenient object-based deletion with O(1) lookup. The tree automatically merges nodes when item counts drop below capacity.
+
+**Can I store rectangles or circles?**
+Yes, you can store rectangles using the `RectQuadTree` class. Circles can be approximated with bounding boxes. See the [RectQuadTree docs](https://elan456.github.io/fastquadtree/api/rect_quadtree/) for details.
+
+**Do I need NumPy installed?**  
+No, NumPy is a fully optional dependency. If you do have NumPy installed, you can use methods such as `query_np` and the NumPy array variant of `insert_many` for better performance. The Rust core is able to handle NumPy arrays faster than Python lists, so there's a lot of time savings in utilizing the NumPy functions. See the [Native vs Shim benchmark](https://elan456.github.io/fastquadtree/benchmark/#native-vs-shim) for details on how returing NumPy arrays can speed up queries.
+
+**Does fastquadtree support multiprocessing?**  
+Yes, fastquadtree objects can be serialized to bytes using the `to_bytes()` method and deserialized back using `from_bytes()`. This allows you to share quadtree data across processes and even cache prebuilt trees to disk. See the [interactive v2 demo](https://github.com/Elan456/fastquadtree/blob/main/interactive/interactive_v2.py) for an example of saving and loading a quadtree.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Acknowledgments
+
+* Python libraries compared: [PyQtree], [e-pyquadtree], [Rtree], [nontree], [quads], [Shapely]
+* Built with [PyO3] and [maturin]
+
+[PyQtree]: https://pypi.org/project/pyqtree/
+[e-pyquadtree]: https://pypi.org/project/e-pyquadtree/
+[PyO3]: https://pyo3.rs/
+[maturin]: https://www.maturin.rs/
+[Rtree]: https://pypi.org/project/Rtree/
+[nontree]: https://pypi.org/project/nontree/
+[quads]: https://pypi.org/project/quads/
+[Shapely]: https://pypi.org/project/Shapely/
+

fastquadtree-1.5.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+fastquadtree-1.5.0.dist-info/METADATA,sha256=F-qLCl6F_1h7um_sHBLFUvY8EzVgiVgq774oe6Sd8JU,10526
+fastquadtree-1.5.0.dist-info/WHEEL,sha256=fqFHtOCr25M-h-Mnj-0-ZSwuoI9vJMsUUAJdvV4MPAM,145
+fastquadtree-1.5.0.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
+fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
+fastquadtree/_base_quadtree.py,sha256=lnblGEYIIlB34rssfdRcfCdc0FI_tL7E8x0dbqhfPgI,17380
+fastquadtree/_item.py,sha256=0ioI1mm-TUPzuAV8Y6t35IOV-R_pSiSMqQDyWAjb4zU,2468
+fastquadtree/_native.abi3.so,sha256=a7aFvTIJcrzDDtT7Fu33FjPfvilo-uSYdkKhtm-ycc0,796648
+fastquadtree/_obj_store.py,sha256=tY8siqTCjr1JK3rigtljDVVYbQmPDRs1m8iUCCBHMO0,6337
+fastquadtree/point_quadtree.py,sha256=-3G_JgbyH8mFRV0bTFygI1mpb3F09v2gr1vqTm4hdUA,7167
+fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastquadtree/pyqtree.py,sha256=iAWAajViag4yTfiRXcGPha8bnNJOLRU7O9jdkjUeJKU,6450
+fastquadtree/rect_quadtree.py,sha256=kTxMH7hQU5c4ocGkzLqd9w35IrUdbnkm1Hec1xjbyV8,8139
+fastquadtree-1.5.0.dist-info/RECORD,,

fastquadtree-1.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp38-abi3-manylinux_2_17_aarch64
+Tag: cp38-abi3-manylinux2014_aarch64

fastquadtree-1.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ethan Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.