OpenVDB Documentation

The Vector Class Library (VCL) is a C++ class library designed to leverage Single Instruction Multiple Data (SIMD) instructions. It improves performance on modern microprocessors using the x86 or x86/64 instruction sets.

Supported Platforms:

• Windows
• Linux
• Mac

Note: There are currently no plans to support ARM or other instruction sets.

The vdb_tool is a lightweight command-line utility for chaining high-level OpenVDB operations. It allows users to:

• Convert polygon meshes and particles into level sets.
• Perform volumetric transformations (e.g., dilation, erosion, Gaussian convolution).
• Generate adaptive meshes or ray-traced images.
• Export results as particles, meshes, or VDB files, or stream them to STDOUT for pipelining.

Operations are defined as actions (e.g., -erode) and options (e.g., radius=2.0). Sequences of actions can be saved to and loaded from configuration files.

NanoVDB is a standalone, static-topology implementation of the sparse volumetric VDB data structure. It is a lightweight version of OpenVDB designed for high-performance random access on both CPUs and GPUs.

Key Characteristics

• Static Topology: You can modify voxel values within a NanoVDB grid, but you cannot modify the tree topology (e.g., you cannot add or remove nodes/voxels once the structure is built).
• Memory Layout: NanoVDB is pointer-less and occupies a contiguous, defragmented block of memory. This results in faster read access and better cache friendliness compared to OpenVDB.
• Dependencies: It has virtually no external dependencies, requiring only C++11 or C99.
• Use Cases: Ideal for GPU/CPU rendering (ray-tracing), collision detection, and applications requiring fast random access to sparse volumetric data.

NanoVDB provides several implementations of its core data structure and access methods depending on your target language and API:

• C++11: Use NanoVDB.h for the standard C++ implementation.
• C99 (OpenCL focus): Use CNanoVDB.h. This is designed for use in OpenCL kernels but relies on zero-sized arrays for _reserved padding, which may not work on all compilers (e.g., MSVC).
• C99 (Graphics API focus): Use PNanoVDB.h. This is a more complete C99 implementation that is pointer-less, making it compatible with virtually all graphics APIs.
• CUDA: For CUDA-specific support, refer to the cuda/ directory for headers like DeviceBuffer.h, GridHandle.cuh, and NodeManager.cuh.

Follow these steps to build and install OpenVDB on Windows using CMake and vcpkg. Replace <PATH_TO_VCPKG> with your actual vcpkg installation path.

git clone git@github.com:AcademySoftwareFoundation/openvdb.git
cd openvdb
mkdir build
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_VCPKG>\scripts\buildsystems\vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -A x64 ..
cmake --build . --parallel 4 --config Release --target install

To install the core OpenVDB library on Linux, you must first install the required development dependencies using apt-get. If your distribution does not have the required versions, consider using apt pinning.

# Linux
apt-get install -y libboost-iostreams-dev
apt-get install -y libtbb-dev
apt-get install -y libblosc-dev

To build vdb_tool on Linux using CMake, navigate to the cloned directory and follow these steps. You must have OpenVDB installed. To enable NanoVDB support, pass -DOPENVDB_BUILD_NANOVDB=ON. To build unit tests, pass -DOPENVDB_BUILD_VDB_TOOL_UNITTESTS=ON.

# Generate makefile
mkdir build
cd build
cmake -DOPENVDB_CMAKE_PATH=/usr/local/lib/cmake/OpenVDB -DUSE_ALL=ON -DOPENVDB_BUILD_VDB_TOOL_UNITTESTS=ON ..

# Build
cmake --build . --parallel 2
# OR
make -j 2

The if(cond, then, else) function implements lazy evaluation. It only evaluates the branch that is taken. This is useful for guarding against mathematical errors like division by zero or square roots of negative numbers.

Note: The switch(...) function is eager (all branches are evaluated). If you need short-circuiting logic in a switch-like structure, use nested if() calls.

The vdb_tool supports loop constructs to automate repetitive tasks.

• -for <var>=<start>,<end>,<step>: Iterates over a range.
• -each <var>=<list>: Iterates over a list of items.
• Use {$var} to reference the loop variable within command arguments.
• Use -end to close the loop block.

To perform an exhaustive build that includes unit tests, examples, benchmarks, CUDA support, and intrinsics alongside the OpenVDB core, use the following configuration from the root OpenVDB directory.

foo@bar:~$ mkdir build
foo@bar:~$ cd build
foo@bar:~$ cmake .. -DUSE_NANOVDB=ON -DNANOVDB_BUILD_UNITTESTS=ON -DNANOVDB_BUILD_EXAMPLES=ON -DNANOVDB_BUILD_BENCHMARK=ON -DNANOVDB_USE_INTRINSICS=ON -DNANOVDB_USE_CUDA=ON -DNANOVDB_CUDA_KEEP_PTX=ON -DTBB_ROOT=/path/to/tbb -DBOOST_ROOT=/path/to/boost -DBLOSC_ROOT=/path/to/blosc -DGTEST_ROOT=/path/to/gtest -DCMAKE_INSTALL_PREFIX=/install/path
foo@bar:~$ make -j 4 && make install