OpenVDB 3.0 beta

[Ken Museth]

A major beta version of OpenVDB 3.0 has just been uploaded to GitHub. See the list below for a summary of all the new features, performance improvements, and bug-fixes. We plan to make a final release next month, but would like to get feedback from developers and users first, so please take it for a spin. The increment of the major version number indicates that the ABI (and API) has changed, but we have added ABI comparability when it is building against existing versions of Houdini (that ships with 2.x). However, version 3.0 is required when developing for the upcoming Houdini Version 14! -K Version 3.0.0 - In development

- The io::File class now supports delayed loading of .vdb files,

meaning that memory is not allocated for voxel values until the values

are actually accessed. (This feature is enabled by default.)

Until a grid has been fully loaded, its source .vdb file must not be

modified or deleted, so for safety, io::File::open() automatically makes

private copies of source files that are smaller than a user-specified

limit (see io::File::setCopyMaxBytes()). The limit can be set to zero

to disable copying, but if it cannot be guaranteed that a file will not

be modified, then it is best not to enable delayed loading for that file.

- Added tools::PointPartitioner, a tool for fast spatial sorting

of points stored in an external array, and tools::PointIndexGrid,

an acceleration structure for fast range and nearest-neighbor searches.

- Added tree::NodeManager, which "linearizes" a tree to facilitate

efficient multithreading across all tree levels.

- Added tools::prune() (and other variants), which replaces and

outperforms Tree::prune().

- Added tools::signedFloodFill(), which replaces and outperforms

Tree::signedFloodFill().

- Added tools::changeBackground (and other variants), which replaces

and outperforms Tree::setBackground().

- Added a fast but approximate narrow-band level set dilation method,

a fast narrow-band level set erosion method,

and a masked normalization method to tools::LevelSetTracker.

- Added tools::Diagnose, which performs multithreaded diagnostics on grids

to identify issues like values that are NaNs or out-of-range.

It optionally generates a boolean grid of all values that fail

user-defined tests (a feature that will soon be exposed in Houdini).

- Added optional alpha masks to tools::LevelSetMorphing.

- Added tools::topologyToLevelSet(), which generates a level set

from the implicit boundary between active and inactive voxels

in an arbitrary input grid.

[DWA internal]

- Improved the performance of point scattering (by orders of magnitude)

and added a DenseUniformPointScatter class as well as support for

fractional numbers of particles per voxel.

- Added edge-adjacent (6+12=18) and vertex-adjacent (6+12+8=26)

dilation algorithms to tools::Morphology::dilateVoxels().

Still defaults to a face-adjacent (6) dilation pattern.

- Improved the performance and memory footprint of the ParticlesToLevelSet

tool for large numbers (tens to hundreds of millions) of particles.

- Added Tree::getNodes(), which allows for fast construction of

linear arrays of tree nodes for use in multithreaded code

such as the LeafManager or NodeManager.

- Added math::Extrema and tools::extrema() to efficiently compute

minimum and maximum values in a grid.

- Added support for material color grids to all level set shaders,

and added an option to vdb_render that allows one to specify a

reference grid to be used for material color lookups.

- Added openvdb::getLibraryVersionString() and

OPENVDB_LIBRARY_VERSION_STRING.

- Modified the mesh to volume converter to always set the grid background

value to the exterior narrow-band width, and added finite value checks

to narrow band parameters.

- tools::volumeToMesh() now compiles for all grid types but throws an

exception if the input grid does not have a scalar value type.

- Added an io::File::readGrid() overload and readBuffers() overloads

to the grid, tree and node classes that allow one to specify

a bounding box against which to clip a grid while reading it.

For large grids, clipping while reading can result in significantly

lower memory usage than clipping after reading.

- Added Grid::clipGrid(), which clips a grid against a world-space

bounding box, and Grid::clip() and Tree::clip(), which clip against

an index-space bounding box.

- Added tools::clip(), which clips a grid either against a bounding box

or against the active voxels of a mask grid.

- io::File::readGridPartial() allocates the nodes of a grid's tree

as before, but it now allocates leaf nodes without data buffers.

(This feature is mainly for internal use; partially-read grids should be

used with care if at all, and they should be treated as read-only.)

- Grid names retrieved using an io::File::NameIterator now always uniquely

identify grids; they no longer generate 'more than one grid named "x"'

warnings when there are multiple grids of the same name in a file

(for files written starting with this version of the OpenVDB library).

- Fixed a bug in Tree::ValueOffIter that could cause depth-bounded

iterators to return incorrect values.

- Fixed memory leaks in RootNode::topologyDifference() and

RootNode::topologyIntersection().

- Fixed a memory leak in io::Queue when the queue was full and

a write task could not be added within the timeout interval.

- Fixed a potential division by zero crash in tools::compDiv()

with integer-valued grids.

- Fixed kernel normalization in tools::Filter so that it is correct

for integer-valued grids.

- Fixed a bug in LeafNode::Buffer::getValue() whereby Visual C++

would return a reference to a temporary.

[Contributed by SESI]

- Fixed a bug in tools::ParticlesToLevelSet related to attribute transfer

when leaf nodes are produced without active values.

- Added util/CpuTimer.h and removed CpuTimer (with a minimal API) from

unittest/util.h.

- Eliminated the use of getopt() for command-line argument parsing

in vdb_test.

- Fixed the vdb_print, vdb_render and vdb_view tools so that they

properly initialize log4cplus if it is enabled.

- Fixed a bug in the QuantizedUnitVec::pack() method that caused

quantization artifacts.

- Added convenience class tools::AlphaMask to tools/Interpolation.h

- Added constructors and methods to both math::RandInt and math::Rand01

to set and reset the random seed value.

- Added convenience methods for transforming bounding boxes to

math::Transform.

- Made many small changes to address type conversion and other warnings

reported by newer compilers like GCC 4.8 and ICC 14.

- Replaced the HALF_INCL_DIR and HALF_LIB_DIR Makefile variables

with ILMBASE_INCL_DIR and ILMBASE_LIB_DIR and added ILMBASE_LIB,

to match OpenEXR's library organization.

[Contributed by Double Negative]

- Eliminated most local (function-scope) static variables, because

Visual C++ doesn't guarantee thread-safe initialization of local statics.

[Contributed by SESI]

- Fixed a bug in readString() related to empty strings.

[Contributed by Fabio Piparo]

API changes:

- The addition of a GridBase::readBuffers() virtual function overload

and the GridBase::clip(), GridBase::readNonresidentBuffers() and

Tree::clipUnallocatedNodes() virtual functions changes the grid ABI

so that it is incompatible with earlier versions of the OpenVDB library

(such as the ones in Houdini 12.5 and 13). Define the macro

OPENVDB_2_ABI_COMPATIBLE when compiling OpenVDB to disable these changes

and preserve ABI compatibility.

- All shaders now have a template argument to specify the type of

an optional material color grid, but the default type mimics

the old, uniform color behavior.

- Removed a deprecated io::Stream::write() overload.

- The point counts in the UniformPointScatter and NonUniformPointScatter

tools are now specified and returned as Index64.

- math::RandInt has an extra template argument to specify the integer

type. The RandomInt typedef is unchanged.

- io::readData(), io::HalfReader::read() and io::HalfWriter::write() now

take a uint32_t argument indicating the type of compression instead of

a bool indicating whether compression is enabled.

- Removed io::Archive::isCompressionEnabled() and

io::Archive::setCompressionEnabled() and renamed

io::Archive::compressionFlags() and io::Archive::setCompressionFlags()

to io::Archive::compression() and io::Archive::setCompression().

- Internal and leaf node classes are now required to provide

"PartialCreate" constructors that optionally bypass the allocation

of voxel buffers. Leaf node classes must now also provide allocate()

and isAllocated() methods to manage the allocation of their buffers.

- Removed pruneInactive() and pruneLevelSet() methods from the Tree

and various node classes. These methods have been replaced by

the much faster pruning functions found in tools/Prune.h.

- Removed signedFloodFill() methods from the Grid, Tree and various

node classes. These methods have been replaced by the much faster

functions found in tools/SignedFloodFill.h.

- Removed Grid::setBackground() and Tree::setBackground() (use the faster

changeBackground() tool instead), and removed the default argument

from RootNode::setBackground().

Python:

- Added grid methods convertToPolygons() and convertToQuads(),

which convert volumes to meshes, and createLevelSetFromPolygons(),

which converts meshes to volumes. NumPy is required.

Houdini:

- Added a new SOP (Trim Narrow Band) that can adjust (i.e. dilate or erode)

the width of a narrow band level set. This allows for a much faster workflows

where level sets are created (e.g. from points or polygons) with a very narrow

band and subsequently dilated with the new SOP.

- Fixed bugs in the Smooth Level Set and Reshape Level Set SOPs that ignored the

selected discretization scheme.

- Added alpha mask options to the Morph Level Set SOP.

- Added a From Points SOP to very quickly generate a level set

from a point cloud, ignoring any radius attribute.

[DWA internal]

- Added a Voxel Scale mode to the Resample SOP.

- Improved the performance and memory footprint of the From Particles SOP

for large numbers (tens to hundreds of millions) of particles.

- The Scatter SOP now accepts fractional numbers of particles per voxel.

- Improved the performance of the Scatter SOP by more than an order

of magnitude.

- The Clip SOP now has a toggle to choose explicitly between a mask grid

or a bounding box as the clipping region. As a consequence, the

mask grid can now be unnamed.

- Added the OpenVDB library version number to the Extended Operator

Information for all SOPs.

- SOPs are now linked with an rpath to the directory containing the

OpenVDB library.

- Like the native Houdini file SOP, the Read SOP now allows missing frames

to be reported either as errors or as warnings.

- The Read SOP now has an optional input for geometry, the bounding box

of which can be used to clip grids as they are read. For large grids,

clipping while reading can result in significantly lower memory usage

than clipping after reading.

Maya:

- Added an adaptive polygonal surface extraction node.