OpenVDB — routines to write OpenVDB files

The OpenVDB format is used by Blender and other VFX software for volumetric data.

This module uses the openvdb library to write OpenVDB files.

Note

This module implements a simple writer for 3D regular grids, sufficient to export density data for visualization in Blender. See the Blender volume docs for details on importing VDB files.

The OpenVDB format uses a sparse tree structure to efficiently store volumetric data. It is the native format for Blender’s volume system.

Writing OpenVDB files

If you have a Grid object, you can write it to OpenVDB format:

from gridData import Grid
g = Grid("data.dx")
g.export("data.vdb")

This will create a file that can be imported directly into Blender (File -> Import -> OpenVDB) or (shift+A -> Volume -> Import OpenVDB). See importing VDB in Blender for details.

Building an OpenVDB field from a numpy array

If you want to create VDB files without using the Grid class, you can directly use the OpenVDB field API. This is useful for custom workflows or when integrating with other libraries.

Requires:

grid

numpy 3D array

origin

cartesian coordinates of the center of the (0,0,0) grid cell

delta

n x n array with the length of a grid cell along each axis

Example:

import numpy as np
from gridData.OpenVDB import OpenVDBField

grid = np.random.rand(10, 10, 10).astype(np.float32)
origin = np.array([0.0, 0.0, 0.0])
delta = np.array([1.0, 1.0, 1.0])

vdb_field = OpenVDBField(grid=grid, origin=origin, delta=delta)
vdb_field.write("output.vdb")

Alternatively, you can also create a Grid from the array and then use the Grid.convert_to method to directly get a gridData.OpenVDB.OpenVDBField:

g = Grid(grid=grid, origin=origin, delta=delta)
vdb_field = g.convert_to("VDB")

See also

OpenVDBField.from_grid

directly create the OpenVDBField from a Grid

Native OpenVDB object

If you need the native openvdb.GridBase grid object (e.g., a openvdb.FloatGrid) then you can use the OpenVDBField.native attribute that gives direct access to this object:

g = Grid("data.dx")
vdb_field = g.convert_to("VDB")
vdb_grid = vdb_field.native

You can then manipulate the vdb_grid using all relevant transformations and other OpenVDB methods.

Classes and functions

class gridData.OpenVDB.DownCastTo(gridType: str)[source]

dataclass() decorator serving as a marker for a downcast.

This function is used to create a proxy for an OpenVDB grid type. The field gridType contains the OpenVDB grid type that it represents. OpenVDBField._get_best_grid_type() selects a OpenVDB grid that best matches the numpy dtype of the data but in some cases, only target OpenVDB grid types are available that loose precision. In this case, this class wraps the orginal OpenVDB class to indicate that the downcast. For example,

np.dtype("int32"): ["Int32Grid", DownCastTo("FloatGrid")]

indicates that NumPy int32 data should be represented by a openvdb.Int32Grid but if this is not available, a openvdb.FloatGrid is used instead, which, however, is only able to represent a subset of all 32-bit integers.

gridType: str
class gridData.OpenVDB.OpenVDBField(grid=None, origin=None, delta=None, name='density', tolerance=None, metadata=None)[source]

OpenVDB field object for writing volumetric data.

This class provides a simple interface to write 3D grid data to OpenVDB format, which can be imported into Blender and other VFX software.

The field object holds grid data and metadata, and can write it to a .vdb file.

Example

Create a field and write it:

import gridData.OpenVDB as OpenVDB

vdb_field = OpenVDB.OpenVDBField(grid=np.ones((3, 4, 5)),
                                 origin=np.array([1.5, 0, 0]),
                                 delta=np.array([0.5, 0.5, 0.25]),
                                 name='density')
vdb_field.write('output.vdb')

Or use directly from Grid:

g = Grid(...)
g.export('output.vdb', format='vdb')

Initialize an OpenVDB field.

Parameters:

  • grid (numpy.ndarray) – 3D numpy array with the data

  • origin (numpy.ndarray) – Coordinates of the center of grid cell [0,0,0]

  • delta (numpy.ndarray) – Grid spacing (can be 1D array or diagonal matrix)

  • name (str) – Name of the grid (will be visible in Blender), default ‘density’

  • tolerance (float (optional)) – Values below this tolerance are treated as background (sparse), default None

  • metadata (dict (optional)) – Additional metadata to embed in the VDB file.

Raises:

  • ImportError – If openvdb is not installed

  • ValueError – If grid is not 3D, or if delta is not 1D/2D or describes non-orthorhombic cell

Added in version 1.2.0.

classmethod from_grid(grid, tolerance=None, **kwargs)[source]

Create OpenVDB field from Grid.

Parameters:

  • grid (Grid) – Grid object to convert

  • tolerance (float, optional) – Values below this tolerance are treated as background (sparse). Default None means no tolerance-based pruning for non-boolean grids.

  • **kwargs – Additional keyword arguments: - name : str, grid name (default ‘density’) - metadata : dict, additional metadata

Returns:

OpenVDB field wrapper

Return type:

OpenVDBField

Added in version 1.2.0.

property native

Return the native openvdb grid object.

The “native” object is the underlying openvdb.GridBase object (e.g., FloatGrid, DoubleGrid) from the openvdb library.

Returns:

Native openvdb grid object (e.g., openvdb.FloatGrid)

Return type:

openvdb.GridBase

Added in version 1.2.0.

write(filename)[source]

Write the field to an OpenVDB file.

Parameters:

filename (str) – Output filename (should end in .vdb)