fastquadtree 0.6.1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

fastquadtree/__init__.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Tuple, overload
+
+from ._bimap import BiMap  # type: ignore[attr-defined]
+from ._item import Item
+
+# Compiled Rust module is provided by maturin (tool.maturin.module-name)
+from ._native import QuadTree as _RustQuadTree
+
+Bounds = Tuple[float, float, float, float]
+"""Axis-aligned rectangle as (min_x, min_y, max_x, max_y)."""
+
+Point = Tuple[float, float]
+"""2D point as (x, y)."""
+
+_IdCoord = Tuple[int, float, float]
+"""Result tuple as (id, x, y)."""
+
+
+class QuadTree:
+    """
+    High-level Python wrapper over the Rust quadtree engine.
+
+    The quadtree stores points with integer IDs. You may attach an arbitrary
+    Python object per ID when object tracking is enabled.
+
+    Performance characteristics:
+        Inserts: average O(log n)
+        Rect queries: average O(log n + k) where k is matches returned
+        Nearest neighbor: average O(log n)
+
+    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.
+        start_id: Starting auto-assigned id when you omit id on insert.
+
+    Raises:
+        ValueError: If parameters are invalid or inserts are out of bounds.
+    """
+
+    __slots__ = ("_bounds", "_count", "_items", "_native", "_next_id")
+
+    def __init__(
+        self,
+        bounds: Bounds,
+        capacity: int,
+        *,
+        max_depth: int | None = None,
+        track_objects: bool = False,
+        start_id: int = 1,
+    ):
+        if max_depth is None:
+            self._native = _RustQuadTree(bounds, capacity)
+        else:
+            self._native = _RustQuadTree(bounds, capacity, max_depth=max_depth)
+        self._items: BiMap | None = BiMap() if track_objects else None
+        self._next_id: int = int(start_id)
+        self._count: int = 0
+        self._bounds = bounds
+
+    # ---------- inserts ----------
+
+    def insert(self, xy: Point, *, id_: int | None = None, obj: Any = None) -> int:
+        """
+        Insert a single point.
+
+        Args:
+            xy: Point (x, y).
+            id: Optional integer id. If None, an auto id is assigned.
+            obj: Optional Python object to associate with id. Stored only if
+                object tracking is enabled.
+
+        Returns:
+            The id used for this insert.
+
+        Raises:
+            ValueError: If the point is outside tree bounds.
+        """
+        if id_ is None:
+            id_ = self._next_id
+            self._next_id += 1
+        # ensure future auto-ids do not collide
+        elif id_ >= self._next_id:
+            self._next_id = id_ + 1
+
+        if not self._native.insert(id_, xy):
+            x, y = xy
+            bx0, by0, bx1, by1 = self._bounds
+            raise ValueError(
+                f"Point ({x}, {y}) is outside bounds ({bx0}, {by0}, {bx1}, {by1})"
+            )
+
+        if self._items is not None:
+            self._items.add(Item(id_, xy[0], xy[1], obj))
+
+        self._count += 1
+        return id_
+
+    def insert_many_points(self, points: list[Point]) -> int:
+        """
+        Bulk insert points with auto-assigned ids.
+
+        Args:
+            points: List of (x, y) points.
+
+        Returns:
+            The number of points inserted
+        """
+        start_id = self._next_id
+        last_id = self._native.insert_many_points(start_id, points)
+
+        num_inserted = last_id - start_id + 1
+
+        if num_inserted < len(points):
+            raise ValueError("One or more points are outside tree bounds")
+
+        self._next_id = last_id + 1
+
+        # Update the item tracker if needed
+        if self._items is not None:
+            for i, id_ in enumerate(range(start_id, last_id + 1)):
+                x, y = points[i]
+                self._items.add(Item(id_, x, y, None))
+
+        return num_inserted
+
+    def attach(self, id_: int, obj: Any) -> None:
+        """
+        Attach or replace the Python object for an existing id.
+        Tracking must be enabled.
+
+        Args:
+            id_: Target id.
+            obj: Object to associate with id.
+        """
+        if self._items is None:
+            raise ValueError("Cannot attach objects when track_objects=False")
+
+        item = self._items.by_id(id_)
+        if item is None:
+            raise KeyError(f"Id {id_} not found in quadtree")
+        self._items.add(Item(id_, item.x, item.y, obj))
+
+    def delete(self, id_: int, xy: Point) -> bool:
+        """
+        Delete an item by id and exact coordinates.
+
+        Args:
+            id_: Integer id to remove.
+            xy: Coordinates (x, y) of the item.
+
+        Returns:
+            True if the item was found and deleted, else False.
+        """
+        deleted = self._native.delete(id_, xy)
+        if deleted:
+            self._count -= 1
+            if self._items is not None:
+                self._items.pop_id(id_)  # ignore result
+        return deleted
+
+    def delete_by_object(self, obj: Any) -> bool:
+        """
+        Delete an item by Python object.
+
+        Requires object tracking to be enabled. Performs an O(1) reverse
+        lookup to get the id, then deletes that entry at the given location.
+
+        Args:
+            obj: The tracked Python object to remove.
+
+        Returns:
+            True if the item was found and deleted, else False.
+
+        Raises:
+            ValueError: If object tracking is disabled.
+        """
+        if self._items is None:
+            raise ValueError(
+                "Cannot delete by object when track_objects=False. Use delete(id, xy) instead."
+            )
+
+        item = self._items.by_obj(obj)
+        if item is None:
+            return False
+
+        return self.delete(item.id_, (item.x, item.y))
+
+    # ---------- queries ----------
+
+    @overload
+    def query(
+        self, rect: Bounds, *, as_items: Literal[False] = ...
+    ) -> list[_IdCoord]: ...
+
+    @overload
+    def query(self, rect: Bounds, *, as_items: Literal[True]) -> list[Item]: ...
+
+    def query(
+        self, rect: Bounds, *, as_items: bool = False
+    ) -> list[_IdCoord] | list[Item]:
+        """
+        Return all points inside an axis-aligned 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, x, y) tuples.
+            If as_items is True: list of Item objects.
+        """
+        raw = self._native.query(rect)
+        if not as_items:
+            return raw
+
+        if self._items is None:
+            raise ValueError("Cannot return results as items with track_objects=False")
+        out: list[Item] = []
+        for id_, _, _ in raw:
+            item = self._items.by_id(id_)
+            if item is None:
+                raise RuntimeError(
+                    f"Internal error: id {id_} found in native tree but missing from object tracker. "
+                    f"Ensure all inserts/deletes are done via this wrapper."
+                )
+            out.append(item)
+        return out
+
+    @overload
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: Literal[False] = ...
+    ) -> _IdCoord | None: ...
+
+    @overload
+    def nearest_neighbor(self, xy: Point, *, as_item: Literal[True]) -> Item | None: ...
+
+    def nearest_neighbor(self, xy: Point, *, as_item: bool = False):
+        """
+        Return the single nearest neighbor to the query point.
+
+        Args:
+            xy: Query point (x, y).
+            as_item: If True, return Item. If False, return (id, x, y).
+
+        Returns:
+            The nearest neighbor or None if the tree is empty.
+        """
+        t = self._native.nearest_neighbor(xy)
+        if t is None or not as_item:
+            return t
+
+        if self._items is None:
+            raise ValueError("Cannot return result as item with track_objects=False")
+        id_, _x, _y = t
+        item = self._items.by_id(id_)
+        if item is None:
+            raise RuntimeError(
+                f"Internal error: id {id_} found in native tree but missing from object tracker. "
+                f"Ensure all inserts/deletes are done via this wrapper."
+            )
+        return item
+
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: Literal[False] = ...
+    ) -> list[_IdCoord]: ...
+
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: Literal[True]
+    ) -> list[Item]: ...
+
+    def nearest_neighbors(self, xy: Point, k: int, *, as_items: bool = False):
+        """
+        Return the k nearest neighbors to the query point.
+
+        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:
+            List of results in ascending distance order.
+        """
+        raw = self._native.nearest_neighbors(xy, k)
+        if not as_items:
+            return raw
+        if self._items is None:
+            raise ValueError("Cannot return results as items with track_objects=False")
+
+        out: list[Item] = []
+        for id_, _, _ in raw:
+            item = self._items.by_id(id_)
+            if item is None:
+                raise RuntimeError(
+                    f"Internal error: id {id_} found in native tree but missing from object tracker. "
+                    f"Ensure all inserts/deletes are done via this wrapper."
+                )
+            out.append(item)
+        return out
+
+    # ---------- misc ----------
+
+    def get(self, id_: int) -> Any | None:
+        """
+        Return the object associated with id.
+
+        Returns:
+            The tracked object if present and tracking is enabled, else None.
+        """
+        if self._items is None:
+            raise ValueError("Cannot get objects when track_objects=False")
+        item = self._items.by_id(id_)
+        if item is None:
+            return None
+        return item.obj
+
+    def get_all_rectangles(self) -> list[Bounds]:
+        """
+        Return all node rectangles in the current quadtree.
+
+        Returns:
+            List of (min_x, min_y, max_x, max_y) for each node in the tree.
+        """
+        return self._native.get_all_rectangles()
+
+    def get_all_objects(self) -> list[Any]:
+        """
+        Return all tracked objects.
+
+        Returns:
+            List of objects if tracking is enabled, else an empty list.
+        """
+        if self._items is None:
+            raise ValueError("Cannot get objects when track_objects=False")
+        return [t.obj for t in self._items.items() if t.obj is not None]
+
+    def get_all_items(self) -> list[Item]:
+        """
+        Return all tracked items.
+
+        Returns:
+            List of Item if tracking is enabled, else an empty list.
+        """
+        if self._items is None:
+            raise ValueError("Cannot get items when track_objects=False")
+        return list(self._items.items())
+
+    def count_items(self) -> int:
+        """
+        Return the number of items stored in the native tree.
+
+        Notes:
+            This calls the native engine and may differ from len(self) if
+            you create multiple wrappers around the same native structure.
+        """
+        return self._native.count_items()
+
+    def __len__(self) -> int:
+        """
+        Return the number of successful inserts done via this wrapper.
+
+        Notes:
+            This is the Python-side counter that tracks calls that returned True.
+            use count_items() to get the authoritative native-side count.
+        """
+        return self._count
+
+    # Power users can access the raw class
+    NativeQuadTree = _RustQuadTree
+
+
+__all__ = ["Bounds", "Item", "Point", "QuadTree"]

fastquadtree/__init__.pyi

@@ -0,0 +1,70 @@
+from typing import (
+    Any,
+    Iterable,
+    Literal as _Literal,  # avoid polluting public namespace
+    overload,
+)
+
+Bounds = tuple[float, float, float, float]
+Point = tuple[float, float]
+
+class Item:
+    id_: int
+    x: float
+    y: float
+    obj: Any | None
+
+class QuadTree:
+    # Expose the raw native class for power users
+    NativeQuadTree: type
+
+    def __init__(
+        self,
+        bounds: Bounds,
+        capacity: int,
+        *,
+        max_depth: int | None = None,
+        track_objects: bool = False,
+        start_id: int = 1,
+    ) -> None: ...
+
+    # Inserts
+    def insert(self, xy: Point, *, id_: int | None = ..., obj: Any = ...) -> int: ...
+    def insert_many_points(self, points: Iterable[Point]) -> int: ...
+    def attach(self, id_: int, obj: Any) -> None: ...
+
+    # Deletions
+    def delete(self, id_: int, xy: Point) -> bool: ...
+    def delete_by_object(self, obj: Any) -> bool: ...
+
+    # Queries
+    @overload
+    def query(
+        self, rect: Bounds, *, as_items: _Literal[False] = ...
+    ) -> list[tuple[int, float, float]]: ...
+    @overload
+    def query(self, rect: Bounds, *, as_items: _Literal[True]) -> list[Item]: ...
+    @overload
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: _Literal[False] = ...
+    ) -> tuple[int, float, float] | None: ...
+    @overload
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: _Literal[True]
+    ) -> Item | None: ...
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: _Literal[False] = ...
+    ) -> list[tuple[int, float, float]]: ...
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: _Literal[True]
+    ) -> list[Item]: ...
+
+    # Misc
+    def get(self, id_: int) -> Any | None: ...
+    def get_all_rectangles(self) -> list[Bounds]: ...
+    def get_all_objects(self) -> list[Any]: ...
+    def get_all_items(self) -> list[Item]: ...
+    def count_items(self) -> int: ...
+    def __len__(self) -> int: ...

fastquadtree/_bimap.py

@@ -0,0 +1,112 @@
+# _bimap.py
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator
+
+from ._item import Item
+
+
+class BiMap:
+    """
+    Bidirectional map to the same Item:
+      id -> Item
+      obj -> Item  (uses object identity)
+
+    Rules:
+      - One-to-one: an id maps to exactly one Item, and an object maps to exactly one Item.
+      - add(item): inserts or replaces both sides so they point to 'item'.
+      - If item.obj is None, only id -> Item is stored.
+    """
+
+    __slots__ = ("_id_to_item", "_objid_to_item")
+
+    def __init__(self, items: Iterable[Item] | None = None) -> None:
+        self._id_to_item: dict[int, Item] = {}
+        self._objid_to_item: dict[int, Item] = {}
+        if items:
+            for it in items:
+                self.add(it)
+
+    # - core -
+
+    def add(self, item: Item) -> None:
+        """
+        Insert or replace mapping for this Item.
+        Handles conflicts so that both id and obj point to this exact Item.
+        """
+        id_ = item.id_
+        obj = item.obj
+
+        # Unlink any old item currently bound to this id
+        old = self._id_to_item.get(id_)
+        if old is not None and old is not item:
+            old_obj = old.obj
+            if old_obj is not None:
+                self._objid_to_item.pop(id(old_obj), None)
+
+        # Unlink any old item currently bound to this obj
+        if obj is not None:
+            prev = self._objid_to_item.get(id(obj))
+            if prev is not None and prev is not item:
+                self._id_to_item.pop(prev.id_, None)
+
+        # Link new
+        self._id_to_item[id_] = item
+        if obj is not None:
+            self._objid_to_item[id(obj)] = item
+
+    def by_id(self, id_: int) -> Item | None:
+        return self._id_to_item.get(id_)
+
+    def by_obj(self, obj: Any) -> Item | None:
+        return self._objid_to_item.get(id(obj))
+
+    def pop_id(self, id_: int) -> Item | None:
+        it = self._id_to_item.pop(id_, None)
+        if it is not None:
+            obj = it.obj
+            if obj is not None:
+                self._objid_to_item.pop(id(obj), None)
+        return it
+
+    def pop_obj(self, obj: Any) -> Item | None:
+        it = self._objid_to_item.pop(id(obj), None)
+        if it is not None:
+            self._id_to_item.pop(it.id_, None)
+        return it
+
+    def pop_item(self, item: Item) -> Item | None:
+        """
+        Remove this exact Item if present on either side.
+        """
+        removed = None
+        # Remove by id first
+        removed = self._id_to_item.pop(item.id_)
+
+        # Remove by obj side
+        obj = item.obj
+        if obj is not None:
+            self._objid_to_item.pop(id(obj), None)
+            removed = removed or item
+        return removed
+
+    # - convenience -
+
+    def __len__(self) -> int:
+        return len(self._id_to_item)
+
+    def clear(self) -> None:
+        self._id_to_item.clear()
+        self._objid_to_item.clear()
+
+    def contains_id(self, id_: int) -> bool:
+        return id_ in self._id_to_item
+
+    def contains_obj(self, obj: Any) -> bool:
+        return id(obj) in self._objid_to_item
+
+    def items_by_id(self) -> Iterator[tuple[int, Item]]:
+        return iter(self._id_to_item.items())
+
+    def items(self) -> Iterator[Item]:
+        return iter(self._id_to_item.values())

fastquadtree/_item.py

@@ -0,0 +1,24 @@
+# item.py
+from __future__ import annotations
+
+from typing import Any
+
+
+class Item:
+    """
+    Lightweight view of an index entry.
+
+    Attributes:
+        id_: Integer identifier.
+        x: X coordinate.
+        y: Y coordinate.
+        obj: The attached Python object if available, else None.
+    """
+
+    __slots__ = ("id_", "obj", "x", "y")
+
+    def __init__(self, id_: int, x: float, y: float, obj: Any | None = None):
+        self.id_ = id_
+        self.x = x
+        self.y = y
+        self.obj = obj

fastquadtree-0.6.1.dist-info/METADATA

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: fastquadtree
+Version: 0.6.1
+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>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1 ; extra == 'dev'
+Requires-Dist: coverage>=7.5 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: build>=1.2.1 ; 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.8
+Description-Content-Type: text/markdown
+Project-URL: Homepage, https://github.com/Elan456/fastquadtree
+Project-URL: Repository, https://github.com/Elan456/fastquadtree
+Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
+
+# fastquadtree
+
+[![PyPI version](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/)
+[![Wheels](https://img.shields.io/pypi/wheel/fastquadtree.svg)](https://pypi.org/project/fastquadtree/#files)
+[![License: MIT](https://img.shields.io/pypi/l/fastquadtree.svg)](LICENSE)
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/fastquadtree?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Total+Downloads)](https://pepy.tech/projects/fastquadtree)
+
+[![Build](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml/badge.svg)](https://github.com/Elan456/fastquadtree/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/Elan456/fastquadtree/branch/main/graph/badge.svg)](https://codecov.io/gh/Elan456/fastquadtree)
+
+[![Rust core via PyO3](https://img.shields.io/badge/Rust-core%20via%20PyO3-orange)](https://pyo3.rs/)
+[![Built with 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)
+
+
+
+![Interactive_V2_Screenshot](https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/interactive_v2_screenshot.png)
+
+
+Rust-optimized quadtree with a simple Python API.
+
+- Python package: **`fastquadtree`**
+- Python ≥ 3.8
+- Import path: `from fastquadtree import QuadTree`
+
+## 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.120 s**
+
+| Library | Build (s) | Query (s) | Total (s) | Speed vs PyQtree |
+|---|---:|---:|---:|---:|
+| fastquadtree | 0.031 | 0.089 | 0.120 | 14.64× |
+| Shapely STRtree | 0.179 | 0.100 | 0.279 | 6.29× |
+| nontree-QuadTree | 0.595 | 0.605 | 1.200 | 1.46× |
+| Rtree        | 0.961 | 0.300 | 1.261 | 1.39× |
+| e-pyquadtree | 1.005 | 0.660 | 1.665 | 1.05× |
+| PyQtree      | 1.492 | 0.263 | 1.755 | 1.00× |
+| quads        | 1.407 | 0.484 | 1.890 | 0.93× |
+
+#### Benchmark Configuration
+| Parameter | Value |
+|---|---:|
+| Bounds | (0, 0, 1000, 1000) |
+| Max points per node | 128 |
+| Max depth | 16 |
+| Queries per experiment | 500 |
+
+## Install
+
+```bash
+pip install fastquadtree
+````
+
+If you are developing locally:
+
+```bash
+# optimized dev install
+maturin develop --release
+```
+
+## Quickstart
+
+```python
+from fastquadtree import QuadTree
+
+# Bounds are (min_x, min_y, max_x, max_y)
+qt = QuadTree(bounds=(0, 0, 1000, 1000), capacity=20)  # max_depth is optional
+
+# Insert points with auto ids
+id1 = qt.insert((10, 10))
+id2 = qt.insert((200, 300))
+id3 = qt.insert((999, 500), id=42)  # you can supply your own id
+
+# Axis-aligned rectangle query
+hits = qt.query((0, 0, 250, 350))  # returns [(id, x, y), ...] by default
+print(hits)  # e.g. [(1, 10.0, 10.0), (2, 200.0, 300.0)]
+
+# Nearest neighbor
+best = qt.nearest_neighbor((210, 310))  # -> (id, x, y) or None
+print(best)
+
+# k-nearest neighbors
+top3 = qt.nearest_neighbors((210, 310), 3)
+print(top3)  # list of up to 3 (id, x, y) tuples
+
+# Delete items by ID and location
+deleted = qt.delete(id2, (200, 300))  # True if found and deleted
+print(f"Deleted: {deleted}")
+print(f"Remaining items: {qt.count_items()}")
+
+# For object tracking with track_objects=True
+qt_tracked = QuadTree((0, 0, 1000, 1000), capacity=4, track_objects=True)
+player1 = {"name": "Alice", "score": 100}
+player2 = {"name": "Bob", "score": 200}
+
+id1 = qt_tracked.insert((50, 50), obj=player1)
+id2 = qt_tracked.insert((150, 150), obj=player2)
+
+# Delete by object reference (O(1) lookup!)
+deleted = qt_tracked.delete_by_object(player1)
+print(f"Deleted player: {deleted}")  # True
+```
+
+### Working with Python objects
+
+You can keep the tree pure and manage your own id → object map, or let the wrapper manage it.
+
+**Wrapper Managed Objects**
+
+```python
+from fastquadtree import QuadTree
+
+qt = QuadTree((0, 0, 1000, 1000), capacity=16, track_objects=True)
+
+# Store the object alongside the point
+qt.insert((25, 40), obj={"name": "apple"})
+
+# Ask for Item objects within a bounding box
+items = qt.query((0, 0, 100, 100), as_items=True)
+for it in items:
+    print(it.id, it.x, it.y, it.obj)
+```
+
+You can also attach or replace an object later:
+
+```python
+qt.attach(123, my_object)  # binds object to id 123
+```
+
+## API
+
+### `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
+
+### Core Methods
+
+Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__.py)
+
+- `insert(xy, *, id=None, obj=None) -> int`
+
+- `insert_many_points(points) -> int`
+
+- `query(rect, *, as_items=False) -> list`
+
+- `nearest_neighbor(xy, *, as_item=False) -> (id, x, y) | Item | None`
+
+- `nearest_neighbors(xy, k, *, as_items=False) -> list`
+
+- `delete(id, xy) -> bool`
+
+- `delete_by_object(obj) -> bool (requires track_objects=True)`
+
+- `attach(id, obj) -> None (requires track_objects=True)`
+
+- `count_items() -> int`
+
+- `get(id) -> object | None`
+
+- `get_all_rectangles() -> list[tuple] (for visualization)`
+
+### `Item` (returned when `as_items=True`)
+
+* Attributes: `id`, `x`, `y`, and a lazy `obj` property
+* Accessing `obj` performs a dictionary lookup only if tracking is enabled
+
+### 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 keeps Python overhead low: raw tuple results by default, `Item` wrappers only when requested.
+
+
+### Native vs Shim Benchmark
+
+**Setup**
+- Points: 500,000
+- Queries: 500
+- Repeats: 5
+
+**Timing (seconds)**
+
+| Variant | Build | Query | Total |
+|---|---:|---:|---:|
+| Native | 0.483 | 4.380 | 4.863 |
+| Shim (no map) | 0.668 | 4.167 | 4.835 |
+| Shim (track+objs) | 1.153 | 4.458 | 5.610 |
+
+**Overhead vs Native**
+
+- No map: build 1.38x, query 0.95x, total 0.99x  
+- Track + objs: build 2.39x, query 1.02x, total 1.15x
+
+### Run benchmarks
+To run the benchmarks yourself, first install the dependencies:
+
+```bash
+pip install -r benchmarks/requirements.txt
+```
+
+Then run:
+
+```bash
+python benchmarks/cross_library_bench.py
+python benchmarks/benchmark_native_vs_shim.py 
+```
+
+## Run Visualizer
+A visualizer is included to help you understand how the quadtree subdivides space.
+
+```bash
+pip install -r interactive/requirements.txt
+python interactive/interactive_v2.py
+```
+
+Check the CLI arguments for the cross-library benchmark in `benchmarks/quadtree_bench/main.py`.
+
+## FAQ
+
+**What happens if I insert the same id more than once?**
+Allowed. For k-nearest, duplicates are de-duplicated by id. For range queries you will see every inserted point.
+
+**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?**
+The core stores points. To index objects with extent, insert whatever representative point you choose. For rectangles you can insert centers or build an AABB tree separately.
+
+**Threading**
+Use one tree per thread if you need heavy parallel inserts from Python.
+
+## 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-0.6.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastquadtree-0.6.1.dist-info/METADATA,sha256=ttnNs9M-mAPdUlOLj23Bq1Ewa_FwxB_pZDQevu3k1Ho,10474
+fastquadtree-0.6.1.dist-info/WHEEL,sha256=lf0-jsOnQyGyURv7tfSV1sL9iSHJ1fDLj4bvJhUjCEA,129
+fastquadtree-0.6.1.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
+fastquadtree/__init__.py,sha256=1hCXNpz85X_UC4JqKj4AseFe0HNMM6yFWH3r8rNgX9U,12054
+fastquadtree/__init__.pyi,sha256=NkLrhMy9HkcqdeEfmK6D9c01w-chiNope7DA4PyTeNQ,1992
+fastquadtree/_bimap.py,sha256=pWY4O4BmOa78r4MnBMfpb-hYZ222U8mEMy4pnosgXLQ,3290
+fastquadtree/_item.py,sha256=9Tk4wUZLFsjIhWALJ9xGW4bknvU_xfy2Na3ixWxh_xI,509
+fastquadtree/_native.abi3.so,sha256=Mcpf2l9wI-8H5JuAMq2fVnfDl_Il6AS0jexV32tOnjk,447880
+fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastquadtree-0.6.1.dist-info/RECORD,,

fastquadtree-0.6.1.dist-info/WHEEL

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

fastquadtree-0.6.1.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.