fastquadtree 1.0.2__tar.gz → 1.1.0__tar.gz

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/.pre-commit-config.yaml

@@ -7,9 +7,11 @@ repos:
       - id: ruff
         name: ruff (lint + fix)
         args: ["--fix", "--exit-non-zero-on-fix"]
+        fail_fast: true
       # Code formatter (Black replacement)
       - id: ruff-format
         name: ruff (format)
+        fail_fast: true
 
   # Local hooks that run in sequence and do not receive file args
   - repo: local

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/Cargo.lock

@@ -10,8 +10,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "fastquadtree"
-version = "1.0.2"
+version = "1.1.0"
 dependencies = [
+ "numpy",
  "pyo3",
  "smallvec",
 ]
@@ -34,6 +35,16 @@ version = "0.2.175"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6a82ae493e598baaea5209805c49bbf2ea7de956d50d7da0da1164f9c6d28543"
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "memoffset"
 version = "0.9.1"
@@ -43,6 +54,64 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.26.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b2dba356160b54f5371b550575b78130a54718b4c6e46b3f33a6da74a27e78b"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -55,6 +124,15 @@ version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f84267b20a16ea918e43c6a88433c2d54fa145c92a811b5b047ccbe153674483"
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8a2f0d8d040d7848a709caf78912debcc3f33ee4b3cac47d73d1e1069e83507"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.101"
@@ -134,6 +212,18 @@ dependencies = [
  "proc-macro2",
 ]
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.0.2"
+version = "1.1.0"
 edition = "2021"
 readme = "README.md"
 
@@ -10,6 +10,7 @@ crate-type = ["rlib", "cdylib"]
 [dependencies]
 pyo3 = { version = "0.26", features = ["extension-module", "abi3-py38"] }
 smallvec = "1.15.1"
+numpy = "0.26"
 
 [profile.release]
 opt-level = 3

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 1.0.2
+Version: 1.1.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -25,6 +25,7 @@ Requires-Dist: mkdocs-git-revision-date-localized-plugin ; extra == 'dev'
 Requires-Dist: mkdocs-minify-plugin ; extra == 'dev'
 Requires-Dist: maturin>=1.5 ; extra == 'dev'
 Requires-Dist: pyqtree==1.0.0 ; extra == 'dev'
+Requires-Dist: numpy ; extra == 'dev'
 Provides-Extra: dev
 License-File: LICENSE
 Summary: Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search.
@@ -48,6 +49,7 @@ Rust-optimized quadtree with a clean Python API
 [![Python versions](https://img.shields.io/pypi/pyversions/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
 [![Downloads](https://static.pepy.tech/personalized-badge/fastquadtree?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Total%20Downloads)](https://pepy.tech/projects/fastquadtree)
 [![Build](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml/badge.svg)](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml)
+![No runtime deps](https://img.shields.io/badge/deps-none-success)
 
 [![PyO3](https://img.shields.io/badge/Rust-core%20via%20PyO3-orange)](https://pyo3.rs/)
 [![maturin](https://img.shields.io/badge/Built%20with-maturin-1f6feb)](https://www.maturin.rs/)
@@ -62,7 +64,7 @@ Rust-optimized quadtree with a clean Python API
 
 ## Why use fastquadtree
 
-- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with modern typing hints
+- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with no external dependencies and modern typing hints
 - The fastest quadtree Python package ([>10x faster](https://elan456.github.io/fastquadtree/benchmark/) than pyqtree)
 - Prebuilt wheels for Windows, macOS, and Linux
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/README.md

@@ -9,6 +9,7 @@ Rust-optimized quadtree with a clean Python API
 [![Python versions](https://img.shields.io/pypi/pyversions/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
 [![Downloads](https://static.pepy.tech/personalized-badge/fastquadtree?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Total%20Downloads)](https://pepy.tech/projects/fastquadtree)
 [![Build](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml/badge.svg)](https://github.com/Elan456/fastquadtree/actions/workflows/release.yml)
+![No runtime deps](https://img.shields.io/badge/deps-none-success)
 
 [![PyO3](https://img.shields.io/badge/Rust-core%20via%20PyO3-orange)](https://pyo3.rs/)
 [![maturin](https://img.shields.io/badge/Built%20with-maturin-1f6feb)](https://www.maturin.rs/)
@@ -23,7 +24,7 @@ Rust-optimized quadtree with a clean Python API
 
 ## Why use fastquadtree
 
-- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with modern typing hints
+- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with no external dependencies and modern typing hints
 - The fastest quadtree Python package ([>10x faster](https://elan456.github.io/fastquadtree/benchmark/) than pyqtree)
 - Prebuilt wheels for Windows, macOS, and Linux
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points

fastquadtree-1.1.0/benchmarks/benchmark_np_vs_list.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import gc
+import statistics as stats
+from time import perf_counter as now
+
+import numpy as np
+from system_info_collector import (
+    collect_system_info,
+    format_system_info_markdown_lite,
+)
+
+from fastquadtree import QuadTree as ShimQuadTree  # high level wrapper with insert_many
+
+BOUNDS: tuple[float, float, float, float] = (0.0, 0.0, 1000.0, 1000.0)
+CAPACITY = 64
+MAX_DEPTH = 10
+SEED = 12345
+
+
+def gen_np_points(n: int, dtype: np.dtype) -> np.ndarray:
+    rng = np.random.default_rng(SEED)
+    # Generate within bounds. Use dtype the user requested.
+    if np.issubdtype(dtype, np.integer):
+        arr = rng.integers(low=0, high=1000, size=(n, 2), dtype=dtype)
+    else:
+        arr = rng.random(size=(n, 2), dtype=dtype) * 1000.0
+    return arr
+
+
+def _build_tree_np(points_np: np.ndarray, track_objects: bool) -> float:
+    t0 = now()
+    qt = ShimQuadTree(
+        BOUNDS, CAPACITY, max_depth=MAX_DEPTH, track_objects=track_objects
+    )
+    # Direct NumPy path
+    inserted = qt.insert_many(points_np)
+    dt = now() - t0
+    assert (
+        inserted == points_np.shape[0]
+    ), f"Inserted {inserted} != {points_np.shape[0]}"
+    return dt
+
+
+def _build_tree_list(
+    points_list: list[tuple[float, float]], track_objects: bool
+) -> float:
+    t0 = now()
+    qt = ShimQuadTree(
+        BOUNDS, CAPACITY, max_depth=MAX_DEPTH, track_objects=track_objects
+    )
+    inserted = qt.insert_many(points_list)
+    dt = now() - t0
+    assert inserted == len(points_list), f"Inserted {inserted} != {len(points_list)}"
+    return dt
+
+
+def bench_np_direct(points_np: np.ndarray, repeats: int, track_objects: bool) -> float:
+    times = []
+    for _ in range(repeats):
+        gc.disable()
+        times.append(_build_tree_np(points_np, track_objects))
+        gc.enable()
+    return stats.median(times)
+
+
+def bench_list_from_np(
+    points_np: np.ndarray, repeats: int, track_objects: bool, include_conversion: bool
+) -> float:
+    times = []
+    if not include_conversion:
+        # Convert once up front so measured time is insert only
+        points_list = [tuple(map(float, row)) for row in points_np]
+    for _ in range(repeats):
+        gc.disable()
+        if include_conversion:
+            # Count conversion cost
+            t0 = now()
+            points_list = [tuple(map(float, row)) for row in points_np]
+            convert_time = now() - t0
+            build_time = _build_tree_list(points_list, track_objects)  # type: ignore
+            times.append(convert_time + build_time)
+        else:
+            # Insert only
+            times.append(_build_tree_list(points_list, track_objects))  # pyright: ignore[reportPossiblyUnboundVariable, reportArgumentType]
+        gc.enable()
+    return stats.median(times)
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Benchmark: NumPy insert vs Python list insert"
+    )
+    ap.add_argument("--points", type=int, default=500_000)
+    ap.add_argument("--repeats", type=int, default=5)
+    ap.add_argument(
+        "--dtype",
+        type=str,
+        default="float32",
+        choices=["float32", "float64", "int32", "int64"],
+        help="Dtype for generated NumPy points",
+    )
+    ap.add_argument(
+        "--track-objects",
+        action="store_true",
+        help="Enable object tracking in the shim to include store overhead",
+    )
+    args = ap.parse_args()
+
+    dtype_map = {
+        "float32": np.float32,
+        "float64": np.float64,
+        "int32": np.int32,
+        "int64": np.int64,
+    }
+    dtype = dtype_map[args.dtype]
+
+    print("NumPy vs list insert benchmark")
+    print("=" * 50)
+    print("Configuration:")
+    print(f"  Points: {args.points:,}")
+    print(f"  Repeats: {args.repeats}")
+    print(f"  Dtype: {args.dtype}")
+    print(f"  Track objects: {args.track_objects}")
+    print()
+
+    # Data
+    pts_np = gen_np_points(args.points, dtype=dtype)
+
+    # Warmup
+    _ = bench_np_direct(pts_np[:10_000], repeats=1, track_objects=args.track_objects)
+    _ = bench_list_from_np(
+        pts_np[:10_000],
+        repeats=1,
+        track_objects=args.track_objects,
+        include_conversion=False,
+    )
+    _ = bench_list_from_np(
+        pts_np[:10_000],
+        repeats=1,
+        track_objects=args.track_objects,
+        include_conversion=True,
+    )
+
+    # Actual runs
+    t_np = bench_np_direct(pts_np, args.repeats, args.track_objects)
+    t_list_insert_only = bench_list_from_np(
+        pts_np, args.repeats, args.track_objects, include_conversion=False
+    )
+    t_list_with_convert = bench_list_from_np(
+        pts_np, args.repeats, args.track_objects, include_conversion=True
+    )
+
+    def fmt(x: float) -> str:
+        if x < 1e-3:
+            return f"{x * 1e6:.1f} µs"
+        if x < 1:
+            return f"{x * 1e3:.1f} ms"
+        return f"{x:.3f} s"
+
+    print("Results (median of repeats)")
+    print()
+    print("| Variant | Build time |")
+    print("|---|---:|")
+    print(f"| NumPy array direct | {fmt(t_np)} |")
+    print(f"| Python list insert only | {fmt(t_list_insert_only)} |")
+    print(f"| Python list including conversion | {fmt(t_list_with_convert)} |")
+
+    if collect_system_info and format_system_info_markdown_lite:
+        info = collect_system_info()
+        print()
+        print(format_system_info_markdown_lite(info))
+
+
+if __name__ == "__main__":
+    main()

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/benchmarks/requirements.txt

@@ -17,4 +17,7 @@ shapely>=2.0.0       # STRtree comparator
 # For getting system info
 psutil
 py-cpuinfo
-distro
+distro
+
+# For benchmarking NumPy bulk insert vs list insert
+numpy

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/docs/benchmark.md

@@ -57,6 +57,8 @@ Using the shim with object tracking increases build time by 5.345x and query tim
 
 Adding the object map tends to impact the build time more than query time.
 
+-----------
+
 ## pyqtree drop-in shim performance gains
 
 ### Configuration
@@ -78,6 +80,33 @@ This is a **total speedup of 6.567x** compared to the original pyqtree and requi
 
 ---------
 
+## NumPy Bulk Insert vs Python List Insert
+### Configuration
+
+- Points: 500,000
+- Repeats: 5
+- Dtype: float32
+- Track objects: False
+
+### Results (median of repeats)
+
+| Variant | Build time |
+|---|---:|
+| NumPy array direct | 42.8 ms |
+| Python list insert only | 51.1 ms |
+| Python list including conversion | 540.2 ms |
+
+Key:  
+
+- *NumPy array direct*: Using the `insert_many` method with a NumPy array of shape (N, 2).  
+- *Python list insert only*: Using the `insert_many` method with a Python list of tuples.  
+- *Python list including conversion*: Time taken to convert a NumPy array to a Python list of tuples, then inserting.  
+
+### Summary
+If your data is already in a NumPy array, using the `insert_many` method directly with the array is significantly faster than converting to a Python list first.
+
+---------
+
 ## System Info
 - **OS**: Windows 11 AMD64
 - **Python**: CPython 3.12.2
@@ -97,6 +126,7 @@ Then run:
 ```bash
 python benchmarks/cross_library_bench.py
 python benchmarks/benchmark_native_vs_shim.py 
+python benchmarks/benchmark_np_vs_list.py 
 ```
 
 Check the CLI arguments for the cross-library benchmark in `benchmarks/quadtree_bench/main.py`.

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/docs/index.md

@@ -35,7 +35,7 @@
 
 ## Why use fastquadtree
 
-- Clean [Python API](api/quadtree.md) with modern typing hints
+- Clean [Python API](api/quadtree.md) with no external dependencies and modern typing hints
 - The fastest quadtree Python package ([>10x faster](benchmark.md) than pyqtree)
 - Prebuilt wheels for Windows, macOS, and Linux
 - Support for [inserting bounding boxes](api/rect_quadtree.md) or points

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/mkdocs.yml

@@ -44,11 +44,11 @@ plugins:
             separate_signature: true
             line_length: 88
             heading_level: 2
-            filters:  # Exclude __slots__ and __len__ and anything with a single underscore prefix
+            filters:  # Exclude __slots__ and __len__ and anything with a single underscore prefix (don't filter insert_many even though it has a single underscore)
               - "!__slots__"
               - "!__len__"
-              - "!_.*"
-              
+              - "!^_[^_]"
+
   - autorefs
   - git-revision-date-localized:
       fallback_to_build_date: true

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/pyproject.toml

@@ -9,6 +9,7 @@ dynamic = ["version"]
 description = "Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.8"
+dependencies = [] # No runtime dependencies
 license = { file = "LICENSE" }
 authors = [{ name = "Ethan Anderson" }]
 keywords = ["quadtree", "spatial-index", "geometry", "rust", "pyo3", "nearest-neighbor", "k-nn"]
@@ -78,6 +79,7 @@ dev = [
   "mkdocs-minify-plugin",
   "maturin>=1.5",  # build Rust wheels
   "pyqtree==1.0.0", # for comparison in tests
+  "numpy",
 ]
 
 [tool.ruff]

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/pysrc/fastquadtree/_base_quadtree.py

@@ -2,11 +2,23 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Generic, Iterable, Tuple, TypeVar
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Iterable,
+    Sequence,
+    Tuple,
+    TypeVar,
+    overload,
+)
 
 from ._item import Item  # base class for PointItem and RectItem
 from ._obj_store import ObjStore
 
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
 Bounds = Tuple[float, float, float, float]
 
 # Generic parameters
@@ -15,6 +27,11 @@ HitT = TypeVar("HitT")  # raw native tuple, e.g. (id,x,y) or (id,x0,y0,x1,y1)
 ItemType = TypeVar("ItemType", bound=Item)  # e.g. PointItem or RectItem
 
 
+def _is_np_array(x: Any) -> bool:
+    mod = getattr(x.__class__, "__module__", "")
+    return mod.startswith("numpy") and hasattr(x, "ndim") and hasattr(x, "shape")
+
+
 class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     """
     Shared logic for Python QuadTree wrappers over native Rust engines.
@@ -110,9 +127,18 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         self._count += 1
         return rid
 
-    def insert_many(self, geoms: list[G], objs: list[Any] | None = None) -> int:
+    @overload
+    def insert_many(self, geoms: Sequence[G], objs: list[Any] | None = None) -> int: ...
+    @overload
+    def insert_many(
+        self, geoms: NDArray[Any], objs: list[Any] | None = None
+    ) -> int: ...
+    def insert_many(
+        self, geoms: NDArray[Any] | Sequence[G], objs: list[Any] | None = None
+    ) -> int:
         """
         Bulk insert with auto-assigned contiguous ids. Faster than inserting one-by-one.<br>
+        Can accept either a Python sequence of geometries or a NumPy array of shape (N,2) or (N,4) with dtype float32.
 
         If tracking is enabled, the objects will be bulk stored internally.
         If no objects are provided, the items will have obj=None (if tracking).
@@ -127,13 +153,30 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         Raises:
             ValueError: If any geometry is outside bounds.
         """
-        if not geoms:
+        if type(geoms) is list and len(geoms) == 0:
             return 0
 
+        if _is_np_array(geoms):
+            import numpy as _np
+        else:
+            _np = None
+
+        # Early return if the numpy array is empty
+        if _np is not None and isinstance(geoms, _np.ndarray):
+            if geoms.size == 0:
+                return 0
+
+            if geoms.dtype != _np.float32:
+                raise TypeError("Numpy array must use dtype float32")
+
         if self._store is None:
             # Simple contiguous path with native bulk insert
             start_id = self._next_id
-            last_id = self._native.insert_many(start_id, geoms)
+
+            if _np is not None:
+                last_id = self._native.insert_many_np(start_id, geoms)
+            else:
+                last_id = self._native.insert_many(start_id, geoms)
             num = last_id - start_id + 1
             if num < len(geoms):
                 raise ValueError("One or more items are outside tree bounds")
@@ -143,7 +186,10 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         # With tracking enabled:
         start_id = len(self._store._arr)  # contiguous tail position
-        last_id = self._native.insert_many(start_id, geoms)
+        if _np is not None:
+            last_id = self._native.insert_many_np(start_id, geoms)
+        else:
+            last_id = self._native.insert_many(start_id, geoms)
         num = last_id - start_id + 1
         if num < len(geoms):
             raise ValueError("One or more items are outside tree bounds")

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/src/lib.rs

@@ -8,6 +8,8 @@ pub use crate::rect_quadtree::{RectItem, RectQuadTree};
 
 use pyo3::prelude::*;
 use pyo3::types::PyList;
+use pyo3::exceptions::PyValueError;
+use numpy::PyReadonlyArray2;
 
 fn item_to_tuple(it: Item) -> (u64, f32, f32) {
     (it.id, it.point.x, it.point.y)
@@ -53,6 +55,35 @@ impl PyQuadTree {
         id.saturating_sub(1)
     }
 
+    /// Assume (n x 2) numpy array of float32 points [[x, y], ...]
+    pub fn insert_many_np<'py>(
+        &mut self,
+        py: Python<'py>, // Allow releasing the GIL during insertion
+        start_id: u64,
+        points: PyReadonlyArray2<'py, f32>,
+    ) -> PyResult<u64> {
+        let view = points.as_array();
+        if view.ncols() != 2 {
+            return Err(PyValueError::new_err("points must have shape (N, 2)"));
+        }
+
+        let mut id = start_id;
+        py.detach(|| {
+            if let Some(slice) = view.as_slice() {
+                for ch in slice.chunks_exact(2) {
+                    let (x, y) = (ch[0], ch[1]);
+                    if self.inner.insert(Item { id, point: Point { x, y } }) { id += 1; }
+                }
+            } else {
+                for row in view.outer_iter() {
+                    let (x, y) = (row[0], row[1]);
+                    if self.inner.insert(Item { id, point: Point { x, y } }) { id += 1; }
+                }
+            }
+        });
+        Ok(id.saturating_sub(1))
+    }
+
     pub fn delete(&mut self, id: u64, xy: (f32, f32)) -> bool {
         let (x, y) = xy;
         self.inner.delete(id, Point { x, y })
@@ -138,6 +169,35 @@ impl PyRectQuadTree {
         id.saturating_sub(1)
     }
 
+    /// Assume (n x 4) numpy array of float32 box [[min_x, min_y, max_x, max_y], ...]
+    pub fn insert_many_np<'py>(
+        &mut self,
+        py: Python<'py>, // Allow releasing the GIL during insertion
+        start_id: u64,
+        points: PyReadonlyArray2<'py, f32>,
+    ) -> PyResult<u64> {
+        let view = points.as_array();
+        if view.ncols() != 4 {
+            return Err(PyValueError::new_err("points must have shape (N, 4)"));
+        }
+
+        let mut id = start_id;
+        py.detach(|| {
+            if let Some(slice) = view.as_slice() {
+                for ch in slice.chunks_exact(4) {
+                    let r = Rect { min_x: ch[0], min_y: ch[1], max_x: ch[2], max_y: ch[3] };
+                    if self.inner.insert(RectItem { id, rect: r }) { id += 1; }
+                }
+            } else {
+                for row in view.outer_iter() {
+                    let r = Rect { min_x: row[0], min_y: row[1], max_x: row[2], max_y: row[3] };
+                    if self.inner.insert(RectItem { id, rect: r }) { id += 1; }
+                }
+            }
+        });
+        Ok(id.saturating_sub(1))
+    }
+
     /// Delete by id and exact rect.
     pub fn delete(&mut self, id: u64, rect: (f32, f32, f32, f32)) -> bool {
         let (min_x, min_y, max_x, max_y) = rect;

fastquadtree-1.1.0/tests/test_insert_many_numpy.py

@@ -0,0 +1,183 @@
+import numpy as np
+import pytest
+
+from fastquadtree import Item, QuadTree, RectQuadTree
+
+BOUNDS = (0, 0, 1000, 1000)
+
+
+def ids(hits):
+    """Return sorted list of ids from [(id, x, y), ...]."""
+    return sorted(h[0] for h in hits)
+
+
+def test_insert_many_seeds_items_and_query_as_items_round_trip():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=True)
+    n = qt.insert_many([(10, 10), (20, 20), (30, 30)])
+    assert n == 3
+
+    qt_np = QuadTree(BOUNDS, capacity=8, track_objects=True)
+
+    points = np.array([[10, 10], [20, 20], [30, 30]], dtype=np.float32)
+    n = qt_np.insert_many(points)
+    assert n == 3
+
+    raw = qt.query((0, 0, 40, 40), as_items=False)
+    its = qt.query((0, 0, 40, 40), as_items=True)
+
+    raw_np = qt_np.query((0, 0, 40, 40), as_items=False)
+    its_np = qt_np.query((0, 0, 40, 40), as_items=True)
+
+    assert len(raw) == len(its) == 3
+    assert len(raw_np) == len(its_np) == 3
+    # ids and positions match
+    m_raw = {t[0]: (t[1], t[2]) for t in raw}
+    for it in its:
+        assert isinstance(it, Item)
+        assert (it.x, it.y) == m_raw[it.id_]
+
+    m_raw_np = {t[0]: (t[1], t[2]) for t in raw_np}
+    for it in its_np:
+        assert isinstance(it, Item)
+        assert (it.x, it.y) == m_raw_np[it.id_]
+    # ids match between raw and raw_np
+    assert ids(raw) == ids(raw_np)
+
+
+def test_type_error_on_wrong_dtype():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=True)
+    points = np.array([[10, 10], [20, 20], [30, 30]], dtype=np.float64)  # Wrong dtype
+    with pytest.raises(TypeError):
+        qt.insert_many(points)
+    assert len(qt) == 0
+
+
+def test_insert_empty_numpy_array():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=True)
+    points = np.empty((0, 2), dtype=np.float32)
+    n = qt.insert_many(points)
+    assert n == 0
+    assert len(qt) == 0
+
+
+def test_insert_many_numpy_out_of_bounds():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=True)
+    points = np.array([[10, 10], (2000, 2000), [30, 30]], dtype=np.float32)
+    with pytest.raises(ValueError):
+        qt.insert_many(points)
+    assert len(qt) == 0
+
+
+def test_insert_many_without_tracking_numpy():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=False)
+    points = np.array([[10, 10], [20, 20], [30, 30]], dtype=np.float32)
+    n = qt.insert_many(points)
+    assert n == 3
+    assert len(qt) == 3
+
+    raw = qt.query((0, 0, 40, 40), as_items=False)
+
+    assert len(raw) == 3
+    # ids and positions match
+    m_raw = {t[0]: (t[1], t[2]) for t in raw}
+    for t in raw:
+        assert (t[1], t[2]) == m_raw[t[0]]
+
+
+def test_insert_many_rect_quadtree_numpy():
+    qt = RectQuadTree(BOUNDS, capacity=8, track_objects=True)
+    rects = np.array(
+        [[10, 10, 15, 15], [20, 20, 25, 25], [30, 30, 35, 35]], dtype=np.float32
+    )
+    n = qt.insert_many(rects)
+    assert n == 3
+
+    raw = qt.query((0, 0, 40, 40), as_items=False)
+    its = qt.query((0, 0, 40, 40), as_items=True)
+    assert len(raw) == len(its) == 3
+    # ids and positions match
+    m_raw = {t[0]: (t[1], t[2], t[3], t[4]) for t in raw}
+    for it in its:
+        assert isinstance(it, Item)
+        assert (it.min_x, it.min_y, it.max_x, it.max_y) == m_raw[it.id_]
+
+    # Query that will only hit one rect
+    raw2 = qt.query((12, 12, 13, 13), as_items=False)
+
+    assert len(raw2) == 1
+    assert raw2[0][0] == 0  # id of the first rect
+
+
+def test_point_query_accuracy_robust_numpy():
+    qt = QuadTree(BOUNDS, capacity=4, track_objects=True)
+    num_points = 10000
+    np.random.seed(42)
+    points = np.random.uniform(0, 999, size=(num_points, 2)).astype(np.float32)
+    qt.insert_many(points)
+
+    # Query a random rectangle and verify all returned points are within it
+    query_rect = (250, 250, 750, 750)
+    results = qt.query(query_rect, as_items=False)
+
+    for _, x, y in results:
+        assert query_rect[0] <= x < query_rect[2]
+        assert query_rect[1] <= y < query_rect[3]
+
+    # Verify that no points within the rectangle are missed
+    all_points_set = {(int(x), int(y)) for x, y in points}
+    queried_points_set = {(int(x), int(y)) for _, x, y in results}
+
+    for x in range(int(query_rect[0]), int(query_rect[2])):
+        for y in range(int(query_rect[1]), int(query_rect[3])):
+            if (x, y) in all_points_set:
+                assert (x, y) in queried_points_set
+
+
+def test_rect_query_accuracy_robust_numpy():
+    qt = RectQuadTree(BOUNDS, capacity=4, track_objects=True)
+    num_rects = 10000
+    np.random.seed(42)
+    rects = np.random.uniform(0, 950, size=(num_rects, 2)).astype(np.float32)
+    sizes = np.random.uniform(5, 50, size=(num_rects, 2)).astype(np.float32)
+    rects = np.hstack((rects, rects + sizes))
+    qt.insert_many(rects)
+
+    # Query a random rectangle and verify all returned rects intersect it
+    query_rect = (250, 250, 750, 750)
+    results = qt.query(query_rect, as_items=False)
+
+    def intersects(r1, r2):
+        return not (r1[2] < r2[0] or r1[0] > r2[2] or r1[3] < r2[1] or r1[1] > r2[3])
+
+    for _, min_x, min_y, max_x, max_y in results:
+        assert intersects((min_x, min_y, max_x, max_y), query_rect)
+
+    # Verify that no rects intersecting the query rectangle are missed
+    all_rects = list(rects)
+    queried_rects_set = {
+        (int(min_x), int(min_y), int(max_x), int(max_y))
+        for _, min_x, min_y, max_x, max_y in results
+    }
+
+    for rect in all_rects:
+        if intersects(rect, query_rect):
+            assert (
+                int(rect[0]),
+                int(rect[1]),
+                int(rect[2]),
+                int(rect[3]),
+            ) in queried_rects_set
+
+
+def test_insert_objects_numpy():
+    qt = QuadTree(BOUNDS, capacity=8, track_objects=True)
+    qt.insert_many(
+        np.array([[10, 10], [20, 20], [30, 30]], dtype=np.float32),
+        objs=[{"name": "A"}, {"name": "B"}, {"name": "C"}],
+    )
+
+    items = qt.query((0, 0, 40, 40), as_items=True)
+    assert len(items) == 3
+
+    names = {item.obj["name"] for item in items if item.obj is not None}
+    assert names == {"A", "B", "C"}

{fastquadtree-1.0.2 → fastquadtree-1.1.0}/tests/test_pyqtree_shim_compat.py

@@ -8,6 +8,8 @@ from fastquadtree.pyqtree import Index as FQTIndex
 
 WORLD = (0.0, 0.0, 100.0, 100.0)
 
+EPS = 1e-6  # Floating point tolerance for edge cases
+
 
 def rand_rect(rng, world=WORLD, min_size=1.0, max_size=20.0):
     x1 = rng.uniform(world[0], world[2] - min_size)
@@ -246,3 +248,98 @@ def test_free_slot_reuse_no_growth_under_churn():
     # None of the removed items should be found
     for obj, box in removed:
         assert obj not in idx.intersect(box)
+
+
+def _boxes_touching_edges_and_corners():
+    # World is (0,0,100,100). Partition lines around 50 are common split lines.
+    return [
+        ("left_edge", (0.0, 10.0, 5.0, 20.0)),  # touches world min-x
+        ("right_edge", (95.0, 10.0, 100.0, 20.0)),  # touches world max-x
+        ("bottom_edge", (10.0, 0.0, 20.0, 5.0)),  # touches world min-y
+        ("top_edge", (10.0, 95.0, 20.0, 100.0)),  # touches world max-y
+        ("bottom_left_pt", (0.0, 0.0, 5.0, 5.0)),  # corner touch
+        ("top_right_pt", (95.0, 95.0, 100.0, 100.0)),
+        # Straddle the vertical split line x=50 with tiny thickness
+        ("straddle_x50", (50.0 - EPS, 40.0, 50.0 + EPS, 60.0)),
+        # Straddle the horizontal split line y=50 with tiny thickness
+        ("straddle_y50", (40.0, 50.0 - EPS, 60.0, 50.0 + EPS)),
+        # Very thin but > 0 width and height
+        ("thin_horizontal", (20.0, 33.333, 80.0, 33.333 + 1e-5)),
+        ("thin_vertical", (33.333, 20.0, 33.333 + 1e-5, 80.0)),
+        # Boxes that just touch each other at an edge or corner
+        ("touch_A", (30.0, 30.0, 40.0, 40.0)),
+        ("touch_B", (40.0, 30.0, 50.0, 40.0)),  # shares an edge with A
+        ("touch_C", (40.0, 40.0, 50.0, 50.0)),  # touches B at one corner
+    ]
+
+
+def _queries_covering_touch_cases():
+    return [
+        (0.0, 0.0, 100.0, 100.0),  # world
+        (0.0, 10.0, 5.0, 20.0),  # exact edge box
+        (95.0, 10.0, 100.0, 20.0),
+        (10.0, 0.0, 20.0, 5.0),
+        (10.0, 95.0, 20.0, 100.0),
+        (30.0, 30.0, 50.0, 40.0),  # spans touch_A and touch_B shared edge
+        (39.9999, 39.9999, 40.0001, 40.0001),  # tiny around touching corner
+        (50.0 - 2 * EPS, 49.0, 50.0 + 2 * EPS, 51.0),  # around x=50 straddle
+        (49.0, 50.0 - 2 * EPS, 51.0, 50.0 + 2 * EPS),  # around y=50 straddle
+        (20.0, 33.333 - 1e-4, 80.0, 33.333 + 1e-4),  # thin horizontal
+        (33.333 - 1e-4, 20.0, 33.333 + 1e-4, 80.0),  # thin vertical
+    ]
+
+
+@pytest.mark.parametrize("ctor", ["bbox", "xywh"])
+def test_edge_and_boundary_semantics_match_pyqtree(ctor):
+    items = _boxes_touching_edges_and_corners()
+    fqt, pyq = build_indices(items, ctor=ctor)
+
+    # Check that every crafted query matches exactly
+    for q in _queries_covering_touch_cases():
+        results_match_exact(fqt, pyq, q)
+
+    # Add a few more probes around the partition lines to stress boundary math
+    for dx in (-EPS, 0.0, EPS):
+        for dy in (-EPS, 0.0, EPS):
+            q = (50.0 + dx - 1.0, 50.0 + dy - 1.0, 50.0 + dx + 1.0, 50.0 + dy + 1.0)
+            results_match_exact(fqt, pyq, q)
+
+
+def test_dense_targets_along_partition_lines_match_pyqtree():
+    """
+    Insert many small rectangles centered along x=50 and y=50 to stress
+    splitting and equality on boundary math.
+    """
+    objs = []
+    boxes = []
+
+    # 40 tiny boxes along x=50 at different y
+    for i in range(40):
+        y = 2.0 + i * 2.4  # spread across the world
+        boxes.append((50.0 - 0.25, y - 0.25, 50.0 + 0.25, y + 0.25))
+        objs.append(f"vx_{i}")
+
+    # 40 tiny boxes along y=50 at different x
+    for i in range(40):
+        x = 2.0 + i * 2.4
+        boxes.append((x - 0.25, 50.0 - 0.25, x + 0.25, 50.0 + 0.25))
+        objs.append(f"hy_{i}")
+
+    items = list(zip(objs, boxes))
+    fqt, pyq = build_indices(items, ctor="bbox")
+
+    # Probe a grid of queries around the center to catch any off by epsilon
+    for cx in (49.5, 50.0, 50.5):
+        for cy in (49.5, 50.0, 50.5):
+            q = (cx - 1.0, cy - 1.0, cx + 1.0, cy + 1.0)
+            results_match_exact(fqt, pyq, q)
+
+    # Also check a sweep of thin queries that align to the lines
+    thin_queries = [
+        (49.9, 0.0, 50.1, 100.0),
+        (0.0, 49.9, 100.0, 50.1),
+        (49.999, 10.0, 50.001, 90.0),
+        (10.0, 49.999, 90.0, 50.001),
+    ]
+    for q in thin_queries:
+        results_match_exact(fqt, pyq, q)