fastquadtree 1.0.1__tar.gz → 1.1.0__tar.gz

{fastquadtree-1.0.1 → 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.1 → fastquadtree-1.1.0}/Cargo.lock

@@ -10,8 +10,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "fastquadtree"
-version = "1.0.1"
+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.1 → fastquadtree-1.1.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.0.1"
+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.1 → fastquadtree-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 1.0.1
+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.1 → 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.1 → 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.1 → 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.1.0/docs/future_features.md

@@ -0,0 +1,30 @@
+# Future Features
+
+Below are a list of features that may be added to future versions of this project. 
+If you really want any of these features, please let us know by opening an issue.
+
+If you have any suggestions or would like to contribute, please feel free to open an issue or a pull request.
+
+## Planned Features
+
+### 1. Quadtree serialization
+
+By serializing the quadtree, we can save its state to a file and load it later. This will allow us to persist the quadtree structure and data across sessions. For example, you could pre build a quadtree with all the walls in your video game level, serialize it to a file, and then load it when the game starts. This will heavily reduce the game load time since you won't have to rebuild the quadtree from scratch every time.
+
+### 2. Circle support
+
+Currently, we support points and rectangles in two separate quadtrees.
+For example, in the ball-pit demo, we use a point quadtree, but then query a larger area to account for the radius of the balls.
+With a circle quadtree, we could directly insert circles and perform circle-circle collision detection.
+
+### 3. KNN with criteria function
+
+Currently, KNN only supports finding the nearest neighbors based on euclidean distance.
+By adding a criteria function, we could allow users to define custom criteria for finding neighbors by passing a function that 
+takes in a point and returns a score. The KNN algorithm would then use this score to determine the nearest neighbors.
+
+### 4. KNN in rectangle quadtree
+
+Currently, KNN is only supported in the point quadtree. By adding KNN support to the rectangle quadtree, we could allow users to find the nearest rectangles to a given point. This would be to the nearest edge of the rectangle, adding complexity to the algorithm.
+However, it will allow for really quick collision detection between a point and a set of rectangles as the point can just do
+robust-collision handling with the nearest rectangles.

{fastquadtree-1.0.1 → 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.1.0/docs/styles/overrides.css

@@ -0,0 +1,38 @@
+/* Global typography tuning */
+:root {
+  /* Larger base size for body copy */
+  --md-typeset-font-size: 0.98rem;   /* default ~0.9-0.95 */
+}
+
+.md-typeset {
+  line-height: 1.65;                 /* more relaxed, better for focus */
+  letter-spacing: 0.001em;
+}
+
+/* Crisper headings without looking heavy */
+.md-typeset h1, .md-typeset h2, .md-typeset h3 {
+  font-weight: 700;
+  line-height: 1.25;
+}
+
+/* Improve contrast on body text and links */
+:root {
+  --md-default-fg-color:          rgba(0,0,0,0.86);
+  --md-default-fg-color--light:   rgba(0,0,0,0.64);
+  --md-typeset-a-color:           #1e40af;  /* indigo-800 like */
+}
+[data-md-color-scheme="slate"] {
+  --md-default-fg-color:          rgba(255,255,255,0.92);
+  --md-default-fg-color--light:   rgba(255,255,255,0.72);
+  --md-typeset-a-color:           #93c5fd;  /* lighter link on dark */
+}
+
+/* Make code a tad larger for readability */
+.md-typeset code, .md-typeset pre code {
+  font-size: 0.93em;
+}
+
+/* Slightly stronger nav text */
+.md-nav__item .md-nav__link {
+  font-weight: 500;
+}

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

@@ -15,10 +15,18 @@ theme:
     - toc.integrate
     - search.suggest
     - search.highlight
+    - content.tooltips
   palette:
     - scheme: slate
       primary: indigo
       accent: deep orange
+  font:
+    text: Inter
+    code: JetBrains Mono
+
+extra_css:
+  - styles/overrides.css
+
 
 plugins:
   - search
@@ -36,6 +44,11 @@ plugins:
             separate_signature: true
             line_length: 88
             heading_level: 2
+            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
@@ -68,6 +81,7 @@ nav:
   - Quickstart: quickstart.md
   - Runnables: runnables.md
   - Benchmark: benchmark.md
+  - Future Features: future_features.md
   - API:
       - QuadTree: api/quadtree.md
       - RectQuadTree: api/rect_quadtree.md
@@ -83,5 +97,4 @@ extra:
       link: https://pypi.org/project/fastquadtree/
 
 # Build options
-extra_css: []
 extra_javascript: []

{fastquadtree-1.0.1 → 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.1 → 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")