fastquadtree 0.7.0__cp38-abi3-win_amd64.whl → 0.8.0__cp38-abi3-win_amd64.whl

fastquadtree/_bimap.py

@@ -1,14 +1,16 @@
 # _bimap.py
 from __future__ import annotations
 
-from typing import Any, Iterable, Iterator
+from typing import Any, Generic, Iterable, Iterator, TypeVar
 
-from ._item import Item
+from ._item import Item  # base class for PointItem and RectItem
 
+TItem = TypeVar("TItem", bound=Item)
 
-class BiMap:
+
+class BiMap(Generic[TItem]):
     """
-    Bidirectional map to the same Item:
+    Bidirectional map to the same Item subtype:
       id -> Item
       obj -> Item  (uses object identity)
 
@@ -20,19 +22,22 @@ class BiMap:
 
     __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] = {}
+    def __init__(
+        self,
+        items: Iterable[TItem] | None = None,
+    ) -> None:
+        self._id_to_item: dict[int, TItem] = {}
+        self._objid_to_item: dict[int, TItem] = {}
         if items:
             for it in items:
                 self.add(it)
 
     # - core -
 
-    def add(self, item: Item) -> None:
+    def add(self, item: TItem) -> None:
         """
         Insert or replace mapping for this Item.
-        Handles conflicts so that both id and obj point to this exact Item.
+        Handles conflicts so both id and obj point to this exact Item.
         """
         id_ = item.id_
         obj = item.obj
@@ -55,13 +60,13 @@ class BiMap:
         if obj is not None:
             self._objid_to_item[id(obj)] = item
 
-    def by_id(self, id_: int) -> Item | None:
+    def by_id(self, id_: int) -> TItem | None:
         return self._id_to_item.get(id_)
 
-    def by_obj(self, obj: Any) -> Item | None:
+    def by_obj(self, obj: Any) -> TItem | None:
         return self._objid_to_item.get(id(obj))
 
-    def pop_id(self, id_: int) -> Item | None:
+    def pop_id(self, id_: int) -> TItem | None:
         it = self._id_to_item.pop(id_, None)
         if it is not None:
             obj = it.obj
@@ -69,25 +74,20 @@ class BiMap:
                 self._objid_to_item.pop(id(obj), None)
         return it
 
-    def pop_obj(self, obj: Any) -> Item | None:
+    def pop_obj(self, obj: Any) -> TItem | 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:
+    def pop_item(self, item: TItem) -> TItem | 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
+        removed = self._id_to_item.pop(item.id_, None)
         obj = item.obj
         if obj is not None:
             self._objid_to_item.pop(id(obj), None)
-            removed = removed or item
         return removed
 
     # - convenience -
@@ -105,8 +105,8 @@ class BiMap:
     def contains_obj(self, obj: Any) -> bool:
         return id(obj) in self._objid_to_item
 
-    def items_by_id(self) -> Iterator[tuple[int, Item]]:
+    def items_by_id(self) -> Iterator[tuple[int, TItem]]:
         return iter(self._id_to_item.items())
 
-    def items(self) -> Iterator[Item]:
+    def items(self) -> Iterator[TItem]:
         return iter(self._id_to_item.values())

fastquadtree/_item.py

@@ -1,7 +1,13 @@
 # item.py
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Tuple
+
+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)."""
 
 
 class Item:
@@ -10,15 +16,37 @@ class Item:
 
     Attributes:
         id_: Integer identifier.
-        x: X coordinate.
-        y: Y coordinate.
+        geom: The geometry, either a Point or Rectangle Bounds.
         obj: The attached Python object if available, else None.
     """
 
-    __slots__ = ("id_", "obj", "x", "y")
+    __slots__ = ("geom", "id_", "obj")
 
-    def __init__(self, id_: int, x: float, y: float, obj: Any | None = None):
+    def __init__(self, id_: int, geom: Point | Bounds, obj: Any | None = None):
         self.id_ = id_
-        self.x = x
-        self.y = y
+        self.geom = geom
         self.obj = obj
+
+
+class PointItem(Item):
+    """
+    Lightweight point item wrapper for tracking and as_items results.
+    """
+
+    __slots__ = ("geom", "id_", "obj", "x", "y")
+
+    def __init__(self, id_: int, geom: Point, obj: Any | None = None):
+        super().__init__(id_, geom, obj)
+        self.x, self.y = geom
+
+
+class RectItem(Item):
+    """
+    Lightweight rectangle item wrapper for tracking and as_items results.
+    """
+
+    __slots__ = ("geom", "id_", "max_x", "max_y", "min_x", "min_y", "obj")
+
+    def __init__(self, id_: int, geom: Bounds, obj: Any | None = None):
+        super().__init__(id_, geom, obj)
+        self.min_x, self.min_y, self.max_x, self.max_y = geom

fastquadtree/point_quadtree.py

@@ -0,0 +1,161 @@
+# point_quadtree.py
+from __future__ import annotations
+
+from typing import Any, Literal, Tuple, overload
+
+from ._base_quadtree import Bounds, _BaseQuadTree
+from ._item import Point, PointItem
+from ._native import QuadTree as _RustQuadTree  # native point tree
+
+_IdCoord = Tuple[int, float, float]
+
+
+class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
+    """
+    Point version of the quadtree. All geometries are 2D points (x, 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.
+        start_id: Starting auto-assigned id when you omit id on insert.
+
+    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,
+        start_id: int = 1,
+    ):
+        super().__init__(
+            bounds,
+            capacity,
+            max_depth=max_depth,
+            track_objects=track_objects,
+            start_id=start_id,
+        )
+
+    @overload
+    def query(
+        self, rect: Bounds, *, as_items: Literal[False] = ...
+    ) -> list[_IdCoord]: ...
+    @overload
+    def query(self, rect: Bounds, *, as_items: Literal[True]) -> list[PointItem]: ...
+    def query(
+        self, rect: Bounds, *, as_items: bool = False
+    ) -> list[PointItem] | list[_IdCoord]:
+        """
+        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[PointItem] = []
+        for id_, _x, _y in raw:
+            it = self._items.by_id(id_)
+            if it is None:
+                raise RuntimeError(
+                    f"Internal error: id {id_} present in native tree but missing from tracker."
+                )
+            out.append(it)
+        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]
+    ) -> PointItem | None: ...
+    def nearest_neighbor(
+        self, xy: Point, *, as_item: bool = False
+    ) -> PointItem | _IdCoord | None:
+        """
+        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
+        it = self._items.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[_IdCoord]: ...
+    @overload
+    def nearest_neighbors(
+        self, xy: Point, k: int, *, as_items: Literal[True]
+    ) -> list[PointItem]: ...
+    def nearest_neighbors(self, xy: Point, k: int, *, as_items: bool = False):
+        """
+        Return the k nearest neighbors to the query point in order of increasing distance.
+
+        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, x, y) tuples.
+            If as_items is True: list of Item objects.
+        """
+        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[PointItem] = []
+        for id_, _x, _y in raw:
+            it = self._items.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:
+        if max_depth is None:
+            return _RustQuadTree(bounds, capacity)
+        return _RustQuadTree(bounds, capacity, max_depth=max_depth)
+
+    def _make_item(self, id_: int, geom: Point, obj: Any | None) -> PointItem:
+        return PointItem(id_, geom, obj)

fastquadtree/rect_quadtree.py

@@ -0,0 +1,98 @@
+# rect_quadtree.py
+from __future__ import annotations
+
+from typing import Any, Literal, Tuple, overload
+
+from ._base_quadtree import Bounds, _BaseQuadTree
+from ._item import RectItem
+from ._native import RectQuadTree as _RustRectQuadTree  # native rect tree
+
+_IdRect = Tuple[int, float, float, float, float]
+Point = Tuple[float, float]  # only for type hints in docstrings
+
+
+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.
+        start_id: Starting auto-assigned id when you omit id on insert.
+
+    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,
+        start_id: int = 1,
+    ):
+        super().__init__(
+            bounds,
+            capacity,
+            max_depth=max_depth,
+            track_objects=track_objects,
+            start_id=start_id,
+        )
+
+    @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):
+        """
+        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.
+        """
+        raw = self._native.query(rect)
+        if not as_items:
+            return raw
+        if self._items is None:
+            # Build RectItem without objects
+            return [
+                RectItem(id_, (x0, y0, x1, y1), None) for (id_, x0, y0, x1, y1) in raw
+            ]
+        out: list[RectItem] = []
+        for id_, _x0, _y0, _x1, _y1 in raw:
+            it = self._items.by_id(id_)
+            if it is None:
+                raise RuntimeError(
+                    f"Internal error: id {id_} present in native tree but missing from tracker."
+                )
+            out.append(it)
+        return out
+
+    def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
+        if max_depth is None:
+            return _RustRectQuadTree(bounds, capacity)
+        return _RustRectQuadTree(bounds, capacity, max_depth=max_depth)
+
+    def _make_item(self, id_: int, geom: Bounds, obj: Any | None) -> RectItem:
+        return RectItem(id_, geom, obj)

{fastquadtree-0.7.0.dist-info → fastquadtree-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 0.7.0
+Version: 0.8.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -12,8 +12,8 @@ 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: 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'
@@ -23,6 +23,7 @@ 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'
 Provides-Extra: dev
 License-File: LICENSE
 Summary: Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search.
@@ -45,7 +46,7 @@ Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
 
 [![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)
+[![Build](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml/badge.svg)](https://github.com/Elan456/fastquadtree/actions/workflows/release.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/)
@@ -76,7 +77,6 @@ fastquadtree **outperforms** all other quadtree Python packages, including the R
 
 ### 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 |
@@ -89,7 +89,7 @@ fastquadtree **outperforms** all other quadtree Python packages, including the R
 | PyQtree      | 1.492 | 0.263 | 1.755 | 1.00× |
 | quads        | 1.407 | 0.484 | 1.890 | 0.93× |
 
-#### Benchmark Configuration
+### Benchmark Configuration
 | Parameter | Value |
 |---|---:|
 | Bounds | (0, 0, 1000, 1000) |
@@ -97,11 +97,13 @@ fastquadtree **outperforms** all other quadtree Python packages, including the R
 | Max depth | 16 |
 | Queries per experiment | 500 |
 
+See the [benchmark section](https://elan456.github.io/fastquadtree/benchmark/) for details.
+
 ## Install
 
 ```bash
 pip install fastquadtree
-````
+```
 
 If you are developing locally:
 
@@ -111,77 +113,11 @@ 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
-```
+[See the quickstart guide](https://elan456.github.io/fastquadtree/quickstart/)
 
 ## API
 
-[Full api for QuadTree](https://elan456.github.io/fastquadtree/api/quadtree/)
+[See the full API](https://elan456.github.io/fastquadtree/api/quadtree/)
 
 ### `QuadTree(bounds, capacity, max_depth=None, track_objects=False, start_id=1)`
 
@@ -191,38 +127,17 @@ qt.attach(123, my_object)  # binds object to id 123
 * `track_objects` — if `True`, the wrapper maintains an id → object map for convenience.
 * `start_id` — starting value for auto-assigned ids
 
-### Core Methods
+### Key Methods
 
 - `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)`
-
-- `clear(*, reset_ids=False) -> None`
-
-- `attach(id, obj) -> None (requires track_objects=True)`
-
-- `count_items() -> int`
-
-- `get(id) -> object | None`
-
-- `get_all_rectangles() -> list[tuple] (for visualization)`
-
-- `get_all_objects() -> list[object] (requires track_objects=True)`
-
-### `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
+There are more methods and object tracking versions in the [docs](https://elan456.github.io/fastquadtree/api/quadtree/).
 
 ### Geometric conventions
 
@@ -236,52 +151,8 @@ qt.attach(123, my_object)  # binds object to id 123
 * 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 only maintains an ID -> Obj map only if the quadtree was constructed with `track_objects=True`. If you don't need it, leave it off for best performance. Look at the [Native vs Shim Benchmark](#native-vs-shim-benchmark) below for details.
-
-
-### 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 
-```
-
-Check the CLI arguments for the cross-library benchmark in `benchmarks/quadtree_bench/main.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
-```
+* 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
 
@@ -290,10 +161,7 @@ python interactive/interactive_v2.py
 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.
 
-```bash
-pip install -r interactive/requirements.txt
-python interactive/ball_pit.py
-```
+See the [runnables guide](https://elan456.github.io/fastquadtree/runnables/) for setup instructions.
 
 ## FAQ
 
@@ -304,7 +172,7 @@ Allowed. For k-nearest, duplicates are de-duplicated by id. For range queries yo
 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.
+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.
 
 ## License