fastquadtree 0.6.1__tar.gz → 0.7.0__tar.gz

fastquadtree-0.7.0/.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+# .github/workflows/docs.yml
+name: Docs
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.11' }
+      - run: pip install -e '.[dev]'
+      - run: mkdocs gh-deploy --force

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/Cargo.lock

@@ -22,7 +22,7 @@ checksum = "2fd1289c04a9ea8cb22300a459a72a385d7c73d3259e2ed7dcb2af674838cfa9"
 
 [[package]]
 name = "fastquadtree"
-version = "0.6.1"
+version = "0.7.0"
 dependencies = [
  "pyo3",
  "smallvec",

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/Cargo.toml

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

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 0.6.1
+Version: 0.7.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -17,6 +17,12 @@ 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'
+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'
 Provides-Extra: dev
 License-File: LICENSE
 Summary: Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search.
@@ -26,10 +32,12 @@ 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: Documentation, https://elan456.github.io/fastquadtree/
 Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
 
 # fastquadtree
 
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://elan456.github.io/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)
@@ -51,6 +59,8 @@ Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
 
 Rust-optimized quadtree with a simple Python API.
 
+👉 **Docs:** https://elan456.github.io/fastquadtree/
+
 - Python package: **`fastquadtree`**
 - Python ≥ 3.8
 - Import path: `from fastquadtree import QuadTree`
@@ -171,6 +181,8 @@ qt.attach(123, my_object)  # binds object to id 123
 
 ## API
 
+[Full api for QuadTree](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
@@ -181,8 +193,6 @@ qt.attach(123, my_object)  # binds object to id 123
 
 ### 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`
@@ -197,6 +207,8 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 
 - `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`
@@ -205,6 +217,8 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 
 - `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
@@ -222,7 +236,7 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 * 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.
+* 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
@@ -259,6 +273,8 @@ 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.
 
@@ -267,7 +283,17 @@ 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`.
+### 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.
+
+```bash
+pip install -r interactive/requirements.txt
+python interactive/ball_pit.py
+```
 
 ## FAQ
 
@@ -280,9 +306,6 @@ Yes! Use `delete(id, xy)` to remove specific items. You must provide both the ID
 **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`.

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/README.md

@@ -1,5 +1,6 @@
 # fastquadtree
 
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://elan456.github.io/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)
@@ -21,6 +22,8 @@
 
 Rust-optimized quadtree with a simple Python API.
 
+👉 **Docs:** https://elan456.github.io/fastquadtree/
+
 - Python package: **`fastquadtree`**
 - Python ≥ 3.8
 - Import path: `from fastquadtree import QuadTree`
@@ -141,6 +144,8 @@ qt.attach(123, my_object)  # binds object to id 123
 
 ## API
 
+[Full api for QuadTree](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
@@ -151,8 +156,6 @@ qt.attach(123, my_object)  # binds object to id 123
 
 ### 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`
@@ -167,6 +170,8 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 
 - `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`
@@ -175,6 +180,8 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 
 - `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
@@ -192,7 +199,7 @@ Full docs are in the docstrings of the [Python Shim](pysrc/fastquadtree/__init__
 * 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.
+* 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
@@ -229,6 +236,8 @@ 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.
 
@@ -237,7 +246,17 @@ 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`.
+### 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.
+
+```bash
+pip install -r interactive/requirements.txt
+python interactive/ball_pit.py
+```
 
 ## FAQ
 
@@ -250,9 +269,6 @@ Yes! Use `delete(id, xy)` to remove specific items. You must provide both the ID
 **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`.

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/benchmarks/quadtree_bench/runner.py

@@ -6,6 +6,7 @@ and result collection for performance analysis.
 """
 
 import gc
+import json
 import math
 import random
 import statistics as stats
@@ -16,6 +17,7 @@ from typing import Any, Dict, List, Tuple
 from tqdm import tqdm
 
 from .engines import Engine
+from .system_info_collector import collect_system_info
 
 
 @dataclass
@@ -315,3 +317,9 @@ class BenchmarkRunner:
         print(f"| Max points per node | {config.max_points} |")
         print(f"| Max depth | {config.max_depth} |")
         print(f"| Queries per experiment | {config.n_queries} |")
+
+        system_info = collect_system_info()
+        print("#### System Info")
+        print("```json")
+        print(json.dumps(system_info, indent=2))
+        print("```")

fastquadtree-0.7.0/benchmarks/quadtree_bench/system_info_collector.py

@@ -0,0 +1,140 @@
+import contextlib
+import json
+import platform
+from typing import Any, Dict
+
+
+def safe_import(name: str):
+    with contextlib.suppress(ImportError):
+        return __import__(name)
+
+
+def collect_system_info() -> Dict[str, Any]:
+    psutil = safe_import("psutil")
+    cpuinfo = safe_import("cpuinfo")
+    distro = safe_import("distro")
+    gputil = safe_import("GPUtil")
+
+    info = {
+        "os": {
+            "system": platform.system(),
+            "release": platform.release(),
+            "version": platform.version(),
+            "machine": platform.machine(),
+        },
+        "python": {
+            "implementation": platform.python_implementation(),
+            "version": platform.python_version(),
+        },
+        "cpu": {},
+        "memory_gb": None,
+        "gpus": [],
+    }
+
+    # CPU and RAM via psutil
+    if psutil:
+        with contextlib.suppress(Exception):
+            info["cpu"]["physical_cores"] = psutil.cpu_count(logical=False)
+            info["cpu"]["logical_cores"] = psutil.cpu_count(logical=True)
+            freq = psutil.cpu_freq()
+            if freq:
+                info["cpu"]["max_freq_mhz"] = getattr(freq, "max", None)
+                info["cpu"]["current_freq_mhz"] = getattr(freq, "current", None)
+            info["memory_gb"] = round(psutil.virtual_memory().total / (1024**3), 1)
+
+    # CPU model via py-cpuinfo
+    if cpuinfo:
+        with contextlib.suppress(Exception):
+            ci = cpuinfo.get_cpu_info()
+            info["cpu"]["model"] = ci.get("brand_raw") or ci.get("brand")
+            if not info["cpu"].get("max_freq_mhz"):
+                hz = ci.get("hz_advertised_friendly") or ci.get("hz_advertised")
+                info["cpu"]["advertised_freq"] = hz
+
+    # Linux distro pretty name
+    if distro and info["os"]["system"] == "Linux":
+        with contextlib.suppress(Exception):
+            info["os"]["distro"] = distro.name(pretty=True)
+
+    # GPUs via GPUtil
+    if gputil:
+        with contextlib.suppress(Exception):
+            for gpu in gputil.getGPUs():
+                info["gpus"].append(
+                    {
+                        "name": gpu.name,
+                        "memory_total_mb": int(gpu.memoryTotal),
+                        "driver": getattr(gpu, "driver", None),
+                        "uuid": getattr(gpu, "uuid", None),
+                    }
+                )
+
+    return info
+
+
+def _fmt_num(x, nd=2):
+    try:
+        return f"{float(x):.{nd}f}"
+    except Exception:  # noqa: BLE001
+        return str(x)
+
+
+def format_system_info_markdown(info: dict) -> str:
+    osd = info.get("os", {})
+    pyd = info.get("python", {})
+    cpu = info.get("cpu", {})
+    gpus = info.get("gpus", []) or []
+    mem = info.get("memory_gb")
+
+    os_name = osd.get("distro") or osd.get("system")
+    kernel = osd.get("release")
+    machine = osd.get("machine")
+    py_impl = pyd.get("implementation")
+    py_ver = pyd.get("version")
+
+    lines = []
+    # Summary bullets
+    lines.append("#### System Info")
+    lines.append(f"- **OS**: {os_name} (Linux {kernel}) on {machine}")
+    lines.append(f"- **Python**: {py_impl} {py_ver}")
+    model = cpu.get("model") or "Unknown CPU"
+    pcores = cpu.get("physical_cores")
+    lcores = cpu.get("logical_cores")
+    maxmhz = cpu.get("max_freq_mhz")
+    curmhz = cpu.get("current_freq_mhz")
+    lines.append(f"- **CPU**: {model}")
+    parts = []
+    if pcores is not None:
+        parts.append(f"physical cores: {pcores}")
+    if lcores is not None:
+        parts.append(f"logical cores: {lcores}")
+    if maxmhz is not None:
+        parts.append(f"max freq: {_fmt_num(maxmhz)} MHz")
+    if curmhz is not None:
+        parts.append(f"current freq: {_fmt_num(curmhz)} MHz")
+    if parts:
+        lines.append("  • " + "  \n  • ".join(parts))
+    if mem is not None:
+        lines.append(f"- **Memory**: {_fmt_num(mem, 1)} GB")
+
+    # GPU section
+    if gpus:
+        lines.append("- **GPUs**:")
+        lines.append("")
+        lines.append("| # | Name | Memory (MB) | Driver | UUID |")
+        lines.append("|-:|------|------------:|:------|:-----|")
+        for i, g in enumerate(gpus):
+            lines.append(
+                f"| {i} | {g.get('name','')} | {g.get('memory_total_mb','')} | "
+                f"{g.get('driver','')} | {g.get('uuid','')} |"
+            )
+    else:
+        lines.append("- **GPUs**: none detected")
+
+    return "\n".join(lines)
+
+
+# Example pretty print
+if __name__ == "__main__":
+    print(json.dumps(collect_system_info(), indent=2))
+    print(format_system_info_markdown(collect_system_info()))

{fastquadtree-0.6.1 → fastquadtree-0.7.0}/benchmarks/requirements.txt

@@ -12,4 +12,10 @@ fastquadtree>=0.1.0
 quads>=1.1.0         # pure-Python quadtree
 nontree>=1.0.5       # pure-Python PR quadtree (TreeMap mode=4)
 rtree>=1.3.0         # R-tree comparator with wheels for Win/macOS/Linux
-shapely>=2.0.0       # STRtree comparator
+shapely>=2.0.0       # STRtree comparator
+
+# For getting system info
+psutil
+py-cpuinfo
+distro
+GPUtil

fastquadtree-0.7.0/docs/api/item.md

@@ -0,0 +1,2 @@
+# fastquadtree.Item
+::: fastquadtree.Item

fastquadtree-0.7.0/docs/api/quadtree.md

@@ -0,0 +1,2 @@
+# fastquadtree.QuadTree
+::: fastquadtree.QuadTree

fastquadtree-0.7.0/docs/index.md

@@ -0,0 +1,4 @@
+# fastquadtree
+
+Rust powered quadtree for Python.  
+See the sidebar for Quickstart and API.

fastquadtree-0.7.0/docs/quickstart.md

@@ -0,0 +1,145 @@
+# Quickstart
+
+Meet **fastquadtree** — a Rust powered spatial index for Python
+
+> TLDR: create a tree, insert points, query ranges or nearest neighbors.
+
+## Installation
+
+```bash
+pip install fastquadtree
+```
+
+---
+
+## 30-second demo
+
+```python
+from fastquadtree import QuadTree
+
+# 1) Make a tree that covers your world
+qt = QuadTree(bounds=(0, 0, 1000, 1000), capacity=20)
+
+# 2) Add some stuff
+a = qt.insert((10, 10))                 # auto id
+b = qt.insert((200, 300))               # auto id
+_ = qt.insert((999, 500), id_=42)       # you can choose ids too
+
+# 3) Ask spatial questions
+print("Range hits:", qt.query((0, 0, 250, 350)))  # -> [(id, x, y), ...]
+
+print("Nearest to (210, 310):", qt.nearest_neighbor((210, 310)))
+
+print("Top 3 near (210, 310):", qt.nearest_neighbors((210, 310), 3))
+
+# 4) Delete by id and exact location
+print("Deleted:", qt.delete(b, (200, 300)))
+print("Count:", qt.count_items())
+```
+
+## Range queries that feel natural
+
+```python
+# Think of it like a camera frustum in 2D
+viewport = (100, 200, 400, 600)
+for id_, x, y in qt.query(viewport):
+    print(f"Visible: id={id_} at ({x:.1f}, {y:.1f})")
+```
+
+Use this for viewport culling, collision broad-phase, spatial filtering, and quick “what is inside this box” checks.
+
+---
+
+## Nearest neighbor for snapping and picking
+
+```python
+cursor = (212, 305)
+hit = qt.nearest_neighbor(cursor)
+if hit:
+    id_, x, y = hit
+    print(f"Closest to cursor is id={id_} at ({x:.1f}, {y:.1f})")
+```
+
+Need more than one neighbor
+
+```python
+for id_, x, y in qt.nearest_neighbors(cursor, k=5):
+    print(id_, x, y)
+```
+
+---
+
+## Track Python objects when you need them
+
+Turn on object tracking to bind your own objects to ids. Delete by object in O(1).
+
+```python
+qt = QuadTree((0, 0, 1000, 1000), capacity=16, track_objects=True)
+
+player = {"name": "Alice", "hp": 100}
+enemy  = {"name": "Boblin", "hp": 60}
+
+pid = qt.insert((50, 50), obj=player)
+eid = qt.insert((80, 60), obj=enemy)
+
+# Query as Item objects for convenience
+items = qt.query((0, 0, 200, 200), as_items=True)
+for it in items:
+    print(it.id, it.x, it.y, it.obj)
+
+# Remove by object identity
+qt.delete_by_object(player)            # True
+```
+
+Tip: leave `track_objects=False` for max speed when you do not need object mapping.
+
+---
+
+## Reset between runs without breaking references
+
+Keep the same `QuadTree` instance alive for UIs or game loops. Wipe contents and optionally reset ids.
+
+```python
+qt.clear(reset_ids=True)  # tree is empty, auto ids start again at 1
+```
+
+---
+
+## Tiny benchmark sketch
+
+```python
+import random, time
+from fastquadtree import QuadTree
+
+N = 200_000
+pts = [(random.random()*1000, random.random()*1000) for _ in range(N)]
+qt = QuadTree((0, 0, 1000, 1000), capacity=32)
+
+t0 = time.perf_counter()
+qt.insert_many_points(pts)
+t1 = time.perf_counter()
+
+hits = qt.query((250, 250, 750, 750))
+t2 = time.perf_counter()
+
+print(f"Build: {(t1-t0):.3f}s  Query: {(t2-t1):.3f}s  Hits: {len(hits)}")
+```
+
+---
+
+## Common patterns
+
+* **Toggle index vs brute force** while debugging performance
+  Keep an array of points for ground truth, wire a flag to switch `qt.query` vs a list comprehension.
+* **Use `capacity` 8 to 64** for most workloads
+  If data is highly skewed, set a `max_depth` to avoid very deep trees.
+* **Do not panic about memory**
+  Rebuilding with `clear()` drops the old native tree as soon as Python releases it.
+
+---
+
+## Next steps
+
+* API reference lives in the sidebar
+* Try the visualizer in `interactive/` to see splits live
+* Bring your own objects, or stay minimal with ids and tuples