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

SectionResponsibilityKey Files
Root buildOrchestrates the entire project.CMakeLists.txt pulls in subdirectories openvdb/, nanovdb/, openvdb_ax/, etc.
Core libraryProvides the grid data structure and algorithms.openvdb/ headers; functions like openvdb::FloatGrid::getPtr().
NanoVDB CLIConverts OpenVDB files to the compact NanoVDB format.nanovdb/nanovdb/cmd/convert/nanovdb_convert.cc → calls nanovdb::convert::Convert.
NanoVDB printDumps a NanoVDB file to text.nanovdb/nanovdb/cmd/print/nanovdb_print.cc → calls nanovdb::print::Print.
BindingsExpose the library to host apps.openvdb_houdini/, openvdb_maya/ modules that include OPENVDB_HOUDINI_EXPORTS.
TestsVerify 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.toml lacks 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.