Large README update (openvdb#299)

swahtz · web-flow · commit 26abaef02388 · 2025-10-25T09:48:01.000+13:00
Large README update
copied in intro copy from docs
replaced banner image
Removed install instructions to point to docs
Updated a bunch of build info
Removed examples
Some formatting unification bits and bobs

Signed-off-by: Jonathan Swartz &lt;jonathan@jswartz.info&gt;

Signed-off-by: Jonathan Swartz &lt;jonathan@jswartz.info&gt;
diff --git a/README.md b/README.md
@@ -1,58 +1,44 @@
 # *ƒ*(VDB)
 
+fVDB is a Python library of data structures and algorithms for building high-performance and large-domain
+spatial applications using [NanoVDB](https://dl.acm.org/doi/abs/10.1145/3450623.3464653) on the GPU
+in [PyTorch](https://pytorch.org/).
+Applications of fVDB include 3D deep learning, computer graphics/vision, robotics, and scientific computing.
 
-This repository contains the code for *f*VDB, a framework for encoding and operating on *sparse voxel hierarchies* of features in PyTorch. A sparse voxel hierarchy is a coarse-to-fine hierarchy of sparse voxel grids such that every fine voxel is contained within some coarse voxel. The image below illustrates an example. *f*VDB supports using PyTorch Tensors to represent features at the corners and centers of voxels in a hierarchy and enables a number of differentiable operations on these Tensors (*e.g.* trilinear interpolation, convolution, splatting, ray tracing).
 
 <p align="center">
-  <img src="docs/imgs/fvdb_teaser.png" style="width: 40%;"alt="fVDB Teaser">
-  <!-- <img src="docs/imgs/readme/av_screenshot.png" style="width: 100%;"alt="fVDB Teaser"> -->
-  <figcaption style="text-align: center; font-style: italic;">An example of a sparse voxel hierarchy with 3 levels. Each fine voxel is contained within exactly one coarse voxel.</figcaption>
+  <img src="docs/imgs/fvdb_teaser.jpg" style="width: 90%;"alt="fVDB Teaser">
 </p>
 
-*f*VDB was first developed by the [NVIDIA High-Fidelity Physics Research Group](https://research.nvidia.com/labs/prl/) (a part of the NVIDIA Spatial Intelligence Lab) and continues to be developed with the OpenVDB community to suit the growing needs for a robust framework for spatial intelligence research and applications.  Please review [the paper](https://research.nvidia.com/labs/prl/publication/williams2024fvdb/) for more details and kindly consider [citing it in your work](#references) if you find it useful.
 
-## Learning to Use *f*VDB
-
-After [installing *f*VDB](#installing-fvdb), we recommend starting with our walk-through [notebooks](notebooks) which provide a gentle, illustrated introduction to the main concepts and operations in *f*VDB.
-
-Once familiar with the basics, [Usage Examples](#usage-examples) introduces a few of the practical python scripts that can be further explored in the [examples](examples) directory.
-
-Lastly, our [documentation](docs) provides deeper details on the concepts as well as an exhaustive set of illustrations of all the operations available in *f*VDB and an API reference. The [documentation can be built locally](#building-documentation) or can be accessed online at https://www.openvdb.org/documentation/fvdb/.
-
-## Installing *f*VDB
-
-The `fvdb_core` Python package can be installed either using published packages with pip or built
-from source.
 
-### Platform Requirements
+fVDB was first developed by the [NVIDIA High-Fidelity Physics Research Group](https://research.nvidia.com/labs/prl/)
+within the [NVIDIA Spatial Intelligence Lab](https://research.nvidia.com/labs/sil/), and continues to be
+developed with the OpenVDB community to suit the growing needs for a robust framework for
+spatial intelligence research and applications.
 
-#### Software
+[The paper](https://research.nvidia.com/labs/prl/publication/williams2024fvdb/) is available for more details, kindly consider [citing it in your work](#references) if you find it useful.
 
-fVDB is currently supported on the matrix of dependencies in the following table.
-
-| OS         | PyTorch     | Python      | CUDA        |
-| ---------- | ----------- | ----------- | ----------- |
-| Linux Only | 2.8.0-2.9.0 | 3.10 - 3.13 | 12.8 - 13.0 |
+## Learning to Use *f*VDB
 
-#### Hardware
+After [installing *f*VDB](#installing-fvdb), we recommend starting with our [documentation](https://fvdb.ai/).
 
-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.
+Beyond the [documentation](https://fvdb.ai/), the walk-through [notebooks](notebooks) in this repository
+can provide an illustrated introduction to the main concepts in *f*VDB.
 
-### 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.
+## Installing *f*VDB
 
-Install fvdb_core using the following pip command.
+The `fvdb-core` Python package can be installed either using published packages with pip or built
+from source.
 
-```
-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
-```
+For the most up-to-date information on installing *f*VDB's pip packages, please see the
+[installation documentation](https://fvdb.ai/installation.html).
 
 ## Building *f*VDB from Source
 
+If the [pre-built packages](https://fvdb.ai/installation.html) do not meet your needs, you can build *f*VDB from source in this repository.
+
 ### Environment Management
 
 ƒVDB is a Python library implemented as a C++ Pytorch extension. We provide three paths to
@@ -110,12 +96,12 @@ Running a Docker container ensures that you have a consistent environment for bu
 
 Our provided [`Dockerfile`](Dockerfile) constructs a container that pre-installs the dependencies needed to build and run ƒVDB.
 
-In the fvdb-core directory, build the Docker image:
+1. In the fvdb-core directory, build the Docker image:
 ```shell
 docker build -t fvdb-devel .
 ```
 
-When you are ready to build ƒVDB, run the following command within the docker container.  `TORCH_CUDA_ARCH_LIST` specifies which CUDA architectures to build for.
+2. When you are ready to build ƒVDB, run the following command within the docker container.  `TORCH_CUDA_ARCH_LIST` specifies which CUDA architectures to build for.
 ```shell
 docker run -it --mount type=bind,src="$(pwd)",target=/workspace fvdb-devel bash
 cd /workspace;
@@ -130,31 +116,39 @@ In order to extract an artifact from the container such as the Python wheel, que
 
 #### **OPTION 3** Python Virtual Environment
 
-Using a Python virtual environment enables you to use your system provided compiler and CUDA toolkit. This can be especially useful if you are using ƒVDB in conjunction with other Python packages, especially packages that have been built from source. Start by installing GCC, the CUDA Toolkit, and cuDNN.
+Using a Python virtual environment enables you to use your system provided compiler and CUDA toolkit. This can be especially useful if you are using ƒVDB in conjunction with other Python packages, especially packages that have been built from source.
+
+1. Start by installing GCC, the CUDA Toolkit, and cuDNN.
 
-Then, create a Python virtual environment, install the requisite dependencies, and build:
+2. Then, create a Python virtual environment, install the requisite dependencies, and build:
 
 ```shell
 python -m venv fvdb
 source fvdb/bin/activate
 pip install -r env/build_requirements.txt
 TORCH_CUDA_ARCH_LIST="7.5;8.0;9.0;10.0;12.0+PTX" ./build.sh install -v
 ```
+
 Note: adjust the TORCH_CUDA_ARCH_LIST to suit your needs. If you are building just to run on a single machine, including only the present GPU architecture(s) reduces build time.
+
 ---
 
 ### Building *f*VDB
 
-**:warning: Note:** Compilation can be very memory-consuming. As part of our build script, we set the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to control compilation job parallelism with a value that we find works well for most machines (allowing for one job every 2.5GB of memory) but this can be overridden by setting the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to a different value.
+#### Tips for Building *f*VDB
 
-** Note:** To save time and trouble on repeated clean builds, configure your `CPM_SOURCE_CACHE`. Add the following to your shell configuration (e.g. `.bashrc`)
+  - **:warning:** Compilation can be very memory-consuming. As part of our build script, we set the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to control compilation job parallelism with a value that we find works well for most machines (allowing for one job every 2.5GB of memory) but this can be overridden by setting the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to a different value.
 
-```shell
-export CPM_SOURCE_CACHE=$HOME/.cache/CPM
-```
+  - To save time and trouble on repeated clean builds, configure your `CPM_SOURCE_CACHE`. Add the following to your shell configuration (e.g. `.bashrc`)
 
-If this is not set, CMake Package Manager (CPM) will cache in the fVDB build directory. Keeping the cache outside of the build directory allows build-time dependencies
-to be reused across fvdb clean-build cycles and saves build time. [See the CPM documentation for more detail](https://github.com/cpm-cmake/CPM.cmake?tab=readme-ov-file#cpm_source_cache)
+    ```shell
+    export CPM_SOURCE_CACHE=$HOME/.cache/CPM
+    ```
+
+    If this is not set, CMake Package Manager (CPM) will cache in the fVDB build directory. Keeping the cache outside of the build directory allows build-time dependencies
+    to be reused across fvdb clean-build cycles and saves build time. [See the CPM documentation for more detail](https://github.com/cpm-cmake/CPM.cmake?tab=readme-ov-file#cpm_source_cache)
+
+#### Build Commands
 
 You can either perform an install:
 ```shell
@@ -166,6 +160,23 @@ or if you would like to build a packaged wheel for installing in other environme
 ./build.sh wheel
 ```
 
+The build script automatically detects the CUDA architectures to build for based on the available GPUs on the system. You can override this behavior by setting the `--cuda-arch-list` option.
+
+```shell
+./build.sh --cuda-arch-list=8.0;8.6+PTX
+```
+
+#### Build Modifiers
+
+The build script supports the following build modifiers:
+
+- `gtests`: Enable building the gtest C++ unit tests.
+- `benchmarks`: Enable building the benchmarks.
+- `editor_skip`: Skip building the nanovdb_editor dependency.
+- `editor_force`: Force rebuild of the nanovdb_editor dependency.
+- `debug`: Build in debug mode with full debug symbols and no optimizations.
+- `strip_symbols`: Strip symbols from the build (will be ignored if debug is enabled).
+- `verbose`: Enable verbose build output for pip and CMake.
 
 ### Running Tests
 
@@ -204,76 +215,11 @@ python -m http.server
 Please see the guide [`Clangd for Intellisense in fVDB`](docs/markdown/clangd.md)
 
 
-## Usage Examples
-The [examples](examples) directory contains a number of useful illustrations using the `fvdb` Python package. The sections below show some notable examples and their outputs. Run all commands from the directory containing this README.
-
-### Trilinear sampling of grids
-```
-python examples/sample_trilinear.py
-```
-This script generates a grid with scalars at the corners of each voxel and samples this grid at points. The visualization below shows the points colored according to their sampled values as well as the values at grid corners.
-<p align="center">
-  <img src="docs/imgs/readme/trilerp.png" style="width: 40%;"alt="fVDB trilinear interpolation demo">
-  <figcaption style="text-align: center; font-style: italic;">Trilinearly interpolate the corner values at the points.</figcaption>
-</p>
-
-
-### Trilinear splatting into grids
-```
-python examples/splat_trilinear.py
-```
-This script splats normals of a point cloud onto grid centers. The green arrows represent the values of the normals splatted onto each grid center
-<p align="center">
-  <img src="docs/imgs/readme/splat.png" style="width: 40%;"alt="fVDB trilinear splatting demo">
-  <figcaption style="text-align: center; font-style: italic;">Splat the normals at the blue points into the center of each grid cell. The green arrows are the splatted normals</figcaption>
-</p>
-
-
-### Tracing voxels along rays (hierarchical DDA)
-```
-python examples/ray_voxel_marching.py
-```
-This script demonstrates finding the first `N` voxels which lie along a ray (returning thier index as well as their entry and exit points).
-<p align="center">
-  <img src="docs/imgs/readme/rayvox.png" style="width: 70%;"alt="fVDB ray voxel marching">
-  <figcaption style="text-align: center; font-style: italic;">Find the voxels (yellow) which intersect the pink rays eminating from the green dot.</figcaption>
-</p>
-
-
-### Tracing contiguous segments along rays
-```
-python examples/ray_segment_marching.py
-```
-This script demonstrates finding the first `N` continuous segments of voxels which lie along a ray (returning thier index as well as their entry and exit points).
-<p align="center">
-  <img src="docs/imgs/readme/rayseg.png" style="width: 70%;"alt="fVDB ray voxel marching">
-  <figcaption style="text-align: center; font-style: italic;">Find the contiguous segments of voxels (red and blue lines) which intersect the cyan rays eminating from the pink dot.</figcaption>
-</p>
-
-
-### Backpropagating through sampling and splatting
-```
-python examples/overfit_sdf.py
-```
-This scripts fits SDF values at a grid corner to the SDF of a mesh using gradient descent.
-<p align="center">
-  <img src="docs/imgs/readme/fitsdf.png" style="width: 70%;"alt="fVDB SDF fitting">
-  <figcaption style="text-align: center; font-style: italic;">SDF values at grid corners (colored dots) fitted using gradient descent to the SDF of a mesh.</figcaption>
-</p>
-
-The following scripts also show how to bakcprop through splatting and sampling with fVDB:
-```
-python scripts/debug_grad_trilerp.py
-```
-```
-python scripts/debug_grad_splat.py
-```
-
 ## Code Structure
 The main source code for fVDB lives in the [src](src) directory. There are several important files here:
 * `src/python/Bindings.cpp` exposes functionality directly to Python. It is mainly a wrapper around the core classes such as `fvdb::GridBatch` and `fvdb::JaggedTensor`.
-* `src/GridBatch.h` contains the implementation of `fvdb::GridBatch` which is the core data structure on which fVDB is built. A `GridBatch` acts as a map between `(i, j, k)` integer coordinates and offsets in linear memory. This mapping can be used to perform a host of operations. The methods in this class are mostly lightweight wrappers around a set of CPU and CUDA *kernels*. The function prototypes for these kernels are defined in `src/detail/ops/Ops.h`.
-* `src/detail/ops/Ops.h` contains the function prototypes for the main kernels used by fVDB. Host and device kernel implementations are provided in the `src/detail/ops/*.cu` source files.
+* `src/GridBatch.h` contains the implementation of `fvdb::GridBatch` which is the core data structure on which fVDB is built. A `GridBatch` acts as a map between `(i, j, k)` voxel coordinates and offsets in linear memory. This mapping can be used to perform a host of operations. The methods in this class are mostly lightweight wrappers around a set of CPU and CUDA *kernels*. The function prototypes for these kernels are defined in `src/detail/ops/*.h`.
+* `src/detail/ops/*.h` contains the function prototypes for the main kernels used by fVDB. Host and device kernel implementations are provided in the `src/detail/ops/*.cu` source files.
 * `src/detail/autograd` contains C++ implementations of PyTorch autograd functions for differentiable operations.  `#include <detail/autograd/Autograd.h>` includes all of the functions in this directory.
 * `src/detail/utils/nanovdb` contains a number of utilities which make it easier to use NanoVDB.
 
@@ -303,3 +249,5 @@ Please consider citing this when using *f*VDB in a project. You can use the cita
 ```
 
 ## Contact
+
+For questions or feedback, plesae use the [GitHub Issues](https://github.com/openvdb/fvdb-core/issues) for this repository.
