Merge branch 'main' into fw/jt_docs

Signed-off-by: Francis Williams <fwilliams@users.noreply.github.com>

Author: fwilliams

.github/workflows/docs.yml

@@ -100,11 +100,22 @@ jobs:
           micromamba activate fvdb
           ./build.sh install verbose --cuda-arch-list '8.9+PTX'
 
+      - name: Clone and build fvdb-reality-capture
+        run: |
+          echo "Cloning fvdb-reality-capture"
+          pwd
+          git clone https://github.com/openvdb/fvdb-reality-capture.git
+          pushd fvdb-reality-capture
+          pip install -e .
+          popd
+
       - name: Build docs
         run: |
           micromamba activate fvdb
           which sphinx-build
           sphinx-build docs/ -E -a _docs_build
+          sphinx-build fvdb-reality-capture/docs -E -a _docs_build/reality-capture
+
 
       - name: Upload static files as artifact
         id: deployment

Dockerfile

@@ -1,10 +1,8 @@
-FROM nvidia/cuda:12.8.1-cudnn-devel-ubuntu22.04
+FROM nvidia/cuda:12.9.1-cudnn-devel-ubuntu22.04
 
 # Set environment variables to prevent interactive prompts during installation.
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN sed -i 's/archive.ubuntu.com/mirrors.ocf.berkeley.edu/g' /etc/apt/sources.list
-
 # Install Python
 RUN apt-get update && \
     apt-get install -y python3-pip python3-dev python3-venv python-is-python3 wget git ninja-build vim libxcb1-dev libx11-dev libgl-dev pkgconf && \

README.md

@@ -21,32 +21,53 @@ Lastly, our [documentation](docs) provides deeper details on the concepts as wel
 
 ## Installing *f*VDB
 
-During the project's initial development stages, it is necessary to [run the build steps](#building-fvdb-from-source) to install ƒVDB. Eventually, ƒVDB will be provided as a pre-built, installable package. We support building the latest ƒVDB version for the following library configurations:
+The `fvdb_core` Python package can be installed either using published packages with pip or built
+from source.
 
-|   PyTorch      | Python      | CUDA |
-| -------------- | ----------- | ------------ |
-|  2.8.0-2.9.0   | 3.10 - 3.13 | 12.8 - 13.0 |
+### Platform Requirements
 
+#### Software
 
+fVDB is currently supported on the matrix of dependencies in the following table.
 
-** Notes:**
-* Linux is the only platform currently supported (Ubuntu >= 22.04 recommended).
-* A CUDA-capable GPU with Ampere architecture or newer (i.e. compute capability >=8.0) is recommended to run the CUDA-accelerated operations in ƒVDB.  A GPU with compute capabililty >=7.0 (Volta architecture) is the minimum requirement but some operations and data types are not supported.
+| OS         | PyTorch     | Python      | CUDA        |
+| ---------- | ----------- | ----------- | ----------- |
+| Linux Only | 2.8.0-2.9.0 | 3.10 - 3.13 | 12.8 - 13.0 |
 
+#### Hardware
+
+A CUDA-capable GPU with Ampere architecture or newer (i.e. compute capability >=8.0) is recommended
+to run the CUDA-accelerated operations in ƒVDB.  A GPU with compute capabililty >=7.0 (Volta) is the
+minimum requirement but some operations and data types are not supported.
+
+### Package Installation with pip
+
+Currently, pip wheels are built with PyTorch 2.8.0 and CUDA 12.9 only. Versions for Python 3.10-3.13
+are provided.
+
+Install fvdb_core using the following pip command.
+
+```
+pip install fvdb_core==0.3.0+pt28.cu129 --extra-index-url="https://d36m13axqqhiit.cloudfront.net/simple" torch==2.8.0 --extra-index-url https://download.pytorch.org/whl/cu129
+```
 
 ## Building *f*VDB from Source
 
 ### Environment Management
-ƒVDB is a Python library implemented as a C++ PyTorch extension.  Of course you can build ƒVDB in whatever environment suits you, but we provide three distinct paths to constructing reliable environments for building and running ƒVDB. These are separate options and are not intended to be used together.
-
-1. **RECOMMENDED** [conda](#option-1-conda-environment-recommended)
-2. Using [Docker](#option-2-docker-container)
-3. [Python virtual environment](#option-3-python-virtual-environment)
 
-`conda` tends to be more flexible since reconfiguring toolchains and modules to suit your larger project can be dynamic, but at the same time this can be a more brittle experience compared to using a virtualized `docker` container.  Using `conda` is generally recommended for development and testing, while using `docker` is recommended for CI/CD and deployment.
+ƒVDB is a Python library implemented as a C++ Pytorch extension. We provide three paths to
+constructing reliable environments for building and running ƒVDB. These are separate options not
+intended to be used together (however with modification you can of course use, for example, a conda
+or pip environment inside a docker container).
 
----
+1. **RECOMMENDED** [conda](#option-1-setting-up-a-conda-environment-recommended)
+2. Using [docker](#option-2-setting-up-a-docker-container)
+3. Python virtual environment. [venv](#option-3-setting-up-a-python-virtual-environment)
 
+`conda` tends to be more flexible since reconfiguring toolchains and modules to suit your larger
+project can be dynamic, but at the same time this can be a more brittle experience compared to using
+a virtualized `docker` container.  Using `conda` is generally recommended for development and
+testing, while using `docker` is recommended for CI/CD and deployment.
 
 #### **OPTION 1** Conda Environment (Recommended)
 
@@ -148,7 +169,18 @@ or if you would like to build a packaged wheel for installing in other environme
 
 ### Running Tests
 
-To make sure that everything works by running tests:
+#### C++ Tests
+
+To run the gtest C++ unit tests
+
+```shell
+./build.sh ctest
+```
+
+#### Python Tests
+
+To run the pytests
+
 ```shell
 cd tests
 pytest unit
@@ -158,10 +190,13 @@ pytest unit
 
 To build the documentation, simply run:
 ```shell
-python setup.py build_ext --inplace
-sphinx-build -E -a docs/ build/sphinx
+sphinx-build ./docs -a -E build/sphinx
 # View the docs
 open build/sphinx/index.html
+# View docs as served
+cd build/sphinx
+python -m http.server
+# Open localhost:8000 in browser
 ```
 
 ### Setting up Intellisense with clangd in Visual Studio Code

fvdb/_Cpp.pyi

@@ -1004,8 +1004,14 @@ class Viewer:
         camera_to_world_matrices: torch.Tensor,
         projection_matrices: torch.Tensor,
         image_sizes: torch.Tensor,
-        frustum_near_plane: float = 0.1,
-        frustum_far_plane: float = 1000.0,
+        frustum_near_plane: float,
+        frustum_far_plane: float,
+        axis_length: float,
+        axis_thickness: float,
+        frustum_line_width: float,
+        frustum_scale: float,
+        frustum_color: tuple[float, float, float],
+        visible: bool,
     ) -> CameraView: ...
     def has_camera_view(self, name: str) -> bool: ...
     def get_camera_view(self, name: str) -> CameraView: ...

fvdb/grid.py

@@ -10,6 +10,7 @@
 - Grid: A single sparse voxel grid with support for efficient operations
 
 Class-methods for creating Grid objects from various sources:
+
 - :meth:`Grid.from_dense()` for dense data
 - :meth:`Grid.from_dense_axis_aligned_bounds()` for dense defined by axis-aligned bounds
 - :meth:`Grid.from_grid_batch()` for a single grid from a grid batch
@@ -19,8 +20,8 @@
 - :meth:`Grid.from_points()` for point clouds
 - :meth:`Grid.from_zero_voxels()` for a single grid with zero voxels
 
-Module-level functions for loading and saving grids:
-- load_grid/save_grid: Load and save grids to/from .nvdb files
+Class/Instance-methods for loading and saving grids:
+- from_nanovdb/save_nanovdb: Load and save grids to/from .nvdb files
 
 Grid supports operations like convolution, pooling, interpolation, ray casting,
 mesh extraction, and coordinate transformations on sparse voxel data.
@@ -66,7 +67,7 @@ class Grid:
     which a grid can be used to index into. This also allows multiple grids to share the same data
     storage if desired.
 
-    When using a :class:`Grid`, voxel coordinates, there are three important coordinate systems to be aware of:
+    When using a :class:`Grid`'s voxel coordinates, there are three important coordinate systems to be aware of:
 
     - **World Space**: The continuous 3D coordinate system in which the grid exists.
     - **Voxel Space**: The discrete voxel index system, where each voxel is identified by its integer indices (i, j, k).
@@ -589,7 +590,6 @@ def clipped_grid(
     def coarsened_grid(self, coarsening_factor: NumericMaxRank1) -> "Grid":
         """
         Return a :class:`Grid` representing the coarsened version of this grid.
-        Each voxel ``[i, j, k]`` in the input is included in the output if it lies within ``ijk_min`` and ``ijk_max``.
 
         Args:
             coarsening_factor (NumericMaxRank1): The factor by which to coarsen the grid,
@@ -737,12 +737,12 @@ def dual_grid(self, exclude_border: bool = False) -> "Grid":
 
     def voxel_to_world(self, ijk: torch.Tensor) -> torch.Tensor:
         """
-        Transform a set of grid-space coordinates to their corresponding positions in world space
+        Transform a set of voxel-space coordinates to their corresponding positions in world space
         using this :class:`Grid`'s origin and voxel size.
 
         .. seealso::
 
-            :meth:`world_to_voxel` for the inverse transformation, and :meth:`voxel_to_world_matrix` and :meth:`world_to_voxel_matrix` for
+            :meth:`world_to_voxel` for the inverse transformation, and :attr:`voxel_to_world_matrix` and :attr:`world_to_voxel_matrix` for
             the actual transformation matrices.
 
 
@@ -974,7 +974,7 @@ def inject_to(
 
             If you pass in destination data, ``dst``, then ``dst`` will be modified in-place.
             If ``dst`` is ``None``, a new :class:`torch.Tensor` will be created with the
-            shape ``(self.num_voxels, *src.shape[1:])`` and filled with ``default_value``
+            shape ``(dst_grid.num_voxels, *src.shape[1:])`` and filled with ``default_value``
             for any voxels that do not have corresponding data in ``src``.
 
         .. note::
@@ -1028,7 +1028,7 @@ def integrate_tsdf(
 
         Args:
             truncation_distance (float): Maximum distance to truncate TSDF values (in world units).
-            projection_matrix (torch.Tensor): Camera projection matrix. A tensor-like object with ``shape: (4, 4)``.
+            projection_matrix (torch.Tensor): Camera projection matrix. A tensor-like object with ``shape: (3, 3)``.
             cam_to_world_matrix (torch.Tensor): Camera to world transformation matrix. A tensor-like object with ``shape: (4, 4)``.
             tsdf (torch.Tensor): Current TSDF values for each voxel. A :class:`torch.Tensor` with shape: ``(self.num_voxels, 1)``.
             weights (torch.Tensor): Current integration weights for each voxel.
@@ -1120,7 +1120,7 @@ def integrate_tsdf_with_features(
 
         Args:
             truncation_distance (float): Maximum distance to truncate TSDF values (in world units).
-            projection_matrix (torch.Tensor): Camera projection matrix. A tensor-like object with ``shape: (4, 4)``.
+            projection_matrix (torch.Tensor): Camera projection matrix. A tensor-like object with ``shape: (3, 3)``.
             cam_to_world_matrix (torch.Tensor): Camera to world transformation matrix. A tensor-like object with ``shape: (4, 4)``.
             features (torch.Tensor): Current feature values associated with each voxel in this :class:`Grid`.
                 A :class:`torch.Tensor` with shape ``(total_voxels, feature_dim)``.
@@ -1325,7 +1325,7 @@ def merged_grid(self, other: "Grid") -> "Grid":
 
     def neighbor_indexes(self, ijk: torch.Tensor, extent: int, bitshift: int = 0) -> torch.Tensor:
         """
-        Get indices of neighboring voxels in this :class:`Grid` in an N-ring neighborhood of each
+        Get indexes of neighboring voxels in this :class:`Grid` in an N-ring neighborhood of each
         voxel coordinate in ``ijk``.
 
         Args:
@@ -1337,9 +1337,9 @@ def neighbor_indexes(self, ijk: torch.Tensor, extent: int, bitshift: int = 0) ->
                 Default is 0.
 
         Returns:
-            neighbor_indices (torch.Tensor): A :class:`torch.Tensor` of shape ``(num_queries, N)``
-                containing the linear indices of neighboring voxels for each voxel coordinate in ``ijk``
-                in the input. If some neighbors are not active in the grid, their indices will be ``-1``.
+            neighbor_indexes (torch.Tensor): A :class:`torch.Tensor` of shape ``(num_queries, N)``
+                containing the linear indexes of neighboring voxels for each voxel coordinate in ``ijk``
+                in the input. If some neighbors are not active in the grid, their indexes will be ``-1``.
         """
         jagged_ijk = JaggedTensor(ijk)
         return self._impl.neighbor_indexes(jagged_ijk._impl, extent, bitshift).jdata
@@ -1459,7 +1459,7 @@ def inject_from_dense_cminor(self, dense_data: torch.Tensor, dense_origin: Numer
 
         Args:
             dense_data (torch.Tensor): Dense :class:`torch.Tensor` to read from. Shape: ``(dense_size_x, dense_size_y, dense_size_z, channels*)``.
-            dense_origins (NumericMaxRank1, optional): Origin of the dense tensor in
+            dense_origin (NumericMaxRank1, optional): Origin of the dense tensor in
                 voxel space, broadcastable to shape ``(3,)``, integer dtype
 
         Returns:
@@ -1490,7 +1490,7 @@ def inject_from_dense_cmajor(self, dense_data: torch.Tensor, dense_origin: Numer
 
         Args:
             dense_data (torch.Tensor): Dense :class:`torch.Tensor` to read from. Shape: ``(channels*, dense_size_x, dense_size_y, dense_size_z)``.
-            dense_origins (NumericMaxRank1, optional): Origin of the dense tensor in
+            dense_origin (NumericMaxRank1, optional): Origin of the dense tensor in
                 voxel space, broadcastable to shape ``(3,)``, integer dtype
 
         Returns:
@@ -1656,7 +1656,7 @@ def sample_trilinear_with_grad(
         Returns:
             interpolated_data (torch.Tensor): Interpolated data at each point. Shape: ``(num_queries, channels*)``.
             interpolation_gradients (torch.Tensor): Gradients of the interpolated data with respect to world coordinates.
-                This is the spatial gradient of the Bézier interpolation at each point.
+                This is the spatial gradient of the trilinear interpolation at each point.
                 Shape: ``(num_queries, 3, channels*)``.
         """
         jagged_points = JaggedTensor(points)
@@ -2052,7 +2052,7 @@ def world_to_voxel(self, points: torch.Tensor) -> torch.Tensor:
 
         .. seealso::
 
-            :meth:`voxel_to_world` for the inverse transformation, and :meth:`voxel_to_world_matrix` and :meth:`world_to_voxel_matrix` for
+            :meth:`voxel_to_world` for the inverse transformation, and :attr:`voxel_to_world_matrix` and :attr:`world_to_voxel_matrix` for
             the actual transformation matrices.
 
         Args:
@@ -2072,7 +2072,7 @@ def inject_to_dense_cminor(
         grid_size: NumericMaxRank1 | None = None,
     ) -> torch.Tensor:
         """
-        Inject values from :class:`torch.Tensor` associated with this :class:`Grid` into a
+        Write values from a :class:`torch.Tensor` associated with this :class:`Grid` into a
         dense :class:`torch.Tensor`.
 
         This is the "C Minor" (channels minor) version, which assumes the ``dense_data`` is in XYZC order. *i.e* the
@@ -2092,8 +2092,8 @@ def inject_to_dense_cminor(
 
         .. seealso::
 
-            :meth:`inject_from_dense_cmajor` for reading from a dense tensor in "C Major" order,
-            which assumes the dense tensor has shape ``[channels*, dense_size_x, dense_size_y, dense_size_z]``.
+            :meth:`inject_from_dense_cminor` for reading from a dense tensor in "C Minor" order,
+            which assumes the dense tensor has shape ``[dense_size_x, dense_size_y, dense_size_z, channels*]``.
 
         .. seealso::
 
@@ -2131,7 +2131,7 @@ def inject_to_dense_cmajor(
         grid_size: NumericMaxRank1 | None = None,
     ) -> torch.Tensor:
         """
-        Write values from :class:`torch.Tensor` associated with this :class:`Grid` into a
+        Write values from a :class:`torch.Tensor` associated with this :class:`Grid` into a
         dense :class:`torch.Tensor`.
 
         This is the "C Major" (channels major) version, which assumes the ``dense_data`` is in CXYZ order. *i.e* the
@@ -2141,7 +2141,7 @@ def inject_to_dense_cmajor(
         within the range defined by ``min_coord`` and ``grid_size``.
         Voxels not present in the sparse grid are filled with zeros. *.i.e.* this method will copy
         all the voxel values in the range ``[min_coord, min_coord + grid_size)`` into a dense tensor
-        of shape ``[dense_size_x, dense_size_y, dense_size_z, channels*]``, such that ``min_coord``
+        of shape ``[channels*, dense_size_x, dense_size_y, dense_size_z]``, such that ``min_coord``
         maps to index ``(0, 0, 0)`` in the dense tensor, and ``min_coord + grid_size - 1`` maps to index
         ``(dense_size_x - 1, dense_size_y - 1, dense_size_z - 1)`` in the dense tensor.
 
@@ -2207,7 +2207,7 @@ def bbox(self) -> torch.Tensor:
 
         .. note::
 
-            The bounding box is inclusive of the minimum voxel and the the maximum voxel.
+            The bounding box is inclusive of the minimum voxel and the maximum voxel.
 
             *e.g.* if you have a grid with a single voxel at index ``(0, 0, 0)``, the bounding box will be
             ``[[0, 0, 0], [0, 0, 0]]``.
@@ -2247,7 +2247,7 @@ def dual_bbox(self) -> torch.Tensor:
 
         .. note::
 
-            The bounding box is inclusive of the minimum voxel and the the maximum voxel.
+            The bounding box is inclusive of the minimum voxel and the maximum voxel.
 
             *e.g.* if you have a grid with a single voxel at index ``(0, 0, 0)``, the dual grid will contain voxels
             at indices ``(0, 0, 0), (0, 0, 1), (0, 1, 0), ..., (1, 1, 1)``, and the bounding box will be