OpenVDB  4.0.2
Using OpenVDB in Python

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:

1 import pyopenvdb as vdb
2 
3 # A grid comprises a sparse tree representation of voxel data,
4 # user-supplied metadata and a voxel space to world space transform,
5 # which defaults to the identity transform.
6 # A FloatGrid stores one single-precision floating point value per voxel.
7 # Other grid types include BoolGrid and Vec3SGrid. The module-level
8 # attribute pyopenvdb.GridTypes gives the complete list.
9 cube = vdb.FloatGrid()
10 cube.fill(min=(100, 100, 100), max=(199, 199, 199), value=1.0)
11 
12 # Name the grid "cube".
13 cube.name = 'cube'
14 
15 # Populate another FloatGrid with a sparse, narrow-band level set
16 # representation of a sphere with radius 50 voxels, located at
17 # (1.5, 2, 3) in index space.
18 sphere = vdb.createLevelSetSphere(radius=50, center=(1.5, 2, 3))
19 
20 # Associate some metadata with the grid.
21 sphere['radius'] = 50.0
22 
23 # Associate a scaling transform with the grid that sets the voxel size
24 # to 0.5 units in world space.
25 sphere.transform = vdb.createLinearTransform(voxelSize=0.5)
26 
27 # Name the grid "sphere".
28 sphere.name = 'sphere'
29 
30 # Write both grids to a VDB file.
31 vdb.write('mygrids.vdb', grids=[cube, sphere])

This example shows how to read grids from files, and some ways to modify grids:

1 import pyopenvdb as vdb
2 
3 # Read a .vdb file and return a list of grids populated with
4 # their metadata and transforms, but not their trees.
5 filename = 'mygrids.vdb'
6 grids = vdb.readAllGridMetadata(filename)
7 
8 # Look for and read in a level-set grid that has certain metadata.
9 sphere = None
10 for grid in grids:
11  if (grid.gridClass == vdb.GridClass.LEVEL_SET and 'radius' in grid
12  and grid['radius'] > 10.0):
13  sphere = vdb.read(filename, grid.name)
14  else:
15  print 'skipping grid', grid.name
16 
17 if sphere:
18  # Convert the level set sphere to a narrow-band fog volume, in which
19  # interior voxels have value 1, exterior voxels have value 0, and
20  # narrow-band voxels have values varying linearly from 0 to 1.
21 
22  outside = sphere.background
23  width = 2.0 * outside
24 
25  # Visit and update all of the grid's active values, which correspond to
26  # voxels in the narrow band.
27  for iter in sphere.iterOnValues():
28  dist = iter.value
29  iter.value = (outside - dist) / width
30 
31  # Visit all of the grid's inactive tile and voxel values and update
32  # the values that correspond to the interior region.
33  for iter in sphere.iterOffValues():
34  if iter.value < 0.0:
35  iter.value = 1.0
36  iter.active = False
37 
38  # Set exterior voxels to 0.
39  sphere.background = 0.0
40 
41  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.

1 >>> import pyopenvdb as vdb
2 
3 >>> grid = vdb.Vec3SGrid()
4 
5 >>> grid['vector'] = 'gradient'
6 >>> grid['radius'] = 50.0
7 >>> grid['center'] = (10, 15, 10)
8 
9 >>> grid.metadata
10 {'vector': 'gradient', 'radius': 50.0, 'center': (10, 15, 10)}
11 
12 >>> grid['radius']
13 50.0
14 
15 >>> 'radius' in grid, 'misc' in grid
16 (True, False)
17 
18 # OK to overwrite an existing value with a value of another type:
19 >>> grid['center'] = 0.0
20 
21 # A 4-element sequence is not a supported metadata value type:
22 >>> grid['center'] = (0, 0, 0, 0)
23  File "<stdin>", line 1, in <module>
24 TypeError: metadata value "(0, 0, 0, 0)" of type tuple is not allowed
25 
26 # Metadata names must be strings:
27 >>> grid[0] = (10.5, 15, 30)
28  File "<stdin>", line 1, in <module>
29 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:

1 >>> metadata = {
2 ... 'vector': 'gradient',
3 ... 'radius': 50.0,
4 ... 'center': (10, 15, 10)
5 ... }
6 
7 # Replace all of the grid's metadata.
8 >>> grid.metadata = metadata
9 
10 >>> metadata = {
11 ... 'center': [10.5, 15, 30],
12 ... 'scale': 3.14159
13 ... }
14 
15 # Overwrite "center" and add "scale":
16 >>> grid.updateMetadata(metadata)

Iterate over a grid’s metadata as you would over a dictionary:

1 >>> for key in grid:
2 ... print '%s = %s' % (key, grid[key])
3 ...
4 vector = gradient
5 radius = 50.0
6 scale = 3.14159
7 center = (10.5, 15.0, 30.0)

Removing metadata is also straightforward:

1 >>> del grid['vector']
2 >>> del grid['center']
3 >>> del grid['vector'] # error: already removed
4  File "<stdin>", line 1, in <module>
5 KeyError: 'vector'
6 
7 >>> grid.metadata = {} # remove all 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:

1 >>> grid = vdb.createLevelSetSphere(radius=10.0)
2 >>> grid.metadata
3 {'class': 'level set'}
4 
5 >>> grid.gridClass = vdb.GridClass.FOG_VOLUME
6 >>> grid.metadata
7 {'class': 'fog volume'}
8 
9 # The gridClass property requires a string value:
10 >>> grid.gridClass = 123
11  File "<stdin>", line 1, in <module>
12 TypeError: expected str, found int as argument 1 to setGridClass()
13 
14 # Only certain strings are recognized; see pyopenvdb.GridClass
15 # for the complete list.
16 >>> grid.gridClass = 'Hello, world.'
17 >>> grid.metadata
18 {'class': 'unknown'}
19 
20 >>> grid.metadata = {}
21 >>> grid.vectorType = vdb.VectorType.COVARIANT
22 >>> grid.metadata
23 {'vector_type': 'covariant'}
24 
25 >>> grid.name = 'sphere'
26 >>> grid.creator = 'Python'
27 >>> grid.metadata
28 {'vector_type': 'covariant', 'name': 'sphere', 'creator': 'Python'}

Setting these properties to None removes the corresponding metadata, but the properties retain default values:

1 >>> grid.creator = grid.vectorType = None
2 >>> grid.metadata
3 {'name': 'sphere'}
4 
5 >>> grid.creator, grid.vectorType
6 ('', '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:

1 >>> metadata = {
2 ... 'creator': 'Python',
3 ... 'time': '11:05:00'
4 ... }
5 >>> vdb.write('mygrids.vdb', grids=grid, metadata=metadata)

File-level metadata can be retrieved with either the readMetadata function or the readAll function:

1 >>> metadata = vdb.readMetadata('mygrids.vdb')
2 >>> metadata
3 {'creator': 'Python', 'time': '11:05:00'}
4 
5 >>> grids, metadata = vdb.readAll('mygrids.vdb')
6 >>> metadata
7 {'creator': 'Python', 'time': '11:05:00'}
8 >>> [grid.name for grid in grids]
9 ['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.

1 >>> import pyopenvdb as vdb
2 
3 # Read two grids from a file.
4 >>> grids, metadata = vdb.readAll('smoke2.vdb')
5 >>> [grid.name for grid in grids]
6 ['density', 'v']
7 
8 # Get read/write accessors to the two grids.
9 >>> dAccessor = grids[0].getAccessor()
10 >>> vAccessor = grids[1].getAccessor()
11 
12 >>> ijk = (100, 103, 101)
13 
14 >>> dAccessor.probeValue(ijk)
15 (0.17614534497261047, True)
16 # Change the value of a voxel.
17 >>> dAccessor.setValueOn(ijk, 0.125)
18 >>> dAccessor.probeValue(ijk)
19 (0.125, True)
20 
21 >>> vAccessor.probeValue(ijk)
22 ((-2.90625, 9.84375, 0.84228515625), True)
23 # Change the active state of a voxel.
24 >>> vAccessor.setActiveState(ijk, False)
25 >>> vAccessor.probeValue(ijk)
26 ((-2.90625, 9.84375, 0.84228515625), False)
27 
28 # Get a read-only accessor to one of the grids.
29 >>> dAccessor = grids[0].getConstAccessor()
30 >>> dAccessor.setActiveState(ijk, False)
31  File "<stdin>", line 1, in <module>
32 TypeError: accessor is read-only
33 
34 # Delete the accessors once they are no longer needed,
35 # so that the grids can be garbage-collected.
36 >>> 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.

1 >>> import pyopenvdb as vdb
2 
3 >>> grid = vdb.read('smoke2.vdb', gridname='v')
4 >>> grid.__class__.__name__
5 'Vec3SGrid'
6 
7 # Iterate over inactive values and print the coordinates of the first
8 # five voxel values and the bounding boxes of the first five tile values.
9 >>> voxels = tiles = 0
10 ... N = 5
11 ... for item in grid.citerOffValues(): # read-only iterator
12 ... if voxels == N and tiles == N:
13 ... break
14 ... if item.count == 1:
15 ... if voxels < N:
16 ... voxels += 1
17 ... print 'voxel', item.min
18 ... else:
19 ... if tiles < N:
20 ... tiles += 1
21 ... print 'tile', item.min, item.max
22 ...
23 tile (0, 0, 0) (7, 7, 7)
24 tile (0, 0, 8) (7, 7, 15)
25 tile (0, 0, 16) (7, 7, 23)
26 tile (0, 0, 24) (7, 7, 31)
27 tile (0, 0, 32) (7, 7, 39)
28 voxel (40, 96, 88)
29 voxel (40, 96, 89)
30 voxel (40, 96, 90)
31 voxel (40, 96, 91)
32 voxel (40, 96, 92)
33 
34 # Iterate over and normalize all active values.
35 >>> from math import sqrt
36 >>> for item in grid.iterOnValues(): # read/write iterator
37 ... vector = item.value
38 ... magnitude = sqrt(sum(x * x for x in vector))
39 ... item.value = [x / magnitude for x in vector]
40 ...

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.

1 >>> import pyopenvdb as vdb
2 >>> from math import sqrt
3 
4 >>> grid = vdb.read('smoke2.vdb', gridname='v')
5 
6 >>> def normalize(vector):
7 ... magnitude = sqrt(sum(x * x for x in vector))
8 ... return [x / magnitude for x in vector]
9 ...
10 >>> 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.

1 >>> import pyopenvdb as vdb
2 
3 >>> density = vdb.read('smoke2.vdb', gridname='density')
4 >>> density.__class__.__name__
5 'FloatGrid'
6 
7 >>> sphere = vdb.createLevelSetSphere(radius=50.0, center=(100, 300, 100))
8 
9 >>> 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.

1 >>> import pyopenvdb as vdb
2 >>> import numpy
3 
4 >>> array = numpy.random.rand(200, 200, 200)
5 >>> array.dtype
6 dtype('float64')
7 
8 # Copy values from a three-dimensional array of doubles
9 # into a grid of floats.
10 >>> grid = vdb.FloatGrid()
11 >>> grid.copyFromArray(array)
12 >>> grid.activeVoxelCount() == array.size
13 True
14 >>> grid.evalActiveVoxelBoundingBox()
15 ((0, 0, 0), (199, 199, 199))
16 
17 # Copy values from a four-dimensional array of ints
18 # into a grid of float vectors.
19 >>> vecarray = numpy.ndarray((60, 70, 80, 3), int)
20 >>> vecarray.fill(42)
21 >>> vecgrid = vdb.Vec3SGrid()
22 >>> vecgrid.copyFromArray(vecarray)
23 >>> vecgrid.activeVoxelCount() == 60 * 70 * 80
24 True
25 >>> vecgrid.evalActiveVoxelBoundingBox()
26 ((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.

1 >>> grid.clear()
2 >>> grid.copyFromArray(array, tolerance=0.2)
3 >>> print '%d%% of copied voxels are active' % (
4 ... round(100.0 * grid.activeVoxelCount() / array.size))
5 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)$.

1 >>> grid.clear()
2 >>> grid.copyFromArray(array, ijk=(-1, 2, 3))
3 >>> grid.evalActiveVoxelBoundingBox()
4 ((-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).

1 >>> grid = vdb.createLevelSetSphere(radius=10.0)
2 >>> array = numpy.ndarray((40, 40, 40), int)
3 >>> array.fill(0)
4 # Copy values from a grid of floats into
5 # a three-dimensional array of ints.
6 >>> grid.copyToArray(array, ijk=(-15, -20, -35))
7 >>> array[15, 20]
8 array([ 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
9  3, 3, 3, 3, 3, 3, 3, 3, 3, 3,
10  3, 3, 3, 2, 1, 0, -1, -2, -3, -3,
11  -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.

1 >>> import pyopenvdb as vdb
2 >>> import numpy
3 
4 >>> grid = vdb.read('bunny.vdb', 'ls_bunny')
5 
6 # Convert a volume to a quadrilateral mesh.
7 >>> points, quads = grid.convertToQuads()
8 
9 # World-space vertices of the mesh:
10 >>> points
11 array([[-14.05082607, -0.10118673, -0.40250054],
12  [-14.05230808, -0.05570767, -0.45693323],
13  [-14.05613995, -0.0734246 , -0.42150033],
14  ...,
15  [ 7.25201273, 13.25417805, 6.45283508],
16  [ 7.25596714, 13.31225586, 6.40827513],
17  [ 7.30518484, 13.21096039, 6.40724468]], dtype=float32)
18 
19 # Quadrilateral faces of the mesh, given by
20 # 4-tuples of indices into the vertex list:
21 >>> quads
22 array([[ 5, 2, 1, 4],
23  [ 11, 7, 6, 10],
24  [ 14, 9, 8, 13],
25  ...,
26  [1327942, 1327766, 1339685, 1339733],
27  [1339728, 1327921, 1327942, 1339733],
28  [1339733, 1339685, 1339661, 1339728]], dtype=uint32)
29 
30 # Convert the mesh back to a (single-precision) volume.
31 # Give the resulting grid the original grid's transform.
32 >>> gridFromQuads = vdb.FloatGrid.createLevelSetFromPolygons(
33 ... points, quads=quads, transform=grid.transform)
34 
35 
36 # Alternatively, mesh a volume adaptively for a lower polygon count.
37 # Adaptive meshing generates both triangular and quadrilateral faces.
38 >>> points, triangles, quads = grid.convertToPolygons(adaptivity=0.5)
39 
40 # World-space vertices of the mesh:
41 >>> points
42 array([[-14.02906322, -0.07213751, -0.49265194],
43  [-14.11877823, -0.11127799, -0.17118289],
44  [-13.85006142, -0.08145611, -0.86669081],
45  ...,
46  [ 7.31098318, 12.97358608, 6.55133963],
47  [ 7.20240211, 12.80632019, 6.80356836],
48  [ 7.23679161, 13.28100395, 6.45595646]], dtype=float32)
49 
50 # Triangular faces of the mesh, given by
51 # triples of indices into the vertex list:
52 >>> triangles
53 array([[ 8, 7, 0],
54  [ 14, 9, 8],
55  [ 14, 11, 9],
56  ...,
57  [22794, 22796, 22797],
58  [22784, 22783, 22810],
59  [22796, 22795, 22816]], dtype=uint32)
60 
61 # Quadrilateral faces of the mesh, given by
62 # 4-tuples of indices into the vertex list:
63 >>> quads
64 array([[ 4, 3, 6, 5],
65  [ 8, 9, 10, 7],
66  [ 11, 12, 10, 9],
67  ...,
68  [23351, 23349, 23341, 23344],
69  [23344, 23117, 23169, 23351],
70  [23169, 23167, 23349, 23351]], dtype=uint32)
71 
72 # Convert the mesh to a double-precision volume.
73 >>> doubleGridFromPolys = vdb.DoubleGrid.createLevelSetFromPolygons(
74 ... 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:

1 >>> def writeObjFile(filename, points, triangles=[], quads=[]):
2 ... f = open(filename, 'w')
3 ... # Output vertices.
4 ... for xyz in points:
5 ... f.write('v %g %g %g\n' % tuple(xyz))
6 ... f.write('\n')
7 ... # Output faces.
8 ... for ijk in triangles:
9 ... f.write('f %d %d %d\n' %
10 ... (ijk[0]+1, ijk[1]+1, ijk[2]+1)) # offset vertex indices by one
11 ... for ijkl in quads:
12 ... f.write('f %d %d %d %d\n' %
13 ... (ijkl[0]+1, ijkl[1]+1, ijkl[2]+1, ijkl[3]+1))
14 ... f.close()
15 ...
16 >>> mesh = grid.convertToPolygons(adaptivity=0.8)
17 >>> 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 PyObjects. 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.