[!NOTE] The API documentation and the documentation website were written with Claude. 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.

pip install -U conquer3d

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.

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:

⚡ 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:

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.

✨ Features & Highlights

🚀 Quickstart Examples

1. Differentiable Dual Marching Cubes (DMC)

import torch
from conquer3d.data_structure import create_voxel_grid
from conquer3d.ops import dmc

# Create 3D Voxel Grid
grid_vertices, voxels, _ = create_voxel_grid(
    grid_min=[-1.0, -1.0, -1.0], grid_max=[1.0, 1.0, 1.0], res=[64, 64, 64], device="cuda"
)

# Evaluate SDF & Feature Colors with autograd tracking
sdf = (torch.norm(grid_vertices, dim=-1) - 0.6).requires_grad_(True)
colors = torch.rand((grid_vertices.shape[0], 3), device="cuda", requires_grad=True)

# Extract 2-manifold triangle mesh with Newton-Raphson levelset projection
verts, faces, out_colors = dmc(
    grid_vertices, voxels, sdf, colors=colors, iso=0.0, quad_split=True
)

# Extract pure quads (shape: (Q, 4))
quad_verts, quad_faces = dmc(grid_vertices, voxels, sdf, iso=0.0, quad_split=False)

# Backward gradient propagation
loss = verts.sum() + out_colors.sum()
loss.backward()
print(f"SDF Gradient Norm: {sdf.grad.norm().item():.4f}")

2. Dual Contouring (DC) with Sharp CAD Feature Preservation

import torch
from conquer3d.data.assets import Fandisk
from conquer3d.data_structure import TriangleMesh, create_voxel_grid_from_tmesh
from conquer3d.ops import dc

fandisk = Fandisk()
v, f, _ = fandisk.get()
tmesh = TriangleMesh(v.cuda(), f.cuda().int())

# Build sparse grid and extract exact CAD triangle normals (mode=0)
grid_vertices, voxels, _, grid_normals = create_voxel_grid_from_tmesh(
    grid_min=[-1.0, -1.0, -1.0], grid_max=[1.0, 1.0, 1.0],
    res=[256, 256, 256], tmesh=tmesh, pad=1, return_normals=True, normal_mode=0
)

# Query signed distance field via GPU Flood Fill
tmesh.build_flood_fill_data([-1.0, -1.0, -1.0], [1.0, 1.0, 1.0], [256, 256, 256])
_, _, _, sdfs = tmesh.query_points(grid_vertices, return_sdf=True, sign_mode=3)

# Extract sharp mesh using GPU Jacobi SVD Quadratic Error Function solver
verts, faces = dc(grid_vertices, voxels, sdfs, grid_normals=grid_normals, iso=0.0)
print(f"Extracted Sharp CAD Mesh: {verts.shape[0]:,} vertices, {faces.shape[0]:,} faces")

3. GPU Spatial Queries & Mesh BVH

import torch
from conquer3d.data_structure import TriangleMesh

# Query closest points, projections, and signed distances with Ray Casting / Flood Fill
query_pts = torch.randn((100000, 3), device="cuda")
query_ids, closest_tri_ids, projected_pts, sdfs = tmesh.query_points(
    query_pts, return_sdf=True, return_prj_pts=True, sign_mode=0
)

[!TIP] More worked pipelines, the core concepts behind them, and the full operator reference are on the documentation site.

📦 Installation

1. Install via PyPI

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)

# Pull and run the pre-built image
docker pull kohido/conquer3d:latest
docker run --rm --gpus all -it kohido/conquer3d:latest bash

Or build locally:

docker build -t conquer3d:latest .
docker run --rm --gpus all -it conquer3d:latest bash

3. Build from Source

Ensure you have a compatible CUDA toolkit ($\ge 12.0$) and PyTorch installed:

# Optional: Setup Conda environment
conda create -c conda-forge -n conquer3d python=3.10 gxx_linux-64=13 gcc_linux-64=13 sparsehash -y
conda activate conquer3d
conda install nvidia::cuda-toolkit==12.8.2 -y
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install pybind11-stubgen

# Install Conquer3D
git clone https://github.com/KhoiDOO/conquer3d.git
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: Computational geometry, differential topology, and acceleration structure foundations.
• Blog Posts: GPU spatial traversal, parallel BVH construction, and CUDA optimization guides.
• Related Repositories: Open-source geometric deep learning ecosystem.
• Books: Core computational geometry references.

A rendered bibliography is also available on the About page.

📝 Citation

@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.