The Problem
Volumetric data in visual effects pipelines needs a compact, fast‑access format that can be edited, streamed, and processed on the GPU. Existing solutions either lack a clear API or are too tightly coupled to specific applications. A library that exposes a unified sparse grid interface and a bundle of tools is required.
What This Does
OpenVDB supplies a C++ API (openvdb/) that implements a hierarchical sparse voxel grid.
openvdb/– core library headers and sources.nanovdb/– a lightweight header‑only subset for GPU‑friendly storage and conversion.openvdb_ax/– advanced tools for editing and analysis.openvdb_cmd/– command‑line utilities (e.g.,nanovdb_convert.cc,nanovdb_print.cc).openvdb_houdini/,openvdb_maya/,openvdb_wolfram/– bindings for host applications.
The repository also bundles a large test suite (523 files) and CI workflows that build and test each component.
How It Is Wired
| Section | Responsibility | Key Files |
|---|---|---|
| Root build | Orchestrates the entire project. | CMakeLists.txt pulls in subdirectories openvdb/, nanovdb/, openvdb_ax/, etc. |
| Core library | Provides the grid data structure and algorithms. | openvdb/ headers; functions like openvdb::FloatGrid::getPtr(). |
| NanoVDB CLI | Converts OpenVDB files to the compact NanoVDB format. | nanovdb/nanovdb/cmd/convert/nanovdb_convert.cc → calls nanovdb::convert::Convert. |
| NanoVDB print | Dumps a NanoVDB file to text. | nanovdb/nanovdb/cmd/print/nanovdb_print.cc → calls nanovdb::print::Print. |
| Bindings | Expose the library to host apps. | openvdb_houdini/, openvdb_maya/ modules that include OPENVDB_HOUDINI_EXPORTS. |
| Tests | Verify correctness of each component. | tests/ hierarchy; each test calls public API functions. |
Control flow for a typical conversion run: cmake .. && make -j4 → builds the openvdb library and the nanovdb command. Running nanovdb_convert input.vdb output.nvdb executes nanovdb_convert.cc, which loads the source VDB using openvdb::readVDB, then calls nanovdb::convert::Convert to produce the target file. The process touches the filesystem (read/write) and the GPU only if CUDA support is enabled via the CMake option -DWITH_CUDA=ON.
How To Use It
Setup
git clone https://github.com/moses-y/openvdb
cd openvdb
mkdir build && cd build
cmake .. -DWITH_CUDA=ON
make -j$(nproc)
The CMakeLists.txt at the root drives the build; it requires tbb, zstd, and optionally cuda. Install them via your package manager or the CI scripts in ci/.
Configuration
No runtime configuration files are required. Build options are passed to CMake:
-DWITH_OPENEXR=ON– enable OpenEXR I/O.-DWITH_TBB=ON– enable Intel TBB parallelism.
Running it
After building, the NanoVDB CLI is located at build/nanovdb/nanovdb/cmd/convert/nanovdb_convert.
./nanovdb_convert input.vdb output.nvdb
The core library can be used from C++ by including <openvdb/openvdb.h> and linking against libopenvdb.so.
Real‑World Use
In a VFX pipeline, a Houdini asset might write a large smoke simulation to a .vdb file. The asset then calls the NanoVDB CLI to pack the grid into a .nvdb file, which is streamed to the compositing node for GPU‑accelerated shading. The same API can be called from a Python script via the nanobind bindings in nanovdb/nanovdb/python/.
#include <openvdb/openvdb.h>
int main() {
openvdb::initialize();
auto grid = openvdb::FloatGrid::create();
grid->setName("smoke");
// … populate grid …
openvdb::io::File file("smoke.vdb");
file.write(*grid);
}
Code Health & Issues
- Low/Medium risk – Dependencies declared without a lockfile (
pyproject.tomllacks a lockfile). - Implication: Reproducible builds for Python consumers are not guaranteed.
- CI – GitHub Actions workflows (
.github/workflows/*.yml) cover Linux, macOS, and Windows builds, as well as documentation generation. - Tests – 523 test files covering core, NanoVDB, and bindings.
- Documentation – 68 documentation files with Doxygen integration (
doc/CMakeLists.txt). - License – Apache‑2.0, fully compliant with open‑source requirements.
No other automated static analysis findings are present in the current tree.
The Bottom Line
The repository offers a mature, well‑tested sparse‑volume library with a rich set of tools and bindings. Build complexity is moderate; CI ensures cross‑platform coverage. The main trade‑off is the absence of a Python lockfile, which could affect reproducibility for downstream users. The project is suitable for production VFX pipelines that need a reliable volumetric data format.