Functional Gaussian Splatting API

.gitignore

@@ -72,3 +72,6 @@ scratch/
 *_benchmark.json
 *_results.json
 comparison_*.png
+
+# A staging file for PR descriptions
+_PR_STAGING.md

CMakeLists.txt

@@ -34,7 +34,7 @@ add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/src/)
 set(FVDB_BINDINGS_CPP_FILES
     src/python/Bindings.cpp
     src/python/FusedSSIMBinding.cpp
-    src/python/GaussianSplatBinding.cpp
+    src/python/GaussianSplatOps.cpp
     src/python/GridBatchDataBinding.cpp
     src/python/GridBatchOps.cpp
     src/python/JaggedTensorBinding.cpp

docs/api/functional_splat.rst

@@ -0,0 +1,136 @@
+Functional Gaussian Splatting API
+=================================
+
+.. module:: fvdb.functional
+
+The Gaussian splatting functions in :mod:`fvdb.functional` provide a
+pure-function interface for Gaussian splatting rendering.  Every operation is a
+standalone function that takes raw tensors as input, following the same design
+philosophy as the rest of :mod:`fvdb.functional` for sparse-grid operations.
+
+The API is organized as a **4-stage composable pipeline**:
+
+1. ``project_gaussians`` -- geometric projection (Stage 1)
+2. ``evaluate_gaussian_sh`` -- SH / feature evaluation (Stage 2)
+3. ``intersect_gaussian_tiles`` / ``intersect_gaussian_tiles_sparse`` -- tile intersection (Stage 3)
+4. ``rasterize_screen_space_gaussians`` / ``rasterize_world_space_gaussians``
+   / ``rasterize_screen_space_gaussians_sparse`` -- rasterization (Stage 4)
+
+All stages are fully differentiable via Python autograd (except tile intersection).
+
+.. tip::
+
+   For standard rendering, the methods on :class:`~fvdb.GaussianSplat3d`
+   are the simplest entry points.
+
+   The decomposed stages are for users who need fine-grained control over the
+   rendering pipeline -- for example, to insert custom logic between projection
+   and rasterization, or to build training loops without the
+   :class:`~fvdb.GaussianSplat3d` wrapper.
+
+
+**Example: building a custom render pipeline**
+
+.. code-block:: python
+
+   import torch
+   import fvdb.functional as F
+   from fvdb.enums import CameraModel, GaussianRenderMode
+
+   # Raw tensors (no GaussianSplat3d needed)
+   means = ...        # [N, 3]
+   quats = ...        # [N, 4]
+   log_scales = ...   # [N, 3]
+   logit_opacities = ...  # [N]
+   sh0 = ...          # [N, 1, 3]
+   shN = ...          # [N, K-1, 3]
+   world_to_cam = ... # [C, 4, 4]
+   K = ...            # [C, 3, 3]
+
+   # Stage 1: Geometric projection
+   projected = F.project_gaussians(
+       means, quats, log_scales, world_to_cam, K,
+       image_width=640, image_height=480,
+   )
+
+   # Stage 2: View-dependent features (SH evaluation)
+   features = F.evaluate_gaussian_sh(
+       means, sh0, shN, world_to_cam, projected,
+       sh_degree_to_use=3,
+       render_mode=GaussianRenderMode.FEATURES,
+   )
+
+   # Stage 3: Tile intersection
+   tiles = F.intersect_gaussian_tiles(projected)
+
+   # Stage 4: Rasterize
+   images, alphas = F.rasterize_screen_space_gaussians(
+       projected, features, logit_opacities, tiles,
+   )
+
+   # Compute loss and backpropagate -- gradients flow through all stages
+   loss = torch.nn.functional.l1_loss(images, target_images)
+   loss.backward()
+
+
+Types
+------
+
+.. autoclass:: ProjectedGaussians
+   :members:
+
+.. autoclass:: GaussianTileIntersection
+   :members:
+
+.. autoclass:: SparseGaussianTileIntersection
+   :members:
+
+
+Stage 1: Projection
+^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: project_gaussians
+
+
+Stage 2: SH / Feature Evaluation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: evaluate_gaussian_sh
+
+
+Stage 3: Tile Intersection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: intersect_gaussian_tiles
+
+.. autofunction:: intersect_gaussian_tiles_sparse
+
+
+Stage 4: Rasterization
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: rasterize_screen_space_gaussians
+
+.. autofunction:: rasterize_world_space_gaussians
+
+.. autofunction:: rasterize_screen_space_gaussians_sparse
+
+
+Analysis
+---------
+
+.. autofunction:: count_contributing_gaussians
+
+.. autofunction:: identify_contributing_gaussians
+
+.. autofunction:: count_contributing_gaussians_sparse
+
+.. autofunction:: identify_contributing_gaussians_sparse
+
+
+Metrics
+--------
+
+.. autofunction:: psnr
+
+.. autofunction:: ssim

docs/api/gaussian_splatting.rst

@@ -1,10 +1,28 @@
 Gaussian Splatting
 ==========================
 
+The :class:`~fvdb.GaussianSplat3d` class provides an object-oriented interface
+for Gaussian splatting rendering.  It manages Gaussian parameters (means,
+quaternions, scales, opacities, SH coefficients) and provides methods for
+projection, rasterization, and training-related operations like gradient
+accumulation and MCMC densification.
+
 .. autoclass:: fvdb.ProjectedGaussianSplats
    :members:
    :special-members: __getitem__, __setitem__
 
 .. autoclass:: fvdb.GaussianSplat3d
    :members:
    :special-members: __getitem__, __setitem__
+
+.. seealso::
+
+   :mod:`fvdb.functional` provides a pure-function alternative for
+   building custom rendering pipelines without the
+   :class:`~fvdb.GaussianSplat3d` wrapper.  The functional API decomposes
+   the rendering pipeline into individually composable stages
+   (:func:`~fvdb.functional.project_gaussians`,
+   :func:`~fvdb.functional.evaluate_gaussian_sh`,
+   :func:`~fvdb.functional.intersect_gaussian_tiles`,
+   :func:`~fvdb.functional.rasterize_screen_space_gaussians`), enabling
+   custom training loops and pipeline composition without mutable state.

docs/api/utils.rst

@@ -7,5 +7,7 @@ Utilities
 ``fvdb.utils.metrics``
 --------------------------
 
-.. automodule:: fvdb.utils.metrics
-    :members:
+.. deprecated::
+   The ``fvdb.utils.metrics`` module re-exports :func:`~fvdb.functional.psnr`
+   and :func:`~fvdb.functional.ssim` for backward compatibility.  Use
+   ``fvdb.functional.psnr`` and ``fvdb.functional.ssim`` directly.

docs/index.rst

@@ -100,6 +100,7 @@ algorithms for 3D reconstruction from sensor data.
    api/convolution_plan
    api/sparse_grids
    api/functional
+   api/functional_splat
    api/gaussian_splatting
    api/viz
    api/enums