Add TSDF / ESDF / Occupancy / Decay APIs and a fast marching-cubes variant (on upstream memory-resource seams)

[swahtz]

Summary

Native CUDA kernels and Python wrappers for TSDF and ESDF reconstruction, occupancy mapping, dynamic-scene decay, and a fast sparse-compact marching-cubes variant, sharing a common PersistentTSDFState + BuildPointTruncationShell substrate.

This supersedes #656, rebased onto the upstream-seams allocator work instead of the forked-header approach: it is stacked on #732 (feat/nanovdb-torch-resource), so the diff shown here includes #732's commits until that PR merges — review only the last three commits:

1. TSDF + ESDF + Occupancy + Decay + fast marching cubes — Fork a small set of nanoVDB headers to share PyTorch's CUDA allocator #655/Add TSDF / ESDF / Occupancy / Decay APIs and a fast marching-cubes variant #656's original feature commit, cherry-picked with authorship preserved. Content is unchanged from Add TSDF / ESDF / Occupancy / Decay APIs and a fast marching-cubes variant #656 apart from one merge-conflict resolution in tests/unit/test_basic_ops.py (main's new ray-intersection tests vs. this PR's fp16-expanded test_marching_cubes decorator; both kept). The multi-frame integrator paths rely on the TorchResource allocator routing from Route NanoVDB builder scratch through PyTorch's active CUDA allocator via upstream memory-resource seams #732 rather than the deleted nanovdb_overrides/ fork.
2. Format fix for the new TSDF / ESDF sources — pure clang-format pass over the three sources touched by the adaptation commit, kept separate so the adaptation diff below stays readable.
3. Adapt TSDF / ESDF stack to current nanovdb and fvdb APIs — the rebase adaptations (46+/35− lines), detailed below.

Draft until the upstream NanoVDB memory-resource stack (AcademySoftwareFoundation/openvdb#2268 / #2269 / #2270 / #2272 / #2273, tracking issue #2232) merges and #732's temporary nanovdb pin is repointed at AcademySoftwareFoundation/openvdb.

For the full feature inventory (topology/state primitives, depth + LiDAR TSDF integrators, occupancy mapping, ESDF, marching cubes, Python surface) see #656's description — the feature set is unchanged.

Rebase notes (May-era main → current main + memory-resource nanovdb)

Three mechanical adaptations to API drift, no behavioral change (commit 3 above):

• fvdb::HDDAVoxelIterator → fvdb::HDDALeafVoxelIterator in the two point-cloud integrators — the renamed alias whose contract matches their per-leaf-voxel sidecar indexing (getValue(ijk) - 1).
• buildVoxelBlockManager raw-pointer overload → direct BuildVoxelBlockManagerFunctor launch in ComputeESDF.cu. The overload was removed upstream in favor of a VoxelBlockManagerHandle API; the handle can't own TorchDeviceBuffers yet because its accessors static_cast from deviceData() (upstream issue NanoVDB: VoxelBlockManagerHandle accessors don't compile for buffer types whose data()/deviceData() return typed pointers AcademySoftwareFoundation/openvdb#2274). Keeping the firstLeafID / jumpMap arrays in torch tensors and launching the public functor directly performs the identical launch while staying in torch's pool; once #2274 lands this can move to the handle.
• VoxelBlockManager<BlockWidth> → VoxelBlockManager<Log2BlockWidth> in the ESDF sweep kernel — the template parameter changed meaning upstream.

Test plan

On a clean ./build.sh install against the stacked branch (full CUDA build, -Werror):

• tests/unit/test_persistent_tsdf_state.py — 7 tests
• tests/unit/test_compute_esdf.py — 17 tests (exercise the rewritten VBM build path)
• tests/unit/test_dirty_mask.py — 9 tests
• tests/unit/test_integrate_occupancy.py — 7 tests
• tests/unit/test_decay_and_prune.py — 9 tests
• tests/unit/test_basic_ops.py — 286 tests including the new TSDF / marching-cubes fp16 / occupancy additions alongside main's current suite

335 passed, 1 skipped locally on the fresh install.

Followups

• Undraft after the upstream stack merges and the nanovdb pin repoints (tracked on Route NanoVDB builder scratch through PyTorch's active CUDA allocator via upstream memory-resource seams #732).
• Move ComputeESDF's VBM arrays onto VoxelBlockManagerHandle<TorchDeviceBuffer> once NanoVDB: VoxelBlockManagerHandle accessors don't compile for buffer types whose data()/deviceData() return typed pointers AcademySoftwareFoundation/openvdb#2274 is fixed.
• Cross-library benchmark drivers (Replica, KITTI, Mai City, 7-Scenes; fvdb vs nvblox / VDBFusion / Open3D) live in a companion PR against openvdb/fvdb-reality-capture, unchanged from Add TSDF / ESDF / Occupancy / Decay APIs and a fast marching-cubes variant #656's plan.

🤖 Generated with Claude Code