This section describes the OpenVDB Python module and includes Python code snippets and some complete programs that illustrate how to perform common tasks. (An API reference is also available, if Epydoc is installed.) As of OpenVDB 2.0, the Python module exposes most of the functionality of the C++ Grid class, including I/O, metadata management, voxel access and iteration, but almost none of the many tools. We expect to add support for tools in forthcoming releases.
The Python module supports a fixed set of grid types. If the symbol PY_OPENVDB_WRAP_ALL_GRID_TYPES
is defined at compile time, most of the grid types declared in openvdb.h are accessible in Python, otherwise only FloatGrid, BoolGrid and Vec3SGrid are accessible. To add support for grids with other value types or configurations, search for PY_OPENVDB_WRAP_ALL_GRID_TYPES
in the module source code, update the code as appropriate and recompile the module. (It is possible that this process will be streamlined in the future with a plugin mechanism.) Note however that adding grid types can significantly increase the time and memory needed to compile the module and can significantly increase the size of the resulting executable. In addition, grids of custom types that are saved to .vdb
files or pickled will not be readable by clients using the standard version of the module.
Also note that the Tree class is not exposed in Python. Much of its functionality is either available through the Grid or is too low-level to be generally useful in Python. Although trees are not accessible in Python, they can of course be operated on indirectly. Of note are the grid methods copy, which returns a new grid that shares its tree with the original grid, deepCopy, which returns a new grid that owns its own tree, and sharesWith, which reports whether two grids share a tree.
Contents
Getting started
The following example is a complete program that illustrates some of the basic steps to create grids and write them to disk:
import pyopenvdb as vdb
cube = vdb.FloatGrid()
cube.fill(min=(100, 100, 100), max=(199, 199, 199), value=1.0)
cube.name = 'cube'
sphere = vdb.createLevelSetSphere(radius=50, center=(1.5, 2, 3))
sphere['radius'] = 50.0
sphere.transform = vdb.createLinearTransform(voxelSize=0.5)
sphere.name = 'sphere'
vdb.write('mygrids.vdb', grids=[cube, sphere])
This example shows how to read grids from files, and some ways to modify grids:
import pyopenvdb as vdb
filename = 'mygrids.vdb'
grids = vdb.readAllGridMetadata(filename)
sphere = None
for grid in grids:
if (grid.gridClass == vdb.GridClass.LEVEL_SET and 'radius' in grid
and grid['radius'] > 10.0):
sphere = vdb.read(filename, grid.name)
else:
print 'skipping grid', grid.name
if sphere:
outside = sphere.background
width = 2.0 * outside
for iter in sphere.iterOnValues():
dist = iter.value
iter.value = (outside - dist) / width
for iter in sphere.iterOffValues():
if iter.value < 0.0:
iter.value = 1.0
iter.active = False
sphere.background = 0.0
sphere.gridClass = vdb.GridClass.FOG_VOLUME
Handling metadata
Metadata of various types (string, bool, int, float, and 2- and 3-element sequences of ints or floats) can be attached both to individual grids and to files on disk, either by supplying a Python dictionary of (name, value) pairs or, in the case of grids, through a dictionary-like interface.
Add (name, value) metadata pairs to a grid as you would to a dictionary. A new value overwrites an existing value if the name matches an existing name.
>>> import pyopenvdb as vdb
>>> grid = vdb.Vec3SGrid()
>>> grid['vector'] = 'gradient'
>>> grid['radius'] = 50.0
>>> grid['center'] = (10, 15, 10)
>>> grid.metadata
{'vector': 'gradient', 'radius': 50.0, 'center': (10, 15, 10)}
>>> grid['radius']
50.0
>>> 'radius' in grid, 'misc' in grid
(True, False)
>>> grid['center'] = 0.0
>>> grid['center'] = (0, 0, 0, 0)
File "<stdin>", line 1, in <module>
TypeError: metadata value "(0, 0, 0, 0)" of type tuple is not allowed
>>> grid[0] = (10.5, 15, 30)
File "<stdin>", line 1, in <module>
TypeError: expected str, found int as argument 1 to __setitem__()
Alternatively, replace all or some of a grid’s metadata by supplying a (name, value) dictionary:
>>> metadata = {
... 'vector': 'gradient',
... 'radius': 50.0,
... 'center': (10, 15, 10)
... }
>>> grid.metadata = metadata
>>> metadata = {
... 'center': [10.5, 15, 30],
... 'scale': 3.14159
... }
>>> grid.updateMetadata(metadata)
Iterate over a grid’s metadata as you would over a dictionary:
>>> for key in grid:
... print '%s = %s' % (key, grid[key])
...
vector = gradient
radius = 50.0
scale = 3.14159
center = (10.5, 15.0, 30.0)
Removing metadata is also straightforward:
>>> del grid['vector']
>>> del grid['center']
>>> del grid['vector']
File "<stdin>", line 1, in <module>
KeyError: 'vector'
>>> grid.metadata = {}
Some grid metadata is exposed in the form of properties, either because it might be frequently accessed (a grid’s name, for example) or because its allowed values are somehow restricted:
>>> grid = vdb.createLevelSetSphere(radius=10.0)
>>> grid.metadata
{'class': 'level set'}
>>> grid.gridClass = vdb.GridClass.FOG_VOLUME
>>> grid.metadata
{'class': 'fog volume'}
>>> grid.gridClass = 123
File "<stdin>", line 1, in <module>
TypeError: expected str, found int
as argument 1 to
setGridClass()
>>> grid.gridClass = 'Hello, world.'
>>> grid.metadata
{'class': 'unknown'}
>>> grid.metadata = {}
>>> grid.vectorType = vdb.VectorType.COVARIANT
>>> grid.metadata
{'vector_type': 'covariant'}
>>> grid.name = 'sphere'
>>> grid.creator = 'Python'
>>> grid.metadata
{'vector_type': 'covariant', 'name': 'sphere', 'creator': 'Python'}
Setting these properties to None
removes the corresponding metadata, but the properties retain default values:
>>> grid.creator = grid.vectorType = None
>>> grid.metadata
{'name': 'sphere'}
>>> grid.creator, grid.vectorType
('', 'invariant')
Metadata can be associated with a .vdb
file at the time the file is written, by supplying a (name, value) dictionary as the optional metadata
argument to the write function:
>>> metadata = {
... 'creator': 'Python',
... 'time': '11:05:00'
... }
>>> vdb.write('mygrids.vdb', grids=grid, metadata=metadata)
File-level metadata can be retrieved with either the readMetadata function or the readAll function:
>>> metadata = vdb.readMetadata('mygrids.vdb')
>>> metadata
{'creator': 'Python', 'time': '11:05:00'}
>>> grids, metadata = vdb.readAll('mygrids.vdb')
>>> metadata
{'creator': 'Python', 'time': '11:05:00'}
>>> [grid.name for grid in grids]
['sphere']
Voxel access
Grids provide read-only and read/write accessors for voxel lookup via (i, j, k) index coordinates. Accessors store references to their parent grids, so a grid will not be deleted while it has accessors in use.
>>> import pyopenvdb as vdb
>>> grids, metadata = vdb.readAll('smoke2.vdb')
>>> [grid.name for grid in grids]
['density', 'v']
>>> dAccessor = grids[0].getAccessor()
>>> vAccessor = grids[1].getAccessor()
>>> ijk = (100, 103, 101)
>>> dAccessor.probeValue(ijk)
(0.17614534497261047, True)
>>> dAccessor.setValueOn(ijk, 0.125)
>>> dAccessor.probeValue(ijk)
(0.125, True)
>>> vAccessor.probeValue(ijk)
((-2.90625, 9.84375, 0.84228515625), True)
>>> vAccessor.setActiveState(ijk, False)
>>> vAccessor.probeValue(ijk)
((-2.90625, 9.84375, 0.84228515625), False)
>>> dAccessor = grids[0].getConstAccessor()
>>> dAccessor.setActiveState(ijk, False)
File "<stdin>", line 1, in <module>
TypeError: accessor is read-only
>>> del dAccessor, vAccessor
Iteration
Grids provide read-only and read/write iterators over their values. Iteration is over sequences of value objects (BoolGrid.Values, FloatGrid.Values, etc.) that expose properties such as the number of voxels spanned by a value (one, for a voxel value, more than one for a tile value), its coordinates and its active state. Value objects returned by read-only iterators are immutable; those returned by read/write iterators permit assignment to their active state and value properties, which modifies the underlying grid. Value objects store references to their parent grids, so a grid will not be deleted while one of its value objects is in use.
>>> import pyopenvdb as vdb
>>> grid = vdb.read('smoke2.vdb', gridname='v')
>>> grid.__class__.__name__
'Vec3SGrid'
>>> voxels = tiles = 0
... N = 5
... for item in grid.citerOffValues():
... if voxels == N and tiles == N:
... break
... if item.count == 1:
... if voxels < N:
... voxels += 1
... print 'voxel', item.min
... else:
... if tiles < N:
... tiles += 1
... print 'tile', item.min, item.max
...
tile (0, 0, 0) (7, 7, 7)
tile (0, 0, 8) (7, 7, 15)
tile (0, 0, 16) (7, 7, 23)
tile (0, 0, 24) (7, 7, 31)
tile (0, 0, 32) (7, 7, 39)
voxel (40, 96, 88)
voxel (40, 96, 89)
voxel (40, 96, 90)
voxel (40, 96, 91)
voxel (40, 96, 92)
>>> from math import sqrt
>>> for item in grid.iterOnValues():
... vector = item.value
... magnitude = sqrt(sum(x * x for x in vector))
... item.value = [x / magnitude for x in vector]
...
For some operations, it might be more convenient to use one of the grid methods mapOn, mapOff or mapAll. These methods iterate over a grid’s tiles and voxels (active, inactive or both, respectively) and replace each value x with f(x), where f is a callable object. These methods are not multithreaded.
>>> import pyopenvdb as vdb
>>> from math import sqrt
>>> grid = vdb.read('smoke2.vdb', gridname='v')
... magnitude = sqrt(sum(x * x for x in vector))
... return [x / magnitude for x in vector]
...
>>> grid.mapOn(normalize)
Similarly, the combine method iterates over corresponding pairs of values (tile and voxel) of two grids A and B of the same type (FloatGrid, Vec3SGrid, etc.), replacing values in A with f(a, b), where f is a callable object. This operation assumes that index coordinates (i, j, k) in both grids correspond to the same physical, world space location. Also, the operation always leaves grid B empty.
>>> import pyopenvdb as vdb
>>> density = vdb.read('smoke2.vdb', gridname='density')
>>> density.__class__.__name__
'FloatGrid'
>>> sphere = vdb.createLevelSetSphere(radius=50.0, center=(100, 300, 100))
>>> density.combine(sphere,
lambda a, b:
min(a, b))
For now, combine operates only on tile and voxel values, not on their active states or other attributes.
Working with NumPy arrays
Large data sets are often handled in Python using NumPy. The OpenVDB Python module can optionally be compiled with NumPy support. With NumPy enabled, the copyFromArray and copyToArray grid methods can be used to exchange data efficiently between scalar-valued grids and three-dimensional NumPy arrays and between vector-valued grids and four-dimensional NumPy arrays.
>>> import pyopenvdb as vdb
>>> import numpy
>>> array = numpy.random.rand(200, 200, 200)
>>> array.dtype
dtype('float64')
>>> grid = vdb.FloatGrid()
>>> grid.copyFromArray(array)
>>> grid.activeVoxelCount() == array.size
True
>>> grid.evalActiveVoxelBoundingBox()
((0, 0, 0), (199, 199, 199))
>>> vecarray = numpy.ndarray((60, 70, 80, 3), int)
>>> vecarray.fill(42)
>>> vecgrid = vdb.Vec3SGrid()
>>> vecgrid.copyFromArray(vecarray)
>>> vecgrid.activeVoxelCount() == 60 * 70 * 80
True
>>> vecgrid.evalActiveVoxelBoundingBox()
((0, 0, 0), (59, 69, 79))
When copying from a NumPy array, values in the array that are equal to the destination grid’s background value (or close to it, if the tolerance
argument to copyFromArray is nonzero) are set to the background value and are marked inactive. All other values are marked active.
>>> grid.clear()
>>> grid.copyFromArray(array, tolerance=0.2)
>>> print '%d%% of copied voxels are active' % (
... round(100.0 * grid.activeVoxelCount() / array.size))
80% of copied voxels are active
The optional ijk
argument specifies the index coordinates of the voxel in the destination grid into which to start copying values. That is, array index (0, 0, 0) maps to voxel (i, j, k).
>>> grid.clear()
>>> grid.copyFromArray(array, ijk=(-1, 2, 3))
>>> grid.evalActiveVoxelBoundingBox()
((-1, 2, 3), (198, 201, 202))
The copyToArray method also accepts an ijk
argument. It specifies the index coordinates of the voxel to be copied to array index (0, 0, 0).
>>> grid = vdb.createLevelSetSphere(radius=10.0)
>>> array = numpy.ndarray((40, 40, 40), int)
>>> array.fill(0)
>>> grid.copyToArray(array, ijk=(-15, -20, -35))
>>> array[15, 20]
array([ 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
3, 3, 3, 2, 1, 0, -1, -2, -3, -3,
-3, -3, -3, -3, -3, -3, -3, -3, -3, -3])
copyToArray has no tolerance
argument, because there is no distinction between active and inactive values in the destination array.
Mesh conversion
Also available if the OpenVDB Python module is compiled with NumPy support (see above) are grid methods to convert polygonal meshes to level sets (see tools::meshToLevelSet for some restrictions) and to convert isosurfaces of scalar-valued grids to meshes.
>>> import pyopenvdb as vdb
>>> import numpy
>>> grid = vdb.read('bunny.vdb', 'ls_bunny')
>>> points, quads = grid.convertToQuads()
>>> points
array([[-14.05082607, -0.10118673, -0.40250054],
[-14.05230808, -0.05570767, -0.45693323],
[-14.05613995, -0.0734246 , -0.42150033],
...,
[ 7.25201273, 13.25417805, 6.45283508],
[ 7.25596714, 13.31225586, 6.40827513],
[ 7.30518484, 13.21096039, 6.40724468]], dtype=float32)
>>> quads
array([[ 5, 2, 1, 4],
[ 11, 7, 6, 10],
[ 14, 9, 8, 13],
...,
[1327942, 1327766, 1339685, 1339733],
[1339728, 1327921, 1327942, 1339733],
[1339733, 1339685, 1339661, 1339728]], dtype=uint32)
>>> gridFromQuads = vdb.FloatGrid.createLevelSetFromPolygons(
... points, quads=quads, transform=grid.transform)
>>> points, triangles, quads = grid.convertToPolygons(adaptivity=0.5)
>>> points
array([[-14.02906322, -0.07213751, -0.49265194],
[-14.11877823, -0.11127799, -0.17118289],
[-13.85006142, -0.08145611, -0.86669081],
...,
[ 7.31098318, 12.97358608, 6.55133963],
[ 7.20240211, 12.80632019, 6.80356836],
[ 7.23679161, 13.28100395, 6.45595646]], dtype=float32)
>>> triangles
array([[ 8, 7, 0],
[ 14, 9, 8],
[ 14, 11, 9],
...,
[22794, 22796, 22797],
[22784, 22783, 22810],
[22796, 22795, 22816]], dtype=uint32)
>>> quads
array([[ 4, 3, 6, 5],
[ 8, 9, 10, 7],
[ 11, 12, 10, 9],
...,
[23351, 23349, 23341, 23344],
[23344, 23117, 23169, 23351],
[23169, 23167, 23349, 23351]], dtype=uint32)
>>> doubleGridFromPolys = vdb.DoubleGrid.createLevelSetFromPolygons(
... points, triangles, quads, transform=grid.transform)
The mesh representation is similar to that of the commonly-used Wavefront .obj
file format, except that the vertex array is indexed starting from 0 rather than 1. To output mesh data to a file in .obj
format, one might do the following:
>>> def writeObjFile(filename, points, triangles=[], quads=[]):
... f = open(filename, 'w')
...
... for xyz in points:
... f.write('v %g %g %g\n' % tuple(xyz))
... f.write('\n')
...
... for ijk in triangles:
... f.write('f %d %d %d\n' %
... (ijk[0]+1, ijk[1]+1, ijk[2]+1))
... for ijkl in quads:
... f.write('f %d %d %d %d\n' %
... (ijkl[0]+1, ijkl[1]+1, ijkl[2]+1, ijkl[3]+1))
... f.close()
...
>>> mesh = grid.convertToPolygons(adaptivity=0.8)
>>> writeObjFile('bunny.obj', *mesh)
C++ glue routines
Python objects of type FloatGrid, Vec3SGrid, etc. are backed by C structs that “inherit” from PyObject
. The OpenVDB Python extension module includes public functions that you can call in your own extension modules to convert between openvdb::Grids and PyObject
s. See the pyopenvdb.h reference for a description of these functions and a usage example.
Your extension module might need to link against the OpenVDB extension module in order to access these functions. On UNIX systems, it might also be necessary to specify the RTLD_GLOBAL
flag when importing the OpenVDB module, to allow its symbols to be shared across modules. See setdlopenflags in the Python sys module for one way to do this.