236 lines
12 KiB
Plaintext
236 lines
12 KiB
Plaintext
/**
|
|
|
|
@page faq Frequently Asked Questions
|
|
|
|
@section sFAQContents Contents
|
|
- @ref sWhatIsVDB
|
|
- @ref sWhatLicense
|
|
- @ref sWhatCLA
|
|
- @ref sWhyUseVDB
|
|
- @ref sVersionNumbering
|
|
- @ref sGeneralizedOctree
|
|
- @ref sLevelSet
|
|
- @ref sCustomizeVDB
|
|
- @ref sAdaptiveGrid
|
|
- @ref sMeaningOfVDB
|
|
- @ref sAccessor
|
|
- @ref sValue
|
|
- @ref sState
|
|
- @ref sVoxel
|
|
- @ref sTile
|
|
- @ref sBackground
|
|
- @ref sThreadSafe
|
|
- @ref sMaxRes
|
|
- @ref sCompareVDB
|
|
- @ref sReplaceDense
|
|
- @ref sContribute
|
|
|
|
@section sWhatIsVDB What is OpenVDB?
|
|
OpenVDB is a library comprising a compact hierarchical data structure and a
|
|
suite of tools for the efficient manipulation of sparse, possibly time-varying,
|
|
volumetric data discretized on a three-dimensional grid. It is based on
|
|
VDB, which was developed by Ken Museth at DreamWorks Animation, and it
|
|
offers an effectively infinite 3D index space, compact storage (both in
|
|
memory and on disk), fast data access (both random and sequential), and
|
|
a collection of algorithms specifically optimized for the data structure
|
|
for common tasks such as filtering, constructive solid geometry (CSG),
|
|
discretization of partial differential equations, voxelization of polygons,
|
|
skinning of particles, volumetric compositing and sampling. The technical
|
|
details of VDB are described in the paper
|
|
<a href="http://www.museth.org/Ken/Publications.html" target="_blank">"VDB: High-Resolution Sparse Volumes with Dynamic Topology"</a>.
|
|
|
|
@section sWhatLicense What license is OpenVDB distributed under?
|
|
OpenVDB is released under the Apache License Version 2.0, which is a
|
|
free, open source software license developed and maintained by the Apache Software
|
|
Foundation. For more information about this license, see
|
|
<a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank">Apache License, Version 2</a>.
|
|
|
|
@section sWhatCLA Is there a Contributor License Agreement for OpenVDB?
|
|
Yes, developers who wish to contribute code to be considered for inclusion
|
|
in the OpenVDB distribution must first be authorized under a signed Contributor
|
|
License Agreement. The signature and authorization process is managed via
|
|
the Linux Foundation's EasyCLA system, to handle the different CLAs depending
|
|
on whether you are contributing on your own behalf or on behalf of your
|
|
employer. The EasyCLA process will begin the first time you submit a PR
|
|
to the project.
|
|
|
|
@section sWhyUseVDB Why should I use OpenVDB?
|
|
The typical reasons to adopt OpenVDB are if you are <b>storing sparse
|
|
data</b> and/or if you are performing <b>sparse computations</b>. OpenVDB
|
|
is also effectively unbounded, which makes it very convenient for
|
|
applications where the topology of the data is dynamic or unknown. Unlike
|
|
many existing sparse data structures, OpenVDB is also optimized for
|
|
numerical simulations, multithreaded volume compositing, near real-time
|
|
boolean CSG operations, fast random and sequential data access and
|
|
voxelization of points and polygons.
|
|
|
|
@section sVersionNumbering What is the version numbering system for OpenVDB?
|
|
We currently use a <I>major.minor.patch</I> version numbering system,
|
|
and with every release of OpenVDB we change one or more of the three numbers.
|
|
The patch number is incremented for new features and bug fixes that change
|
|
neither the API nor the file format of the library nor the ABIs of the @b Grid
|
|
class or its constituent classes (@b Tree, @b Transform, @b Metadata,
|
|
@b io::StreamMetadata, etc.).
|
|
The minor version is incremented for releases that change the API without
|
|
changing the @b Grid ABI, and for releases that change the file format
|
|
in such a way that older files can still be read.
|
|
The major version is incremented when the @b Grid ABI changes, or when the
|
|
file format changes in a non-backward-compatible way (which should be rare).
|
|
No release of OpenVDB guarantees ABI compatibility across the entire library,
|
|
but rather only for the @b Grid and its constituent classes, and primarily
|
|
to allow third-party app plugins compiled against different versions of
|
|
the library to coexist and exchange data.
|
|
|
|
@section sCustomizeVDB Can I customize the configuration of OpenVDB?
|
|
Yes! OpenVDB is specifically developed to be highly customizable. That is,
|
|
the user can define the sizes of all the nodes at each level of a tree as
|
|
well as the number of tree levels and the data type of values stored in the
|
|
tree. However, note that since OpenVDB makes extensive use of C++
|
|
templating, configurations are fixed at compile time rather than at run
|
|
time. This is a fundamental design characteristic of OpenVDB, and it leads
|
|
to very high performance, thanks to techniques like inlining and template
|
|
metaprogramming.
|
|
|
|
@section sGeneralizedOctree Is OpenVDB merely a generalized octree or N-tree?
|
|
No! While OpenVDB can conceptually be configured as a (height-balanced)
|
|
octree, it is much more than an octree or N-tree. Whereas octrees and
|
|
N-trees have fixed branching factors of respectively two and N in each
|
|
coordinate direction, OpenVDB’s branching factors typically vary between
|
|
tree levels and are only limited to be powers of two. To understand why
|
|
and also learn about other unique features of OpenVDB, refer to the
|
|
paper in <i>ACM Transactions on Graphics</i>.
|
|
|
|
@section sLevelSet Is OpenVDB primarily for level set applications?
|
|
No! Don’t let the fact that OpenVDB can represent and operate so well on
|
|
level sets mislead you into thinking that it is limited to or even focusing
|
|
on this special type of sparse volumetric application. OpenVDB was developed
|
|
for general-purpose volumetric processing and numerical simulation, and we
|
|
have even had success using it for volumetric applications that traditionally
|
|
call for blocked or dense grids. However, the fact remains that narrow-band
|
|
level sets play an essential role in many volumetric applications, and this
|
|
explains why OpenVDB includes so many tools and algorithms specifically
|
|
for level sets.
|
|
|
|
@section sAdaptiveGrid Is OpenVDB an adaptive grid?
|
|
Let’s first stress that the term "adaptive grid" is somewhat ambiguous.
|
|
Some use it to mean a grid that can store data sampled at adaptive voxel sizes
|
|
typically derived from a so-called "refinement oracle", whereas others mean
|
|
multiple grids with different fixed voxel sizes all sampling the same data.
|
|
An example of the former is an octree and of the latter is a mipmap.
|
|
Since OpenVDB stores both data values and child nodes at each level of
|
|
the tree, it is adaptive only in the first sense, not the second.
|
|
The level of adaptivity or refinement between the tree levels is defined
|
|
by the branching factors of the nodes, which are fixed at compile time.
|
|
|
|
@section sMeaningOfVDB What does "VDB" stand for?
|
|
Over the years VDB has been interpreted to mean different things, none of
|
|
which are very descriptive: "Voxel Data Base", "Volumetric Data Blocks",
|
|
"Volumetric Dynamic B+tree", etc. In early presentations of VDB we even used
|
|
a different name, "DB+Grid", which was abandoned to emphasize its
|
|
distinction from similarly named, but different, existing sparse data
|
|
structures like DT-Grid or DB-Grid. The simple truth is that "VDB" is just a
|
|
name. :-)
|
|
|
|
@section sAccessor Why are there no coordinate-based access methods on the grid?
|
|
It might surprise you that the @b Grid class doesn’t directly provide
|
|
access to voxels via their @ijk coordinates.
|
|
Instead, the recommended procedure is to ask the grid for a "value accessor",
|
|
which is an accelerator object that performs bottom-up tree traversal using
|
|
cached information from previous traversals.
|
|
Caching greatly improves performance, but it is inherently not thread-safe.
|
|
However, a single grid may have multiple value accessors, so each thread
|
|
can safely be assigned its own value accessor.
|
|
Uncached—and therefore slower, but thread-safe—random access
|
|
is possible through a grid’s tree, for example with a call like
|
|
<tt>grid.tree().getValue(ijk)</tt>.
|
|
|
|
@section sValue How and where does OpenVDB store values?
|
|
OpenVDB stores voxel data in a tree with a fixed maximum height (chosen
|
|
at compile time), with a root node that has a dynamic branching factor,
|
|
with internal nodes that have fixed branching factors, and with leaf nodes
|
|
of fixed dimensions. Values can be stored in nodes at all levels of
|
|
the tree. Values stored in leaf nodes correspond to individual voxels;
|
|
all other values correspond to "tiles" (see below).
|
|
|
|
@section sState What are active and inactive values?
|
|
Every value in a grid has a binary state that we refer to as its
|
|
"active state".
|
|
The interpretation of this binary state is application-specific, but
|
|
typically an active (on) value is "interesting" in some sense, and an
|
|
inactive (off) value is less interesting or uninteresting.
|
|
For example, the values in a narrow-band level set are all active, and
|
|
values outside the narrow band are all inactive.
|
|
Active states of values are stored in very compact bit masks that
|
|
support sparse iteration, so visiting all active (or inactive) values
|
|
in a grid can be done very efficiently.
|
|
|
|
@section sVoxel How are voxels represented in OpenVDB?
|
|
Values stored in nodes of type @b LeafNode (which, when they exist,
|
|
have a fixed depth), correspond to individual voxels.
|
|
These are the smallest addressable units of index space.
|
|
|
|
@section sTile What are tiles?
|
|
Values stored in nodes of type @b RootNode or @b InternalNode correspond to
|
|
regions of index space with a constant value and active state and with
|
|
power of two dimensions. We refer to such regions as "tiles". By
|
|
construction, tiles have no child nodes.
|
|
|
|
@section sBackground What is the background value?
|
|
A tree’s background value is the value that is returned whenever
|
|
one accesses a region of index space that is not explicitly represented by
|
|
voxels or tiles in the tree. Thus, you can think of the background value
|
|
as the default value associated with an empty tree.
|
|
Note that the background value is always inactive!
|
|
|
|
@section sThreadSafe Is OpenVDB thread-safe?
|
|
Yes and no. If you’re asking if OpenVDB can safely be used in a
|
|
multithreaded application then the answer is a resounding yes.
|
|
In fact, many of the tools included in OpenVDB are multithreaded (using
|
|
Intel’s Threading Building Blocks library).
|
|
However, like virtually all data structures that employ caching and
|
|
allocate-on-insert, certain operations in OpenVDB are not thread-safe
|
|
in the general sense.
|
|
In particular, it is not safe to retrieve voxels from a grid while
|
|
another thread is inserting voxels.
|
|
For multithreaded insertion operations we typically assign a separate grid
|
|
to each thread and then merge the grids as threads terminate.
|
|
This technique works remarkably well: because OpenVDB
|
|
is sparse and hierarchical, merging is very efficient.
|
|
For more details, please consult the @subpage codeExamples and
|
|
Appendix B in the <i>Transactions on Graphics</i> paper.
|
|
|
|
@section sMaxRes Is OpenVDB unbounded?
|
|
Yes, to within available memory and the 32-bit precision of the coordinates
|
|
used to index voxels. And OpenVDB supports signed coordinates, unlike most
|
|
existing sparse data structures, so there are almost no restrictions on the
|
|
available grid resolution or the index range of OpenVDB grids.
|
|
|
|
@section sCompareVDB How does OpenVDB compare to existing sparse data structures?
|
|
OpenVDB is very different from existing sparse data structures that you are
|
|
likely to have heard of. Foremost it is hierarchical (unlike DT-Grid and
|
|
Field3D), supports simulations and dynamic topology (unlike GigaVoxels), is
|
|
effectively unbounded (unlike Field3D), and offers fast random and sequential
|
|
voxel access.
|
|
|
|
@section sReplaceDense Does OpenVDB replace dense grids?
|
|
This depends a lot on your application of dense grids and your configuration
|
|
of OpenVDB.
|
|
Clearly, if you are storing or processing sparse data, OpenVDB
|
|
will offer a smaller memory footprint and faster (sparse) data processing.
|
|
However, even in some cases where both data and computation are dense, OpenVDB
|
|
can offer benefits like improved CPU cache performance due to its underlying
|
|
blocking and hierarchical tree structure.
|
|
Exceptions are of course algorithms that expect dense data to be laid out
|
|
linearly in memory, or applications that use very small grids.
|
|
The simple truth is only a benchmark comparison can tell you the preferred
|
|
data structure, but for what it’s worth it is our experience that
|
|
for the volumetric applications we encounter in production, OpenVDB is
|
|
almost always superior.
|
|
|
|
@section sContribute How can I contribute to OpenVDB?
|
|
If you have bug reports or ideas for improvements or new features,
|
|
please contact us! If you want to contribute code, please see our
|
|
<a href="http://www.openvdb.org/license/index.html" target="_blank">License page</a>.
|
|
|
|
*/
|