Basic Tutorials

NeuralVDB is a compression technique for OpenVDB and NanoVDB volumes. In this page, we will present different ways of encoding (i.e. compressing) a VDB volume to NeuralVDB, and then decompressing it back to standard VDB format.

Encoding and Decoding VDB using NeuralVDB

You can encode a VDB volume using Python. Below is a simple example where it loads a VDB file and encode it to a NeuralVDB representation:

import omni.volume
import omni.vdb.neuralvdb

# Acquire interfaces
ivolume = omni.volume.get_volume_interface()
ineuralvdb = omni.vdb.neuralvdb.get_neuralvdb_interface()

# Read VDB file
volume = ivolume.create_from_file("my_volume.vdb")

# Encode into NeuralVDB
auto_config_params = omni.vdb.neuralvdb.AutoConfigParams()
mvdb_volume = ineuralvdb.encode_grids_with_auto_config(volume, auto_config_params)

You can also encode a series of volumes by batch-encoding:

volumes = [volume1, volume2]
num_batch_threads = 0  # 0 for the number of concurrent threads supported.
mvdb_volumes = ineuralvdb.batch_encode_grids(volumes, num_batch_threads=num_batch_threads)

In this example, the final output mvdb_volume is the NeuralVDB data which can be decoded back to a VDB file as shown below:

decode_params = omni.vdb.neuralvdb.DecodeParams()
volume_recon = ineuralvdb.decode_grids(mvdb_volume, decode_params)

The final output volume_recon is now the reconstructed VDB that should be similar to the source volume data.

If you want to serialize mvdb_volume into a NeuralVDB file, you can simple run the following code:

with open("example.mvdb", "wb") as f:
    f.write(mvdb_volume.tobytes())

Controlling the Compression Quality and Size

The previous example compressed the source volume using the default encoding parameters. To further control the quality of the compression, you can modify the previous example like below:

...

# Encode into NeuralVDB
auto_config_params = omni.vdb.neuralvdb.AutoConfigParams()

# Compression quality (1-9 where 1 is lowest quality), 3 by default
auto_config_params.compression_quality = 3

# Sharpness level of the encoded grid (1-9 where 1 is the lowest sharpness), 7 by default
auto_config_params.sharpness_level = 7

# Precision of the encoded grid, Float32 by default
auto_config_params.precision = omni.vdb.neuralvdb.NeuralGridParams.Precision.Float32

# Tree class of the encoded grid, NeuralValueTree by default
auto_config_params.tree_class = omni.vdb.neuralvdb.NeuralGridParams.TreeClass.NeuralValueTree

...

The first parameter, compression_quality, controls the reconstruction capability of the encoded NeuralVDB which is set as an integer value between 1 and 9. When higher value is selected, it will take longer to encode and decode, but will capture more details. Default value is set to 3.

The second parameter, sharpness_level, controls the level of “over-fitting” when encoding a volume which is set as an integer value between 1 and 9. Higher value will result sharper decoded volume, but will introduce noise-like artifacts. Lower value will give smoother results, but may lose some details. Default value is set to 7.

The third parameter, precision, is the precision of the neural network where you can chose between NeuralGridParams.Precision.Float32 and NeuralGridParams.Precision.Float16. Default value is set to NeuralGridParams.Precision.Float32.

The forth parameter, tree_class, determines whether to compress the leaf voxel values only (NeuralGridParams.TreeClass.NeuralValueTree) or compress voxels and part of the VDB tree as well (NeuralGridParams.TreeClass.NeuralMaskValueTree). The former will provide faster encoding and decoding time and the latter will give you higher compression ratio. Default value is set to NeuralGridParams.TreeClass.NeuralValueTree.

Using NeuralVDB as a Volume Texture

When NeuralVDB extension is enabled, you can load a NeuralVDB file (.mvdb) directly from Omniverse as if it is a regular VDB file (.vdb or .nvdb). For example, if a fog-density volume is encoded as a NeuralVDB file, you can use it as a volume texture for OmniVolumeDensity material.

For example, in USD Composer, first switch the renderer to RTX - Interactive (Path Tracing). Under the Render Settings, enable Non-uniform Volumes. Then, create a cube and OmniVolumeDensity in a new stage. Click on the cube and enable primvars:isVolume under Extra Properties in Property tab. Click on the OmniVolumeDensity material from the Stage tab and pick a NeuralVDB file from Base > Volume Density Texture under the Property tab. After a few seconds (depends on the size of the volume), the decoded VDB volume will be visible from the viewport.