fastquadtree 1.1.1__tar.gz → 1.2.0__tar.gz

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/.gitignore

@@ -210,4 +210,5 @@ __marimo__/
 
 
 *.exe 
-*.pdb
+*.pdb
+*.bin

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/Cargo.lock

@@ -8,12 +8,34 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
+[[package]]
+name = "bincode"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36eaf5d7b090263e8150820482d5d93cd964a81e4019913c972f4edcc6edb740"
+dependencies = [
+ "bincode_derive",
+ "serde",
+ "unty",
+]
+
+[[package]]
+name = "bincode_derive"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf95709a440f45e986983918d0e8a1f30a9b1df04918fc828670606804ac3c09"
+dependencies = [
+ "virtue",
+]
+
 [[package]]
 name = "fastquadtree"
-version = "1.1.1"
+version = "1.2.0"
 dependencies = [
+ "bincode",
  "numpy",
  "pyo3",
+ "serde",
  "smallvec",
 ]
 
@@ -224,6 +246,36 @@ version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
 
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"
@@ -258,3 +310,15 @@ name = "unindent"
 version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "unty"
+version = "0.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae"
+
+[[package]]
+name = "virtue"
+version = "0.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "051eb1abcf10076295e815102942cc58f9d5e3b4560e46e53c21e8ff6f3af7b1"

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.1.1"
+version = "1.2.0"
 edition = "2021"
 readme = "README.md"
 
@@ -11,6 +11,8 @@ crate-type = ["rlib", "cdylib"]
 pyo3 = { version = "0.26", features = ["extension-module", "abi3-py38"] }
 smallvec = "1.15.1"
 numpy = "0.26"
+serde = { version = "1.0", features = ["derive"] }
+bincode = {version = "2.0.1", features = ["serde"]}
 
 [profile.release]
 opt-level = 3

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 1.1.1
+Version: 1.2.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -70,6 +70,7 @@ Rust-optimized quadtree with a clean Python API
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
+- Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
 - Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
 

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/README.md

@@ -30,6 +30,7 @@ Rust-optimized quadtree with a clean Python API
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
+- Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
 - Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
 

fastquadtree-1.2.0/benchmarks/benchmark_serialization_vs_rebuild.py

@@ -0,0 +1,149 @@
+"""
+Benchmark: serialization/deserialization vs rebuild from NumPy array
+"""
+
+from __future__ import annotations
+
+import gc
+import statistics as stats
+from pathlib import Path
+from time import perf_counter as pc
+
+import numpy as np
+
+from fastquadtree import QuadTree
+
+CAPACITY = 64
+MAX_DEPTH = 10
+N = 1_000_000
+REPEATS = 7
+
+
+def timeit(fn, repeat=REPEATS):
+    # warmup
+    fn()
+    times = []
+    gc.disable()
+    try:
+        for _ in range(repeat):
+            t0 = pc()
+            fn()
+            times.append(pc() - t0)
+    finally:
+        gc.enable()
+    return times
+
+
+def make_points():
+    rng = np.random.default_rng(42)  # seed
+    # shape (N, 2), float32 to match native expectations
+    return rng.uniform(0.0, 1000.0, size=(N, 2)).astype(np.float32)
+
+
+def build_original(pts: np.ndarray) -> QuadTree:
+    qt = QuadTree((0, 0, 1000, 1000), capacity=CAPACITY, max_depth=MAX_DEPTH)
+    qt.insert_many(pts)
+    return qt
+
+
+def main():
+    pts = make_points()
+    original_qt = build_original(pts)
+
+    # correctness baseline
+    base_count = original_qt.count_items()
+    assert base_count == N
+
+    # serialize timing
+    ser_times = timeit(lambda: original_qt.to_bytes())
+    qt_bytes = original_qt.to_bytes()
+    print(f"Serialized size: {len(qt_bytes):,} bytes")
+
+    # write once for the file path
+    fname = "quadtree_serialization.bin"
+    with Path(fname).open("wb") as f:
+        f.write(qt_bytes)
+
+    def rebuild_points():
+        qt = QuadTree((0, 0, 1000, 1000), capacity=CAPACITY, max_depth=MAX_DEPTH)
+        qt.insert_many(pts)
+        assert qt.count_items() == base_count
+        _ = qt.query((100, 100, 200, 200))
+        return qt
+
+    def rebuild_from_mem():
+        qt = QuadTree.from_bytes(qt_bytes)
+        assert qt.count_items() == base_count
+        _ = qt.query((100, 100, 200, 200))
+        return qt
+
+    def rebuild_from_file():
+        with Path(fname).open("rb") as f:
+            data = f.read()
+        qt = QuadTree.from_bytes(data)
+        assert qt.count_items() == base_count
+        _ = qt.query((100, 100, 200, 200))
+        return qt
+
+    t_points = timeit(rebuild_points)
+    t_mem = timeit(rebuild_from_mem)
+    t_file = timeit(rebuild_from_file)
+
+    Path(fname).unlink(missing_ok=True)
+
+    def show(label, arr):
+        print(
+            f"{label:<28} mean={stats.mean(arr):.6f}s  stdev={stats.pstdev(arr):.6f}s "
+        )
+
+    show("serialize to bytes", ser_times)
+    show("rebuild from points", t_points)
+    show("rebuild from bytes", t_mem)
+    show("rebuild from file", t_file)
+
+    # ----- Markdown summary -----
+    def fmt(x: float) -> str:
+        return f"{x:.6f}"
+
+    m_ser = stats.mean(ser_times)
+    m_pts = stats.mean(t_points)
+    m_mem = stats.mean(t_mem)
+    m_file = stats.mean(t_file)
+
+    s_ser = stats.pstdev(ser_times)
+    s_pts = stats.pstdev(t_points)
+    s_mem = stats.pstdev(t_mem)
+    s_file = stats.pstdev(t_file)
+
+    speedup_mem = m_pts / m_mem if m_mem > 0 else float("inf")
+    speedup_file = m_pts / m_file if m_file > 0 else float("inf")
+
+    md = f"""
+## Serialization vs Rebuild
+
+### Configuration
+- Points: {N:,}
+- Capacity: {CAPACITY}
+- Max depth: {MAX_DEPTH}
+- Repeats: {REPEATS}
+
+### Results
+
+| Variant | Mean (s) | Stdev (s) |
+|---|---:|---:|
+| Serialize to bytes | {fmt(m_ser)} | {fmt(s_ser)} |
+| Rebuild from points | {fmt(m_pts)} | {fmt(s_pts)} |
+| Rebuild from bytes | {fmt(m_mem)} | {fmt(s_mem)} |
+| Rebuild from file | {fmt(m_file)} | {fmt(s_file)} |
+
+### Summary
+
+- Rebuild from bytes is **{fmt(speedup_mem)}x** faster than reinserting points.
+- Rebuild from file is **{fmt(speedup_file)}x** faster than reinserting points.
+- Serialized blob size is **{len(qt_bytes):,} bytes**.
+"""
+    print(md.strip())
+
+
+if __name__ == "__main__":
+    main()

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/docs/benchmark.md

@@ -107,6 +107,31 @@ If your data is already in a NumPy array, using the `insert_many` method directl
 
 ---------
 
+## Serialization vs Rebuild
+
+### Configuration
+- Points: 1,000,000
+- Capacity: 64
+- Max depth: 10
+- Repeats: 7
+
+### Results
+
+| Variant | Mean (s) | Stdev (s) |
+|---|---:|---:|
+| Serialize to bytes | 0.021356 | 0.000937 |
+| Rebuild from points | 0.106783 | 0.011430 |
+| Rebuild from bytes | 0.021754 | 0.001687 |
+| Rebuild from file | 0.024887 | 0.001846 |
+
+### Summary
+
+- Rebuild from bytes is **4.908747x** faster than reinserting points.
+- Rebuild from file is **4.290712x** faster than reinserting points.
+- Serialized blob size is **13,770,328 bytes**.
+
+----------------
+
 ## System Info
 - **OS**: Windows 11 AMD64
 - **Python**: CPython 3.12.2
@@ -127,6 +152,7 @@ Then run:
 python benchmarks/cross_library_bench.py
 python benchmarks/benchmark_native_vs_shim.py 
 python benchmarks/benchmark_np_vs_list.py 
+python benchmarks/benchmark_serialization_vs_rebuild.py
 ```
 
 Check the CLI arguments for the cross-library benchmark in `benchmarks/quadtree_bench/main.py`.

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/docs/future_features.md

@@ -7,7 +7,7 @@ If you have any suggestions or would like to contribute, please feel free to ope
 
 ## Planned Features
 
-### 1. Quadtree serialization
+### 1. [COMPLETE] 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.
 

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/docs/index.md

@@ -41,6 +41,7 @@
 - Support for [inserting bounding boxes](api/rect_quadtree.md) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
+- Fast [serialization](benchmark.md#serialization-vs-rebuild) to/from bytes
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
 
 ## Examples

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/interactive/interactive_v2.py

@@ -1,6 +1,7 @@
 import math
 import random
 from collections import deque
+from pathlib import Path
 
 import pygame
 
@@ -240,6 +241,7 @@ def hud(text_lines):
 # ------------------------------
 def handle_events(running, paused, show_nodes, show_nn, show_trails, zoom_target):
     """Handle discrete events like key presses and mouse clicks."""
+    global qtree
     for ev in pygame.event.get():
         if ev.type == pygame.QUIT:
             running = False
@@ -258,6 +260,21 @@ def handle_events(running, paused, show_nodes, show_nn, show_trails, zoom_target
                 zoom_target = clamp(zoom_target * ZOOM_FACTOR, ZOOM_MIN, ZOOM_MAX)
             elif ev.key in (pygame.K_MINUS, pygame.K_KP_MINUS):
                 zoom_target = clamp(zoom_target / ZOOM_FACTOR, ZOOM_MIN, ZOOM_MAX)
+            elif ev.key == pygame.K_c:
+                # Save quadtree state
+                data = qtree.to_bytes()
+                with Path("quadtree_state.bin").open("wb") as f:
+                    f.write(data)
+                print("Quadtree state saved to quadtree_state.bin")
+            elif ev.key == pygame.K_v:
+                # Load quadtree state
+                try:
+                    with Path("quadtree_state.bin").open("rb") as f:
+                        data = f.read()
+                    qtree = QuadTree.from_bytes(data)
+                    print("Quadtree state loaded from quadtree_state.bin")
+                except Exception as e:  # noqa: BLE001
+                    print(f"Failed to load quadtree state: {e}")
 
         elif ev.type == pygame.MOUSEWHEEL:
             if ev.y != 0:
@@ -436,6 +453,7 @@ def main():
                 f"zoom: {zoom:.2f}  target: {zoom_target:.2f}",
                 "WASD to pan. Mouse wheel or +/- to zoom.",
                 "arrow keys to resize rectangle.",
+                "c to save current state, v to load.",
                 "1 nodes. 2 NN rays. 3 trails. SPACE pause. L-click add. R-click remove (shift to repeat)",
             ]
         )

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/_base_quadtree.py

@@ -1,6 +1,7 @@
 # _abc_quadtree.py
 from __future__ import annotations
 
+import pickle
 from abc import ABC, abstractmethod
 from typing import (
     TYPE_CHECKING,
@@ -58,8 +59,9 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
         """Create the native engine instance."""
 
+    @staticmethod
     @abstractmethod
-    def _make_item(self, id_: int, geom: G, obj: Any | None) -> ItemType:
+    def _make_item(id_: int, geom: G, obj: Any | None) -> ItemType:
         """Build an ItemType from id, geometry, and optional object."""
 
     # ---- ctor ----
@@ -84,6 +86,71 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         self._next_id = 0
         self._count = 0
 
+    # ---- serialization ----
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize the quadtree to a dict suitable for JSON or other serialization.
+
+        Returns:
+            Includes a binary 'core' key for the native engine state, plus other metadata such as bounds and capacity and the obj store if tracking is enabled.
+        """
+
+        core_bytes = self._native.to_bytes()
+
+        return {
+            "core": core_bytes,
+            "store": self._store.to_dict() if self._store is not None else None,
+            "bounds": self._bounds,
+            "capacity": self._capacity,
+            "max_depth": self._max_depth,
+            "track_objects": self._track_objects,
+            "next_id": self._next_id,
+            "count": self._count,
+        }
+
+    def to_bytes(self) -> bytes:
+        """
+        Serialize the quadtree to bytes.
+
+        Returns:
+            Bytes representing the serialized quadtree. Can be saved as a file or loaded with `from_bytes()`.
+        """
+        return pickle.dumps(self.to_dict())
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> _BaseQuadTree[G, HitT, ItemType]:
+        """
+        Deserialize a quadtree from bytes.
+
+        Args:
+            data: Bytes representing the serialized quadtree from `to_bytes()`.
+
+        Returns:
+            A new quadtree instance with the same state as when serialized.
+        """
+        in_dict = pickle.loads(data)
+        core_bytes = in_dict["core"]
+        store_dict = in_dict["store"]
+
+        qt = cls.__new__(cls)  # type: ignore[call-arg]
+        qt._native = cls._new_native_from_bytes(core_bytes)
+
+        if store_dict is not None:
+            qt._store = ObjStore.from_dict(store_dict, qt._make_item)
+        else:
+            qt._store = None
+
+        # Extract bounds, capacity, max_depth from native
+        qt._bounds = in_dict["bounds"]
+        qt._capacity = in_dict["capacity"]
+        qt._max_depth = in_dict["max_depth"]
+        qt._next_id = in_dict["next_id"]
+        qt._count = in_dict["count"]
+        qt._track_objects = in_dict["track_objects"]
+
+        return qt
+
     # ---- internal helper ----
 
     def _ids_to_objects(self, ids: Iterable[int]) -> list[Any]:

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/_item.py

@@ -27,6 +27,35 @@ class Item:
         self.geom: Point | Bounds = geom
         self.obj: Any | None = obj
 
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize the item to a dictionary.
+
+        Returns:
+            A dictionary with 'id', 'geom', and 'obj' keys.
+        """
+        return {
+            "id": self.id_,
+            "geom": self.geom,
+            "obj": self.obj,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Item:
+        """
+        Deserialize an item from a dictionary.
+
+        Args:
+            data: A dictionary with 'id', 'geom', and 'obj' keys.
+
+        Returns:
+            An Item instance populated with the deserialized data.
+        """
+        id_ = data["id"]
+        geom = data["geom"]
+        obj = data["obj"]
+        return cls(id_, geom, obj)
+
 
 class PointItem(Item):
     """

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/_obj_store.py

@@ -35,11 +35,40 @@ class ObjStore(Generic[TItem]):
 
         if items:
             for it in items:
-                self.add(it)
+                self.add(it, handle_out_of_order=True)
+
+    # ---- Serialization ----
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize to a dict suitable for JSON or other serialization.
+
+        Returns:
+            A dict with 'items' key containing list of serialized items.
+        """
+        items = [it.to_dict() for it in self._arr if it is not None]
+        return {"items": items}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], item_factory: Any) -> ObjStore[TItem]:
+        """
+        Deserialize from a dict.
+
+        Args:
+            data: A dict with 'items' key containing list of serialized items.
+            item_factory: A callable that takes (id, obj) and returns an Item.
+
+        Returns:
+            An ObjStore instance populated with the deserialized items.
+        """
+        items = []
+        for item_data in data.get("items", []):
+            item = Item.from_dict(item_data)
+            items.append(item_factory(item.id_, item.geom, item.obj))
+        return cls(items)
 
     # -------- core --------
 
-    def add(self, item: TItem) -> None:
+    def add(self, item: TItem, handle_out_of_order: bool = False) -> None:
         """
         Insert or replace the mapping at item.id_. Reverse map updated so obj points to id.
         """
@@ -48,9 +77,14 @@ class ObjStore(Generic[TItem]):
 
         # ids must be dense and assigned by the caller
         if id_ > len(self._arr):
-            raise AssertionError(
-                "ObjStore.add received an out-of-order id, use alloc_id() to get the next available id"
-            )
+            if not handle_out_of_order:
+                raise AssertionError(
+                    "ObjStore.add received an out-of-order id, use alloc_id() to get the next available id"
+                )
+            # fill holes with None
+            while len(self._arr) < id_:
+                self._arr.append(None)
+                self._objs.append(None)
 
         if id_ == len(self._arr):
             # append

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/point_quadtree.py

@@ -49,6 +49,18 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
             track_objects=track_objects,
         )
 
+    @classmethod
+    def from_bytes(cls, data: bytes) -> QuadTree:
+        """
+        Create a QuadTree instance from serialized bytes.
+
+        Args:
+            data: Serialized byte data from `to_bytes()`.
+        Returns:
+            A QuadTree instance.
+        """
+        return super().from_bytes(data)
+
     @overload
     def query(
         self, rect: Bounds, *, as_items: Literal[False] = ...
@@ -145,5 +157,11 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
             return _RustQuadTree(bounds, capacity)
         return _RustQuadTree(bounds, capacity, max_depth=max_depth)
 
-    def _make_item(self, id_: int, geom: Point, obj: Any | None) -> PointItem:
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes) -> Any:
+        """Create a new native engine instance from serialized bytes."""
+        return _RustQuadTree.from_bytes(data)
+
+    @staticmethod
+    def _make_item(id_: int, geom: Point, obj: Any | None) -> PointItem:
         return PointItem(id_, geom, obj)

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/pyqtree.py

@@ -122,6 +122,9 @@ class Index:
         - **item**: The item to insert into the index, which will be returned by the intersection method
         - **bbox**: The spatial bounding box tuple of the item, with four members (xmin,ymin,xmax,ymax)
         """
+        if type(bbox) is list:  # Handle list input
+            bbox = tuple(bbox)
+
         if self._free:
             rid = self._free.pop()
             self._objects[rid] = item
@@ -141,6 +144,9 @@ class Index:
 
         Both parameters need to exactly match the parameters provided to the insert method.
         """
+        if type(bbox) is list:  # Handle list input
+            bbox = tuple(bbox)
+
         rid = self._item_to_id.pop(id(item))
         self._qt.delete(rid, bbox)
         self._objects[rid] = None

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/pysrc/fastquadtree/rect_quadtree.py

@@ -50,6 +50,18 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
             track_objects=track_objects,
         )
 
+    @classmethod
+    def from_bytes(cls, data: bytes) -> RectQuadTree:
+        """
+        Create a RectQuadTree instance from serialized bytes.
+
+        Args:
+            data: Serialized byte data from `to_bytes()`.
+        Returns:
+            A RectQuadTree instance.
+        """
+        return super().from_bytes(data)
+
     @overload
     def query(
         self, rect: Bounds, *, as_items: Literal[False] = ...
@@ -81,5 +93,11 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
             return _RustRectQuadTree(bounds, capacity)
         return _RustRectQuadTree(bounds, capacity, max_depth=max_depth)
 
-    def _make_item(self, id_: int, geom: Bounds, obj: Any | None) -> RectItem:
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes) -> Any:
+        """Create a new native engine instance from serialized bytes."""
+        return _RustRectQuadTree.from_bytes(data)
+
+    @staticmethod
+    def _make_item(id_: int, geom: Bounds, obj: Any | None) -> RectItem:
         return RectItem(id_, geom, obj)

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/src/geom.rs

@@ -1,10 +1,12 @@
-#[derive(Copy, Clone, Debug, PartialEq, Default)]
+use serde::{Serialize, Deserialize};
+
+#[derive(Copy, Clone, Debug, PartialEq, Default, Serialize, Deserialize)]
 pub struct Point {
     pub x: f32,
     pub y: f32,
 }
 
-#[derive(Copy, Clone, Debug, PartialEq, Default)]
+#[derive(Copy, Clone, Debug, PartialEq, Default, Serialize, Deserialize)]
 pub struct Rect {
     pub min_x: f32,
     pub min_y: f32,

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/src/lib.rs

@@ -8,6 +8,7 @@ pub use crate::rect_quadtree::{RectItem, RectQuadTree};
 
 use pyo3::prelude::*;
 use pyo3::types::PyList;
+use pyo3::types::PyBytes;
 use pyo3::exceptions::PyValueError;
 use numpy::PyReadonlyArray2;
 
@@ -38,6 +39,23 @@ impl PyQuadTree {
         Self { inner }
     }
 
+    // Return Python bytes
+    pub fn to_bytes<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
+        let buf = self
+            .inner
+            .to_bytes()
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("serialize failed: {e}")))?;
+        Ok(PyBytes::new(py, &buf))
+    }
+
+    // Construct from Python bytes
+    #[staticmethod]
+    pub fn from_bytes(bytes: &Bound<PyBytes>) -> PyResult<Self> {
+        let inner = QuadTree::from_bytes(bytes.as_bytes())
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("deserialize failed: {e}")))?;
+        Ok(Self { inner })
+    }
+
     pub fn insert(&mut self, id: u64, xy: (f32, f32)) -> bool {
         let (x, y) = xy;
         self.inner.insert(Item { id, point: Point { x, y } })
@@ -152,6 +170,23 @@ impl PyRectQuadTree {
         Self { inner }
     }
 
+    // Return Python bytes
+    pub fn to_bytes<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
+        let buf = self
+            .inner
+            .to_bytes()
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("serialize failed: {e}")))?;
+        Ok(PyBytes::new(py, &buf))
+    }
+
+    // Construct from Python bytes
+    #[staticmethod]
+    pub fn from_bytes(bytes: &Bound<PyBytes>) -> PyResult<Self> {
+        let inner = RectQuadTree::from_bytes(bytes.as_bytes())
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("deserialize failed: {e}")))?;
+        Ok(Self { inner })
+    }
+
     /// Insert one AABB by id.
     pub fn insert(&mut self, id: u64, rect: (f32, f32, f32, f32)) -> bool {
         let (min_x, min_y, max_x, max_y) = rect;

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/src/quadtree.rs

@@ -1,14 +1,17 @@
 use std::collections::HashSet;
 use crate::geom::{Point, Rect, dist_sq_point_to_rect, dist_sq_points};
 use smallvec::SmallVec;
+use serde::{Serialize, Deserialize};
+use bincode::config::standard;
+use bincode::serde::{encode_to_vec, decode_from_slice};
 
-#[derive(Copy, Clone, Debug, PartialEq, Default)]
+#[derive(Copy, Clone, Debug, PartialEq, Default, Serialize, Deserialize)]
 pub struct Item {
     pub id: u64,
     pub point: Point, 
 }
 
-
+#[derive(Serialize, Deserialize)]
 pub struct QuadTree {
     pub boundary: Rect,
     pub items: Vec<Item>,
@@ -55,6 +58,14 @@ impl QuadTree {
         }
     }
 
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::error::EncodeError> {
+        encode_to_vec(self, standard())
+    }
+    pub fn from_bytes(bytes: &[u8]) -> Result<Self, bincode::error::DecodeError> {
+        let (qt, _len): (Self, usize) = decode_from_slice(bytes, standard())?;
+        Ok(qt)
+    }
+
     pub fn new_child(boundary: Rect, capacity: usize, depth: usize, max_depth: usize) -> Self {
         QuadTree {
             boundary,

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/src/rect_quadtree.rs

@@ -1,12 +1,16 @@
 use smallvec::SmallVec;
 use crate::geom::Rect;
+use serde::{Serialize, Deserialize};
+use bincode::config::standard;
+use bincode::serde::{encode_to_vec, decode_from_slice};
 
-#[derive(Copy, Clone, Debug, PartialEq, Default)]
+#[derive(Copy, Clone, Debug, PartialEq, Default, Serialize, Deserialize)]
 pub struct RectItem {
     pub id: u64,
     pub rect: Rect,
 }
 
+#[derive(Serialize, Deserialize)]
 pub struct RectQuadTree {
     pub boundary: Rect,
     pub items: Vec<RectItem>,
@@ -68,6 +72,14 @@ impl RectQuadTree {
         }
     }
 
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::error::EncodeError> {
+        encode_to_vec(self, standard())
+    }
+    pub fn from_bytes(bytes: &[u8]) -> Result<Self, bincode::error::DecodeError> {
+        let (qt, _len): (Self, usize) = decode_from_slice(bytes, standard())?;
+        Ok(qt)
+    }
+
     fn new_child(boundary: Rect, capacity: usize, depth: usize, max_depth: usize) -> Self {
         RectQuadTree {
             boundary,

fastquadtree-1.2.0/tests/serialization.rs

@@ -0,0 +1,61 @@
+use fastquadtree::{RectQuadTree, QuadTree, Item, RectItem, Point, Rect};
+
+#[test]
+fn quadtree_roundtrip_bytes() {
+    // Build a small tree
+    let mut qt = QuadTree::new(
+        Rect { min_x: 0.0, min_y: 0.0, max_x: 10.0, max_y: 10.0 },
+        4,
+    );
+    for (i, (x, y)) in [(1.0, 1.0), (2.0, 3.0), (7.5, 8.5), (9.0, 0.5)].into_iter().enumerate() {
+        qt.insert(Item { id: i as u64 + 1, point: Point { x, y } });
+    }
+
+    // Serialize
+    let bytes = qt.to_bytes().expect("serialize quadtree");
+
+    // Deserialize
+    let qt2 = QuadTree::from_bytes(&bytes).expect("deserialize quadtree");
+
+    // Basic invariants
+    assert_eq!(qt.count_items(), qt2.count_items());
+
+    // Query equality for a region
+    let rect = Rect { min_x: 0.0, min_y: 0.0, max_x: 5.0, max_y: 5.0 };
+    let a: Vec<_> = qt.query(rect).into_iter().map(|(id, _, _)| id).collect();
+    let b: Vec<_> = qt2.query(rect).into_iter().map(|(id, _, _)| id).collect();
+    assert_eq!(a, b);
+
+    // Nearest neighbor equality
+    let nn1 = qt.nearest_neighbor(Point { x: 1.2, y: 1.1 }).map(|it| it.id);
+    let nn2 = qt2.nearest_neighbor(Point { x: 1.2, y: 1.1 }).map(|it| it.id);
+    assert_eq!(nn1, nn2);
+}
+
+
+#[test]
+fn rectquadtree_roundtrip_bytes() {
+    // Build a small tree
+    let mut qt = RectQuadTree::new(
+        Rect { min_x: 0.0, min_y: 0.0, max_x: 10.0, max_y: 10.0 },
+        4,
+    );
+    for (i, (x, y)) in [(1.0, 1.0), (2.0, 3.0), (7.5, 8.5), (9.0, 0.5)].into_iter().enumerate() {
+        qt.insert(RectItem { id: i as u64 + 1, rect: Rect { min_x: x, min_y: y, max_x: x + 1.0, max_y: y + 1.0 } });
+    }
+
+    // Serialize
+    let bytes = qt.to_bytes().expect("serialize quadtree");
+
+    // Deserialize
+    let qt2 = RectQuadTree::from_bytes(&bytes).expect("deserialize quadtree");
+
+    // Basic invariants
+    assert_eq!(qt.count_items(), qt2.count_items());
+
+    // Query equality for a region
+    let rect = Rect { min_x: 0.0, min_y: 0.0, max_x: 5.0, max_y: 5.0 };
+    let a: Vec<_> = qt.query(rect).into_iter().map(|it| it.0).collect();
+    let b: Vec<_> = qt2.query(rect).into_iter().map(|it| it.0).collect();
+    assert_eq!(a, b);
+}

{fastquadtree-1.1.1 → fastquadtree-1.2.0}/tests/test_pyqtree_shim_compat.py

@@ -362,3 +362,42 @@ def test_query_list_and_tuple_equivalence():
     results_from_list = idx.intersect(query_list)
 
     assert results_from_tuple == results_from_list == [obj1]
+
+
+def test_remove_list_and_tuple_equivalence():
+    """Test that both list and tuple inputs for bbox work the same in remove."""
+    idx = FQTIndex(bbox=WORLD)
+
+    obj1, box1 = "obj1", (10.0, 10.0, 20.0, 20.0)
+    obj2, box2 = "obj2", (30.0, 30.0, 40.0, 40.0)
+
+    idx.insert(obj1, box1)
+    idx.insert(obj2, box2)
+
+    # Remove using tuple
+    idx.remove(obj1, box1)
+
+    # Remove using list
+    box2_list = [30.0, 30.0, 40.0, 40.0]
+    idx.remove(obj2, box2_list)
+
+    # Both objects should be removed
+    assert idx.intersect((0.0, 0.0, 100.0, 100.0)) == []
+
+
+def test_insert_list_and_tuple_equivalence():
+    """Test that both list and tuple inputs for bbox work the same in insert."""
+    idx = FQTIndex(bbox=WORLD)
+
+    obj1, box1 = "obj1", (10.0, 10.0, 20.0, 20.0)
+    obj2, box2 = "obj2", [30.0, 30.0, 40.0, 40.0]  # box2 as list
+
+    # Insert using tuple
+    idx.insert(obj1, box1)
+
+    # Insert using list
+    idx.insert(obj2, box2)
+
+    # Both objects should be present
+    results = idx.intersect((0.0, 0.0, 100.0, 100.0))
+    assert set(results) == {obj1, obj2}

fastquadtree-1.2.0/tests/test_serialization.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Test unconventional quadtree bounding boxes including negative regions."""
+
+from fastquadtree import QuadTree, RectQuadTree
+
+
+def test_serialization_point_quadtree():
+    """Test serialization and deserialization of PointQuadTree."""
+    qt = QuadTree((0, 0, 100, 100), capacity=4)
+    points = [(10, 10), (20, 20), (30, 30), (40, 40)]
+    for pt in points:
+        qt.insert(pt)
+
+    data = qt.to_bytes()
+    qt2 = QuadTree.from_bytes(data)
+
+    assert qt.count_items() == qt2.count_items()
+    for rect in [(0, 0, 50, 50), (15, 15, 35, 35)]:
+        res1 = qt.query(rect)
+        res2 = qt2.query(rect)
+        assert sorted(res1) == sorted(res2)
+
+
+def test_serialization_rect_quadtree():
+    """Test serialization and deserialization of RectQuadTree."""
+    rqt = RectQuadTree((0, 0, 100, 100), capacity=4)
+    rects = [(5, 5, 15, 15), (20, 20, 30, 30), (35, 35, 45, 45), (50, 50, 60, 60)]
+    for rect in rects:
+        rqt.insert(rect)
+
+    data = rqt.to_bytes()
+    rqt2 = RectQuadTree.from_bytes(data)
+
+    assert rqt.count_items() == rqt2.count_items()
+    for query_rect in [(0, 0, 25, 25), (30, 30, 55, 55)]:
+        res1 = rqt.query(query_rect)
+        res2 = rqt2.query(query_rect)
+        assert sorted(res1) == sorted(res2)
+
+
+def test_serialization_with_objects_point():
+    """Test serialization of quadtree with associated objects."""
+    qt = QuadTree((0, 0, 100, 100), capacity=4, track_objects=True)
+    items = [((10, 10), "A"), ((20, 20), "B"), ((30, 30), "C")]
+    for pt, obj in items:
+        qt.insert(pt, obj=obj)
+
+    data = qt.to_bytes()
+    qt2 = QuadTree.from_bytes(data)
+
+    assert qt.count_items() == qt2.count_items()
+
+    # Check that the objects in the object store are preserved
+    all_qt2_items = [item.to_dict() for item in qt2.get_all_items()]
+    all_qt_items = [item.to_dict() for item in qt.get_all_items()]
+
+    for item in all_qt_items:
+        assert item in all_qt2_items
+
+    assert type(qt2.get_all_items()[0]) is type(qt.get_all_items()[0])
+    assert type(qt2.get_all_items()[0].obj) is type(qt.get_all_items()[0].obj)
+
+
+def test_serialization_with_objects_rect():
+    """Test serialization of rect quadtree with associated objects."""
+    rqt = RectQuadTree((0, 0, 100, 100), capacity=4, track_objects=True)
+    items = [
+        ((5, 5, 15, 15), "RectA"),
+        ((20, 20, 30, 30), "RectB"),
+        ((35, 35, 45, 45), "RectC"),
+    ]
+    for rect, obj in items:
+        rqt.insert(rect, obj=obj)
+
+    data = rqt.to_bytes()
+    rqt2 = RectQuadTree.from_bytes(data)
+
+    assert rqt.count_items() == rqt2.count_items()
+
+    # Check that the objects in the object store are preserved
+    all_rqt2_items = [item.to_dict() for item in rqt2.get_all_items()]
+    all_rqt_items = [item.to_dict() for item in rqt.get_all_items()]
+
+    for item in all_rqt_items:
+        assert item in all_rqt2_items
+
+    assert type(rqt2.get_all_items()[0]) is type(rqt.get_all_items()[0])
+    assert type(rqt2.get_all_items()[0].obj) is type(rqt.get_all_items()[0].obj)
+
+
+def test_serialization_perserves_ids():
+    """Test that serialization and deserialization preserves item ids."""
+    qt = QuadTree((0, 0, 100, 100), capacity=4, track_objects=True)
+    items = [((10, 10), "A"), ((20, 20), "B"), ((30, 30), "C")]
+    for pt, obj in items:
+        qt.insert(pt, obj=obj)
+
+    original_ids = [item.id_ for item in qt.get_all_items()]
+
+    data = qt.to_bytes()
+    qt2 = QuadTree.from_bytes(data)
+
+    deserialized_ids = [item.id_ for item in qt2.get_all_items()]
+
+    assert sorted(original_ids) == sorted(deserialized_ids)
+
+    # Delete id 1
+    qt.delete(1, (20, 20))
+    ids_after_delete = [item.id_ for item in qt.get_all_items()]
+
+    qt3 = QuadTree.from_bytes(qt.to_bytes())
+    ids_after_delete_deserialized = [item.id_ for item in qt3.get_all_items()]
+    assert sorted(ids_after_delete) == [0, 2]
+    assert sorted(ids_after_delete_deserialized) == [0, 2]