conquer3d 0.7.0__tar.gz → 0.7.4__tar.gz

{conquer3d-0.7.0/conquer3d.egg-info → conquer3d-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conquer3d
-Version: 0.7.0
+Version: 0.7.4
 Summary: Geometric Cuda Tool Box
 Author-email: Do Hoang Khoi <khoido8899@gmail.com>
 License-Expression: MIT
@@ -37,40 +37,125 @@ Dynamic: license-file
 
 ### *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%20%7C%203.10%20%7C%203.11-3776AB?logo=python&logoColor=white&style=for-the-badge)](https://www.python.org/)
+
+[![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-1018_symbols_·_100%25-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/api/index.html)
 
 <p align="center">
-  <a href="#-features--highlights">Key Features</a> •
-  <a href="#-benchmarks">Benchmarks</a> •
-  <a href="#-quickstart-examples">Quickstart</a> •
+  <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="#-installation">Installation</a> •
-  <a href="#-acknowledgements--references">References</a>
+  <a href="#-features--highlights">Features</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.0 Billion faces/second** isosurface extraction, exact CAD sharp crease preservation, and memory-efficient spatial acceleration structures.
+**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
+```
+
+---
+
+## 📖 Documentation
+
+**Full documentation lives at [khoidoo.github.io/conquer3d](https://khoidoo.github.io/conquer3d/).**
+
+| | |
+| :--- | :--- |
+| **[Showcase](https://khoidoo.github.io/conquer3d/)** | What the library is for, and how to start. |
+| **[Documentation](https://khoidoo.github.io/conquer3d/documentation.html)** | Installation, core concepts, architecture, and worked pipelines. |
+| **[API Reference](https://khoidoo.github.io/conquer3d/api/index.html)** | Every symbol, across seven tiers. |
+| **[Benchmarks](https://khoidoo.github.io/conquer3d/benchmarks.html)** | Measured extraction throughput on real geometry. |
+| **[About](https://khoidoo.github.io/conquer3d/about.html)** | Motivation and the research this builds on. |
+
+The API reference does not stop at the Python surface. It descends through the pybind11 bindings and host dispatchers into the CUDA kernels themselves, the device helpers they call, and the inline math those are built from — **1018 symbols, fully documented**:
+
+| Tier | Layer | Symbols |
+| :--- | :--- | ---: |
+| **T1** | Python API | 159 |
+| **T2** | Native bindings (`conquer3d._C`) | 151 |
+| **T3** | Host dispatchers & C++ declarations | 437 |
+| **T4** | CUDA `__global__` kernels | 109 |
+| **T5** | CUDA `__device__` helpers | 69 |
+| **T6** | Inline math primitives | 65 |
+| **T7** | `__constant__` topology tables | 28 |
+
+---
+
+## ⚡ Benchmarks
+
+*Measured on **NVIDIA GeForce RTX 4090** (torch 2.8.0+cu128, CUDA 12.8) on the **Fandisk CAD model** at **$1024^3$ resolution** (5.15M active cells). Timed with CUDA events around the operator alone, median of 7 runs after 2 warm-ups:*
+
+| Algorithm | Mesh Output | Extracted Vertices | Extracted Faces / Quads | Latency (ms) | Throughput |
+| :--- | :--- | ---: | ---: | ---: | ---: |
+| **DMC (pure quads)** | Pure Quads | 1,716,384 | 1,716,382 | **2.51 ms** | **684M faces/s** |
+| **Dual Marching Cubes** | Triangles | 1,716,384 | 3,432,764 | **2.62 ms** | **1,311M faces/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 |
+
+All figures are produced by `docs/_figures/make_benchmarks.py` and can be reproduced. Sign-mode costs, pipeline setup breakdown and memory scaling are on the **[benchmarks page](https://khoidoo.github.io/conquer3d/benchmarks.html)**.
 
 ---
 
 ## ✨ Features & Highlights
 
-### 🔷 1. Isosurface Extraction & Meshing
-- **Dual Marching Cubes (`dmc`)**: High-throughput manifold surface extraction with pure quad $(Q, 4)$ or triangle $(F, 3)$ outputs (~1.0B faces/s).
+<details open>
+<summary><b>🔷 1. Isosurface Extraction &amp; Meshing</b></summary>
+<br>
+
+- **Dual Marching Cubes (`dmc`)**: High-throughput manifold surface extraction with pure quad $(Q, 4)$ or triangle $(F, 3)$ outputs (~1.3B faces/s measured).
 - **Dual Contouring (`dc`)**: Sharp CAD crease and mechanical corner preservation via GPU Quadratic Error Function (QEF) solving.
 - **Marching Cubes Asymptotic (`mca`)**: Decider-enhanced Marching Cubes resolving topological face ambiguities on-the-fly.
+- **Differentiable Poisson Surface Reconstruction (`dpsr`, `DPSR`)**: Differentiable spectral Fourier Poisson indicator field solving directly from oriented point clouds.
 - **Differentiable Marching Cubes (`diff_marching_cubes`)**: PyTorch autograd gradient backpropagation through levelsets into SDF and color fields.
 - **Marching Tetrahedra (`marching_tetrahedra`, `marching_tetrahedra_grid`)**: Consistent isosurface extraction across unstructured meshes and regular cubic tetrahedral grids.
 
-### 🚀 2. Hardware-Accelerated Spatial Acceleration
+</details>
+
+<details>
+<summary><b>🚀 2. Hardware-Accelerated Spatial Acceleration</b></summary>
+<br>
+
 - **Triangle Mesh BVH (`MeshBVH`)**: GPU Bounding Volume Hierarchy for fast ray intersections, point projections, and signed distance queries.
 - **Gaussian Splatting BVHs (`GSBVH`, `PGSBVH`)**: Spatial hierarchies specialized for 3D Gaussian Splatting and Periodic Gaussian Splatting.
 - **Radix Linear BVH (`BVH`)**: High-throughput parallel bounding volume hierarchy for generic 3D primitives.
@@ -78,45 +163,59 @@ Dynamic: license-file
 - **Morton Z-Curve Sorting (`z_curve_sort`)**: 64-bit Radix-sorted space-filling curve indexing for maximizing GPU cache locality.
 - **Volumetric 3D Flood Fill**: Fast GPU bitmask ray-boundary flood fill for sign evaluation across complex geometries.
 
-### 🌐 3. Volumetric Grids & Surface Conversions
+</details>
+
+<details>
+<summary><b>🌐 3. Volumetric Grids &amp; Surface Conversions</b></summary>
+<br>
+
 - **Narrow-Band Sparse Voxel Grids (`create_voxel_grid_from_tmesh`)**: Direct surface-confined voxelization bypassing dense 3D memory.
 - **Multi-Mode Normal Field Generation**: On-the-fly extraction of exact CAD face normals (`mode=0`), smooth vertex normals (`mode=1`), or SDF gradients (`mode=2`).
 - **Mesh-to-Grid Pipelines (`tmesh2voxel`, `tmesh2sparse`)**: One-line conversion from 3D meshes to dense or sparse Signed Distance Fields.
 - **Depth-Map Surface Carving (`get_active_voxel_ids_from_depth`)**: Multi-view RGB-D depth image backprojection into active voxel grids.
 - **Sparse & Occupancy Conversions (`sparse_coo2dense_occ`, `dense_occ2sparse_coo`)**: Seamless conversion between sparse coordinate tensors and dense binary occupancy volumes.
 
-### 🎨 4. Radiance Fields & Differentiable Primitives
+</details>
+
+<details>
+<summary><b>🎨 4. Radiance Fields &amp; Differentiable Primitives</b></summary>
+<br>
+
 - **3D Gaussian Splatting Primitives (`compute_gs_covi`, `compute_gs_aabb`)**: GPU-accelerated covariance matrices, Mahalanobis distances, and tight AABB computation.
 - **Periodic Gaussian Splatting (`solve_pgs_cluster_tangency_radius`)**: Spatial frequency-aware radiance field query operators.
 - **Geometric Primitive Structures (`Ray`, `Triangle`, `AABB`, `Edge`)**: Vectorized GPU ray tracing and collision primitives.
 
-### 📐 5. Geometric Distances & Volume Integrals
+</details>
+
+<details>
+<summary><b>📐 5. Geometric Distances &amp; Volume Integrals</b></summary>
+<br>
+
 - **Exact Chamfer Distances (`chamfer_distance`, `one_sided_chamfer_distance`)**: Point-to-point and point-to-mesh geometric error evaluation.
 - **Exact Hausdorff Distances (`hausdorff_distance`, `one_sided_hausdorff_distance`)**: Maximum deviation metrics for surface fidelity assessment.
 - **Single-View Volume Integrals (`single_view_volume_integral`)**: Analytical divergence-theorem ray volume integration.
 
-### 📦 6. 3D Data Loading, Augmentation & Collation
+</details>
+
+<details>
+<summary><b>📦 6. 3D Data Loading, Augmentation &amp; Collation</b></summary>
+<br>
+
 - **Benchmark 3D Datasets (`Digit3D`, `PointDigit3D`, `RedWood`, `MeshDataset`)**: Ready-to-use PyTorch dataset abstractions.
 - **Standard Benchmark 3D Assets (`conquer3d.data.assets`)**: One-click download & caching for Stanford Bunny, Armadillo, Dragon, Lucy, Happy Buddha, Spot, Cow, Teapot, Suzanne, Fandisk, Iphigenia, and more.
 - **Geometric Data Augmentations (`Rotation`, `Scale`, `RandomRotation`, `RandomScale`, `Sequence`, `MeshSequence`)**: Composable spatial transformation pipelines.
 - **Custom PyTorch Batch Collation (`bmesh_collate_fn`, `sparse_collate_fn`)**: Efficient handling of variable-sized meshes and sparse tensors in DataLoaders.
 
-### 🛠️ 7. Procedural Generation & File I/O
-- **Procedural Mesh Generators (`create_sphere`, `create_tetrahedra`)**: Parametric geometric shape creation utilities.
-- **High-Performance Mesh I/O (`read_obj`, `write_obj`, `read_off`)**: Native loading and saving for vertices, faces, and vertex colors.
-
----
+</details>
 
-## ⚡ Benchmarks
+<details>
+<summary><b>🛠️ 7. Procedural Generation &amp; File I/O</b></summary>
+<br>
 
-*Empirical extraction performance on **NVIDIA GeForce RTX 4090** on the **Fandisk CAD model** at **$1024^3$ resolution** (6.86M sparse vertices, 5.15M active voxels):*
+- **Procedural Mesh Generators (`create_sphere`, `create_tetrahedra`)**: Parametric geometric shape creation utilities.
+- **High-Performance Mesh I/O (`read_obj`, `write_obj`, `read_off`)**: Native loading and saving for vertices, faces, and vertex colors.
 
-| Algorithm | Mesh Output | Extracted Vertices | Extracted Faces / Quads | Latency (ms) | Throughput | Watertight |
-| :--- | :--- | :--- | :--- | :---: | :---: | :---: |
-| **Dual Marching Cubes (DMC)** | Triangles | **1,716,386** | **3,432,768** | **3.44 ms** | **~1.0B faces/s** | **Yes** |
-| **Dual Marching Cubes (DMC)** | Pure Quads | **1,716,386** | **1,716,384** | **3.22 ms** | **533M quads/s** | **Yes** |
-| **Dual Contouring (DC + Normals)** | Triangles | 1,716,386 | 3,432,768 | **4.79 ms** | **717M faces/s** | **Yes** |
-| **Marching Cubes Asymptotic (MCA)** | Triangles | 1,716,384 | 3,432,764 | 16.42 ms | **209M faces/s** | **Yes** |
+</details>
 
 ---
 
@@ -189,6 +288,10 @@ query_ids, closest_tri_ids, projected_pts, sdfs = tmesh.query_points(
 )
 ```
 
+> [!TIP]
+> More worked pipelines, the core concepts behind them, and the full operator reference are on the
+> **[documentation site](https://khoidoo.github.io/conquer3d/documentation.html)**.
+
 ---
 
 ## 📦 Installation
@@ -198,6 +301,8 @@ query_ids, closest_tri_ids, projected_pts, sdfs = tmesh.query_points(
 pip install -U conquer3d
 ```
 
+Prebuilt CUDA wheels are attached to each release for **Python 3.10–3.14** against **PyTorch 2.8 and 2.11** (CUDA 12.8).
+
 ### 2. Docker (Recommended for instant GPU / CUDA environment)
 ```bash
 # Pull and run the pre-built image
@@ -228,16 +333,42 @@ cd conquer3d
 pip install -e . --no-build-isolation
 ```
 
+> [!NOTE]
+> Importing `conquer3d` loads the compiled `_C` extension at module scope, so a CUDA-capable device
+> and a matching PyTorch build are required.
+
 ---
 
 ## 📚 Acknowledgements & References
+
 For further theoretical background, GPU collision detection guides, and related literature, please visit:
+
 - **[Research Papers](acknowledgement/REFERENCE.md)**: Computational geometry, differential topology, and acceleration structure foundations.
 - **[Blog Posts](acknowledgement/BLOG_POST.md)**: GPU spatial traversal, parallel BVH construction, and CUDA optimization guides.
 - **[Related Repositories](acknowledgement/REPOSITORY.md)**: Open-source geometric deep learning ecosystem.
 - **[Books](acknowledgement/BOOK.md)**: Core computational geometry references.
 
+A rendered bibliography is also available on the **[About page](https://khoidoo.github.io/conquer3d/about.html)**.
+
+---
+
+## 📝 Citation
+
+```bibtex
+@software{conquer3d,
+  title   = {Conquer3D: GPU-Accelerated Differentiable Geometry and Spatial Computing},
+  author  = {Do, Hoang Khoi},
+  year    = {2025},
+  url     = {https://github.com/KhoiDOO/conquer3d}
+}
+```
+
 ---
 
 ## 📄 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.0 → conquer3d-0.7.4}/README.md

@@ -4,40 +4,125 @@
 
 ### *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%20%7C%203.10%20%7C%203.11-3776AB?logo=python&logoColor=white&style=for-the-badge)](https://www.python.org/)
+
+[![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-1018_symbols_·_100%25-76B900?style=for-the-badge)](https://khoidoo.github.io/conquer3d/api/index.html)
 
 <p align="center">
-  <a href="#-features--highlights">Key Features</a> •
-  <a href="#-benchmarks">Benchmarks</a> •
-  <a href="#-quickstart-examples">Quickstart</a> •
+  <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="#-installation">Installation</a> •
-  <a href="#-acknowledgements--references">References</a>
+  <a href="#-features--highlights">Features</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.0 Billion faces/second** isosurface extraction, exact CAD sharp crease preservation, and memory-efficient spatial acceleration structures.
+**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
+```
+
+---
+
+## 📖 Documentation
+
+**Full documentation lives at [khoidoo.github.io/conquer3d](https://khoidoo.github.io/conquer3d/).**
+
+| | |
+| :--- | :--- |
+| **[Showcase](https://khoidoo.github.io/conquer3d/)** | What the library is for, and how to start. |
+| **[Documentation](https://khoidoo.github.io/conquer3d/documentation.html)** | Installation, core concepts, architecture, and worked pipelines. |
+| **[API Reference](https://khoidoo.github.io/conquer3d/api/index.html)** | Every symbol, across seven tiers. |
+| **[Benchmarks](https://khoidoo.github.io/conquer3d/benchmarks.html)** | Measured extraction throughput on real geometry. |
+| **[About](https://khoidoo.github.io/conquer3d/about.html)** | Motivation and the research this builds on. |
+
+The API reference does not stop at the Python surface. It descends through the pybind11 bindings and host dispatchers into the CUDA kernels themselves, the device helpers they call, and the inline math those are built from — **1018 symbols, fully documented**:
+
+| Tier | Layer | Symbols |
+| :--- | :--- | ---: |
+| **T1** | Python API | 159 |
+| **T2** | Native bindings (`conquer3d._C`) | 151 |
+| **T3** | Host dispatchers & C++ declarations | 437 |
+| **T4** | CUDA `__global__` kernels | 109 |
+| **T5** | CUDA `__device__` helpers | 69 |
+| **T6** | Inline math primitives | 65 |
+| **T7** | `__constant__` topology tables | 28 |
+
+---
+
+## ⚡ Benchmarks
+
+*Measured on **NVIDIA GeForce RTX 4090** (torch 2.8.0+cu128, CUDA 12.8) on the **Fandisk CAD model** at **$1024^3$ resolution** (5.15M active cells). Timed with CUDA events around the operator alone, median of 7 runs after 2 warm-ups:*
+
+| Algorithm | Mesh Output | Extracted Vertices | Extracted Faces / Quads | Latency (ms) | Throughput |
+| :--- | :--- | ---: | ---: | ---: | ---: |
+| **DMC (pure quads)** | Pure Quads | 1,716,384 | 1,716,382 | **2.51 ms** | **684M faces/s** |
+| **Dual Marching Cubes** | Triangles | 1,716,384 | 3,432,764 | **2.62 ms** | **1,311M faces/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 |
+
+All figures are produced by `docs/_figures/make_benchmarks.py` and can be reproduced. Sign-mode costs, pipeline setup breakdown and memory scaling are on the **[benchmarks page](https://khoidoo.github.io/conquer3d/benchmarks.html)**.
 
 ---
 
 ## ✨ Features & Highlights
 
-### 🔷 1. Isosurface Extraction & Meshing
-- **Dual Marching Cubes (`dmc`)**: High-throughput manifold surface extraction with pure quad $(Q, 4)$ or triangle $(F, 3)$ outputs (~1.0B faces/s).
+<details open>
+<summary><b>🔷 1. Isosurface Extraction &amp; Meshing</b></summary>
+<br>
+
+- **Dual Marching Cubes (`dmc`)**: High-throughput manifold surface extraction with pure quad $(Q, 4)$ or triangle $(F, 3)$ outputs (~1.3B faces/s measured).
 - **Dual Contouring (`dc`)**: Sharp CAD crease and mechanical corner preservation via GPU Quadratic Error Function (QEF) solving.
 - **Marching Cubes Asymptotic (`mca`)**: Decider-enhanced Marching Cubes resolving topological face ambiguities on-the-fly.
+- **Differentiable Poisson Surface Reconstruction (`dpsr`, `DPSR`)**: Differentiable spectral Fourier Poisson indicator field solving directly from oriented point clouds.
 - **Differentiable Marching Cubes (`diff_marching_cubes`)**: PyTorch autograd gradient backpropagation through levelsets into SDF and color fields.
 - **Marching Tetrahedra (`marching_tetrahedra`, `marching_tetrahedra_grid`)**: Consistent isosurface extraction across unstructured meshes and regular cubic tetrahedral grids.
 
-### 🚀 2. Hardware-Accelerated Spatial Acceleration
+</details>
+
+<details>
+<summary><b>🚀 2. Hardware-Accelerated Spatial Acceleration</b></summary>
+<br>
+
 - **Triangle Mesh BVH (`MeshBVH`)**: GPU Bounding Volume Hierarchy for fast ray intersections, point projections, and signed distance queries.
 - **Gaussian Splatting BVHs (`GSBVH`, `PGSBVH`)**: Spatial hierarchies specialized for 3D Gaussian Splatting and Periodic Gaussian Splatting.
 - **Radix Linear BVH (`BVH`)**: High-throughput parallel bounding volume hierarchy for generic 3D primitives.
@@ -45,45 +130,59 @@
 - **Morton Z-Curve Sorting (`z_curve_sort`)**: 64-bit Radix-sorted space-filling curve indexing for maximizing GPU cache locality.
 - **Volumetric 3D Flood Fill**: Fast GPU bitmask ray-boundary flood fill for sign evaluation across complex geometries.
 
-### 🌐 3. Volumetric Grids & Surface Conversions
+</details>
+
+<details>
+<summary><b>🌐 3. Volumetric Grids &amp; Surface Conversions</b></summary>
+<br>
+
 - **Narrow-Band Sparse Voxel Grids (`create_voxel_grid_from_tmesh`)**: Direct surface-confined voxelization bypassing dense 3D memory.
 - **Multi-Mode Normal Field Generation**: On-the-fly extraction of exact CAD face normals (`mode=0`), smooth vertex normals (`mode=1`), or SDF gradients (`mode=2`).
 - **Mesh-to-Grid Pipelines (`tmesh2voxel`, `tmesh2sparse`)**: One-line conversion from 3D meshes to dense or sparse Signed Distance Fields.
 - **Depth-Map Surface Carving (`get_active_voxel_ids_from_depth`)**: Multi-view RGB-D depth image backprojection into active voxel grids.
 - **Sparse & Occupancy Conversions (`sparse_coo2dense_occ`, `dense_occ2sparse_coo`)**: Seamless conversion between sparse coordinate tensors and dense binary occupancy volumes.
 
-### 🎨 4. Radiance Fields & Differentiable Primitives
+</details>
+
+<details>
+<summary><b>🎨 4. Radiance Fields &amp; Differentiable Primitives</b></summary>
+<br>
+
 - **3D Gaussian Splatting Primitives (`compute_gs_covi`, `compute_gs_aabb`)**: GPU-accelerated covariance matrices, Mahalanobis distances, and tight AABB computation.
 - **Periodic Gaussian Splatting (`solve_pgs_cluster_tangency_radius`)**: Spatial frequency-aware radiance field query operators.
 - **Geometric Primitive Structures (`Ray`, `Triangle`, `AABB`, `Edge`)**: Vectorized GPU ray tracing and collision primitives.
 
-### 📐 5. Geometric Distances & Volume Integrals
+</details>
+
+<details>
+<summary><b>📐 5. Geometric Distances &amp; Volume Integrals</b></summary>
+<br>
+
 - **Exact Chamfer Distances (`chamfer_distance`, `one_sided_chamfer_distance`)**: Point-to-point and point-to-mesh geometric error evaluation.
 - **Exact Hausdorff Distances (`hausdorff_distance`, `one_sided_hausdorff_distance`)**: Maximum deviation metrics for surface fidelity assessment.
 - **Single-View Volume Integrals (`single_view_volume_integral`)**: Analytical divergence-theorem ray volume integration.
 
-### 📦 6. 3D Data Loading, Augmentation & Collation
+</details>
+
+<details>
+<summary><b>📦 6. 3D Data Loading, Augmentation &amp; Collation</b></summary>
+<br>
+
 - **Benchmark 3D Datasets (`Digit3D`, `PointDigit3D`, `RedWood`, `MeshDataset`)**: Ready-to-use PyTorch dataset abstractions.
 - **Standard Benchmark 3D Assets (`conquer3d.data.assets`)**: One-click download & caching for Stanford Bunny, Armadillo, Dragon, Lucy, Happy Buddha, Spot, Cow, Teapot, Suzanne, Fandisk, Iphigenia, and more.
 - **Geometric Data Augmentations (`Rotation`, `Scale`, `RandomRotation`, `RandomScale`, `Sequence`, `MeshSequence`)**: Composable spatial transformation pipelines.
 - **Custom PyTorch Batch Collation (`bmesh_collate_fn`, `sparse_collate_fn`)**: Efficient handling of variable-sized meshes and sparse tensors in DataLoaders.
 
-### 🛠️ 7. Procedural Generation & File I/O
-- **Procedural Mesh Generators (`create_sphere`, `create_tetrahedra`)**: Parametric geometric shape creation utilities.
-- **High-Performance Mesh I/O (`read_obj`, `write_obj`, `read_off`)**: Native loading and saving for vertices, faces, and vertex colors.
-
----
+</details>
 
-## ⚡ Benchmarks
+<details>
+<summary><b>🛠️ 7. Procedural Generation &amp; File I/O</b></summary>
+<br>
 
-*Empirical extraction performance on **NVIDIA GeForce RTX 4090** on the **Fandisk CAD model** at **$1024^3$ resolution** (6.86M sparse vertices, 5.15M active voxels):*
+- **Procedural Mesh Generators (`create_sphere`, `create_tetrahedra`)**: Parametric geometric shape creation utilities.
+- **High-Performance Mesh I/O (`read_obj`, `write_obj`, `read_off`)**: Native loading and saving for vertices, faces, and vertex colors.
 
-| Algorithm | Mesh Output | Extracted Vertices | Extracted Faces / Quads | Latency (ms) | Throughput | Watertight |
-| :--- | :--- | :--- | :--- | :---: | :---: | :---: |
-| **Dual Marching Cubes (DMC)** | Triangles | **1,716,386** | **3,432,768** | **3.44 ms** | **~1.0B faces/s** | **Yes** |
-| **Dual Marching Cubes (DMC)** | Pure Quads | **1,716,386** | **1,716,384** | **3.22 ms** | **533M quads/s** | **Yes** |
-| **Dual Contouring (DC + Normals)** | Triangles | 1,716,386 | 3,432,768 | **4.79 ms** | **717M faces/s** | **Yes** |
-| **Marching Cubes Asymptotic (MCA)** | Triangles | 1,716,384 | 3,432,764 | 16.42 ms | **209M faces/s** | **Yes** |
+</details>
 
 ---
 
@@ -156,6 +255,10 @@ query_ids, closest_tri_ids, projected_pts, sdfs = tmesh.query_points(
 )
 ```
 
+> [!TIP]
+> More worked pipelines, the core concepts behind them, and the full operator reference are on the
+> **[documentation site](https://khoidoo.github.io/conquer3d/documentation.html)**.
+
 ---
 
 ## 📦 Installation
@@ -165,6 +268,8 @@ query_ids, closest_tri_ids, projected_pts, sdfs = tmesh.query_points(
 pip install -U conquer3d
 ```
 
+Prebuilt CUDA wheels are attached to each release for **Python 3.10–3.14** against **PyTorch 2.8 and 2.11** (CUDA 12.8).
+
 ### 2. Docker (Recommended for instant GPU / CUDA environment)
 ```bash
 # Pull and run the pre-built image
@@ -195,16 +300,42 @@ cd conquer3d
 pip install -e . --no-build-isolation
 ```
 
+> [!NOTE]
+> Importing `conquer3d` loads the compiled `_C` extension at module scope, so a CUDA-capable device
+> and a matching PyTorch build are required.
+
 ---
 
 ## 📚 Acknowledgements & References
+
 For further theoretical background, GPU collision detection guides, and related literature, please visit:
+
 - **[Research Papers](acknowledgement/REFERENCE.md)**: Computational geometry, differential topology, and acceleration structure foundations.
 - **[Blog Posts](acknowledgement/BLOG_POST.md)**: GPU spatial traversal, parallel BVH construction, and CUDA optimization guides.
 - **[Related Repositories](acknowledgement/REPOSITORY.md)**: Open-source geometric deep learning ecosystem.
 - **[Books](acknowledgement/BOOK.md)**: Core computational geometry references.
 
+A rendered bibliography is also available on the **[About page](https://khoidoo.github.io/conquer3d/about.html)**.
+
+---
+
+## 📝 Citation
+
+```bibtex
+@software{conquer3d,
+  title   = {Conquer3D: GPU-Accelerated Differentiable Geometry and Spatial Computing},
+  author  = {Do, Hoang Khoi},
+  year    = {2025},
+  url     = {https://github.com/KhoiDOO/conquer3d}
+}
+```
+
 ---
 
 ## 📄 License
-Conquer3D is licensed under the [MIT License](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.0 → conquer3d-0.7.4}/conquer3d/conversion/tmesh.py

@@ -97,15 +97,17 @@ def tmesh2sparse(
     pad: int = 0,
     return_normals: bool = False,
     normal_mode: int = 0,
-    drop_empty_vertex_voxels: bool = False
+    drop_empty_vertex_voxels: bool = False,
+    return_sdf: bool = True
 ) -> Union[
+    Tuple[torch.Tensor, torch.Tensor],
     Tuple[torch.Tensor, torch.Tensor, torch.Tensor],
     Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]
 ]:
     """Computes Signed Distance Fields on sparse voxel grids strictly near the surface.
 
     Completely bypasses dense $O(R^3)$ volume allocation by querying the mesh BVH,
-    re-indexing sparse active vertices, and evaluating SDF solely on active points.
+    re-indexing sparse active vertices, and optionally evaluating SDF solely on active points.
 
     Args:
         tm (TriangleMesh): Input TriangleMesh GPU object.
@@ -126,11 +128,19 @@ def tmesh2sparse(
         return_normals (bool, optional): If True, returns surface normal vectors. Defaults to False.
         normal_mode (int, optional): Normal mode (0: face normals, 1: vertex normals, 2: displacement vector).
         drop_empty_vertex_voxels (bool, optional): If True, drops voxels containing no mesh vertices inside their bounding box. Defaults to False.
+        return_sdf (bool, optional): If True, queries and returns the Signed Distance Field on sparse grid vertices.
+            If False, skips SDF evaluation entirely. Defaults to True.
 
     Returns:
-        Union[Tuple[torch.Tensor, torch.Tensor, torch.Tensor], Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]]:
-            - If `return_normals=False`: `(sparse_grid_vertices, active_voxels, sdfs)`
-            - If `return_normals=True`: `(sparse_grid_vertices, active_voxels, sdfs, grid_normals)`
+        Union[
+            Tuple[torch.Tensor, torch.Tensor],
+            Tuple[torch.Tensor, torch.Tensor, torch.Tensor],
+            Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]
+        ]:
+            - If `return_sdf=True` and `return_normals=False`: `(sparse_grid_vertices, active_voxels, sdfs)`
+            - If `return_sdf=True` and `return_normals=True`: `(sparse_grid_vertices, active_voxels, sdfs, grid_normals)`
+            - If `return_sdf=False` and `return_normals=False`: `(sparse_grid_vertices, active_voxels)`
+            - If `return_sdf=False` and `return_normals=True`: `(sparse_grid_vertices, active_voxels, grid_normals)`
     """
     if grid_min is None:
         grid_min = [-1.0, -1.0, -1.0]
@@ -155,6 +165,11 @@ def tmesh2sparse(
         )
     
     num_points = grid_vertices.shape[0]
+    if not return_sdf:
+        if return_normals:
+            return grid_vertices, active_voxels.to(torch.int64), grid_normals
+        return grid_vertices, active_voxels.to(torch.int64)
+
     if num_points == 0:
         sdfs = torch.empty(0, dtype=torch.float32, device=device)
         if return_normals: