deploy: 4609d3b

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: fe8663d64e9867dfb3fe1a43b977c592
+tags: 645f666f9bcd5a90fca523b33c5a78b7

CNAME

@@ -0,0 +1 @@
+docs.gsplat.studio

_sources/apis/proj.rst.txt

@@ -0,0 +1,42 @@
+ProjectGaussians
+===================================
+
+.. currentmodule:: gsplat
+
+Given 3D gaussians parametrized by means :math:`μ`, covariances :math:`Σ`, colors :math:`c`, and opacities :math:`o`, the 
+:func:`gsplat.project_gaussians` function computes the projected 2D gaussians in the camera frame with means :math:`μ'`, covariances :math:`Σ'`, and depths :math:`z`
+as well as their maximum radii in screen space and conic parameters. 
+
+Note, covariances are reparametrized by the eigen decomposition:
+
+.. math::
+   
+   Σ = RSS^{T}R^{T}
+
+Where rotation matrices :math:`R` are obtained from four dimensional quaternions.
+
+The projection of 3D Gaussians is approximated with the Jacobian of the perspective projection equation 
+as shown in :cite:p:`zwicker2002ewa`:
+
+.. math::
+
+    J = \begin{bmatrix}
+            f_{x}/t_{z} & 0 & -f_{x} t_{x}/t_{z}^{2} \\
+            0 & f_{y}/t_{z} & -f_{y} t_{y}/t_{z}^{2} \\
+            0 & 0 & 0
+        \end{bmatrix}
+
+Where :math:`t` is the center of a gaussian in camera frame :math:`t = Wμ+p`. The projected 2D covarience is then given by: 
+
+.. math::
+
+    Σ' = J W Σ W^{⊤} J^{⊤}
+
+
+Citations
+-------------
+.. bibliography::
+    :style: unsrt
+    :filter: docname in docnames
+
+.. autofunction:: project_gaussians

_sources/apis/rast.rst.txt

@@ -0,0 +1,36 @@
+RasterizeGaussians
+===================================
+
+.. currentmodule:: gsplat
+
+Given 2D gaussians that are parametrized by their means :math:`μ'` and covariances :math:`Σ'` as well as their radii and conic parameters,
+the :func:`gsplat.rasterize_gaussians` function first sorts each gaussian such that all gaussians within the bounds of a tile are grouped and sorted by increasing depth :math:`z`,
+and then renders each pixel within a tile with alpha-compositing. 
+
+The discrete rendering equation is given by: 
+
+.. math::
+
+    \sum_{t=n}^{N}c_{n}·α_{n}·T_{n}
+
+Where 
+
+.. math::
+
+    T_{n} = \prod_{t=m}^{M}(1-α_{m})
+
+And 
+
+.. math::
+
+    α_{n} = o_{n} \exp(-σ_{n})
+    
+    σ_{n} = \frac{1}{2} ∆^{⊤}_{n} Σ'^{−1} ∆_{n}
+
+
+:math:`σ ∈ R^{2}` is the Mahalanobis distance (here referred to as sigma) which measures how many standard deviations away the center of a gaussian and the rendered pixel center is which is denoted by delta :math:`∆.`
+
+The python bindings support conventional 3-channel RGB rasterization as well as N-dimensional rasterization with :func:`gsplat.rasterize_gaussians`.
+
+
+.. autofunction:: rasterize_gaussians

_sources/apis/utils.rst.txt

@@ -0,0 +1,18 @@
+Utils
+===================================
+In addition to the main projection and rasterization functions, a few CUDA kernel and helper functions are exposed to python with the following bindings:
+
+
+.. currentmodule:: gsplat
+
+.. autofunction:: bin_and_sort_gaussians
+
+.. autofunction:: compute_cov2d_bounds
+
+.. autofunction:: get_tile_bin_edges
+
+.. autofunction:: spherical_harmonics
+
+.. autofunction:: map_gaussian_to_intersects
+
+.. autofunction:: compute_cumulative_intersects

_sources/conventions/cuda_conventions.rst.txt

@@ -0,0 +1,44 @@
+CUDA Conventions
+===================================
+
+.. currentmodule:: diff_rast
+
+Here we explain some conventions used for the implementation of the CUDA backend.
+
+Kernel Launch Conventions
+-------------------------
+
+The backend CUDA code consists of several kernel functions that run in parallel for either arbitrary number of gaussians or for arbitrary image dimensions.
+Here we explain some of the conventions used for launching these kernel functions using the ``<<<gridDim, blockDim>>>`` notation.
+
+
+1D Grids
+^^^^^^^^
+
+Kernel functions that depend on the number of input gaussians are organized into one dimensional CUDA grids consisting of 
+
+.. code-block::
+
+    const int gridDim = (num_gaussian_operations + NUM_THREADS - 1) / NUM_THREADS;
+    
+1-D blocks containing ``const int blockDim = NUM_THREADS;`` threads each. An example of a kernel function that depends on the number of gaussians (here denoted by the ``num_gaussian_operations`` variable)
+is the main `project_gaussians` kernel that projects an arbitrary number of 3D gaussians into 2D.
+
+
+2D Grids
+^^^^^^^^
+
+Kernel functions that depend on the rendered output image size are organized into two dimensional CUDA grids. The shape of the grid is determined by 
+
+.. code-block:: 
+    
+    const dim3 gridDim = {(img_width + NUM_THREADS_X - 1) / NUM_THREADS_X, (img_height + NUM_THREADS_Y - 1) / NUM_THREADS_Y, 1};
+
+where each individual block within the grid contains a layout of threads defined by ``const dim3 blockDim = {NUM_THREADS_X, NUM_THREADS_Y, 1};``.
+An example of a kernel function that requires two dimensional grids is the main :func:`gsplat.rasterize_gaussians` kernel that renders an arbitrary number of pixels in an output image.
+
+
+Config Constants
+----------------
+
+We fix the total number of threads within a block to 256. This means that for 1D blocks the block dimension is given by ``const int blockDim = 256;`` and for 2D blocks ``const dim3 blockDim = {16, 16, 1};``.

_sources/conventions/data_conventions.rst.txt

@@ -0,0 +1,41 @@
+Data Conventions
+===================================
+
+.. currentmodule:: gsplat
+
+Here we explain the various data conventions used in our repo.
+
+Rotation Convention
+-------------------
+We represent rotations with four dimensional vectors :math:`q = (w,x,y,z)` such that the 3x3 :math:`SO(3)` rotation matrix is defined by:
+
+.. math::
+
+    R = \begin{bmatrix}
+        1 - 2 \left( y^2 + z^2 \right) & 2 \left( x y - w z \right) & 2 \left( x z + w y \right) \\
+        2 \left( x y + w z \right) & 1 - 2 \left( x^2 + z^2 \right) & 2 \left( y z - w x \right) \\
+        2 \left( x z - w y \right) & 2 \left( y z + w x \right) & 1 - 2 \left( x^2 + y^2 \right) \\
+        \end{bmatrix}
+
+View Matrix and Projection Matrix
+---------------------------------
+We refer to the `view matrix` :math:`W` as the world to camera frame transformation (referred to as `w2c` in some sources) that maps
+3D world points :math:`(x,y,z)_{world}` to 3D camera points :math:`(x,y,z)_{cam}` where :math:`z_{cam}` is the relative depth to the camera center.
+
+
+The `projection matrix` refers to the full projective transformation that maps 3D points in the world frame to the 2D points in the image/pixel frame.
+This transformation is the concatenation of the perspective projection matrix :math:`K` (obtained from camera intrinsics) and the view matrix :math:`W`.
+We adopt the `OpenGL <http://www.songho.ca/opengl/gl_projectionmatrix.html>`_ perspective projection convention. The projection matrix :math:`P` is given by:
+
+.. math:: 
+
+    P = K W
+
+.. math::
+
+    K = \begin{bmatrix}
+        \frac{2n}{r - l} & 0.0 & \frac{r + l}{r - l} & 0.0 \\
+        0.0 & \frac{2n}{t - b} & \frac{t + b}{t - b} & 0.0 \\
+        0.0 & 0.0 & \frac{f + n}{f - n} & -\frac{f \cdot n}{f - n} \\
+        0.0 & 0.0 & 1.0 & 0.0 \\
+    \end{bmatrix}

_sources/examples/simple_trainer.rst.txt

@@ -0,0 +1,28 @@
+Simple Trainer
+===================================
+
+.. currentmodule:: gsplat
+
+Training on an image
+-----------------------------------
+The `examples/simple_trainer.py` script allows you to test the basic forward projection and rasterization of random gaussians
+and their differentiability on a single training image. This allows you to overfit gaussians on a single view.
+
+Simply run the script with:
+
+.. code-block:: bash
+    :caption: simple_trainer.py
+
+    python examples/simple_trainer.py --height 256 --width 256 --num_points 2000 --save_imgs
+
+to get a result similar to the one below:
+
+.. image:: ../imgs/square.gif
+    :alt: Gaussians overfit on a single image
+    :width: 256
+
+You can also provide a path to your own custom image file using the ``--img_path`` flag:
+
+.. code-block:: bash
+
+    python examples/simple_trainer.py --img_path PATH_TO_IMG --save_imgs

_sources/index.rst.txt

@@ -0,0 +1,59 @@
+gsplat
+===================================
+
+.. image:: imgs/training.gif
+    :width: 800
+    :alt: Example training image
+
+Overview
+--------
+
+*gsplat* is an open-source library for CUDA accelerated rasterization of gaussians with python bindings. It is inspired by the SIGGRAPH paper "3D Gaussian Splatting for Real-Time Rendering of Radiance Fields" :cite:p:`kerbl3Dgaussians`.
+This libary contains the neccessary components for efficient 3D to 2D projection, sorting, and alpha compositing of gaussians and their associated backward passes for inverse rendering.
+
+Contributing
+------------
+
+This repository was born from the curiosity of people on the Nerfstudio team trying to understand a new rendering technique. We welcome contributions of any kind and are open to feedback, bug-reports, and improvements to help expand the capabilities of this software.
+
+
+Links
+-----
+
+.. toctree::    
+   :glob:
+   :maxdepth: 1
+   :caption: Examples
+
+   examples/*
+
+
+.. toctree::    
+   :glob:
+   :maxdepth: 1
+   :caption: Conventions
+
+   conventions/*
+
+
+.. toctree::    
+   :glob:
+   :maxdepth: 1
+   :caption: Python API
+
+   apis/*
+
+
+.. toctree::    
+   :glob:
+   :maxdepth: 1
+   :caption: Tests
+
+   tests/*
+
+
+Citations
+-------------
+.. bibliography::
+   :style: unsrt
+   :filter: docname in docnames