conquer3d 0.7.6__tar.gz → 0.7.8__tar.gz

conquer3d-0.7.8/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: conquer3d
+Version: 0.7.8
+Summary: Geometric Cuda Tool Box
+Author-email: Do Hoang Khoi <khoido8899@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KhoiDOO/conquer3d
+Project-URL: Repository, https://github.com/KhoiDOO/conquer3d.git
+Project-URL: Documentation, https://github.com/KhoiDOO/conquer3d#readme
+Project-URL: Issues, https://github.com/KhoiDOO/conquer3d/issues
+Keywords: geometry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: trimesh
+Requires-Dist: tqdm
+Requires-Dist: gdown
+Provides-Extra: cuda
+Requires-Dist: cuda-toolkit==12.8.2; extra == "cuda"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Dynamic: license-file
+
+<div align="center">
+
+# ⚡ Conquer3D
+
+### *High-Performance GPU-Accelerated Differentiable Geometry, Spatial Computing & Neural Rendering Toolbox*
+
+[![Documentation](https://img.shields.io/badge/📖_Documentation-conquer3d-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/)
+[![PyPI Version](https://img.shields.io/pypi/v/conquer3d.svg?color=blue&style=for-the-badge)](https://pypi.org/project/conquer3d/)
+[![Docker Image](https://img.shields.io/badge/Docker-kohido%2Fconquer3d-2496ED?logo=docker&logoColor=white&style=for-the-badge)](https://hub.docker.com/r/kohido/conquer3d)
+[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+
+[![Python Version](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white&style=for-the-badge)](https://www.python.org/)
+[![CUDA](https://img.shields.io/badge/CUDA-12.0%2B-76B900?logo=nvidia&logoColor=white&style=for-the-badge)](https://developer.nvidia.com/cuda-toolkit)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C?logo=pytorch&logoColor=white&style=for-the-badge)](https://pytorch.org/)
+[![API Coverage](https://img.shields.io/badge/API_docs-1020_symbols_·_100%25-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/api/index.html)
+
+<p align="center">
+  <b><a href="https://khoidoo.github.io/conquer3d/">🌐 Website</a></b> •
+  <a href="https://khoidoo.github.io/conquer3d/documentation.html">Guide</a> •
+  <a href="https://khoidoo.github.io/conquer3d/api/index.html">API Reference</a> •
+  <a href="https://khoidoo.github.io/conquer3d/benchmarks.html">Benchmarks</a> •
+  <a href="#-qualitative-results">Results</a> •
+  <a href="#-installation">Installation</a>
+</p>
+
+</div>
+
+---
+
+> [!NOTE]
+> The API documentation and the [documentation website](https://khoidoo.github.io/conquer3d/)
+> were written with [Claude](https://claude.ai/code). The library itself — every CUDA kernel,
+> data structure and operator — is the author's own work.
+
+---
+
+## 🌟 Overview
+
+**Conquer3D** is an ultra-fast, GPU-native computational geometry and differentiable spatial computing library engineered in **PyTorch and CUDA**. Designed from the ground up for 3D computer vision, generative AI, neural surface reconstruction, and differentiable rendering, **Conquer3D** delivers up to **~1.3 Billion faces/second** isosurface extraction, exact CAD sharp crease preservation, and memory-efficient spatial acceleration structures.
+
+Every operator consumes and produces PyTorch tensors **in place** — no host round-trip, no format conversion — so meshing a field is an operation *inside* a training step rather than a preprocessing stage around it.
+
+```bash
+pip install -U conquer3d
+```
+
+```python
+import torch
+from conquer3d.data_structure import create_voxel_grid
+from conquer3d.ops import dmc
+
+grid_vertices, voxels, _ = create_voxel_grid(
+    grid_min=[-1.0] * 3, grid_max=[1.0] * 3, res=[64, 64, 64], device="cuda"
+)
+
+sdf = (torch.norm(grid_vertices, dim=-1) - 0.6).requires_grad_(True)
+verts, faces = dmc(grid_vertices, voxels, sdf, iso=0.0)
+
+verts.sum().backward()          # gradients flow back into the field
+```
+
+---
+
+## 🔬 Qualitative Results
+
+Every figure below is real library output on the bundled benchmark assets, regenerated
+by `docs/_figures/make_figures.py` — nothing is mocked or hand-drawn. More, at full size,
+on the **[showcase](https://khoidoo.github.io/conquer3d/)**.
+
+### Isosurface extraction
+
+<img src="docs/assets/img/fig-algorithms.webp" alt="Five extractors on one signed distance field" width="100%">
+
+One signed distance field on a 64³ narrow-band grid of 19,329 cells, meshed by five
+extractors, with the source mesh on the left. The lower row crops the crease where
+Marching Cubes and Dual Contouring disagree most.
+
+### Sharp features from Hermite data
+
+<img src="docs/assets/img/fig-hermite.webp" alt="Dual methods with and without Hermite data" width="100%">
+
+Dual Contouring and Dual Marching Cubes run twice each: once with normals interpolated
+from the grid, once with exact Hermite data from `compute_hermite_from_mesh`, which
+ray-casts all 25,832 sign-crossing edges for the true intersection and face normal.
+The crease is reconstructed rather than rounded.
+
+### Detail is a resolution dial
+
+<img src="docs/assets/img/fig-resolution.webp" alt="Resolution ladder from 64 to 2048 cubed" width="100%">
+
+Dual Marching Cubes on the Armadillo at seven grid resolutions from 64³ to 2048³.
+Face count runs from 12,076 to 13,294,500, with Chamfer and Hausdorff distance to the
+source measured at every step.
+
+### From mesh to surface, step by step
+
+<img src="docs/assets/img/fig-pipeline.webp" alt="Sparse grid construction and extraction" width="100%">
+
+The input mesh, the narrow-band cells allocated around it (7,863 of a possible 64,000
+at 40³), the signed distance shown as a cutaway, the 2,646 bipolar cells, and the
+extracted surface. No dense volume is ever held.
+
+### Six ways to decide inside
+
+<img src="docs/assets/img/fig-sign-modes.webp" alt="Six sign determination modes" width="100%">
+
+One axial slice signed by each of the six sign modes and contoured at zero — ray parity,
+pseudonormal, winding number, flood fill, hybrid consensus, and coarse-fine fill.
+
+### Ray queries against the hierarchies
+
+<img src="docs/assets/img/fig-meshbvh.webp" alt="Ray-triangle and ray-voxel queries" width="100%">
+
+`MeshBVH.get_ray_intersection` returns the triangles a ray pierces; `BVH.query_ray`
+returns the narrow-band cells it crosses. Five rays from five origins, each drawn as far
+as its own first hit.
+
+---
+
+## ⚡ Benchmarks
+
+*RTX 4090, torch 2.8.0+cu128, CUDA 12.8. Fandisk at $1024^3$ (5.15M active cells).
+CUDA events around the operator alone, median of 7 runs after 2 warm-ups.*
+
+| Algorithm | Output | Vertices | Faces | Latency | Throughput |
+| :--- | :--- | ---: | ---: | ---: | ---: |
+| **Dual Marching Cubes** | Triangles | 1,716,384 | 3,432,764 | **2.62 ms** | **1,311M faces/s** |
+| DMC (pure quads) | Quads | 1,716,384 | 1,716,382 | 2.51 ms | 684M quads/s |
+| MC Asymptotic | Triangles | 1,716,382 | 3,432,760 | 2.71 ms | 1,267M faces/s |
+| Dual Contouring | Triangles | 1,716,384 | 3,432,764 | 3.88 ms | 884M faces/s |
+| Marching Cubes | Triangles | 1,716,382 | 3,432,760 | 7.90 ms | 434M faces/s |
+| Marching Tetrahedra | Triangles | 6,113,918 | 12,227,832 | 44.90 ms | 272M faces/s |
+
+Sign-mode costs, distance-operator throughput, pipeline breakdown and memory scaling are
+on the **[benchmarks page](https://khoidoo.github.io/conquer3d/benchmarks.html)**.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install -U conquer3d
+```
+
+Building from source, the full feature list, worked pipelines and the 1,020-symbol API
+reference are on the **[documentation site](https://khoidoo.github.io/conquer3d/documentation.html)**.
+
+---
+
+## 📄 License
+
+Conquer3D is licensed under the [MIT License](LICENSE).
+
+<div align="center">
+<sub>Built with CUDA and PyTorch · <a href="https://khoidoo.github.io/conquer3d/">khoidoo.github.io/conquer3d</a></sub>
+</div>

conquer3d-0.7.8/README.md

@@ -0,0 +1,156 @@
+<div align="center">
+
+# ⚡ Conquer3D
+
+### *High-Performance GPU-Accelerated Differentiable Geometry, Spatial Computing & Neural Rendering Toolbox*
+
+[![Documentation](https://img.shields.io/badge/📖_Documentation-conquer3d-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/)
+[![PyPI Version](https://img.shields.io/pypi/v/conquer3d.svg?color=blue&style=for-the-badge)](https://pypi.org/project/conquer3d/)
+[![Docker Image](https://img.shields.io/badge/Docker-kohido%2Fconquer3d-2496ED?logo=docker&logoColor=white&style=for-the-badge)](https://hub.docker.com/r/kohido/conquer3d)
+[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+
+[![Python Version](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white&style=for-the-badge)](https://www.python.org/)
+[![CUDA](https://img.shields.io/badge/CUDA-12.0%2B-76B900?logo=nvidia&logoColor=white&style=for-the-badge)](https://developer.nvidia.com/cuda-toolkit)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C?logo=pytorch&logoColor=white&style=for-the-badge)](https://pytorch.org/)
+[![API Coverage](https://img.shields.io/badge/API_docs-1020_symbols_·_100%25-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/api/index.html)
+
+<p align="center">
+  <b><a href="https://khoidoo.github.io/conquer3d/">🌐 Website</a></b> •
+  <a href="https://khoidoo.github.io/conquer3d/documentation.html">Guide</a> •
+  <a href="https://khoidoo.github.io/conquer3d/api/index.html">API Reference</a> •
+  <a href="https://khoidoo.github.io/conquer3d/benchmarks.html">Benchmarks</a> •
+  <a href="#-qualitative-results">Results</a> •
+  <a href="#-installation">Installation</a>
+</p>
+
+</div>
+
+---
+
+> [!NOTE]
+> The API documentation and the [documentation website](https://khoidoo.github.io/conquer3d/)
+> were written with [Claude](https://claude.ai/code). The library itself — every CUDA kernel,
+> data structure and operator — is the author's own work.
+
+---
+
+## 🌟 Overview
+
+**Conquer3D** is an ultra-fast, GPU-native computational geometry and differentiable spatial computing library engineered in **PyTorch and CUDA**. Designed from the ground up for 3D computer vision, generative AI, neural surface reconstruction, and differentiable rendering, **Conquer3D** delivers up to **~1.3 Billion faces/second** isosurface extraction, exact CAD sharp crease preservation, and memory-efficient spatial acceleration structures.
+
+Every operator consumes and produces PyTorch tensors **in place** — no host round-trip, no format conversion — so meshing a field is an operation *inside* a training step rather than a preprocessing stage around it.
+
+```bash
+pip install -U conquer3d
+```
+
+```python
+import torch
+from conquer3d.data_structure import create_voxel_grid
+from conquer3d.ops import dmc
+
+grid_vertices, voxels, _ = create_voxel_grid(
+    grid_min=[-1.0] * 3, grid_max=[1.0] * 3, res=[64, 64, 64], device="cuda"
+)
+
+sdf = (torch.norm(grid_vertices, dim=-1) - 0.6).requires_grad_(True)
+verts, faces = dmc(grid_vertices, voxels, sdf, iso=0.0)
+
+verts.sum().backward()          # gradients flow back into the field
+```
+
+---
+
+## 🔬 Qualitative Results
+
+Every figure below is real library output on the bundled benchmark assets, regenerated
+by `docs/_figures/make_figures.py` — nothing is mocked or hand-drawn. More, at full size,
+on the **[showcase](https://khoidoo.github.io/conquer3d/)**.
+
+### Isosurface extraction
+
+<img src="docs/assets/img/fig-algorithms.webp" alt="Five extractors on one signed distance field" width="100%">
+
+One signed distance field on a 64³ narrow-band grid of 19,329 cells, meshed by five
+extractors, with the source mesh on the left. The lower row crops the crease where
+Marching Cubes and Dual Contouring disagree most.
+
+### Sharp features from Hermite data
+
+<img src="docs/assets/img/fig-hermite.webp" alt="Dual methods with and without Hermite data" width="100%">
+
+Dual Contouring and Dual Marching Cubes run twice each: once with normals interpolated
+from the grid, once with exact Hermite data from `compute_hermite_from_mesh`, which
+ray-casts all 25,832 sign-crossing edges for the true intersection and face normal.
+The crease is reconstructed rather than rounded.
+
+### Detail is a resolution dial
+
+<img src="docs/assets/img/fig-resolution.webp" alt="Resolution ladder from 64 to 2048 cubed" width="100%">
+
+Dual Marching Cubes on the Armadillo at seven grid resolutions from 64³ to 2048³.
+Face count runs from 12,076 to 13,294,500, with Chamfer and Hausdorff distance to the
+source measured at every step.
+
+### From mesh to surface, step by step
+
+<img src="docs/assets/img/fig-pipeline.webp" alt="Sparse grid construction and extraction" width="100%">
+
+The input mesh, the narrow-band cells allocated around it (7,863 of a possible 64,000
+at 40³), the signed distance shown as a cutaway, the 2,646 bipolar cells, and the
+extracted surface. No dense volume is ever held.
+
+### Six ways to decide inside
+
+<img src="docs/assets/img/fig-sign-modes.webp" alt="Six sign determination modes" width="100%">
+
+One axial slice signed by each of the six sign modes and contoured at zero — ray parity,
+pseudonormal, winding number, flood fill, hybrid consensus, and coarse-fine fill.
+
+### Ray queries against the hierarchies
+
+<img src="docs/assets/img/fig-meshbvh.webp" alt="Ray-triangle and ray-voxel queries" width="100%">
+
+`MeshBVH.get_ray_intersection` returns the triangles a ray pierces; `BVH.query_ray`
+returns the narrow-band cells it crosses. Five rays from five origins, each drawn as far
+as its own first hit.
+
+---
+
+## ⚡ Benchmarks
+
+*RTX 4090, torch 2.8.0+cu128, CUDA 12.8. Fandisk at $1024^3$ (5.15M active cells).
+CUDA events around the operator alone, median of 7 runs after 2 warm-ups.*
+
+| Algorithm | Output | Vertices | Faces | Latency | Throughput |
+| :--- | :--- | ---: | ---: | ---: | ---: |
+| **Dual Marching Cubes** | Triangles | 1,716,384 | 3,432,764 | **2.62 ms** | **1,311M faces/s** |
+| DMC (pure quads) | Quads | 1,716,384 | 1,716,382 | 2.51 ms | 684M quads/s |
+| MC Asymptotic | Triangles | 1,716,382 | 3,432,760 | 2.71 ms | 1,267M faces/s |
+| Dual Contouring | Triangles | 1,716,384 | 3,432,764 | 3.88 ms | 884M faces/s |
+| Marching Cubes | Triangles | 1,716,382 | 3,432,760 | 7.90 ms | 434M faces/s |
+| Marching Tetrahedra | Triangles | 6,113,918 | 12,227,832 | 44.90 ms | 272M faces/s |
+
+Sign-mode costs, distance-operator throughput, pipeline breakdown and memory scaling are
+on the **[benchmarks page](https://khoidoo.github.io/conquer3d/benchmarks.html)**.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install -U conquer3d
+```
+
+Building from source, the full feature list, worked pipelines and the 1,020-symbol API
+reference are on the **[documentation site](https://khoidoo.github.io/conquer3d/documentation.html)**.
+
+---
+
+## 📄 License
+
+Conquer3D is licensed under the [MIT License](LICENSE).
+
+<div align="center">
+<sub>Built with CUDA and PyTorch · <a href="https://khoidoo.github.io/conquer3d/">khoidoo.github.io/conquer3d</a></sub>
+</div>

{conquer3d-0.7.6 → conquer3d-0.7.8}/conquer3d/csrc/data_structure/bvh.cu

@@ -5,6 +5,7 @@
 
 #include "bvh.h"
 #include "zcurve.h"
+#include "bvh_traverse.cuh"
 #include "../primitive/ray.h"
 
 #include <thrust/device_vector.h>
@@ -434,41 +435,19 @@ __global__ void query_bvh_kernel(
         float3 q_max = query_maxs[q_idx];
 
         // The local thread stack
-        int stack[BVH_STACK_SIZE];
-        int stack_ptr = 0;
-        
-        // Push the Root Node (Index 0) to start
-        stack[0] = 0; 
-
-        while (stack_ptr >= 0) 
-        {
-            int node_idx = stack[stack_ptr--]; 
-
-            if (aabb::test_aabb_overlap(q_min, q_max, bvh_aabb_mins[node_idx], bvh_aabb_maxs[node_idx])) 
-            {
-                if (node_idx >= num_objects - 1) 
-                {
-                    int leaf_idx = node_idx - (num_objects - 1);
-                    int original_obj_id = object_ids[leaf_idx];
-
-                    uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
-
-                    if (write_idx < max_capacity) {
-                        out_query_ids[write_idx] = q_idx;
-                        out_object_ids[write_idx] = original_obj_id;
-                    }
-                } 
-                else 
-                {
-                    if (stack_ptr + 2 < BVH_STACK_SIZE)
-                    {
-                        int2 children = bvh_children[node_idx];
-                        stack[++stack_ptr] = children.x;
-                        stack[++stack_ptr] = children.y;
-                    }
+        bvh::traverse(num_objects, bvh_children,
+            [&] (int node_idx) {
+                return aabb::test_aabb_overlap(q_min, q_max,
+                    bvh_aabb_mins[node_idx], bvh_aabb_maxs[node_idx]);
+            },
+            [&] (int leaf_idx) {
+                uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
+                if (write_idx < max_capacity) {
+                    out_query_ids[write_idx] = q_idx;
+                    out_object_ids[write_idx] = object_ids[leaf_idx];
                 }
-            }
-        }
+                return true;
+            });
     }
 
     void query(
@@ -545,42 +524,22 @@ __global__ void query_self_bvh_kernel(
         float3 q_max = bvh_aabb_maxs[node_offset + leaf_idx];
         int original_q_id = object_ids[leaf_idx];
 
-        int stack[BVH_STACK_SIZE];
-        int stack_ptr = 0;
-        stack[0] = 0; 
-
-        while (stack_ptr >= 0) 
-        {
-            int node_idx = stack[stack_ptr--]; 
-
-            if (aabb::test_aabb_overlap(q_min, q_max, bvh_aabb_mins[node_idx], bvh_aabb_maxs[node_idx])) 
-            {
-                if (node_idx >= num_objects - 1) 
-                {
-                    int other_leaf_idx = node_idx - (num_objects - 1);
-                    int original_obj_id = object_ids[other_leaf_idx];
-
-                    if (original_q_id < original_obj_id) 
-                    {
-                        uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
-
-                        if (write_idx < max_capacity) {
-                            out_query_ids[write_idx] = original_q_id;
-                            out_object_ids[write_idx] = original_obj_id;
-                        }
-                    }
-                } 
-                else 
-                {
-                    if (stack_ptr + 2 < BVH_STACK_SIZE)
-                    {
-                        int2 children = bvh_children[node_idx];
-                        stack[++stack_ptr] = children.x;
-                        stack[++stack_ptr] = children.y;
+        bvh::traverse(num_objects, bvh_children,
+            [&] (int node_idx) {
+                return aabb::test_aabb_overlap(q_min, q_max,
+                    bvh_aabb_mins[node_idx], bvh_aabb_maxs[node_idx]);
+            },
+            [&] (int other_leaf_idx) {
+                int original_obj_id = object_ids[other_leaf_idx];
+                if (original_q_id < original_obj_id) {
+                    uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
+                    if (write_idx < max_capacity) {
+                        out_query_ids[write_idx] = original_q_id;
+                        out_object_ids[write_idx] = original_obj_id;
                     }
                 }
-            }
-        }
+                return true;
+            });
     }
 
     void query_self(
@@ -655,40 +614,20 @@ __global__ void query_ray_bvh_kernel(
 
         Ray ray(ray_origins[q_idx], ray_dirs[q_idx]);
 
-        int stack[BVH_STACK_SIZE];
-        int stack_ptr = 0;
-        stack[0] = 0; 
-
-        while (stack_ptr >= 0) 
-        {
-            int node_idx = stack[stack_ptr--]; 
-            float t_hit;
-
-            if (ray.is_intersect_aabb(bvh_aabb_mins[node_idx], bvh_aabb_maxs[node_idx], t_hit)) 
-            {
-                if (node_idx >= num_objects - 1) 
-                {
-                    int leaf_idx = node_idx - (num_objects - 1);
-                    int original_obj_id = object_ids[leaf_idx];
-
-                    uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
-
-                    if (write_idx < max_capacity) {
-                        out_query_ids[write_idx] = q_idx;
-                        out_object_ids[write_idx] = original_obj_id;
-                    }
-                } 
-                else 
-                {
-                    if (stack_ptr + 2 < BVH_STACK_SIZE)
-                    {
-                        int2 children = bvh_children[node_idx];
-                        stack[++stack_ptr] = children.x;
-                        stack[++stack_ptr] = children.y;
-                    }
+        bvh::traverse(num_objects, bvh_children,
+            [&] (int node_idx) {
+                float t_hit;
+                return ray.is_intersect_aabb(bvh_aabb_mins[node_idx],
+                                             bvh_aabb_maxs[node_idx], t_hit);
+            },
+            [&] (int leaf_idx) {
+                uint64_t write_idx = (uint64_t)atomicAdd((unsigned long long int*)hit_counter, 1ULL);
+                if (write_idx < max_capacity) {
+                    out_query_ids[write_idx] = q_idx;
+                    out_object_ids[write_idx] = object_ids[leaf_idx];
                 }
-            }
-        }
+                return true;
+            });
     }
 
     void query_ray(

conquer3d-0.7.8/conquer3d/csrc/data_structure/bvh_traverse.cuh

@@ -0,0 +1,82 @@
+/**
+ * @file bvh_traverse.cuh
+ * @brief Shared stack-based descent over a Linear BVH.
+ *
+ * @details Every query in the library walks the hierarchy the same way: pop a node, ask
+ * whether it is worth entering, and either visit it as a leaf or push its two children.
+ * Only the node test and the leaf action differ. Writing that loop once and passing those
+ * two steps as functors keeps the traversal -- including the stack bound, the leaf index
+ * arithmetic and the overflow guard -- in a single place, so a fix lands everywhere rather
+ * than in one of eighteen copies.
+ *
+ * The functors are device lambdas and are fully inlined, so the generated code matches the
+ * hand-written loop it replaces.
+ *
+ * @note Two query shapes are deliberately *not* expressed here and remain hand-written:
+ * nearest-point search, which pushes the closer child last and prunes each child against
+ * the running best distance, and the Fast Winding Number descent, which does work on the
+ * branch where the node test *fails* rather than skipping it. Forcing either into this
+ * interface would obscure it for no gain.
+ */
+
+#ifndef BVH_TRAVERSE_CUH
+#define BVH_TRAVERSE_CUH
+
+#include "../constants.h"
+#include <cuda_runtime.h>
+
+namespace bvh
+{
+    /**
+     * @brief Walks the hierarchy, visiting every leaf the node test admits.
+     *
+     * @tparam NodeTest  Callable `bool(int node_idx)`; return false to prune the subtree.
+     * @tparam LeafVisit Callable `bool(int leaf_idx)` receiving the leaf's slot in
+     *         `object_ids`; return false to abandon the traversal, which is how
+     *         any-hit queries stop at their first result.
+     *
+     * @param[in] num_objects Number of primitives $N$; internal nodes occupy $[0, N-1)$ and
+     *     leaves $[N-1, 2N-1)$.
+     * @param[in] children Device array of $N - 1$ child index pairs.
+     * @param[in] node_test Predicate deciding whether to enter a node.
+     * @param[in] leaf_visit Action performed at an admitted leaf.
+     *
+     * @warning The stack holds `BVH_STACK_SIZE` entries in local memory. A hierarchy deeper
+     * than that silently drops the remaining children rather than failing, so a
+     * pathologically unbalanced tree can under-report. Morton ordering keeps real trees
+     * far shallower than the bound.
+     */
+    template <class NodeTest, class LeafVisit>
+    __device__ __forceinline__ void traverse(
+        const int num_objects,
+        const int2 *__restrict__ children,
+        NodeTest node_test,
+        LeafVisit leaf_visit)
+    {
+        int stack[BVH_STACK_SIZE];
+        int stack_ptr = 0;
+        stack[0] = 0;
+
+        while (stack_ptr >= 0)
+        {
+            const int node_idx = stack[stack_ptr--];
+
+            if (!node_test(node_idx))
+                continue;
+
+            if (node_idx >= num_objects - 1)
+            {
+                if (!leaf_visit(node_idx - (num_objects - 1)))
+                    return;
+            }
+            else if (stack_ptr + 2 < BVH_STACK_SIZE)
+            {
+                const int2 c = children[node_idx];
+                if (c.x >= 0) stack[++stack_ptr] = c.x;
+                if (c.y >= 0) stack[++stack_ptr] = c.y;
+            }
+        }
+    }
+}
+
+#endif // BVH_TRAVERSE_CUH