TSDF + ESDF + Occupancy + Decay + fast marching cubes

Add native CUDA kernels and Python wrappers for TSDF and ESDF
reconstruction, occupancy mapping, dynamic-scene decay, and a fast
sparse-compact marching-cubes variant. These features sit on top of
the nanoVDB allocator-overrides change (parent PR) and share a
common `PersistentTSDFState` + `BuildPointTruncationShell` substrate.

Topology + state primitives

  src/fvdb/detail/ops/BuildPointTruncationShell.{cu,h}
      Shared primitive that turns `(points, base_grid, truncation_margin)`
      into the set of voxels within the truncation shell. Used by both
      depth and LiDAR TSDF integrators.

  src/fvdb/detail/ops/PersistentTSDFState.{cu,h}
      Grow-on-touch state holder for incremental integration: wraps a
      monotonically-growing live grid with fixed-shape tsdf / weights /
      optional feature sidecars and exposes a `grow` method that
      expands the grid + sidecars atomically while preserving values
      at already-live voxels.

  src/python/PersistentTSDFStateBinding.cpp
      Pybind11 binding for the above.

Integrators

  src/fvdb/detail/ops/IntegrateTSDF.{cu,h}  (modified)
      Depth TSDF integrator now uses `BuildPointTruncationShell` and
      `PersistentTSDFState`, and exposes a new N-frame batched entry
      point `integrateTSDFBatch` that grows the union grid one frame
      at a time and copy-forwards sidecars through the
      persistent-state object. Bit-identical to the per-frame loop
      (pinned by `test_integrate_tsdf_frames_matches_sequential`).

  src/fvdb/detail/ops/IntegrateTSDFFromPoints.{cu,h}
      Native LiDAR / range-sensor TSDF integrator: per-point thread
      HDDA-walks the union grid and `atomicAdd`s a running-sum into
      (sum_w_sdf, sum_w, sum_w_feat) accumulators within the
      truncation (and optionally free-space) band. Single-frame,
      with-features, and N-frames-batched variants.

  src/fvdb/detail/ops/IntegrateOccupancyFromPoints.{cu,h}
      LiDAR occupancy mapping with free-space carving and log-odds
      updates. Single-frame and N-frames-batched variants. Same
      ray-walk structure as the LiDAR TSDF integrator.

ESDF

  src/fvdb/detail/ops/ComputeESDF.{cu,h}
      Euclidean Signed Distance Field from an integrated narrow-band
      TSDF. Composition pattern is
      `dilateGrid -> esdfSeed -> N sweeps of 26-N min-propagation`,
      reusing the topology-op primitives.

  src/fvdb/detail/ops/DirtyMaskFromSidecars.{cu,h}
      Per-voxel dirty-mask primitive that lets the incremental ESDF
      variant scope work to just the voxels whose sidecars changed.

Marching cubes

  src/fvdb/detail/ops/MarchingCubesFast.{cu,h}
      Sparse-compact, packed-key marching cubes for fp32 / fp16 CUDA.
      `marchingCubes` now dispatches to this for eligible inputs and
      to `marchingCubesLegacy` (the previous default, kept verbatim)
      otherwise.

  src/fvdb/detail/ops/MarchingCubes.{cu,h}  (modified)
      Routes through to the new fast path.

Python surface

  fvdb/functional/_meshing.py
      Wrappers for the new N-frame + with-features + LiDAR variants
      of TSDF integration, occupancy mapping (single + frames), and
      ESDF (single + incremental).

  fvdb/functional/_topology.py
      Wrapper for `dirty_mask_from_sidecars_single`.

  fvdb/grid.py
      New methods on `Grid`: `decay_and_prune`,
      `integrate_tsdf_frames`, `integrate_tsdf_with_features`,
      `integrate_tsdf_from_points` (+ frames + with-features
      variants), `integrate_occupancy_from_points` (+ frames),
      `compute_esdf`, `compute_esdf_incremental`. `decay_and_prune`
      is implemented entirely in Python on top of existing fvdb
      sidecar + topology primitives.

  fvdb/functional/__init__.py
      Export the new functional names.

  src/python/Bindings.cpp, src/python/GridBatchOps.cpp
      Register the new C++ bindings.

Tests

  tests/unit/test_persistent_tsdf_state.py
  tests/unit/test_compute_esdf.py
  tests/unit/test_dirty_mask.py
  tests/unit/test_integrate_occupancy.py
  tests/unit/test_decay_and_prune.py
  tests/unit/test_basic_ops.py  (extended)

      Cover the new primitives, the persistent-state invariants
      (`grow` semantics, sidecar carry-forward), bit-identity of the
      batched-vs-sequential TSDF paths, atomic-noise tolerance for
      the LiDAR/occupancy variants, and fp16-vs-fp32 numerical
      agreement for the new marching-cubes fast path.

Signed-off-by: Francis Williams <francis@fwilliams.info>

Author: fwilliams

CMakeLists.txt

@@ -139,6 +139,7 @@ set(FVDB_BINDINGS_CPP_FILES
     src/python/GridBatchDataBinding.cpp
     src/python/GridBatchOps.cpp
     src/python/JaggedTensorBinding.cpp
+    src/python/PersistentTSDFStateBinding.cpp
     src/python/ViewerBinding.cpp)
 
 # Build library

fvdb/functional/__init__.py

@@ -10,51 +10,6 @@
 - ``*_single`` -- operates on :class:`~fvdb.Grid` with plain ``torch.Tensor``.
 """
 
-# Grid constructors (batch)
-from ._constructors import (
-    concatenate_grids,
-    gridbatch_from_dense,
-    gridbatch_from_dense_axis_aligned_bounds,
-    gridbatch_from_ijk,
-    gridbatch_from_mesh,
-    gridbatch_from_nearest_voxels_to_points,
-    gridbatch_from_points,
-    gridbatch_from_zero_grids,
-    gridbatch_from_zero_voxels,
-)
-
-# isort: split
-
-# Grid constructors (single)
-from ._constructors import (
-    grid_from_dense,
-    grid_from_dense_axis_aligned_bounds,
-    grid_from_ijk,
-    grid_from_mesh,
-    grid_from_nearest_voxels_to_points,
-    grid_from_points,
-    grid_from_zero_voxels,
-)
-
-# Dense <-> sparse I/O and grid-to-grid injection
-from ._dense import (
-    inject_batch,
-    inject_from_dense_cmajor_batch,
-    inject_from_dense_cmajor_single,
-    inject_from_dense_cminor_batch,
-    inject_from_dense_cminor_single,
-    inject_from_ijk_batch,
-    inject_from_ijk_single,
-    inject_single,
-    inject_to_dense_cmajor_batch,
-    inject_to_dense_cmajor_single,
-    inject_to_dense_cminor_batch,
-    inject_to_dense_cminor_single,
-)
-
-# Grid indexing
-from ._indexing import index_grid_batch
-
 # Interpolation / splatting
 from ._interpolation import (
     sample_bezier_batch,
@@ -73,24 +28,12 @@
     splat_trilinear_single,
 )
 
-# I/O
-from ._io import (
-    grid_names_in_nanovdb,
-    load_nanovdb,
-    load_nanovdb_single,
-    read_nanovdb_metadata,
-    save_nanovdb,
-    save_nanovdb_single,
-)
-
-# Meshing / TSDF
-from ._meshing import (
-    integrate_tsdf_batch,
-    integrate_tsdf_single,
-    integrate_tsdf_with_features_batch,
-    integrate_tsdf_with_features_single,
-    marching_cubes_batch,
-    marching_cubes_single,
+# Coordinate transforms
+from ._transforms import (
+    voxel_to_world_batch,
+    voxel_to_world_single,
+    world_to_voxel_batch,
+    world_to_voxel_single,
 )
 
 # Pooling / refinement
@@ -103,6 +46,22 @@
     refine_single,
 )
 
+# Dense <-> sparse I/O and grid-to-grid injection
+from ._dense import (
+    inject_batch,
+    inject_from_dense_cmajor_batch,
+    inject_from_dense_cmajor_single,
+    inject_from_dense_cminor_batch,
+    inject_from_dense_cminor_single,
+    inject_from_ijk_batch,
+    inject_from_ijk_single,
+    inject_single,
+    inject_to_dense_cmajor_batch,
+    inject_to_dense_cmajor_single,
+    inject_to_dense_cminor_batch,
+    inject_to_dense_cminor_single,
+)
+
 # Spatial queries
 from ._query import (
     active_grid_coords_batch,
@@ -137,6 +96,27 @@
     voxels_along_rays_single,
 )
 
+# Meshing / TSDF
+from ._meshing import (
+    compute_esdf_incremental_single,
+    compute_esdf_single,
+    integrate_occupancy_from_points_frames_single,
+    integrate_occupancy_from_points_single,
+    integrate_tsdf_batch,
+    integrate_tsdf_frames_single,
+    integrate_tsdf_frames_with_features_single,
+    integrate_tsdf_from_points_batch,
+    integrate_tsdf_from_points_frames_single,
+    integrate_tsdf_from_points_single,
+    integrate_tsdf_from_points_with_features_batch,
+    integrate_tsdf_from_points_with_features_single,
+    integrate_tsdf_single,
+    integrate_tsdf_with_features_batch,
+    integrate_tsdf_with_features_single,
+    marching_cubes_batch,
+    marching_cubes_single,
+)
+
 # Grid topology
 from ._topology import (
     clip_batch,
@@ -155,6 +135,7 @@
     conv_transpose_grid_single,
     dilated_grid_batch,
     dilated_grid_single,
+    dirty_mask_from_sidecars_single,
     dual_grid_batch,
     dual_grid_single,
     edge_network_batch,
@@ -175,12 +156,41 @@
     refined_grid_single,
 )
 
-# Coordinate transforms
-from ._transforms import (
-    voxel_to_world_batch,
-    voxel_to_world_single,
-    world_to_voxel_batch,
-    world_to_voxel_single,
+# Grid indexing
+from ._indexing import index_grid_batch
+
+# Grid constructors (batch)
+from ._constructors import (
+    concatenate_grids,
+    gridbatch_from_dense,
+    gridbatch_from_dense_axis_aligned_bounds,
+    gridbatch_from_ijk,
+    gridbatch_from_mesh,
+    gridbatch_from_nearest_voxels_to_points,
+    gridbatch_from_points,
+    gridbatch_from_zero_grids,
+    gridbatch_from_zero_voxels,
+)
+
+# Grid constructors (single)
+from ._constructors import (
+    grid_from_dense,
+    grid_from_dense_axis_aligned_bounds,
+    grid_from_ijk,
+    grid_from_mesh,
+    grid_from_nearest_voxels_to_points,
+    grid_from_points,
+    grid_from_zero_voxels,
+)
+
+# I/O
+from ._io import (
+    grid_names_in_nanovdb,
+    load_nanovdb,
+    load_nanovdb_single,
+    read_nanovdb_metadata,
+    save_nanovdb,
+    save_nanovdb_single,
 )
 
 __all__ = [
@@ -254,9 +264,20 @@
     "ray_implicit_intersection_batch",
     "ray_implicit_intersection_single",
     # Meshing
+    "compute_esdf_incremental_single",
+    "compute_esdf_single",
+    "integrate_occupancy_from_points_frames_single",
+    "integrate_occupancy_from_points_single",
     "marching_cubes_batch",
     "marching_cubes_single",
     "integrate_tsdf_batch",
+    "integrate_tsdf_frames_single",
+    "integrate_tsdf_frames_with_features_single",
+    "integrate_tsdf_from_points_batch",
+    "integrate_tsdf_from_points_frames_single",
+    "integrate_tsdf_from_points_single",
+    "integrate_tsdf_from_points_with_features_batch",
+    "integrate_tsdf_from_points_with_features_single",
     "integrate_tsdf_single",
     "integrate_tsdf_with_features_batch",
     "integrate_tsdf_with_features_single",
@@ -277,6 +298,7 @@
     "dual_grid_single",
     "dilated_grid_batch",
     "dilated_grid_single",
+    "dirty_mask_from_sidecars_single",
     "merged_grid_batch",
     "merged_grid_single",
     "pruned_grid_batch",