trimkit 0.1.0__tar.gz → 0.2.1__tar.gz

{trimkit-0.1.0 → trimkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trimkit
-Version: 0.1.0
+Version: 0.2.1
 Summary: Thin stable-ABI numpy bindings to mature geometry libraries: rays and boxes, collision, triangulation, convex decomposition, UV atlases, simplification, draco and SVG paths.
 Description-Content-Type: text/markdown
 Requires-Python: >=3.12
@@ -52,6 +52,44 @@ Most of the underlying geometry implementations in this package are mature and c
 
 The weekly GitHub Actions compromise and overall threat environment has made the zoo less attractive to maintain. With half a dozen packages there's half-a-dozen places we might have not pinned something; this is an attempt to lint, fuzz, and lock down in one place.
 
+## Example
+
+
+```python
+import trimkit
+import numpy as np
+
+# a tetrahedron
+vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype=np.float64)
+faces = np.array([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]], dtype=np.int64)
+
+# place 2 tetrahedrons
+instance_matrices = np.tile(np.eye(4), (2, 1, 1))
+# translate the second one 0.5 units from the origin
+instance_matrices[1, 0, 3] = 0.5
+# the instance will be 2 copies of mesh `0`
+instance_index = np.zeros(2, dtype=np.int64)
+
+# the constructor takes numpy arrays
+rays = trimkit.RayScene([(vertices, faces)])
+
+# ray queries also take numpy arrays
+origin, direction = np.array([-1.0, 0.2, 0.2]), np.array([1.0, 0.0, 0.0])
+# the scene instancing is per-query
+ray, instance, face, distance = rays.intersect(
+     origin, direction, instance_matrices, instance_index)
+
+# the same constructor arguments work for collisions!
+# convex can be per-mesh or every mesh
+# if you're using trimesh you probably want this as:
+# [m.is_convex for m in meshes]
+# if you say it is, but it isn't, it won't break, just the
+# returned queries will be wrong 
+solids = trimkit.CollisionScene([(vertices, faces)], convex=True)
+touching = solids.collides(matrices, index)
+distances, points, normals = solids.distances(matrices, index)
+```
+
 ## Packaging
 
 This uses a Python script to construct a `ninja` build file from a declarative `TOML` file, and then builds with `clang` and `lld`. Ninja is awesome, and this lets us retire `cmake`. It runs `clang` with profile-guided-optimization, and tries to get everything it can out of performance.
@@ -80,33 +118,6 @@ This does not and will never load meshes, parse XML, or support anything that is
 
 Everything below this line is LLM output.
 
-Rays and collision against the same meshes, placed the same way: one mesh, two
-instances of it, and every query names where they are.
-
-```python
-import numpy as np
-import trimkit
-
-# a tetrahedron, placed twice: where it is, and moved half a unit along x
-vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype=np.float64)
-faces = np.array([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]], dtype=np.int64)
-matrices = np.tile(np.eye(4), (2, 1, 1))
-matrices[1, 0, 3] = 0.5
-index = np.zeros(2, dtype=np.int64)
-
-origin, direction = np.array([-1.0, 0.2, 0.2]), np.array([1.0, 0.0, 0.0])
-rays = trimkit.RayScene([(vertices, faces)])
-ray, instance, face, distance = rays.intersect(origin, direction, matrices, index)
-solids = trimkit.CollisionScene([(vertices, faces)], convex=True)
-touching = solids.collides(matrices, index)
-distances, points, normals = solids.distances(matrices, index)
-```
-
-The ray crosses the two tetrahedra four times (`distance` is `[1.0, 1.5, 1.6,
-2.1]`, `instance` `[0, 1, 0, 1]`), the pair touches (`touching` is `[[0, 1]]`),
-and `distances` says how deep, where and along which direction (`-0.29`, with
-the closest points and the unit normal a planner's gradient is made of).
-
 <!-- api:start -->
 <!-- generated by `uv run scripts generate` from the docstrings and trimkit.toml: don't edit -->
 
@@ -119,7 +130,7 @@ the closest points and the unit normal a planner's gradient is made of).
 | `Boxes` | Axis-aligned boxes built into a BVH for overlap queries: a static, numpy-native replacement for a bulk-loaded R-tree.<br>`tree = trimkit.Boxes(np.array([[[0.0, 0.0], [1.0, 1.0]], [[2.0, 2.0], [3.0, 3.0]]]))` |
 | `Boxes.bounds` | The box around every box.<br>`bounds = tree.bounds` |
 | `Boxes.boxes` | Every box, exactly as given.<br>`boxes = tree.boxes()` |
-| `Boxes.intersect` | Every box overlapping each query box, touching included.<br>`pairs = tree.intersect(np.array([[[0.5, 0.5], [2.5, 2.5]]]))` |
+| `Boxes.intersection` | Every box overlapping one query box or each of many, touching included.<br>`hits = tree.intersection(np.array([0.5, 0.5, 2.5, 2.5]))` |
 | `triangulate` | Triangulate a polygon with holes.<br>`vertices, faces = trimkit.triangulate(exterior)` |
 | `decompose` | Decompose a closed triangle mesh into approximately convex hulls.<br>`hulls = trimkit.decompose(vertices, faces, maximum_hulls=1)` |
 | `parametrize` | Cut a mesh into charts and pack them into a UV atlas.<br>`vertex_sources, faces, uv = trimkit.parametrize(vertices, faces)` |
@@ -169,6 +180,15 @@ pairs) and sparse rows of what was found otherwise (hits, touching pairs,
 overlapping boxes), and `decompose` answers a list of `Mesh`, one per hull. Nothing a
 scene answers ever depends on what it was asked before, so threads can share one.
 
+Every class pickles as exactly the arguments its constructor took, by name:
+`Boxes` its `boxes`, `RayScene` its `meshes` and `use_gpu`, and `CollisionScene`
+its `meshes` and which are `convex`. A pickle holds only numpy arrays and Python
+values, never a BVH or a collision model, so loading one (or a `copy.deepcopy`)
+builds those again, taking as long as the constructor did, and answers bit for
+bit what the original does. It loads into any version of trimkit whose
+constructor takes the same names, and a `RayScene` pickled with `use_gpu=True`
+answers on the CPU, with its one warning, where no device is found.
+
 `RayScene`, `Boxes` and `CollisionScene` queries spread big batches, and
 `decompose` its hull splits and merge costs, across the cores they may run on
 (their affinity, within a cgroup's CPU quota), on one pool of workers that exit

{trimkit-0.1.0 → trimkit-0.2.1}/README.md

@@ -16,6 +16,44 @@ Most of the underlying geometry implementations in this package are mature and c
 
 The weekly GitHub Actions compromise and overall threat environment has made the zoo less attractive to maintain. With half a dozen packages there's half-a-dozen places we might have not pinned something; this is an attempt to lint, fuzz, and lock down in one place.
 
+## Example
+
+
+```python
+import trimkit
+import numpy as np
+
+# a tetrahedron
+vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype=np.float64)
+faces = np.array([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]], dtype=np.int64)
+
+# place 2 tetrahedrons
+instance_matrices = np.tile(np.eye(4), (2, 1, 1))
+# translate the second one 0.5 units from the origin
+instance_matrices[1, 0, 3] = 0.5
+# the instance will be 2 copies of mesh `0`
+instance_index = np.zeros(2, dtype=np.int64)
+
+# the constructor takes numpy arrays
+rays = trimkit.RayScene([(vertices, faces)])
+
+# ray queries also take numpy arrays
+origin, direction = np.array([-1.0, 0.2, 0.2]), np.array([1.0, 0.0, 0.0])
+# the scene instancing is per-query
+ray, instance, face, distance = rays.intersect(
+     origin, direction, instance_matrices, instance_index)
+
+# the same constructor arguments work for collisions!
+# convex can be per-mesh or every mesh
+# if you're using trimesh you probably want this as:
+# [m.is_convex for m in meshes]
+# if you say it is, but it isn't, it won't break, just the
+# returned queries will be wrong 
+solids = trimkit.CollisionScene([(vertices, faces)], convex=True)
+touching = solids.collides(matrices, index)
+distances, points, normals = solids.distances(matrices, index)
+```
+
 ## Packaging
 
 This uses a Python script to construct a `ninja` build file from a declarative `TOML` file, and then builds with `clang` and `lld`. Ninja is awesome, and this lets us retire `cmake`. It runs `clang` with profile-guided-optimization, and tries to get everything it can out of performance.
@@ -44,33 +82,6 @@ This does not and will never load meshes, parse XML, or support anything that is
 
 Everything below this line is LLM output.
 
-Rays and collision against the same meshes, placed the same way: one mesh, two
-instances of it, and every query names where they are.
-
-```python
-import numpy as np
-import trimkit
-
-# a tetrahedron, placed twice: where it is, and moved half a unit along x
-vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype=np.float64)
-faces = np.array([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]], dtype=np.int64)
-matrices = np.tile(np.eye(4), (2, 1, 1))
-matrices[1, 0, 3] = 0.5
-index = np.zeros(2, dtype=np.int64)
-
-origin, direction = np.array([-1.0, 0.2, 0.2]), np.array([1.0, 0.0, 0.0])
-rays = trimkit.RayScene([(vertices, faces)])
-ray, instance, face, distance = rays.intersect(origin, direction, matrices, index)
-solids = trimkit.CollisionScene([(vertices, faces)], convex=True)
-touching = solids.collides(matrices, index)
-distances, points, normals = solids.distances(matrices, index)
-```
-
-The ray crosses the two tetrahedra four times (`distance` is `[1.0, 1.5, 1.6,
-2.1]`, `instance` `[0, 1, 0, 1]`), the pair touches (`touching` is `[[0, 1]]`),
-and `distances` says how deep, where and along which direction (`-0.29`, with
-the closest points and the unit normal a planner's gradient is made of).
-
 <!-- api:start -->
 <!-- generated by `uv run scripts generate` from the docstrings and trimkit.toml: don't edit -->
 
@@ -83,7 +94,7 @@ the closest points and the unit normal a planner's gradient is made of).
 | `Boxes` | Axis-aligned boxes built into a BVH for overlap queries: a static, numpy-native replacement for a bulk-loaded R-tree.<br>`tree = trimkit.Boxes(np.array([[[0.0, 0.0], [1.0, 1.0]], [[2.0, 2.0], [3.0, 3.0]]]))` |
 | `Boxes.bounds` | The box around every box.<br>`bounds = tree.bounds` |
 | `Boxes.boxes` | Every box, exactly as given.<br>`boxes = tree.boxes()` |
-| `Boxes.intersect` | Every box overlapping each query box, touching included.<br>`pairs = tree.intersect(np.array([[[0.5, 0.5], [2.5, 2.5]]]))` |
+| `Boxes.intersection` | Every box overlapping one query box or each of many, touching included.<br>`hits = tree.intersection(np.array([0.5, 0.5, 2.5, 2.5]))` |
 | `triangulate` | Triangulate a polygon with holes.<br>`vertices, faces = trimkit.triangulate(exterior)` |
 | `decompose` | Decompose a closed triangle mesh into approximately convex hulls.<br>`hulls = trimkit.decompose(vertices, faces, maximum_hulls=1)` |
 | `parametrize` | Cut a mesh into charts and pack them into a UV atlas.<br>`vertex_sources, faces, uv = trimkit.parametrize(vertices, faces)` |
@@ -133,6 +144,15 @@ pairs) and sparse rows of what was found otherwise (hits, touching pairs,
 overlapping boxes), and `decompose` answers a list of `Mesh`, one per hull. Nothing a
 scene answers ever depends on what it was asked before, so threads can share one.
 
+Every class pickles as exactly the arguments its constructor took, by name:
+`Boxes` its `boxes`, `RayScene` its `meshes` and `use_gpu`, and `CollisionScene`
+its `meshes` and which are `convex`. A pickle holds only numpy arrays and Python
+values, never a BVH or a collision model, so loading one (or a `copy.deepcopy`)
+builds those again, taking as long as the constructor did, and answers bit for
+bit what the original does. It loads into any version of trimkit whose
+constructor takes the same names, and a `RayScene` pickled with `use_gpu=True`
+answers on the CPU, with its one warning, where no device is found.
+
 `RayScene`, `Boxes` and `CollisionScene` queries spread big batches, and
 `decompose` its hull splits and merge costs, across the cores they may run on
 (their affinity, within a cgroup's CPU quota), on one pool of workers that exit

{trimkit-0.1.0 → trimkit-0.2.1}/bench/versus.py

@@ -148,7 +148,7 @@ row(
     "trimkit.Boxes",
     "rtree",
     rtree_both,
-    lambda: trimkit.Boxes(bounds).intersect(queries),
+    lambda: trimkit.Boxes(bounds).intersection(queries),
     repeat=2,
     note="build 100k boxes, query 20k",
 )

{trimkit-0.1.0 → trimkit-0.2.1}/pyproject.toml

@@ -8,7 +8,7 @@ backend-path = ["scripts"]
 
 [project]
 name = "trimkit"
-version = "0.1.0"
+version = "0.2.1"
 description = "Thin stable-ABI numpy bindings to mature geometry libraries: rays and boxes, collision, triangulation, convex decomposition, UV atlases, simplification, draco and SVG paths."
 readme = "README.md"
 requires-python = ">=3.12"

{trimkit-0.1.0 → trimkit-0.2.1}/src/bvh.cpp

@@ -63,6 +63,8 @@ using FacesArg = trimkit::Array<std::int64_t, -1, 3>;
 using BoundsArg = trimkit::Array<double, -1, 2, -1>;
 using Bounds = trimkit::In<double, -1, 2, -1>;
 
+using BoxQueriesArgument = trimkit::BoxQueriesArgument;
+
 // A BVH as tinybvh builds it, with its test of a ray against one known
 // triangle callable: tinybvh keeps that protected, and every hit of
 // `intersect` is measured with it
@@ -265,7 +267,7 @@ public:
     RayScene(const RayScene&) = delete;
     RayScene& operator=(const RayScene&) = delete;
 
-    RayScene(const trimkit::Meshes& meshes, trimkit::Flag use_gpu) {
+    RayScene(const trimkit::Meshes& meshes, trimkit::Flag use_gpu) : use_gpu_(use_gpu.value) {
         std::vector<trimkit::Mesh<std::uint64_t>> read = trimkit::read_meshes<std::uint64_t>(meshes);
         meshes_.resize(read.size());
         blas_.resize(read.size());
@@ -296,6 +298,28 @@ public:
 
     std::size_t size() const { return meshes_.size(); }
 
+    // pickled as its meshes, exactly as it holds them, and `use_gpu` as asked:
+    // a load without a device answers on the CPU, as a build without one does
+    nb::dict constructor_arguments() const {
+        nb::list meshes;
+        for (const std::unique_ptr<RayMesh>& mesh : meshes_) {
+            const std::vector<Vec>& points = mesh->vertices();
+            std::vector<double> vertices(3 * points.size());
+            for (std::size_t i = 0; i < points.size(); i++) {
+                for (std::size_t axis = 0; axis < 3; axis++) {
+                    vertices[(3 * i) + axis] = points[i][static_cast<std::int32_t>(axis)];
+                }
+            }
+            std::vector<std::uint64_t> faces = mesh->faces();
+            meshes.append(nb::make_tuple(trimkit::to_numpy_rows(std::move(vertices), {3}),
+                                         trimkit::to_numpy_rows<std::int64_t>(std::move(faces), {3})));
+        }
+        const nb::dict arguments;
+        arguments["meshes"] = meshes;
+        arguments["use_gpu"] = use_gpu_;
+        return arguments;
+    }
+
     trimkit::Out<bool> intersect_any(const RaysArg& origins_argument, const RaysArg& directions_argument,
                                      const trimkit::InstanceMatrices& matrices_argument,
                                      const trimkit::InstanceIndex& index_argument) const {
@@ -729,6 +753,8 @@ private:
     static constexpr double RELATIVE_STEP = 9.094947017729282e-13;  // 2^-40
 
     std::vector<std::unique_ptr<RayMesh>> meshes_;
+    // whether it was asked to trace on a device, which a pickle asks again
+    bool use_gpu_ = false;
     // each mesh's BVH, or null without faces, as every top level indexes them
     std::vector<tinybvh::BVH_Double*> blas_;
     // the top level last built, swapped whole: a query keeps the one it read.
@@ -757,7 +783,7 @@ public:
                                  ")");
         }
         const nb::gil_scoped_release release;
-        build(corners_of(boxes, "boxes"));
+        build(corners_of(boxes.data(), boxes.shape(0), "boxes"));
     }
 
     // 3D boxes as (minimum, maximum) corner pairs, already checked
@@ -768,6 +794,13 @@ public:
 
     std::size_t size() const { return boxes_.size() / 2; }
 
+    // pickled as the boxes it was built from
+    nb::dict constructor_arguments() const {
+        const nb::dict arguments;
+        arguments["boxes"] = boxes();
+        return arguments;
+    }
+
     // the box around every box: (2, d), or +inf then -inf with none
     trimkit::Out<double> bounds() const {
         std::vector<double> bounds(2 * dimension_);
@@ -796,22 +829,29 @@ public:
         return trimkit::to_numpy_rows(std::move(boxes), {2, dimension_});
     }
 
-    trimkit::Out<std::int64_t> intersect(const BoundsArg& queries_argument) const {
-        const Bounds queries = trimkit::read(queries_argument, "queries");
-        if (dimension_of(queries) != dimension_) {
-            trimkit::value_error("queries must have the boxes' dimension, " + std::to_string(dimension_));
-        }
-        const std::size_t n = queries.shape(0);
-        const std::vector<Vec> boxes = corners_of(queries, "queries");
-        // [query, box] rows, in query order
+    // every box overlapping each query, touching included like rtree: one
+    // query, (2d,) or (2, d), answers its sorted boxes, (n,), and many,
+    // (q, 2d) or (q, 2, d), their [query, box] rows, (k, 2). Every form is
+    // (q, 2, d) in memory, so they read as it and share one traversal; the
+    // last extent tells the layouts apart, as 2d is never d
+    trimkit::Out<std::int64_t> intersection(const BoxQueriesArgument& argument) const {
+        const trimkit::BoxQueries queries = trimkit::read_box_queries(argument, dimension_, "queries");
+        return answer(queries.data, queries.count, queries.one);
+    }
+
+private:
+    // `count` queries of (2, d) corners at `data`: their sorted boxes for
+    // `one` query, else [query, box] rows in query order
+    trimkit::Out<std::int64_t> answer(const double* data, std::size_t count, bool one) const {
+        const std::vector<Vec> corners = corners_of(data, count, "queries");
         trimkit::Gathered<std::int64_t> pairs;
         trimkit::gather_in_parallel<std::int64_t>(
-            n, &pairs, [&](std::size_t begin, std::size_t end, std::vector<std::int64_t>& rows) {
+            count, &pairs, [&](std::size_t begin, std::size_t end, std::vector<std::int64_t>& rows) {
                 Stack stack = make_stack();
                 std::vector<std::int64_t> boxes_hit;
                 for (std::size_t q = begin; q < end; q++) {
                     boxes_hit.clear();
-                    overlapping(boxes[2 * q], boxes[(2 * q) + 1], stack,
+                    overlapping(corners[2 * q], corners[(2 * q) + 1], stack,
                                 [&](std::uint64_t box) { boxes_hit.push_back(static_cast<std::int64_t>(box)); });
                     // ascending boxes, so the same query always reads the same
                     std::sort(boxes_hit.begin(), boxes_hit.end());
@@ -821,10 +861,19 @@ public:
                     }
                 }
             });
-        return trimkit::to_numpy_rows<std::int64_t>(trimkit::gathered_rows(pairs), {2});
+        auto rows = trimkit::gathered_rows(pairs);
+        if (!one) {
+            return trimkit::to_numpy_rows<std::int64_t>(std::move(rows), {2});
+        }
+        // one query: its column of boxes
+        const std::int64_t* row = trimkit::elements(rows);
+        std::vector<std::int64_t> boxes(rows.size() / 2);
+        for (std::size_t i = 0; i < boxes.size(); i++) {
+            boxes[i] = row[(2 * i) + 1];
+        }
+        return trimkit::to_numpy(std::move(boxes), {boxes.size()});
     }
 
-private:
     void build(std::vector<Vec>&& corners) {
         boxes_ = std::move(corners);
         for (std::size_t corner = 0; corner < boxes_.size(); corner += 2) {
@@ -844,11 +893,10 @@ private:
         return bounds.ndim() == 3 ? bounds.shape(2) : 0;
     }
 
-    // (min, max) corner pairs as 3D points, each pair checked to be ordered
-    std::vector<Vec> corners_of(const trimkit::In<double, -1, 2, -1>& bounds, const char* name) const {
-        const std::size_t n = bounds.shape(0);
+    // `n` (min, max) corner pairs of the boxes' dimension at `b`, as 3D
+    // points, each pair checked to be ordered
+    std::vector<Vec> corners_of(const double* b, std::size_t n, const char* name) const {
         const std::size_t d = dimension_;
-        const double* b = bounds.data();
         std::vector<Vec> corners(2 * n);
         for (std::size_t i = 0; i < n; i++) {
             const double* lo = b + (2 * d * i);
@@ -922,8 +970,8 @@ trimkit::BoxesObject trimkit::scene_boxes(const std::vector<double>& boxes) {
 void bind_bvh(nb::module_& m) {
     tinybvh::tinybvh_set_fatal_error_handler(throw_tinybvh_error);
 
-    nb::class_<RayScene>(m, "RayScene",
-                         R"(Meshes, each built once into a double precision BVH, and the only
+    trimkit::picklable_class<RayScene>(m, "RayScene",
+                                       R"(Meshes, each built once into a double precision BVH, and the only
 thing rays are cast against.
 
 Every query names its instances (which mesh, placed where), as a
@@ -1074,8 +1122,8 @@ Examples
 >>> hits.tolist()
 [True])");
 
-    nb::class_<Boxes>(m, "Boxes",
-                      R"(Axis-aligned boxes built into a BVH for overlap queries: a static,
+    trimkit::picklable_class<Boxes>(m, "Boxes",
+                                    R"(Axis-aligned boxes built into a BVH for overlap queries: a static,
 numpy-native replacement for a bulk-loaded R-tree.
 
 Parameters
@@ -1131,26 +1179,34 @@ Examples
 >>> boxes = tree.boxes()
 >>> boxes.shape
 (2, 2, 2))")
-        .def("intersect", &Boxes::intersect, nb::arg("queries"),
-             R"(Every box overlapping each query box, touching included.
+        .def("intersection", &Boxes::intersection, nb::arg("queries"),
+             R"(Every box overlapping one query box or each of many, touching included.
+
+A superset of an R-tree's `intersection`: one query box, flat as
+(min..., max...) or as its two corners, answers the boxes it overlaps,
+and a batch of either answers every overlap at once.
 
 Parameters
 ----------
-queries : (m, 2, d) float64
-  Each query's minimum and maximum corner, in the boxes' dimension.
+queries : (2d,), (2, d), (m, 2d) or (m, 2, d) float64
+  One query's or each query's minimum and maximum corner, in the
+  boxes' dimension d: flat, (min..., max...), or as two corners.
 
 Returns
 -------
-pairs : (k, 2) int64
-  Rows of [query, box] for every overlap, sorted by query
-  and then box.
+hits : (n,) or (k, 2) int64
+  For one query, every box it overlaps, ascending. For many,
+  rows of [query, box] for every overlap, sorted by query and
+  then box.
 
 Examples
 --------
 >>> import numpy as np
 >>> import trimkit
 >>> tree = trimkit.Boxes(np.array([[[0.0, 0.0], [1.0, 1.0]], [[2.0, 2.0], [3.0, 3.0]]]))
->>> pairs = tree.intersect(np.array([[[0.5, 0.5], [2.5, 2.5]]]))
->>> pairs.tolist()
+>>> hits = tree.intersection(np.array([0.5, 0.5, 2.5, 2.5]))
+>>> hits.tolist()
+[0, 1]
+>>> tree.intersection(np.array([[[0.5, 0.5], [2.5, 2.5]]])).tolist()
 [[0, 0], [0, 1]])");
 }

{trimkit-0.1.0 → trimkit-0.2.1}/src/collision.cpp

@@ -82,9 +82,33 @@ public:
         if (face_count_ > 0) {
             const nb::gil_scoped_release release;
             build(mesh.vertices.data(), mesh.vertices.shape(0), mesh.faces, convex);
+        } else {
+            // no model holds them, so a pickle can still give them back
+            loose_vertices_.assign(mesh.vertices.data(), mesh.vertices.data() + (3 * mesh.vertices.shape(0)));
         }
     }
 
+    // the mesh as it was given: the model's own copy, in the order given
+    nb::tuple as_given() const {
+        std::vector<double> vertices = loose_vertices_;
+        std::vector<std::int64_t> faces(3 * face_count_);
+        if (model_) {
+            vertices.resize(3 * model_->vertices->size());
+            for (std::size_t i = 0; i < model_->vertices->size(); i++) {
+                for (std::size_t axis = 0; axis < 3; axis++) {
+                    vertices[(3 * i) + axis] = (*model_->vertices)[i][static_cast<Eigen::Index>(axis)];
+                }
+            }
+            for (std::size_t f = 0; f < face_count_; f++) {
+                for (std::size_t corner = 0; corner < 3; corner++) {
+                    faces[(3 * f) + corner] = (*model_->tri_indices)[f][static_cast<std::uint32_t>(corner)];
+                }
+            }
+        }
+        return nb::make_tuple(trimkit::to_numpy_rows(std::move(vertices), {3}),
+                              trimkit::to_numpy_rows(std::move(faces), {3}));
+    }
+
     std::size_t size() const { return face_count_; }
     bool empty() const { return face_count_ == 0; }
     const Model& model() const { return *model_; }
@@ -123,6 +147,8 @@ private:
     }
 
     std::size_t face_count_ = 0;
+    // the vertices of a mesh without faces, which no model holds
+    std::vector<double> loose_vertices_;
     std::array<double, 6> box_{};
     std::shared_ptr<Model> model_;
     std::unique_ptr<Convex> convex_;
@@ -360,6 +386,21 @@ public:
 
     std::size_t size() const { return meshes_.size(); }
 
+    // pickled as its meshes as given and which of them are convex
+    nb::dict constructor_arguments() const {
+        nb::list meshes;
+        std::vector<std::uint8_t> convex(meshes_.size());
+        for (std::size_t i = 0; i < meshes_.size(); i++) {
+            meshes.append(meshes_[i]->as_given());
+            convex[i] = meshes_[i]->convex() != nullptr ? 1 : 0;
+        }
+        const std::size_t count = convex.size();
+        const nb::dict arguments;
+        arguments["meshes"] = meshes;
+        arguments["convex"] = trimkit::to_numpy<bool>(std::move(convex), {count});
+        return arguments;
+    }
+
     trimkit::Out<std::int64_t> collides(const trimkit::InstanceMatrices& matrices_argument,
                                         const trimkit::InstanceIndex& index_argument, const PairsArg& pairs_argument,
                                         trimkit::Number<double> margin_argument) const {
@@ -593,8 +634,8 @@ private:
 }  // namespace
 
 void bind_collision(nb::module_& m) {
-    nb::class_<CollisionScene>(m, "CollisionScene",
-                               R"(Meshes to place and query against each other. A scene never changes:
+    trimkit::picklable_class<CollisionScene>(m, "CollisionScene",
+                                             R"(Meshes to place and query against each other. A scene never changes:
 each query names its own instances, so threads may share one.
 
 Every query takes its instances (which mesh, placed where) and the pairs

{trimkit-0.1.0 → trimkit-0.2.1}/src/common.hpp

@@ -21,6 +21,8 @@
 #include <memory>
 #include <string>
 #include <thread>
+#include <type_traits>
+#include <utility>
 #include <vector>
 
 // Each part of the one extension, src/PART.cpp, adds its functions and
@@ -475,6 +477,34 @@ inline Instances read_instances(const InstanceViews& views, std::size_t mesh_cou
     return instances;
 }
 
+// A bound class whose objects pickle, the only way the package binds one.
+// `T` says what it pickles as with `nb::dict constructor_arguments() const`:
+// its constructor's arguments, by their names, from which a load builds it
+// again (a compile error without it). Never an acceleration structure, which
+// is rebuilt: a pickle holds only arrays and Python values, named, so it loads
+// into any build whose constructor takes the same names.
+// tests/test_invariants.py round-trips every class the package binds
+template <typename T>
+nb::class_<T> picklable_class(nb::module_& m, const char* name, const char* doc) {
+    static_assert(std::is_same_v<decltype(std::declval<const T&>().constructor_arguments()), nb::dict>,
+                  "a bound class must say what it pickles as: nb::dict constructor_arguments() const");
+    nb::class_<T> bound(m, name, doc);
+    bound.def(
+        "__reduce__",
+        [](nb::handle self) {
+            const nb::dict arguments = nb::cast<const T&>(self).constructor_arguments();
+            const nb::object partial = nb::module_::import_("functools").attr("partial");
+            return nb::make_tuple(partial(nb::borrow(self.type()), **arguments), nb::make_tuple());
+        },
+        R"(Pickle as its constructor's arguments, by name: anything built from them is built again on load.
+
+Returns
+-------
+reduced : tuple
+  Its constructor with those arguments bound, as pickle and copy call it.)");
+    return bound;
+}
+
 }  // namespace trimkit
 
 // `BoxesObject` returns its object, shown as `Boxes`

{trimkit-0.1.0 → trimkit-0.2.1}/src/numpy.hpp

@@ -88,6 +88,24 @@ struct RaysArgument {
     nb::handle object;
 };
 
+// Boxes' queries as an argument: (2d,) or (2, d) for one query, (q, 2d) or
+// (q, 2, d) for many, each (q, 2, d) in memory. `read_box_queries` reads it,
+// and the signature shows each array shape it takes
+struct BoxQueriesArgument {
+    nb::handle object;
+};
+
+// What `read_box_queries` read: `count` queries of a minimum and a maximum
+// corner at `data`, each `dimension` float64, and whether it was given as
+// `one` query rather than a batch. Valid while it is: it holds the argument,
+// or its one copy
+struct BoxQueries {
+    AnyIn held;
+    const double* data = nullptr;
+    std::size_t count = 0;
+    bool one = false;
+};
+
 // What `read_rays` read: `count` rows of three, or one row that is every
 // ray's (`one`, with a count of 1), float64 or, for a float32 array taken as
 // it is, float32. Valid while it is: it holds the argument, or its one copy
@@ -424,6 +442,47 @@ inline void check_rays(const Rays& rays, const std::string& name) {
     }
 }
 
+// A box queries argument for boxes of `dimension`: one query, (2d,) flat as
+// (min..., max...) or (2, d) as two corners, or many, (q, 2d) or (q, 2, d),
+// told apart by the last extent as 2d is never d. Read as `read` takes any
+// array: its shape checked first, in place when exactly float64, else one
+// copy, converted with the warning when its dtype isn't, and its values
+// checked. Any other shape is the wrong type, as every argument's is
+inline BoxQueries read_box_queries(const BoxQueriesArgument& argument, std::size_t dimension, const std::string& name) {
+    // its shape as numpy sees it: none when it isn't array-like at all
+    const nb::object seen = detail::seen_as_array(argument.object);
+    std::vector<std::size_t> extents;
+    if (seen.is_valid()) {
+        for (const nb::handle extent : nb::borrow<nb::tuple>(seen.attr("shape"))) {
+            extents.push_back(nb::cast<std::size_t>(extent));
+        }
+    }
+    const std::size_t last = extents.empty() ? 0 : extents.back();
+    BoxQueries queries;
+    queries.one =
+        (extents.size() == 1 && last == 2 * dimension) || (extents.size() == 2 && extents[0] == 2 && last == dimension);
+    const bool many =
+        (extents.size() == 2 && last == 2 * dimension) || (extents.size() == 3 && extents[1] == 2 && last == dimension);
+    bool taken = false;
+    if (queries.one || many) {
+        taken = detail::any_readable(argument.object, &queries.held) && queries.held.dtype() == nb::dtype<double>();
+        if (!taken) {
+            const nb::object copy = detail::relaid(argument.object, seen, "float64", name);
+            taken = copy.is_valid() && detail::any_readable(copy, &queries.held) &&
+                    queries.held.dtype() == nb::dtype<double>();
+        }
+    }
+    if (!taken) {
+        type_error(name + " must be float64 of shape (" + std::to_string(2 * dimension) + ",) or (2, " +
+                   std::to_string(dimension) + ") for one query, or (*, " + std::to_string(2 * dimension) +
+                   ") or (*, 2, " + std::to_string(dimension) + ") for many, not " + describe(argument.object));
+    }
+    queries.data = static_cast<const double*>(queries.held.data());
+    queries.count = queries.one ? 1 : extents[0];
+    check_values(queries.data, 2 * dimension * queries.count, COORDINATE_LIMIT, name);
+    return queries;
+}
+
 // An array argument viewed: its dtype, shape and layout as `read` checks
 // them, its values not looked at. For what copies the values and checks the
 // copy (a query's instances)
@@ -719,6 +778,16 @@ struct rays_shown {
 template <>
 struct type_caster<trimkit::RaysArgument> : passed_through<trimkit::RaysArgument, rays_shown> {};
 
+// `BoxQueriesArgument` shows up as each array shape it reads
+struct box_queries_shown {
+    // NOLINTNEXTLINE(readability-identifier-naming): the name nanobind reads
+    static constexpr auto Name = make_caster<trimkit::In<double, -1>>::Name + const_name(" | ") +
+                                 make_caster<trimkit::In<double, -1, -1>>::Name + const_name(" | ") +
+                                 make_caster<trimkit::In<double, -1, 2, -1>>::Name;
+};
+template <>
+struct type_caster<trimkit::BoxQueriesArgument> : passed_through<trimkit::BoxQueriesArgument, box_queries_shown> {};
+
 // `MeshArgument` shows up as the `Mesh` alias
 struct mesh_shown {
     // NOLINTNEXTLINE(readability-identifier-naming): the name nanobind reads