fastquadtree 2.0.0__tar.gz → 2.0.2__tar.gz

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/Cargo.lock

@@ -30,7 +30,7 @@ dependencies = [
 
 [[package]]
 name = "fastquadtree"
-version = "2.0.0"
+version = "2.0.2"
 dependencies = [
  "bincode",
  "num-traits",

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "2.0.0"
+version = "2.0.2"
 edition = "2021"
 readme = "README.md"
 

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 2.0.0
+Version: 2.0.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -80,11 +80,6 @@ Rust-optimized quadtree with a clean Python 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
@@ -98,6 +93,17 @@ from fastquadtree import RectQuadTreeObjects  # Bounding box handling with objec
 from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (~6.5x faster while keeping the same API)
 ```
 
+
+## Quickstart
+
+```python
+from fastquadtree import QuadTree
+
+qt = QuadTree((0, 0, 1000, 1000), 16)  # bounds and capacity
+qt.insert((100, 200), id_=1)  # insert point with ID 1
+print(qt.query((0, 0, 500, 500)))  # gets all points in that area: [(1, 100.0, 200.0)]
+```
+[See the quickstart guide](https://elan456.github.io/fastquadtree/quickstart/) or the [interactive demos](https://elan456.github.io/fastquadtree/runnables/) for more details.
 ## Benchmarks
 
 fastquadtree **outperforms** all other quadtree Python packages, including the Rtree spatial index.
@@ -113,20 +119,23 @@ fastquadtree **outperforms** all other quadtree Python packages, including the R
 
 | Library | Build (s) | Query (s) | Total (s) | Speed vs PyQtree |
 |---|---:|---:|---:|---:|
-| fastquadtree | 0.063 | 0.026 | 0.089 | 48.99× |
-| Shapely STRtree | 0.314 | 0.178 | 0.492 | 8.90× |
-| fastquadtree (obj tracking) | 0.388 | 0.244 | 0.632 | 6.93× |
-| nontree-QuadTree | 1.180 | 1.287 | 2.467 | 1.77× |
-| Rtree        | 1.905 | 0.622 | 2.527 | 1.73× |
-| e-pyquadtree | 2.083 | 1.479 | 3.562 | 1.23× |
-| quads        | 3.058 | 1.140 | 4.198 | 1.04× |
-| PyQtree      | 3.775 | 0.603 | 4.378 | 1.00× |
+| fastquadtree (np)[^fqtnp] | 0.057 | 0.021 | 0.078 | 54.45× |
+| fastquadtree[^fqt] | 0.060 | 0.189 | 0.249 | 17.04× |
+| Shapely STRtree[^npreturn] | 0.321 | 0.196 | 0.517 | 8.21× |
+| fastquadtree (obj tracking)[^fqto] | 0.437 | 0.239 | 0.675 | 6.28× |
+| Rtree        | 1.796 | 0.561 | 2.357 | 1.80× |
+| nontree-QuadTree | 1.275 | 1.272 | 2.547 | 1.67× |
+| e-pyquadtree | 2.144 | 1.507 | 3.650 | 1.16× |
+| quads        | 3.001 | 1.171 | 4.172 | 1.02× |
+| PyQtree      | 3.677 | 0.565 | 4.242 | 1.00× |
+
+[^fqtnp]: Uses `query_np` for Numpy array return values rather than Python lists.  
+[^fqt]: Uses standard `query` method returning Python lists.  
+[^npreturn]: Uses Shapely STRtree with Numpy array points and returns.  
+[^fqto]: Uses QuadTreeObjects with object association.  
 
 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/)
@@ -170,7 +179,8 @@ For object tracking, use `QuadTreeObjects` instead. See the [docs](https://elan4
 ![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.
+You can toggle between fastquadtree, pyqtree, and brute-force mode to see the performance difference.
+I typically see an FPS of ~70 with fastquadtree, ~25 with pyqtree, and <1 FPS with brute-force on my machine with 1500 balls. 
 
 See the [runnables guide](https://elan456.github.io/fastquadtree/runnables/) for setup instructions.
 

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/README.md

@@ -39,11 +39,6 @@ Rust-optimized quadtree with a clean Python 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
@@ -57,6 +52,17 @@ from fastquadtree import RectQuadTreeObjects  # Bounding box handling with objec
 from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (~6.5x faster while keeping the same API)
 ```
 
+
+## Quickstart
+
+```python
+from fastquadtree import QuadTree
+
+qt = QuadTree((0, 0, 1000, 1000), 16)  # bounds and capacity
+qt.insert((100, 200), id_=1)  # insert point with ID 1
+print(qt.query((0, 0, 500, 500)))  # gets all points in that area: [(1, 100.0, 200.0)]
+```
+[See the quickstart guide](https://elan456.github.io/fastquadtree/quickstart/) or the [interactive demos](https://elan456.github.io/fastquadtree/runnables/) for more details.
 ## Benchmarks
 
 fastquadtree **outperforms** all other quadtree Python packages, including the Rtree spatial index.
@@ -72,20 +78,23 @@ fastquadtree **outperforms** all other quadtree Python packages, including the R
 
 | Library | Build (s) | Query (s) | Total (s) | Speed vs PyQtree |
 |---|---:|---:|---:|---:|
-| fastquadtree | 0.063 | 0.026 | 0.089 | 48.99× |
-| Shapely STRtree | 0.314 | 0.178 | 0.492 | 8.90× |
-| fastquadtree (obj tracking) | 0.388 | 0.244 | 0.632 | 6.93× |
-| nontree-QuadTree | 1.180 | 1.287 | 2.467 | 1.77× |
-| Rtree        | 1.905 | 0.622 | 2.527 | 1.73× |
-| e-pyquadtree | 2.083 | 1.479 | 3.562 | 1.23× |
-| quads        | 3.058 | 1.140 | 4.198 | 1.04× |
-| PyQtree      | 3.775 | 0.603 | 4.378 | 1.00× |
+| fastquadtree (np)[^fqtnp] | 0.057 | 0.021 | 0.078 | 54.45× |
+| fastquadtree[^fqt] | 0.060 | 0.189 | 0.249 | 17.04× |
+| Shapely STRtree[^npreturn] | 0.321 | 0.196 | 0.517 | 8.21× |
+| fastquadtree (obj tracking)[^fqto] | 0.437 | 0.239 | 0.675 | 6.28× |
+| Rtree        | 1.796 | 0.561 | 2.357 | 1.80× |
+| nontree-QuadTree | 1.275 | 1.272 | 2.547 | 1.67× |
+| e-pyquadtree | 2.144 | 1.507 | 3.650 | 1.16× |
+| quads        | 3.001 | 1.171 | 4.172 | 1.02× |
+| PyQtree      | 3.677 | 0.565 | 4.242 | 1.00× |
+
+[^fqtnp]: Uses `query_np` for Numpy array return values rather than Python lists.  
+[^fqt]: Uses standard `query` method returning Python lists.  
+[^npreturn]: Uses Shapely STRtree with Numpy array points and returns.  
+[^fqto]: Uses QuadTreeObjects with object association.  
 
 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/)
@@ -129,7 +138,8 @@ For object tracking, use `QuadTreeObjects` instead. See the [docs](https://elan4
 ![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.
+You can toggle between fastquadtree, pyqtree, and brute-force mode to see the performance difference.
+I typically see an FPS of ~70 with fastquadtree, ~25 with pyqtree, and <1 FPS with brute-force on my machine with 1500 balls. 
 
 See the [runnables guide](https://elan456.github.io/fastquadtree/runnables/) for setup instructions.
 

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/benchmarks/quadtree_bench/engines.py

@@ -100,7 +100,7 @@ def _create_pyqtree_engine(
 def _create_fastquadtree_np_engine(
     bounds: Tuple[int, int, int, int], max_points: int, max_depth: int
 ) -> Engine:
-    """Create engine adapter for fastquadtree."""
+    """Create engine adapter for fastquadtree but queries are returned as numpy arrays instead of Python lists."""
 
     def build(points):
         qt = FQTQuadTree(bounds, max_points, max_depth=max_depth)
@@ -111,9 +111,31 @@ def _create_fastquadtree_np_engine(
         for q in queries:
             _ = qt.query_np(q)
 
+    return Engine(
+        "fastquadtree (np)",
+        "#e55100",
+        build,
+        query,  # display name  # color (orange)
+    )
+
+
+def _create_fastquadtree_engine(
+    bounds: Tuple[int, int, int, int], max_points: int, max_depth: int
+) -> Engine:
+    """Create engine adapter for fastquadtree."""
+
+    def build(points):
+        qt = FQTQuadTree(bounds, max_points, max_depth=max_depth)
+        qt.insert_many(points)
+        return qt
+
+    def query(qt, queries):
+        for q in queries:
+            _ = qt.query(q)
+
     return Engine(
         "fastquadtree",
-        "#ff7f0e",
+        "#ff9500",
         build,
         query,  # display name  # color (orange)
     )
@@ -134,8 +156,8 @@ def _create_fastquadtree_items_engine(
             _ = qt.query(q)
 
     return Engine(
-        "fastquadtree (obj tracking)",
-        "#ffb347",
+        "fastquadtree (objs)",
+        "#ffc107",
         build,
         query,  # display name  # color (orange)
     )
@@ -314,7 +336,10 @@ def get_engines(
     """
     # Always available engines
     engines = {
-        "fastquadtree": _create_fastquadtree_np_engine(bounds, max_points, max_depth),
+        "fastquadtree (np)": _create_fastquadtree_np_engine(
+            bounds, max_points, max_depth
+        ),
+        "fastquadtree": _create_fastquadtree_engine(bounds, max_points, max_depth),
         "fastquadtree (obj tracking)": _create_fastquadtree_items_engine(
             bounds, max_points, max_depth
         ),

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/benchmarks/quadtree_bench/plotting.py

@@ -61,23 +61,27 @@ class PlotManager:
 
         # Update layout
         fig.update_layout(
-            title=(
-                f"Tree build and query benchmarks "
-                f"(Max Depth {self.config.max_depth}, "
-                f"Capacity {self.config.max_points}, "
-                f"{self.config.repeats}x median, "
-                f"{self.config.n_queries} queries)"
-            ),
+            title={
+                "text": (
+                    f"Tree build and query benchmarks "
+                    f"(Max Depth {self.config.max_depth}, "
+                    f"Capacity {self.config.max_points}, "
+                    f"{self.config.repeats}x median, "
+                    f"{self.config.n_queries} queries)"
+                ),
+                "y": 0.98,
+                "x": 0.5,
+                "xanchor": "center",
+            },
             template="plotly_dark",
             legend={
-                "orientation": "v",
-                "traceorder": "normal",
-                "xanchor": "left",
-                "x": 0,
-                "yanchor": "top",
-                "y": 1,
+                "orientation": "h",
+                "x": 0.5,
+                "xanchor": "center",
+                "y": 1.12,
+                "yanchor": "bottom",
             },
-            margin={"l": 40, "r": 20, "t": 80, "b": 40},
+            margin={"l": 40, "r": 20, "t": 140, "b": 40},  # Increase top margin
             height=520,
         )
 
@@ -93,7 +97,7 @@ class PlotManager:
         )
 
         # Set logarithmic scale for query rate
-        fig.update_yaxes(type="log", row=1, col=2)
+        fig.update_yaxes(type="log", row=1, col=2, tickformat=".0s", dtick=0.25)
 
         for name in list(self.results["query_rate"].keys()):
             # Determine color
@@ -136,16 +140,21 @@ class PlotManager:
 
         # Update layout
         fig.update_layout(
-            title="Throughput",
+            title={
+                "text": "Throughput",
+                "y": 0.98,  # Push title to very top
+                "x": 0.5,
+                "xanchor": "center",
+            },
             template="plotly_dark",
             legend={
                 "orientation": "h",
-                "x": 0,
-                "xanchor": "left",
-                "y": 1.08,  # above the subplots
+                "x": 0.5,
+                "xanchor": "center",
+                "y": 1.15,  # Move legend higher
                 "yanchor": "bottom",
             },
-            margin={"l": 60, "r": 40, "t": 120, "b": 40},
+            margin={"l": 60, "r": 40, "t": 140, "b": 40},  # Increase top margin
             height=480,
         )
 

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/benchmarks/quadtree_bench/runner.py

@@ -35,7 +35,7 @@ class BenchmarkConfig:
 
     def __post_init__(self):
         """Generate experiment point sizes."""
-        self.experiments = [2, 4, 8, 16]
+        self.experiments = [128000]
         while self.experiments[-1] < self.max_experiment_points:
             self.experiments.append(int(self.experiments[-1] * 2))
         self.experiments[-1] = min(self.experiments[-1], self.max_experiment_points)

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/docs/benchmark.md

@@ -16,14 +16,23 @@ Quadtrees are the focus of the benchmark, but Rtrees are included for reference.
 
 | Library | Build (s) | Query (s) | Total (s) | Speed vs PyQtree |
 |---|---:|---:|---:|---:|
-| fastquadtree | 0.063 | 0.026 | 0.089 | 48.99× |
-| Shapely STRtree | 0.314 | 0.178 | 0.492 | 8.90× |
-| fastquadtree (obj tracking) | 0.388 | 0.244 | 0.632 | 6.93× |
-| nontree-QuadTree | 1.180 | 1.287 | 2.467 | 1.77× |
-| Rtree        | 1.905 | 0.622 | 2.527 | 1.73× |
-| e-pyquadtree | 2.083 | 1.479 | 3.562 | 1.23× |
-| quads        | 3.058 | 1.140 | 4.198 | 1.04× |
-| PyQtree      | 3.775 | 0.603 | 4.378 | 1.00× |
+| fastquadtree (np)[^fqtnp] | 0.057 | 0.021 | 0.078 | 54.45× |
+| fastquadtree[^fqt] | 0.060 | 0.189 | 0.249 | 17.04× |
+| Shapely STRtree[^npreturn] | 0.321 | 0.196 | 0.517 | 8.21× |
+| fastquadtree (obj tracking)[^fqto] | 0.437 | 0.239 | 0.675 | 6.28× |
+| Rtree        | 1.796 | 0.561 | 2.357 | 1.80× |
+| nontree-QuadTree | 1.275 | 1.272 | 2.547 | 1.67× |
+| e-pyquadtree | 2.144 | 1.507 | 3.650 | 1.16× |
+| quads        | 3.001 | 1.171 | 4.172 | 1.02× |
+| PyQtree      | 3.677 | 0.565 | 4.242 | 1.00× |
+
+[^fqtnp]: Uses `query_np` for Numpy array return values rather than Python lists.
+[^fqt]: Uses standard `query` method returning Python lists.
+[^npreturn]: Uses Shapely STRtree with Numpy array points and returns.
+[^fqto]: Uses QuadTreeObjects with object association.
+
+
+
 
 #### Benchmark Configuration
 | Parameter | Value |

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/docs/runnables.md

@@ -1,6 +1,26 @@
 
 # Runnable Examples
 
+After cloning the repository, you can run the following examples to see how fastquadtree works in practice.
+
+## Environment Setup
+
+### Clone the repo
+```bash
+git clone https://github.com/Elan456/fastquadtree.git
+cd fastquadtree
+```
+
+### Create and activate a virtual environment, install dependencies
+This step can be skipped if you already have a suitable environment.
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+pip install -e .
+maturin develop --release
+pip install -r interactive/requirements.txt
+```
+
 ## 1. Interactive demo  
 - Add and delete boids with mouse clicks
 - Visualize KNN and range queries
@@ -10,7 +30,6 @@ You can see how the quadtree subdivides as you add points, and validate the accu
 By pressing 1, you can visualize the KNN query for each boid. 
 
 ```bash
-pip install -r interactive/requirements.txt
 python interactive/interactive_v2.py
 ```
 
@@ -24,7 +43,6 @@ If you are creating a game or simulation environment where entities have boundin
 rectangular quadtree to quickly check which entities are intersecting with another. 
 
 ```bash
-pip install -r interactive/requirements.txt
 python interactive/interactive_v2_rect.py
 ```
 
@@ -38,7 +56,6 @@ The ball pit demo shows how quadtrees offer massive performance improvements for
 Rectangular queries are used to find potential collisions, and then precise circle-circle collision checks are performed.
 
 ```bash
-pip install -r interactive/requirements.txt
 python interactive/ball_pit.py
 ```
 

fastquadtree-2.0.2/examples/custom_id_example.py

@@ -0,0 +1,31 @@
+from fastquadtree import QuadTree
+
+
+class Person:
+    def __init__(self, x: float, y: float, name: str):
+        self.x = x
+        self.y = y
+        self.name = name
+
+
+qt = QuadTree((0, 0, 1000, 1000), 16)
+
+people = [
+    Person(100, 200, "Alice"),
+    Person(150, 250, "Bob"),
+    Person(300, 400, "Charlie"),
+]
+
+for idx, person in enumerate(people):
+    qt.insert((person.x, person.y), id_=idx)
+
+# Find people in a specific area
+results = qt.query((90, 190, 200, 300))
+for id_, x, y in results:
+    person = people[id_]
+    print(f"Found {person.name} at ({x}, {y})")
+
+
+# Output:
+# Found Alice at (100.0, 200.0)
+# Found Bob at (150.0, 250.0)

fastquadtree-2.0.2/examples/object_tracking_example.py

@@ -0,0 +1,30 @@
+from fastquadtree import QuadTreeObjects
+
+
+class Person:
+    def __init__(self, x: float, y: float, name: str):
+        self.x = x
+        self.y = y
+        self.name = name
+
+
+qt = QuadTreeObjects((0, 0, 1000, 1000), 16)
+
+people = [
+    Person(100, 200, "Alice"),
+    Person(150, 250, "Bob"),
+    Person(300, 400, "Charlie"),
+]
+
+for person in people:
+    qt.insert((person.x, person.y), obj=person)
+
+# Find people in a specific area
+results = qt.query((90, 190, 200, 300))
+for item in results:
+    print(f"Found {item.obj.name} at ({item.x}, {item.y})")
+
+
+# Output:
+# Found Alice at (100, 200)
+# Found Bob at (150, 250)

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/interactive/ballpit.py

@@ -1,12 +1,13 @@
 import math
 import random
+import time
 from typing import Iterable, List, Set, Tuple
 
 import pygame
 from pyqtree import Index as PyQIndex
 
 # Spatial backends -------------------------------------------------------------
-from fastquadtree import QuadTreeObjects
+from fastquadtree import Quadtree
 
 # ---------------------------- Ball object ---------------------------- #
 
@@ -130,23 +131,23 @@ class FastQTIndex(SpatialBase):
         self.width = width
         self.height = height
         self.capacity = capacity
-        self.qt = QuadTreeObjects((0, 0, width, height), capacity)
+        self.qt = Quadtree((0, 0, width, height), capacity)
 
     def rebuild(self, balls: List[Ball], width: int, height: int) -> None:
         if width != self.width or height != self.height:
             self.width, self.height = width, height
-            self.qt = QuadTreeObjects((0, 0, width, height), self.capacity)
+            self.qt.clear()
         else:
             self.qt.clear()
-        for b in balls:
-            self.qt.insert((b.x, b.y), obj=b)
 
-    def neighbors(self, b: Ball) -> Iterable[Ball]:
+        self.qt.insert_many([(b.x, b.y) for b in balls])
+
+    def neighbors(self, b: Ball, balls: List[Ball]) -> Iterable[Ball]:
         r2 = 2 * b.r
         min_x, min_y, max_x, max_y = b.x - r2, b.y - r2, b.x + r2, b.y + r2
         neighbors = self.qt.query((min_x, min_y, max_x, max_y))
         for it in neighbors:
-            other = it.obj
+            other = balls[it[0]]
             if other is not None and other is not b:
                 yield other
 
@@ -259,7 +260,7 @@ class BallPit:
     def _backend(self) -> SpatialBase:
         return self.backends[self.mode]
 
-    def update(self, dt: float):
+    def update(self, dt: float) -> tuple[float, float]:
         # 1) Integrate motion
         ax, ay = 0.0, 0.0
         for b in self.balls:
@@ -268,13 +269,26 @@ class BallPit:
 
         # 2) Rebuild spatial index
         backend = self._backend()
+        start = time.perf_counter()
         backend.rebuild(self.balls, self.width, self.height)
+        end = time.perf_counter()
+
+        tree_build_time = end - start
+
+        total_neighbor_collection_time = 0.0
 
         # 3) Neighborhood checks with dedup on object id pairs
         self.pair_checks = 0
         processed: Set[Tuple[int, int]] = set()
         for a in self.balls:
-            for other in backend.neighbors(a):
+            start = time.perf_counter()
+            if self.mode == "fastquadtree":
+                neighbors = backend.neighbors(a, self.balls)  # type: ignore
+            else:
+                neighbors = backend.neighbors(a)
+            end = time.perf_counter()
+            total_neighbor_collection_time += end - start
+            for other in neighbors:
                 a_id = id(a)
                 o_id = id(other)
                 key = (a_id, o_id) if a_id < o_id else (o_id, a_id)
@@ -283,11 +297,11 @@ class BallPit:
                 processed.add(key)
                 self.pair_checks += 1
                 resolve_ball_ball(a, other)
+        return (total_neighbor_collection_time, tree_build_time)
 
-        # 4) Some backends benefit from post-resolution rebuild for next frame
-        backend.rebuild(self.balls, self.width, self.height)
-
-    def draw(self, fps: float):
+    def draw(
+        self, fps: float, total_neighbor_collection_time: float, tree_build_time: float
+    ):
         for ball in self.balls:
             ball.draw(self.screen)
 
@@ -295,6 +309,8 @@ class BallPit:
         font = pygame.font.SysFont(None, 20)
         hud_lines = [
             f"FPS: {fps:.1f}",
+            f"Build time: {tree_build_time * 1000:.2f} ms",
+            f"Query time: {total_neighbor_collection_time * 1000:.2f} ms",
             f"Mode: {self.mode} (Tab to cycle, 1/2/3 to select)",
             f"Balls: {len(self.balls)}",
             f"Pair checks this frame: {self.pair_checks}",
@@ -373,7 +389,7 @@ def main():
                 )
                 ball_pit.add_ball(x, y, radius=r, color=color)
 
-        ball_pit.update(dt)
+        stats = ball_pit.update(dt)
 
         screen.fill((255, 255, 255))
         fps = clock.get_fps()
@@ -387,7 +403,7 @@ def main():
             + fps
         ) / metrics[ball_pit.mode]["count"]
 
-        ball_pit.draw(fps)
+        ball_pit.draw(fps, stats[0], stats[1])
         pygame.display.flip()
 
     pygame.quit()

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/pysrc/fastquadtree/__init__.py

@@ -19,13 +19,23 @@ from .point_quadtree_objects import QuadTreeObjects
 from .rect_quadtree import RectQuadTree
 from .rect_quadtree_objects import RectQuadTreeObjects
 
+# Allow lowercase version of quadtree for convenience
+Quadtree = QuadTree
+QuadtreeObjects = QuadTreeObjects
+Rectquadtree = RectQuadTree
+RectquadtreeObjects = RectQuadTreeObjects
+
 __all__ = [
     "InsertResult",
     "Item",
     "PointItem",
     "QuadTree",
     "QuadTreeObjects",
+    "Quadtree",
+    "QuadtreeObjects",
     "RectItem",
     "RectQuadTree",
     "RectQuadTreeObjects",
+    "Rectquadtree",
+    "RectquadtreeObjects",
 ]

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/pysrc/fastquadtree/_base_quadtree.py

@@ -116,7 +116,8 @@ class _BaseQuadTree(Generic[G], ABC):
 
     def insert_many(self, geoms: list[G]) -> InsertResult:
         """
-        Bulk insert geometries with auto-assigned contiguous IDs.
+        Bulk insert geometries with auto-assigned contiguous IDs. <br>
+        IDs start at 0 and increment by 1, so they will be aligned with the indexes of the input list if the tree started empty. <br>
 
         Custom IDs are not supported for bulk insertion. Use single insert()
         calls if you need custom IDs.
@@ -130,6 +131,16 @@ class _BaseQuadTree(Generic[G], ABC):
         Raises:
             TypeError: If geoms is a NumPy array (use insert_many_np instead).
             ValueError: If any geometry is outside bounds.
+
+        Example:
+            ```python
+            # Point Quadtree Example:
+
+            points = [(1.0, 2.0), (3.0, 4.0), (5.0, 6.0)]
+            qt = QuadTree(bounds=(0.0, 0.0, 10.0, 10.0), capacity=16)
+            result = qt.insert_many(points) # Each point's ID corresponds to its index in the points list
+            print(result)  # InsertResult(count=3, start_id=0, end_id=2)
+            ```
         """
         if _is_np_array(geoms):
             raise TypeError(

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/pysrc/fastquadtree/_item.py

@@ -24,10 +24,10 @@ class Item(Generic[G]):
 
     __slots__ = ("geom", "id_", "obj")
 
-    def __init__(self, id_: int, geom: G, obj: Any | None = None):
+    def __init__(self, id_: int, geom: G, obj: Any = None):
         self.id_: int = id_
         self.geom: G = geom
-        self.obj: Any | None = obj
+        self.obj: Any = obj
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -76,7 +76,7 @@ class PointItem(Item[Point]):
 
     __slots__ = ("x", "y")
 
-    def __init__(self, id_: int, geom: Point, obj: Any | None = None):
+    def __init__(self, id_: int, geom: Point, obj: Any = None):
         super().__init__(id_, geom, obj)
         self.x, self.y = geom
 
@@ -100,6 +100,6 @@ class RectItem(Item[Bounds]):
 
     __slots__ = ("max_x", "max_y", "min_x", "min_y")
 
-    def __init__(self, id_: int, geom: Bounds, obj: Any | None = None):
+    def __init__(self, id_: int, geom: Bounds, obj: Any = None):
         super().__init__(id_, geom, obj)
         self.min_x, self.min_y, self.max_x, self.max_y = geom

{fastquadtree-2.0.0 → fastquadtree-2.0.2}/tests/test_python/integration/test_public_api_contracts.py

@@ -13,6 +13,10 @@ def test_public_api_all_exports():
         "RectItem",
         "RectQuadTree",
         "RectQuadTreeObjects",
+        "Quadtree",  # Lowercase added in 2.0.2
+        "QuadtreeObjects",
+        "Rectquadtree",
+        "RectquadtreeObjects",
     ]
     assert sorted(fqt.__all__) == sorted(expected)