OpenVDB
2.1.0
|
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.
The following example is a complete program that illustrates some of the basic steps to create grids and write them to disk:
This example shows how to read grids from files, and some ways to modify grids:
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.
Alternatively, replace all or some of a grid’s metadata by supplying a (name, value) dictionary:
Iterate over a grid’s metadata as you would over a dictionary:
Removing metadata is also straightforward:
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:
Setting these properties to None
removes the corresponding metadata, but the properties retain default values:
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:
File-level metadata can be retrieved with either the readMetadata function or the readAll function:
Grids provide read-only and read/write accessors for voxel lookup via index coordinates. Accessors store references to their parent grids, so a grid will not be deleted while it has accessors in use.
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.
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.
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 in both grids correspond to the same physical, world space location. Also, the operation always leaves grid B empty.
For now, combine operates only on tile and voxel values, not on their active states or other attributes.
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.
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.
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 .
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).
copyToArray has no tolerance
argument, because there is no distinction between active and inactive values in the destination array.
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.