OpenVDB: Tree< _RootNodeType > Class Template Reference

OpenVDB 11.0.0

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | List of all members
Tree< _RootNodeType > Class Template Reference

`#include <openvdb/tree/Tree.h>`

Inheritance diagram for Tree< _RootNodeType >:

## Classes
struct | DeallocateNodes
struct | ValueConverter
| ValueConverter<T>::Type is the type of a tree having the same hierarchy as this tree but a different value type, T. More...

## Public Types
using | Ptr = SharedPtr< Tree >
using | ConstPtr = SharedPtr< const Tree >
using | RootNodeType = _RootNodeType
using | ValueType = typename RootNodeType::ValueType
using | BuildType = typename RootNodeType::BuildType
using | LeafNodeType = typename RootNodeType::LeafNodeType
using | NodeIter = NodeIteratorBase< Tree, typename RootNodeType::ChildOnIter >
| Iterator over all nodes in this tree.
using | NodeCIter = NodeIteratorBase< const Tree, typename RootNodeType::ChildOnCIter >
using | LeafIter = LeafIteratorBase< Tree, typename RootNodeType::ChildOnIter >
| Iterator over all leaf nodes in this tree.
using | LeafCIter = LeafIteratorBase< const Tree, typename RootNodeType::ChildOnCIter >
using | ValueAllIter = TreeValueIteratorBase< Tree, typename RootNodeType::ValueAllIter >
using | ValueAllCIter = TreeValueIteratorBase< const Tree, typename RootNodeType::ValueAllCIter >
using | ValueOnIter = TreeValueIteratorBase< Tree, typename RootNodeType::ValueOnIter >
using | ValueOnCIter = TreeValueIteratorBase< const Tree, typename RootNodeType::ValueOnCIter >
using | ValueOffIter = TreeValueIteratorBase< Tree, typename RootNodeType::ValueOffIter >
using | ValueOffCIter = TreeValueIteratorBase< const Tree, typename RootNodeType::ValueOffCIter >

## Public Member Functions
| Tree ()
Tree & | operator= (const Tree &)=delete
| Tree (const Tree &other)
| Deep copy constructor.
template<typename OtherRootType >
| Tree (const Tree< OtherRootType > &other)
| Value conversion deep copy constructor.
template<typename OtherTreeType >
| Tree (const OtherTreeType &other, const ValueType &inactiveValue, const ValueType &activeValue, TopologyCopy)
| Topology copy constructor from a tree of a different type.
template<typename OtherTreeType >
| Tree (const OtherTreeType &other, const ValueType &background, TopologyCopy)
| Topology copy constructor from a tree of a different type.
| Tree (const ValueType &background)
| Empty tree constructor.
| ~Tree () override
TreeBase::Ptr | copy () const override
| Return a pointer to a deep copy of this tree.
Name | valueType () const override
| Return the name of the type of a voxel's value (e.g., "float" or "vec3d")
const Name & | type () const override
| Return the name of this type of tree.
bool | operator== (const Tree &) const
bool | operator!= (const Tree &) const
RootNodeType & | root ()
| Return this tree's root node.
const RootNodeType & | root () const
template<typename OtherRootNodeType >
bool | hasSameTopology (const Tree< OtherRootNodeType > &other) const
| Return `true` if the given tree has the same node and active value topology as this tree, whether or not it has the same `ValueType`.
bool | evalLeafBoundingBox (CoordBBox &bbox) const override
| Return in bbox the axis-aligned bounding box of all active tiles and leaf nodes with active values.
bool | evalActiveVoxelBoundingBox (CoordBBox &bbox) const override
| Return in bbox the axis-aligned bounding box of all active voxels and tiles.
bool | evalActiveVoxelDim (Coord &dim) const override
| Return in dim the dimensions of the axis-aligned bounding box of all active voxels. This is a tighter bounding box than the leaf node bounding box.
bool | evalLeafDim (Coord &dim) const override
| Return in dim the dimensions of the axis-aligned bounding box of all leaf nodes.
void | readTopology (std::istream &, bool saveFloatAsHalf=false) override
| Read the tree topology from a stream.
void | writeTopology (std::ostream &, bool saveFloatAsHalf=false) const override
| Write the tree topology to a stream.
void | readBuffers (std::istream &, bool saveFloatAsHalf=false) override
| Read all data buffers for this tree.
void | readBuffers (std::istream &, const CoordBBox &, bool saveFloatAsHalf=false) override
| Read all of this tree's data buffers that intersect the given bounding box.
void | readNonresidentBuffers () const override
| Read all of this tree's data buffers that are not yet resident in memory (because delayed loading is in effect).
void | writeBuffers (std::ostream &, bool saveFloatAsHalf=false) const override
| Write out all data buffers for this tree.
void | print (std::ostream &os=std::cout, int verboseLevel=1) const override
| Print statistics, memory usage and other information about this tree.
Index | treeDepth () const override
| Return the depth of this tree.
Index32 | leafCount () const override
| Return the number of leaf nodes.
std::vector< Index32 > | nodeCount () const override
Index32 | nonLeafCount () const override
| Return the number of non-leaf nodes.
Index64 | activeLeafVoxelCount () const override
| Return the number of active voxels stored in leaf nodes.
Index64 | inactiveLeafVoxelCount () const override
| Return the number of inactive voxels stored in leaf nodes.
Index64 | activeVoxelCount () const override
| Return the total number of active voxels.
Index64 | inactiveVoxelCount () const override
| Return the number of inactive voxels within the bounding box of all active voxels.
Index64 | activeTileCount () const override
| Return the total number of active tiles.
void | evalMinMax (ValueType &min, ValueType &max) const
| Return the minimum and maximum active values in this tree.
Index64 | memUsage () const override
| Return the total amount of memory in bytes occupied by this tree.
const ValueType & | getValue (const Coord &xyz) const
| Return the value of the voxel at the given coordinates.
template<typename AccessT >
const ValueType & | getValue (const Coord &xyz, AccessT &) const
| Return the value of the voxel at the given coordinates and update the given accessor's node cache.
int | getValueDepth (const Coord &xyz) const
| Return the tree depth (0 = root) at which the value of voxel (x, y, z) resides.
void | setActiveState (const Coord &xyz, bool on)
| Set the active state of the voxel at the given coordinates but don't change its value.
void | setValueOnly (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates but don't change its active state.
void | setValueOn (const Coord &xyz)
| Mark the voxel at the given coordinates as active but don't change its value.
void | setValueOn (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as active.
void | setValue (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as active.
template<typename AccessT >
void | setValue (const Coord &xyz, const ValueType &value, AccessT &)
| Set the value of the voxel at the given coordinates, mark the voxel as active, and update the given accessor's node cache.
void | setValueOff (const Coord &xyz)
| Mark the voxel at the given coordinates as inactive but don't change its value.
void | setValueOff (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as inactive.
template<typename ModifyOp >
void | modifyValue (const Coord &xyz, const ModifyOp &op)
| Apply a functor to the value of the voxel at the given coordinates and mark the voxel as active.
template<typename ModifyOp >
void | modifyValueAndActiveState (const Coord &xyz, const ModifyOp &op)
| Apply a functor to the voxel at the given coordinates.
bool | probeValue (const Coord &xyz, ValueType &value) const
| Get the value of the voxel at the given coordinates.
bool | isValueOn (const Coord &xyz) const
| Return `true` if the value at the given coordinates is active.
bool | isValueOff (const Coord &xyz) const
| Return `true` if the value at the given coordinates is inactive.
bool | hasActiveTiles () const
| Return `true` if this tree has any active tiles.
void | clip (const CoordBBox &)
| Set all voxels that lie outside the given axis-aligned box to the background.
void | clipUnallocatedNodes () override
| Replace with background tiles any nodes whose voxel buffers have not yet been allocated.
Index32 | unallocatedLeafCount () const override
| Return the total number of unallocated leaf nodes residing in this tree.
void | sparseFill (const CoordBBox &bbox, const ValueType &value, bool active=true)
| Set all voxels within a given axis-aligned box to a constant value.
void | fill (const CoordBBox &bbox, const ValueType &value, bool active=true)
void | denseFill (const CoordBBox &bbox, const ValueType &value, bool active=true)
| Set all voxels within a given axis-aligned box to a constant value and ensure that those voxels are all represented at the leaf level.
void | voxelizeActiveTiles (bool threaded=true)
| Densify active tiles, i.e., replace them with leaf-level active voxels.
void | prune (const ValueType &tolerance=zeroVal< ValueType >())
| Reduce the memory footprint of this tree by replacing with tiles any nodes whose values are all the same (optionally to within a tolerance) and have the same active state.
void | addLeaf (LeafNodeType *leaf)
| Add the given leaf node to this tree, creating a new branch if necessary. If a leaf node with the same origin already exists, replace it.
void | addTile (Index level, const Coord &xyz, const ValueType &value, bool active)
| Add a tile containing voxel (x, y, z) at the specified tree level, creating a new branch if necessary. Delete any existing lower-level nodes that contain (x, y, z).
template<typename NodeT >
NodeT * | stealNode (const Coord &xyz, const ValueType &value, bool active)
| Return a pointer to the node of type `NodeT` that contains voxel (x, y, z) and replace it with a tile of the specified value and state. If no such node exists, leave the tree unchanged and return `nullptr`.
LeafNodeType * | touchLeaf (const Coord &xyz)
| Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, create one that preserves the values and active states of all voxels.
template<typename NodeType >
NodeType * | probeNode (const Coord &xyz)
| Return a pointer to the node of type `NodeType` that contains voxel (x, y, z). If no such node exists, return `nullptr`.
template<typename NodeType >
const NodeType * | probeConstNode (const Coord &xyz) const
template<typename NodeType >
const NodeType * | probeNode (const Coord &xyz) const
LeafNodeType * | probeLeaf (const Coord &xyz)
| Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, return `nullptr`.
const LeafNodeType * | probeConstLeaf (const Coord &xyz) const
const LeafNodeType * | probeLeaf (const Coord &xyz) const
template<typename ArrayT >
void | getNodes (ArrayT &array)
| Adds all nodes of a certain type to a container with the following API:
template<typename ArrayT >
void | getNodes (ArrayT &array) const
template<typename ArrayT >
void | stealNodes (ArrayT &array)
| Steals all nodes of a certain type from the tree and adds them to a container with the following API:
template<typename ArrayT >
void | stealNodes (ArrayT &array, const ValueType &value, bool state)
bool | empty () const
| Return `true` if this tree contains no nodes other than the root node and no tiles other than background tiles.
void | clear ()
| Remove all tiles from this tree and all nodes other than the root node.
void | clearAllAccessors ()
| Clear all registered accessors.
void | attachAccessor (ValueAccessorBase< Tree, true > &) const
| Register an accessor for this tree. Registered accessors are automatically cleared whenever one of this tree's nodes is deleted.
void | attachAccessor (ValueAccessorBase< const Tree, true > &) const
void | attachAccessor (ValueAccessorBase< Tree, false > &) const
| Dummy implementations.
void | attachAccessor (ValueAccessorBase< const Tree, false > &) const
void | releaseAccessor (ValueAccessorBase< Tree, true > &) const
| Deregister an accessor so that it is no longer automatically cleared.
void | releaseAccessor (ValueAccessorBase< const Tree, true > &) const
void | releaseAccessor (ValueAccessorBase< Tree, false > &) const
| Dummy implementations.
void | releaseAccessor (ValueAccessorBase< const Tree, false > &) const
Metadata::Ptr | getBackgroundValue () const override
| Return this tree's background value wrapped as metadata.
const ValueType & | background () const
| Return this tree's background value.
void | getIndexRange (CoordBBox &bbox) const override
| Min and max are both inclusive.
void | merge (Tree &other, MergePolicy=MERGE_ACTIVE_STATES)
| Efficiently merge another tree into this tree using one of several schemes.
template<typename OtherRootNodeType >
void | topologyUnion (const Tree< OtherRootNodeType > &other, const bool preserveTiles=false)
| Union this tree's set of active values with the active values of the other tree, whose `ValueType` may be different.
template<typename OtherRootNodeType >
void | topologyIntersection (const Tree< OtherRootNodeType > &other)
| Intersects this tree's set of active values with the active values of the other tree, whose `ValueType` may be different.
template<typename OtherRootNodeType >
void | topologyDifference (const Tree< OtherRootNodeType > &other)
| Difference this tree's set of active values with the active values of the other tree, whose `ValueType` may be different. So a resulting voxel will be active only if the original voxel is active in this tree and inactive in the other tree.
template<typename CombineOp >
void | combine (Tree &other, CombineOp &op, bool prune=false)
template<typename CombineOp >
void | combine (Tree &other, const CombineOp &op, bool prune=false)
template<typename ExtendedCombineOp >
void | combineExtended (Tree &other, ExtendedCombineOp &op, bool prune=false)
template<typename ExtendedCombineOp >
void | combineExtended (Tree &other, const ExtendedCombineOp &op, bool prune=false)
template<typename CombineOp , typename OtherTreeType >
void | combine2 (const Tree &a, const OtherTreeType &b, CombineOp &op, bool prune=false)
template<typename CombineOp , typename OtherTreeType >
void | combine2 (const Tree &a, const OtherTreeType &b, const CombineOp &op, bool prune=false)
template<typename ExtendedCombineOp , typename OtherTreeType >
void | combine2Extended (const Tree &a, const OtherTreeType &b, ExtendedCombineOp &op, bool prune=false)
template<typename ExtendedCombineOp , typename OtherTreeType >
void | combine2Extended (const Tree &a, const OtherTreeType &b, const ExtendedCombineOp &, bool prune=false)
RootNodeType::ChildOnCIter | beginRootChildren () const
| Return an iterator over children of the root node.
RootNodeType::ChildOnCIter | cbeginRootChildren () const
RootNodeType::ChildOnIter | beginRootChildren ()
RootNodeType::ChildOffCIter | beginRootTiles () const
| Return an iterator over non-child entries of the root node's table.
RootNodeType::ChildOffCIter | cbeginRootTiles () const
RootNodeType::ChildOffIter | beginRootTiles ()
RootNodeType::ChildAllCIter | beginRootDense () const
| Return an iterator over all entries of the root node's table.
RootNodeType::ChildAllCIter | cbeginRootDense () const
RootNodeType::ChildAllIter | beginRootDense ()
NodeIter | beginNode ()
| Return an iterator over all nodes in this tree.
NodeCIter | beginNode () const
NodeCIter | cbeginNode () const
LeafIter | beginLeaf ()
| Return an iterator over all leaf nodes in this tree.
LeafCIter | beginLeaf () const
LeafCIter | cbeginLeaf () const
ValueAllIter | beginValueAll ()
| Return an iterator over all values (tile and voxel) across all nodes.
ValueAllCIter | beginValueAll () const
ValueAllCIter | cbeginValueAll () const
ValueOnIter | beginValueOn ()
| Return an iterator over active values (tile and voxel) across all nodes.
ValueOnCIter | beginValueOn () const
ValueOnCIter | cbeginValueOn () const
ValueOffIter | beginValueOff ()
| Return an iterator over inactive values (tile and voxel) across all nodes.
ValueOffCIter | beginValueOff () const
ValueOffCIter | cbeginValueOff () const
template<typename IterT >
IterT | begin ()
| Return an iterator of type `IterT` (for example, begin<ValueOnIter>() is equivalent to beginValueOn()).
template<typename CIterT >
CIterT | cbegin () const
| Return a const iterator of type CIterT (for example, cbegin<ValueOnCIter>() is equivalent to cbeginValueOn()).
template<typename IterT >
IterT | cbegin () const
template<typename AccessT >
const RootNodeType::ValueType & | getValue (const Coord &xyz, AccessT &accessor) const
template<typename TreeType >
bool | isType () const
| Return `true` if this tree is of the same type as the template parameter.

## Static Public Member Functions
static const Name & | treeType ()
| Return the name of this type of tree.
static void | getNodeLog2Dims (std::vector< Index > &dims)
| Traverse the type hierarchy of nodes, and return, in dims, a list of the Log2Dims of nodes in order from RootNode to LeafNode.

## Static Public Attributes
static const Index | DEPTH = RootNodeType::LEVEL + 1

## Protected Types
using | AccessorRegistry = tbb::concurrent_hash_map< ValueAccessorBase< Tree, true > *, bool >
using | ConstAccessorRegistry = tbb::concurrent_hash_map< ValueAccessorBase< const Tree, true > *, bool >

## Protected Member Functions
void | releaseAllAccessors ()
| Notify all registered accessors, by calling ValueAccessor::release(), that this tree is about to be deleted.

## Protected Attributes
RootNodeType | mRoot
AccessorRegistry | mAccessorRegistry
ConstAccessorRegistry | mConstAccessorRegistry

## Member Typedef Documentation

## ◆ AccessorRegistry

template<typename _RootNodeType >

using AccessorRegistry = tbb::concurrent_hash_map<ValueAccessorBase<Tree, true>*, bool>
| protected

## ◆ BuildType

template<typename _RootNodeType >

using BuildType = typename RootNodeType::BuildType

## ◆ ConstAccessorRegistry

template<typename _RootNodeType >

using ConstAccessorRegistry = tbb::concurrent_hash_map<ValueAccessorBase<const Tree, true>*, bool>
| protected

## ◆ ConstPtr

template<typename _RootNodeType >

using ConstPtr = SharedPtr<const Tree>

## ◆ LeafCIter

template<typename _RootNodeType >

using LeafCIter = LeafIteratorBase<const Tree, typename RootNodeType::ChildOnCIter>

## ◆ LeafIter

template<typename _RootNodeType >

using LeafIter = LeafIteratorBase<Tree, typename RootNodeType::ChildOnIter>

Iterator over all leaf nodes in this tree.

## ◆ LeafNodeType

template<typename _RootNodeType >

using LeafNodeType = typename RootNodeType::LeafNodeType

## ◆ NodeCIter

template<typename _RootNodeType >

using NodeCIter = NodeIteratorBase<const Tree, typename RootNodeType::ChildOnCIter>

## ◆ NodeIter

template<typename _RootNodeType >

using NodeIter = NodeIteratorBase<Tree, typename RootNodeType::ChildOnIter>

Iterator over all nodes in this tree.

## ◆ Ptr

template<typename _RootNodeType >

using Ptr = SharedPtr<Tree>

## ◆ RootNodeType

template<typename _RootNodeType >

using RootNodeType = _RootNodeType

## ◆ ValueAllCIter

template<typename _RootNodeType >

using ValueAllCIter = TreeValueIteratorBase<const Tree, typename RootNodeType::ValueAllCIter>

## ◆ ValueAllIter

template<typename _RootNodeType >

using ValueAllIter = TreeValueIteratorBase<Tree, typename RootNodeType::ValueAllIter>

## ◆ ValueOffCIter

template<typename _RootNodeType >

using ValueOffCIter = TreeValueIteratorBase<const Tree, typename RootNodeType::ValueOffCIter>

## ◆ ValueOffIter

template<typename _RootNodeType >

using ValueOffIter = TreeValueIteratorBase<Tree, typename RootNodeType::ValueOffIter>

## ◆ ValueOnCIter

template<typename _RootNodeType >

using ValueOnCIter = TreeValueIteratorBase<const Tree, typename RootNodeType::ValueOnCIter>

## ◆ ValueOnIter

template<typename _RootNodeType >

using ValueOnIter = TreeValueIteratorBase<Tree, typename RootNodeType::ValueOnIter>

## ◆ ValueType

template<typename _RootNodeType >

using ValueType = typename RootNodeType::ValueType

## Constructor & Destructor Documentation

## ◆ Tree() [1/6]

template<typename _RootNodeType >

Tree | ( |  | ) |
| inline

## ◆ Tree() [2/6]

template<typename _RootNodeType >

Tree | ( | const Tree< _RootNodeType > & | other | ) |
| inline

Deep copy constructor.

## ◆ Tree() [3/6]

template<typename _RootNodeType >
template<typename OtherRootType >

Tree | ( | const Tree< OtherRootType > & | other | ) |
| inlineexplicit

Value conversion deep copy constructor.

Deep copy a tree of the same configuration as this tree type but a different ValueType, casting the other tree's values to this tree's ValueType.

Exceptions

  TypeError | if the other tree's configuration doesn't match this tree's or if this tree's ValueType is not constructible from the other tree's ValueType.

## ◆ Tree() [4/6]

template<typename _RootNodeType >
template<typename OtherTreeType >

Tree | ( | const OtherTreeType & | other,
|  | const ValueType & | inactiveValue,
|  | const ValueType & | activeValue,
|  | TopologyCopy |
| ) |  |
| inline

Topology copy constructor from a tree of a different type.

Copy the structure, i.e., the active states of tiles and voxels, of another tree of a possibly different type, but don't copy any tile or voxel values. Instead, initialize tiles and voxels with the given active and inactive values.

Parameters

  other | a tree having (possibly) a different ValueType
  inactiveValue | background value for this tree, and the value to which all inactive tiles and voxels are initialized
  activeValue | value to which active tiles and voxels are initialized

Exceptions

  TypeError | if the other tree's configuration doesn't match this tree's.

## ◆ Tree() [5/6]

template<typename _RootNodeType >
template<typename OtherTreeType >

Tree | ( | const OtherTreeType & | other,
|  | const ValueType & | background,
|  | TopologyCopy |
| ) |  |
| inline

Topology copy constructor from a tree of a different type.

Note
  This topology copy constructor is generally faster than the one that takes both a foreground and a background value.

Copy the structure, i.e., the active states of tiles and voxels, of another tree of a possibly different type, but don't copy any tile or voxel values. Instead, initialize tiles and voxels with the given background value.

Parameters

  other | a tree having (possibly) a different ValueType
  background | the value to which tiles and voxels are initialized

Exceptions

  TypeError | if the other tree's configuration doesn't match this tree's.

## ◆ Tree() [6/6]

template<typename _RootNodeType >

Tree | ( | const ValueType & | background | ) |
| inline

Empty tree constructor.

## ◆ ~Tree()

template<typename _RootNodeType >

~Tree | ( |  | ) |
| inlineoverride

## Member Function Documentation

## ◆ activeLeafVoxelCount()

template<typename _RootNodeType >

Index64 activeLeafVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of active voxels stored in leaf nodes.

Implements TreeBase.

## ◆ activeTileCount()

template<typename _RootNodeType >

Index64 activeTileCount | ( |  | ) | const
| inlineoverridevirtual

Return the total number of active tiles.

Implements TreeBase.

## ◆ activeVoxelCount()

template<typename _RootNodeType >

Index64 activeVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the total number of active voxels.

Implements TreeBase.

## ◆ addLeaf()

template<typename _RootNodeType >

void addLeaf | ( | LeafNodeType * | leaf | ) |
| inline

Add the given leaf node to this tree, creating a new branch if necessary. If a leaf node with the same origin already exists, replace it.

Warning
  Ownership of the leaf is transferred to the tree so the client code should not attempt to delete the leaf pointer!

## ◆ addTile()

template<typename RootNodeType >

void addTile | ( | Index | level,
|  | const Coord & | xyz,
|  | const ValueType & | value,
|  | bool | active
| ) |  |
| inline

Add a tile containing voxel (x, y, z) at the specified tree level, creating a new branch if necessary. Delete any existing lower-level nodes that contain (x, y, z).

Note
  level must be less than this tree's depth.

## ◆ attachAccessor() [1/4]

template<typename _RootNodeType >

void attachAccessor | ( | ValueAccessorBase< const Tree< _RootNodeType >, false > & |  | ) | const
| inline

## ◆ attachAccessor() [2/4]

template<typename RootNodeType >

void attachAccessor | ( | ValueAccessorBase< const Tree< _RootNodeType >, true > & | accessor | ) | const
| inline

## ◆ attachAccessor() [3/4]

template<typename _RootNodeType >

void attachAccessor | ( | ValueAccessorBase< Tree< _RootNodeType >, false > & |  | ) | const
| inline

Dummy implementations.

## ◆ attachAccessor() [4/4]

template<typename RootNodeType >

void attachAccessor | ( | ValueAccessorBase< Tree< _RootNodeType >, true > & | accessor | ) | const
| inline

Register an accessor for this tree. Registered accessors are automatically cleared whenever one of this tree's nodes is deleted.

## ◆ background()

template<typename _RootNodeType >

const ValueType & background | ( |  | ) | const
| inline

Return this tree's background value.

Note
  Use tools::changeBackground to efficiently modify the background values. Else use tree.root().setBackground, which is serial and hence slower.

## ◆ begin()

template<typename RootNodeType >
template<typename IterT >

IterT begin | ( |  | ) |
| inline

Return an iterator of type `IterT` (for example, begin<ValueOnIter>() is equivalent to beginValueOn()).

## ◆ beginLeaf() [1/2]

template<typename _RootNodeType >

LeafIter beginLeaf | ( |  | ) |
| inline

Return an iterator over all leaf nodes in this tree.

## ◆ beginLeaf() [2/2]

template<typename _RootNodeType >

LeafCIter beginLeaf | ( |  | ) | const
| inline

## ◆ beginNode() [1/2]

template<typename _RootNodeType >

NodeIter beginNode | ( |  | ) |
| inline

Return an iterator over all nodes in this tree.

## ◆ beginNode() [2/2]

template<typename _RootNodeType >

NodeCIter beginNode | ( |  | ) | const
| inline

## ◆ beginRootChildren() [1/2]

template<typename _RootNodeType >

RootNodeType::ChildOnIter beginRootChildren | ( |  | ) |
| inline

## ◆ beginRootChildren() [2/2]

template<typename _RootNodeType >

RootNodeType::ChildOnCIter beginRootChildren | ( |  | ) | const
| inline

Return an iterator over children of the root node.

## ◆ beginRootDense() [1/2]

template<typename _RootNodeType >

RootNodeType::ChildAllIter beginRootDense | ( |  | ) |
| inline

## ◆ beginRootDense() [2/2]

template<typename _RootNodeType >

RootNodeType::ChildAllCIter beginRootDense | ( |  | ) | const
| inline

Return an iterator over all entries of the root node's table.

## ◆ beginRootTiles() [1/2]

template<typename _RootNodeType >

RootNodeType::ChildOffIter beginRootTiles | ( |  | ) |
| inline

## ◆ beginRootTiles() [2/2]

template<typename _RootNodeType >

RootNodeType::ChildOffCIter beginRootTiles | ( |  | ) | const
| inline

Return an iterator over non-child entries of the root node's table.

## ◆ beginValueAll() [1/2]

template<typename _RootNodeType >

ValueAllIter beginValueAll | ( |  | ) |
| inline

Return an iterator over all values (tile and voxel) across all nodes.

## ◆ beginValueAll() [2/2]

template<typename _RootNodeType >

ValueAllCIter beginValueAll | ( |  | ) | const
| inline

## ◆ beginValueOff() [1/2]

template<typename _RootNodeType >

ValueOffIter beginValueOff | ( |  | ) |
| inline

Return an iterator over inactive values (tile and voxel) across all nodes.

## ◆ beginValueOff() [2/2]

template<typename _RootNodeType >

ValueOffCIter beginValueOff | ( |  | ) | const
| inline

## ◆ beginValueOn() [1/2]

template<typename _RootNodeType >

ValueOnIter beginValueOn | ( |  | ) |
| inline

Return an iterator over active values (tile and voxel) across all nodes.

## ◆ beginValueOn() [2/2]

template<typename _RootNodeType >

ValueOnCIter beginValueOn | ( |  | ) | const
| inline

## ◆ cbegin() [1/2]

template<typename _RootNodeType >
template<typename CIterT >

CIterT cbegin | ( |  | ) | const

Return a const iterator of type CIterT (for example, cbegin<ValueOnCIter>() is equivalent to cbeginValueOn()).

## ◆ cbegin() [2/2]

template<typename _RootNodeType >
template<typename IterT >

IterT cbegin | ( |  | ) | const
| inline

## ◆ cbeginLeaf()

template<typename _RootNodeType >

LeafCIter cbeginLeaf | ( |  | ) | const
| inline

## ◆ cbeginNode()

template<typename _RootNodeType >

NodeCIter cbeginNode | ( |  | ) | const
| inline

## ◆ cbeginRootChildren()

template<typename _RootNodeType >

RootNodeType::ChildOnCIter cbeginRootChildren | ( |  | ) | const
| inline

## ◆ cbeginRootDense()

template<typename _RootNodeType >

RootNodeType::ChildAllCIter cbeginRootDense | ( |  | ) | const
| inline

## ◆ cbeginRootTiles()

template<typename _RootNodeType >

RootNodeType::ChildOffCIter cbeginRootTiles | ( |  | ) | const
| inline

## ◆ cbeginValueAll()

template<typename _RootNodeType >

ValueAllCIter cbeginValueAll | ( |  | ) | const
| inline

## ◆ cbeginValueOff()

template<typename _RootNodeType >

ValueOffCIter cbeginValueOff | ( |  | ) | const
| inline

## ◆ cbeginValueOn()

template<typename _RootNodeType >

ValueOnCIter cbeginValueOn | ( |  | ) | const
| inline

## ◆ clear()

template<typename RootNodeType >

void clear | ( |  | ) |
| inline

Remove all tiles from this tree and all nodes other than the root node.

## ◆ clearAllAccessors()

template<typename RootNodeType >

void clearAllAccessors | ( |  | ) |
| inline

Clear all registered accessors.

## ◆ clip()

template<typename RootNodeType >

void clip | ( | const CoordBBox & | bbox | ) |
| inline

Set all voxels that lie outside the given axis-aligned box to the background.

## ◆ clipUnallocatedNodes()

template<typename RootNodeType >

void clipUnallocatedNodes | ( |  | ) |
| inlineoverridevirtual

Replace with background tiles any nodes whose voxel buffers have not yet been allocated.

Typically, unallocated nodes are leaf nodes whose voxel buffers are not yet resident in memory because delayed loading is in effect.

See also
  readNonresidentBuffers, io::File::open

Implements TreeBase.

## ◆ combine() [1/2]

template<typename RootNodeType >
template<typename CombineOp >

void combine | ( | Tree< _RootNodeType > & | other,
|  | CombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

For a given function `f`, use sparse traversal to compute `f(this, other)` over all corresponding pairs of values (tile or voxel) of this tree and the other tree and store the result in this tree. This method is typically more space-efficient than the two-tree combine2(), since it moves rather than copies nodes from the other tree into this tree.

Note
  This operation always empties the other tree.

Parameters

  other | a tree of the same type as this tree
  op | a functor of the form `void op(const T& a, const T& b, T& result)`, where `T` is this tree's `ValueType`, that computes `result = f(a, b)`
  prune | if true, prune the resulting tree one branch at a time (this is usually more space-efficient than pruning the entire tree in one pass)

Example:
  Compute the per-voxel difference between two floating-point trees, `aTree` and `bTree`, and store the result in `aTree` (leaving `bTree` empty).
  {
  struct Local {
  static inline void diff(const float& a, const float& b, float& result) {
  result = a - b;
  }
  };
  aTree.combine(bTree, Local::diff);
  }

Example:
  Compute `f * a + (1 - f) * b` over all voxels of two floating-point trees, `aTree` and `bTree`, and store the result in `aTree` (leaving `bTree` empty).
  namespace {
  struct Blend {
  Blend(float f): frac(f) {}
  inline void operator()(const float& a, const float& b, float& result) const {
  result = frac * a + (1.0 - frac) * b;
  }
  float frac;
  };
  }
  {
  aTree.combine(bTree, Blend(0.25)); // 0.25 * a + 0.75 * b
  }

## ◆ combine() [2/2]

template<typename RootNodeType >
template<typename CombineOp >

void combine | ( | Tree< _RootNodeType > & | other,
|  | const CombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

## ◆ combine2() [1/2]

template<typename RootNodeType >
template<typename CombineOp , typename OtherTreeType >

void combine2 | ( | const Tree< _RootNodeType > & | a,
|  | const OtherTreeType & | b,
|  | CombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

For a given function `f`, use sparse traversal to compute `f(a, b)` over all corresponding pairs of values (tile or voxel) of trees A and B and store the result in this tree.

Parameters

  a,b | two trees with the same configuration (levels and node dimensions) as this tree but with the B tree possibly having a different value type
  op | a functor of the form `void op(const T1& a, const T2& b, T1& result)`, where `T1` is this tree's and the A tree's `ValueType` and `T2` is the B tree's `ValueType`, that computes `result = f(a, b)`
  prune | if true, prune the resulting tree one branch at a time (this is usually more space-efficient than pruning the entire tree in one pass)

Exceptions

  TypeError | if the B tree's configuration doesn't match this tree's or if this tree's ValueType is not constructible from the B tree's ValueType.

Example:
  Compute the per-voxel difference between two floating-point trees, `aTree` and `bTree`, and store the result in a third tree.
  {
  struct Local {
  static inline void diff(const float& a, const float& b, float& result) {
  result = a - b;
  }
  };
  FloatTree resultTree;
  resultTree.combine2(aTree, bTree, Local::diff);
  }
  openvdb::v11_0::tree::Tree
  Definition Tree.h:178
  openvdb::v11_0::tree::Tree::combine2
  void combine2(const Tree &a, const OtherTreeType &b, CombineOp &op, bool prune=false)
  Definition Tree.h:1776

## ◆ combine2() [2/2]

template<typename RootNodeType >
template<typename CombineOp , typename OtherTreeType >

void combine2 | ( | const Tree< _RootNodeType > & | a,
|  | const OtherTreeType & | b,
|  | const CombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

## ◆ combine2Extended() [1/2]

template<typename RootNodeType >
template<typename ExtendedCombineOp , typename OtherTreeType >

void combine2Extended | ( | const Tree< _RootNodeType > & | a,
|  | const OtherTreeType & | b,
|  | const ExtendedCombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

## ◆ combine2Extended() [2/2]

template<typename RootNodeType >
template<typename ExtendedCombineOp , typename OtherTreeType >

void combine2Extended | ( | const Tree< _RootNodeType > & | a,
|  | const OtherTreeType & | b,
|  | ExtendedCombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

Like combine2(), but with

Parameters

  a,b | two trees with the same configuration (levels and node dimensions) as this tree but with the B tree possibly having a different value type
  op | a functor of the form `void op(CombineArgs<T1, T2>& args)`, where `T1` is this tree's and the A tree's `ValueType` and `T2` is the B tree's `ValueType`, that computes `args.setResult(f(args.a(), args.b()))` and, optionally, `args.setResultIsActive(g(args.aIsActive(), args.bIsActive()))` for some functions `f` and `g`
  prune | if true, prune the resulting tree one branch at a time (this is usually more space-efficient than pruning the entire tree in one pass) This variant passes not only the a and b values but also the active states of the a and b values to the functor, which may then return, by calling `args.setResultIsActive()`, a computed active state for the result value. By default, the result is active if either the a or the b value is active.

Exceptions

  TypeError | if the B tree's configuration doesn't match this tree's or if this tree's ValueType is not constructible from the B tree's ValueType.

See also
  openvdb/Types.h for the definition of the CombineArgs struct.

Example:
  Compute the per-voxel maximum values of two single-precision floating-point trees, `aTree` and `bTree`, and store the result in a third tree. Set the active state of each output value to that of the larger of the two input values.
  {
  struct Local {
  static inline void max(CombineArgs<float>& args) {
  if (args.b() > args.a()) {
  // Transfer the B value and its active state.
  args.setResult(args.b());
  args.setResultIsActive(args.bIsActive());
  } else {
  // Preserve the A value and its active state.
  args.setResult(args.a());
  args.setResultIsActive(args.aIsActive());
  }
  }
  };
  FloatTree aTree = ...;
  FloatTree bTree = ...;
  FloatTree resultTree;
  resultTree.combine2Extended(aTree, bTree, Local::max);
  }
  openvdb::v11_0::CombineArgs
  This struct collects both input and output arguments to "grid combiner" functors used with the tree::...
  Definition Types.h:569
  openvdb::v11_0::CombineArgs::bIsActive
  bool bIsActive() const
  Definition Types.h:630
  openvdb::v11_0::CombineArgs::setResultIsActive
  CombineArgs & setResultIsActive(bool b)
  Set the active state of the output value.
  Definition Types.h:639
  openvdb::v11_0::CombineArgs::aIsActive
  bool aIsActive() const
  Definition Types.h:628
  openvdb::v11_0::CombineArgs::b
  const BValueType & b() const
  Get the B input value.
  Definition Types.h:610
  openvdb::v11_0::CombineArgs::a
  const AValueType & a() const
  Get the A input value.
  Definition Types.h:608
  openvdb::v11_0::CombineArgs::setResult
  CombineArgs & setResult(const AValueType &val)
  Set the output value.
  Definition Types.h:618
  openvdb::v11_0::FloatTree
  tree::Tree4< float, 5, 4, 3 >::Type FloatTree
  Definition openvdb.h:55

Example:
  Compute the per-voxel maximum values of a double-precision and a single-precision floating-point tree, `aTree` and `bTree`, and store the result in a third, double-precision tree. Set the active state of each output value to that of the larger of the two input values.
  {
  struct Local {
  static inline void max(CombineArgs<double, float>& args) {
  if (args.b() > args.a()) {
  // Transfer the B value and its active state.
  args.setResult(args.b());
  args.setResultIsActive(args.bIsActive());
  } else {
  // Preserve the A value and its active state.
  args.setResult(args.a());
  args.setResultIsActive(args.aIsActive());
  }
  }
  };
  DoubleTree aTree = ...;
  FloatTree bTree = ...;
  DoubleTree resultTree;
  resultTree.combine2Extended(aTree, bTree, Local::max);
  }
  openvdb::v11_0::DoubleTree
  tree::Tree4< double, 5, 4, 3 >::Type DoubleTree
  Definition openvdb.h:54

## ◆ combineExtended() [1/2]

template<typename RootNodeType >
template<typename ExtendedCombineOp >

void combineExtended | ( | Tree< _RootNodeType > & | other,
|  | const ExtendedCombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

## ◆ combineExtended() [2/2]

template<typename RootNodeType >
template<typename ExtendedCombineOp >

void combineExtended | ( | Tree< _RootNodeType > & | other,
|  | ExtendedCombineOp & | op,
|  | bool | prune = `false`
| ) |  |
| inline

Like combine(), but with

Parameters

  other | a tree of the same type as this tree
  op | a functor of the form `void op(CombineArgs<ValueType>& args)` that computes `args.setResult(f(args.a(), args.b()))` and, optionally, `args.setResultIsActive(g(args.aIsActive(), args.bIsActive()))` for some functions `f` and `g`
  prune | if true, prune the resulting tree one branch at a time (this is usually more space-efficient than pruning the entire tree in one pass)

This variant passes not only the a and b values but also the active states of the a and b values to the functor, which may then return, by calling `args.setResultIsActive()`, a computed active state for the result value. By default, the result is active if either the a or the b value is active.

See also
  openvdb/Types.h for the definition of the CombineArgs struct.

Example:
  Replace voxel values in floating-point `aTree` with corresponding values from floating-point `bTree` (leaving `bTree` empty) wherever the `bTree` values are larger. Also, preserve the active states of any transferred values.
  {
  struct Local {
  static inline void max(CombineArgs<float>& args) {
  if (args.b() > args.a()) {
  // Transfer the B value and its active state.
  args.setResult(args.b());
  args.setResultIsActive(args.bIsActive());
  } else {
  // Preserve the A value and its active state.
  args.setResult(args.a());
  args.setResultIsActive(args.aIsActive());
  }
  }
  };
  aTree.combineExtended(bTree, Local::max);
  }

## ◆ copy()

template<typename _RootNodeType >

TreeBase::Ptr copy | ( |  | ) | const
| inlineoverridevirtual

Return a pointer to a deep copy of this tree.

Implements TreeBase.

## ◆ denseFill()

template<typename RootNodeType >

void denseFill | ( | const CoordBBox & | bbox,
|  | const ValueType & | value,
|  | bool | active = `true`
| ) |  |
| inline

Set all voxels within a given axis-aligned box to a constant value and ensure that those voxels are all represented at the leaf level.

Parameters

  bbox | inclusive coordinates of opposite corners of an axis-aligned box.
  value | the value to which to set voxels within the box.
  active | if true, mark voxels within the box as active, otherwise mark them as inactive.

See also
  voxelizeActiveTiles()

## ◆ empty()

template<typename _RootNodeType >

bool empty | ( |  | ) | const
| inline

Return `true` if this tree contains no nodes other than the root node and no tiles other than background tiles.

## ◆ evalActiveVoxelBoundingBox()

template<typename RootNodeType >

bool evalActiveVoxelBoundingBox | ( | CoordBBox & | bbox | ) | const
| inlineoverridevirtual

Return in bbox the axis-aligned bounding box of all active voxels and tiles.

This method produces a more accurate, i.e. tighter, bounding box than evalLeafBoundingBox which is approximate but faster.

Returns
  `false` if the bounding box is empty (in which case the bbox is set to its default value).

Implements TreeBase.

## ◆ evalActiveVoxelDim()

template<typename RootNodeType >

bool evalActiveVoxelDim | ( | Coord & | dim | ) | const
| inlineoverridevirtual

Return in dim the dimensions of the axis-aligned bounding box of all active voxels. This is a tighter bounding box than the leaf node bounding box.

Returns
  `false` if the bounding box is empty.

Implements TreeBase.

## ◆ evalLeafBoundingBox()

template<typename RootNodeType >

bool evalLeafBoundingBox | ( | CoordBBox & | bbox | ) | const
| inlineoverridevirtual

Return in bbox the axis-aligned bounding box of all active tiles and leaf nodes with active values.

This is faster than calling evalActiveVoxelBoundingBox, which visits the individual active voxels, and hence evalLeafBoundingBox produces a less tight, i.e. approximate, bbox.

Returns
  `false` if the bounding box is empty (in which case the bbox is set to its default value).

Implements TreeBase.

## ◆ evalLeafDim()

template<typename RootNodeType >

bool evalLeafDim | ( | Coord & | dim | ) | const
| inlineoverridevirtual

Return in dim the dimensions of the axis-aligned bounding box of all leaf nodes.

Returns
  `false` if the bounding box is empty.

Implements TreeBase.

## ◆ evalMinMax()

template<typename RootNodeType >

void evalMinMax | ( | ValueType & | min,
|  | ValueType & | max
| ) |  | const
| inline

Return the minimum and maximum active values in this tree.

Deprecated:
  "Switch to tools::minMax. Use threaded = false for serial execution"

## ◆ fill()

template<typename _RootNodeType >

void fill | ( | const CoordBBox & | bbox,
|  | const ValueType & | value,
|  | bool | active = `true`
| ) |  |
| inline

## ◆ getBackgroundValue()

template<typename RootNodeType >

Metadata::Ptr getBackgroundValue | ( |  | ) | const
| overridevirtual

Return this tree's background value wrapped as metadata.

Note
  Query the metadata object for the value's type.

Reimplemented from TreeBase.

## ◆ getIndexRange()

template<typename _RootNodeType >

void getIndexRange | ( | CoordBBox & | bbox | ) | const
| inlineoverridevirtual

Min and max are both inclusive.

Implements TreeBase.

## ◆ getNodeLog2Dims()

template<typename RootNodeType >

void getNodeLog2Dims | ( | std::vector< Index > & | dims | ) |
| inlinestatic

Traverse the type hierarchy of nodes, and return, in dims, a list of the Log2Dims of nodes in order from RootNode to LeafNode.

Note
  Because RootNodes are resizable, the RootNode Log2Dim is 0 for all trees.

## ◆ getNodes() [1/2]

template<typename RootNodeType >
template<typename ArrayT >

void getNodes | ( | ArrayT & | array | ) |
| inline

Adds all nodes of a certain type to a container with the following API:

struct ArrayT {
using value_type = ...; // the type of node to be added to the array
void push_back(value_type nodePtr); // add a node to the array
};

An example of a wrapper around a c-style array is:

struct MyArray {
using value_type = LeafType*;
value_type* ptr;
MyArray(value_type* array) : ptr(array) {}
void push_back(value_type leaf) { *ptr++ = leaf; }
};

An example that constructs a list of pointer to all leaf nodes is:

std::vector<const LeafNodeType*> array;//most std contains have the required API
array.reserve(tree.leafCount());//this is a fast preallocation.
tree.getNodes(array);

## ◆ getNodes() [2/2]

template<typename RootNodeType >
template<typename ArrayT >

void getNodes | ( | ArrayT & | array | ) | const
| inline

## ◆ getValue() [1/3]

template<typename RootNodeType >

const RootNodeType::ValueType & getValue | ( | const Coord & | xyz | ) | const
| inline

Return the value of the voxel at the given coordinates.

## ◆ getValue() [2/3]

template<typename _RootNodeType >
template<typename AccessT >

const ValueType & getValue | ( | const Coord & | xyz,
|  | AccessT & |
| ) |  | const

Return the value of the voxel at the given coordinates and update the given accessor's node cache.

## ◆ getValue() [3/3]

template<typename _RootNodeType >
template<typename AccessT >

const RootNodeType::ValueType & getValue | ( | const Coord & | xyz,
|  | AccessT & | accessor
| ) |  | const
| inline

## ◆ getValueDepth()

template<typename RootNodeType >

int getValueDepth | ( | const Coord & | xyz | ) | const
| inline

Return the tree depth (0 = root) at which the value of voxel (x, y, z) resides.

If (x, y, z) isn't explicitly represented in the tree (i.e., it is implicitly a background voxel), return -1.

## ◆ hasActiveTiles()

template<typename _RootNodeType >

bool hasActiveTiles | ( |  | ) | const
| inline

Return `true` if this tree has any active tiles.

## ◆ hasSameTopology()

template<typename RootNodeType >
template<typename OtherRootNodeType >

bool hasSameTopology | ( | const Tree< OtherRootNodeType > & | other | ) | const
| inline

Return `true` if the given tree has the same node and active value topology as this tree, whether or not it has the same `ValueType`.

## ◆ inactiveLeafVoxelCount()

template<typename _RootNodeType >

Index64 inactiveLeafVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of inactive voxels stored in leaf nodes.

Implements TreeBase.

## ◆ inactiveVoxelCount()

template<typename _RootNodeType >

Index64 inactiveVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of inactive voxels within the bounding box of all active voxels.

Implements TreeBase.

## ◆ isType()

template<typename TreeType >

bool isType | ( |  | ) | const
| inlineinherited

Return `true` if this tree is of the same type as the template parameter.

## ◆ isValueOff()

template<typename _RootNodeType >

bool isValueOff | ( | const Coord & | xyz | ) | const
| inline

Return `true` if the value at the given coordinates is inactive.

## ◆ isValueOn()

template<typename _RootNodeType >

bool isValueOn | ( | const Coord & | xyz | ) | const
| inline

Return `true` if the value at the given coordinates is active.

## ◆ leafCount()

template<typename _RootNodeType >

Index32 leafCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of leaf nodes.

Implements TreeBase.

## ◆ memUsage()

template<typename _RootNodeType >

Index64 memUsage | ( |  | ) | const
| inlineoverridevirtual

Return the total amount of memory in bytes occupied by this tree.

Reimplemented from TreeBase.

## ◆ merge()

template<typename RootNodeType >

void merge | ( | Tree< _RootNodeType > & | other,
|  | MergePolicy | policy = `MERGE_ACTIVE_STATES`
| ) |  |
| inline

Efficiently merge another tree into this tree using one of several schemes.

This operation is primarily intended to combine trees that are mostly non-overlapping (for example, intermediate trees from computations that are parallelized across disjoint regions of space).

Note
  This operation is not guaranteed to produce an optimally sparse tree. Follow merge() with prune() for optimal sparseness.

Warning
  This operation always empties the other tree.

## ◆ modifyValue()

template<typename RootNodeType >
template<typename ModifyOp >

void modifyValue | ( | const Coord & | xyz,
|  | const ModifyOp & | op
| ) |  |
| inline

Apply a functor to the value of the voxel at the given coordinates and mark the voxel as active.

Provided that the functor can be inlined, this is typically significantly faster than calling getValue() followed by setValueOn().

Parameters

  xyz | the coordinates of a voxel whose value is to be modified
  op | a functor of the form `void op(ValueType&) const` that modifies its argument in place

Example:
  Coord xyz(1, 0, -2);
  // Multiply the value of a voxel by a constant and mark the voxel as active.
  floatTree.modifyValue(xyz, [](float& f) { f *= 0.25; }); // C++11
  // Set the value of a voxel to the maximum of its current value and 0.25,
  // and mark the voxel as active.
  floatTree.modifyValue(xyz, [](float& f) { f = std::max(f, 0.25f); }); // C++11
  openvdb::v11_0::math::Coord
  Signed (x, y, z) 32-bit integer coordinates.
  Definition Coord.h:25

Note
  The functor is not guaranteed to be called only once.

See also
  tools::foreach()

## ◆ modifyValueAndActiveState()

template<typename RootNodeType >
template<typename ModifyOp >

void modifyValueAndActiveState | ( | const Coord & | xyz,
|  | const ModifyOp & | op
| ) |  |
| inline

Apply a functor to the voxel at the given coordinates.

Provided that the functor can be inlined, this is typically significantly faster than calling getValue() followed by setValue().

Parameters

  xyz | the coordinates of a voxel to be modified
  op | a functor of the form `void op(ValueType&, bool&) const` that modifies its arguments, a voxel's value and active state, in place

Example:
  Coord xyz(1, 0, -2);
  // Multiply the value of a voxel by a constant and mark the voxel as inactive.
  floatTree.modifyValueAndActiveState(xyz,
  [](float& f, bool& b) { f *= 0.25; b = false; }); // C++11
  // Set the value of a voxel to the maximum of its current value and 0.25,
  // but don't change the voxel's active state.
  floatTree.modifyValueAndActiveState(xyz,
  [](float& f, bool&) { f = std::max(f, 0.25f); }); // C++11

Note
  The functor is not guaranteed to be called only once.

See also
  tools::foreach()

## ◆ nodeCount()

template<typename _RootNodeType >

std::vector< Index32 > nodeCount | ( |  | ) | const
| inlineoverridevirtual

Return a vector with node counts. The number of nodes of type NodeType is given as element NodeType::LEVEL in the return vector. Thus, the size of this vector corresponds to the height (or depth) of this tree.

Implements TreeBase.

## ◆ nonLeafCount()

template<typename _RootNodeType >

Index32 nonLeafCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of non-leaf nodes.

Implements TreeBase.

## ◆ operator!=()

template<typename _RootNodeType >

bool operator!= | ( | const Tree< _RootNodeType > & |  | ) | const
| inline

## ◆ operator=()

template<typename _RootNodeType >

Tree & operator= | ( | const Tree< _RootNodeType > & |  | ) |
| delete

## ◆ operator==()

template<typename _RootNodeType >

bool operator== | ( | const Tree< _RootNodeType > & |  | ) | const
| inline

## ◆ print()

template<typename RootNodeType >

void print | ( | std::ostream & | os = `std::cout`,
|  | int | verboseLevel = `1`
| ) |  | const
| inlineoverridevirtual

Print statistics, memory usage and other information about this tree.

Parameters

  os | a stream to which to write textual information
  verboseLevel | 1: print tree configuration only; 2: include node and voxel statistics; 3: include memory usage; 4: include minimum and maximum voxel values

Warning
  verboseLevel 4 forces loading of any unallocated nodes.

Reimplemented from TreeBase.

## ◆ probeConstLeaf()

template<typename RootNodeType >

const RootNodeType::LeafNodeType * probeConstLeaf | ( | const Coord & | xyz | ) | const
| inline

## ◆ probeConstNode()

template<typename RootNodeType >
template<typename NodeType >

const NodeType * probeConstNode | ( | const Coord & | xyz | ) | const
| inline

## ◆ probeLeaf() [1/2]

template<typename RootNodeType >

RootNodeType::LeafNodeType * probeLeaf | ( | const Coord & | xyz | ) |
| inline

Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, return `nullptr`.

## ◆ probeLeaf() [2/2]

template<typename _RootNodeType >

const LeafNodeType * probeLeaf | ( | const Coord & | xyz | ) | const
| inline

## ◆ probeNode() [1/2]

template<typename RootNodeType >
template<typename NodeType >

NodeType * probeNode | ( | const Coord & | xyz | ) |
| inline

Return a pointer to the node of type `NodeType` that contains voxel (x, y, z). If no such node exists, return `nullptr`.

## ◆ probeNode() [2/2]

template<typename RootNodeType >
template<typename NodeType >

const NodeType * probeNode | ( | const Coord & | xyz | ) | const
| inline

## ◆ probeValue()

template<typename RootNodeType >

bool probeValue | ( | const Coord & | xyz,
|  | ValueType & | value
| ) |  | const
| inline

Get the value of the voxel at the given coordinates.

Returns
  `true` if the value is active.

## ◆ prune()

template<typename _RootNodeType >

void prune | ( | const ValueType & | tolerance = `zeroVal<ValueType>()` | ) |
| inline

Reduce the memory footprint of this tree by replacing with tiles any nodes whose values are all the same (optionally to within a tolerance) and have the same active state.

Warning
  Will soon be deprecated!

## ◆ readBuffers() [1/2]

template<typename RootNodeType >

void readBuffers | ( | std::istream & | is,
|  | bool | saveFloatAsHalf = `false`
| ) |  |
| inlineoverridevirtual

Read all data buffers for this tree.

Implements TreeBase.

## ◆ readBuffers() [2/2]

template<typename RootNodeType >

void readBuffers | ( | std::istream & | is,
|  | const CoordBBox & | bbox,
|  | bool | saveFloatAsHalf = `false`
| ) |  |
| inlineoverridevirtual

Read all of this tree's data buffers that intersect the given bounding box.

Implements TreeBase.

## ◆ readNonresidentBuffers()

template<typename RootNodeType >

void readNonresidentBuffers | ( |  | ) | const
| inlineoverridevirtual

Read all of this tree's data buffers that are not yet resident in memory (because delayed loading is in effect).

If this tree was read from a memory-mapped file, this operation disconnects the tree from the file.

See also
  clipUnallocatedNodes, io::File::open, io::MappedFile

Implements TreeBase.

## ◆ readTopology()

template<typename RootNodeType >

void readTopology | ( | std::istream & | is,
|  | bool | saveFloatAsHalf = `false`
| ) |  |
| overridevirtual

Read the tree topology from a stream.

This will read the tree structure and tile values, but not voxel data.

Reimplemented from TreeBase.

## ◆ releaseAccessor() [1/4]

template<typename _RootNodeType >

void releaseAccessor | ( | ValueAccessorBase< const Tree< _RootNodeType >, false > & |  | ) | const
| inline

## ◆ releaseAccessor() [2/4]

template<typename RootNodeType >

void releaseAccessor | ( | ValueAccessorBase< const Tree< _RootNodeType >, true > & | accessor | ) | const
| inline

## ◆ releaseAccessor() [3/4]

template<typename _RootNodeType >

void releaseAccessor | ( | ValueAccessorBase< Tree< _RootNodeType >, false > & |  | ) | const
| inline

Dummy implementations.

## ◆ releaseAccessor() [4/4]

template<typename RootNodeType >

void releaseAccessor | ( | ValueAccessorBase< Tree< _RootNodeType >, true > & | accessor | ) | const
| inline

Deregister an accessor so that it is no longer automatically cleared.

## ◆ releaseAllAccessors()

template<typename RootNodeType >

void releaseAllAccessors | ( |  | ) |
| inlineprotected

Notify all registered accessors, by calling ValueAccessor::release(), that this tree is about to be deleted.

## ◆ root() [1/2]

template<typename _RootNodeType >

RootNodeType & root | ( |  | ) |
| inline

Return this tree's root node.

## ◆ root() [2/2]

template<typename _RootNodeType >

const RootNodeType & root | ( |  | ) | const
| inline

## ◆ setActiveState()

template<typename RootNodeType >

void setActiveState | ( | const Coord & | xyz,
|  | bool | on
| ) |  |
| inline

Set the active state of the voxel at the given coordinates but don't change its value.

## ◆ setValue() [1/2]

template<typename RootNodeType >

void setValue | ( | const Coord & | xyz,
|  | const ValueType & | value
| ) |  |
| inline

Set the value of the voxel at the given coordinates and mark the voxel as active.

## ◆ setValue() [2/2]

template<typename RootNodeType >
template<typename AccessT >

void setValue | ( | const Coord & | xyz,
|  | const ValueType & | value,
|  | AccessT & | accessor
| ) |  |
| inline

Set the value of the voxel at the given coordinates, mark the voxel as active, and update the given accessor's node cache.

## ◆ setValueOff() [1/2]

template<typename RootNodeType >

void setValueOff | ( | const Coord & | xyz | ) |
| inline

Mark the voxel at the given coordinates as inactive but don't change its value.

## ◆ setValueOff() [2/2]

template<typename RootNodeType >

void setValueOff | ( | const Coord & | xyz,
|  | const ValueType & | value
| ) |  |
| inline

Set the value of the voxel at the given coordinates and mark the voxel as inactive.

## ◆ setValueOn() [1/2]

template<typename RootNodeType >

void setValueOn | ( | const Coord & | xyz | ) |
| inline

Mark the voxel at the given coordinates as active but don't change its value.

## ◆ setValueOn() [2/2]

template<typename RootNodeType >

void setValueOn | ( | const Coord & | xyz,
|  | const ValueType & | value
| ) |  |
| inline

Set the value of the voxel at the given coordinates and mark the voxel as active.

## ◆ setValueOnly()

template<typename RootNodeType >

void setValueOnly | ( | const Coord & | xyz,
|  | const ValueType & | value
| ) |  |
| inline

Set the value of the voxel at the given coordinates but don't change its active state.

## ◆ sparseFill()

template<typename RootNodeType >

void sparseFill | ( | const CoordBBox & | bbox,
|  | const ValueType & | value,
|  | bool | active = `true`
| ) |  |
| inline

Set all voxels within a given axis-aligned box to a constant value.

Parameters

  bbox | inclusive coordinates of opposite corners of an axis-aligned box
  value | the value to which to set voxels within the box
  active | if true, mark voxels within the box as active, otherwise mark them as inactive

Note
  This operation generates a sparse, but not always optimally sparse, representation of the filled box. Follow fill operations with a prune() operation for optimal sparseness.

## ◆ stealNode()

template<typename RootNodeType >
template<typename NodeT >

NodeT * stealNode | ( | const Coord & | xyz,
|  | const ValueType & | value,
|  | bool | active
| ) |  |
| inline

Return a pointer to the node of type `NodeT` that contains voxel (x, y, z) and replace it with a tile of the specified value and state. If no such node exists, leave the tree unchanged and return `nullptr`.

Note
  The caller takes ownership of the node and is responsible for deleting it.

## ◆ stealNodes() [1/2]

template<typename _RootNodeType >
template<typename ArrayT >

void stealNodes | ( | ArrayT & | array | ) |
| inline

Steals all nodes of a certain type from the tree and adds them to a container with the following API:

struct ArrayT {
using value_type = ...; // the type of node to be added to the array
void push_back(value_type nodePtr); // add a node to the array
};

An example of a wrapper around a c-style array is:

struct MyArray {
using value_type = LeafType*;
value_type* ptr;
MyArray(value_type* array) : ptr(array) {}
void push_back(value_type leaf) { *ptr++ = leaf; }
};

An example that constructs a list of pointer to all leaf nodes is:

std::vector<const LeafNodeType*> array;//most std contains have the required API
array.reserve(tree.leafCount());//this is a fast preallocation.
tree.stealNodes(array);

## ◆ stealNodes() [2/2]

template<typename _RootNodeType >
template<typename ArrayT >

void stealNodes | ( | ArrayT & | array,
|  | const ValueType & | value,
|  | bool | state
| ) |  |
| inline

## ◆ topologyDifference()

template<typename RootNodeType >
template<typename OtherRootNodeType >

void topologyDifference | ( | const Tree< OtherRootNodeType > & | other | ) |
| inline

Difference this tree's set of active values with the active values of the other tree, whose `ValueType` may be different. So a resulting voxel will be active only if the original voxel is active in this tree and inactive in the other tree.

Note
  This operation can delete branches in this grid if they overlap with active tiles in the other grid. Likewise active voxels can be turned into inactive voxels resulting in leaf nodes with no active values. Thus, it is recommended to subsequently call tools::pruneInactive.

## ◆ topologyIntersection()

template<typename RootNodeType >
template<typename OtherRootNodeType >

void topologyIntersection | ( | const Tree< OtherRootNodeType > & | other | ) |
| inline

Intersects this tree's set of active values with the active values of the other tree, whose `ValueType` may be different.

The resulting state of a value is active only if the corresponding value was already active AND if it is active in the other tree. Also, a resulting value maps to a voxel if the corresponding value already mapped to an active voxel in either of the two grids and it maps to an active tile or voxel in the other grid.

Note
  This operation can delete branches in this grid if they overlap with inactive tiles in the other grid. Likewise active voxels can be turned into inactive voxels resulting in leaf nodes with no active values. Thus, it is recommended to subsequently call tools::pruneInactive.

## ◆ topologyUnion()

template<typename RootNodeType >
template<typename OtherRootNodeType >

void topologyUnion | ( | const Tree< OtherRootNodeType > & | other,
|  | const bool | preserveTiles = `false`
| ) |  |
| inline

Union this tree's set of active values with the active values of the other tree, whose `ValueType` may be different.

The resulting state of a value is active if the corresponding value was already active OR if it is active in the other tree. Also, a resulting value maps to a voxel if the corresponding value already mapped to a voxel OR if it is a voxel in the other tree. Thus, a resulting value can only map to a tile if the corresponding value already mapped to a tile AND if it is a tile value in other tree.

Note
  This operation modifies only active states, not values. Specifically, active tiles and voxels in this tree are not changed, and tiles or voxels that were inactive in this tree but active in the other tree are marked as active in this tree but left with their original values.
  If preserveTiles is true, any active tile in this topology will not be densified by overlapping child topology.

## ◆ touchLeaf()

template<typename RootNodeType >

RootNodeType::LeafNodeType * touchLeaf | ( | const Coord & | xyz | ) |
| inline

Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, create one that preserves the values and active states of all voxels.

Use this method to preallocate a static tree topology over which to safely perform multithreaded processing.

## ◆ treeDepth()

template<typename _RootNodeType >

Index treeDepth | ( |  | ) | const
| inlineoverridevirtual

Return the depth of this tree.

A tree with only a root node and leaf nodes has depth 2, for example.

Implements TreeBase.

## ◆ treeType()

template<typename RootNodeType >

const Name & treeType | ( |  | ) |
| inlinestatic

Return the name of this type of tree.

## ◆ type()

template<typename _RootNodeType >

const Name & type | ( |  | ) | const
| inlineoverridevirtual

Return the name of this type of tree.

Implements TreeBase.

## ◆ unallocatedLeafCount()

template<typename RootNodeType >

Index32 unallocatedLeafCount | ( |  | ) | const
| inlineoverridevirtual

Return the total number of unallocated leaf nodes residing in this tree.

Implements TreeBase.

## ◆ valueType()

template<typename _RootNodeType >

Name valueType | ( |  | ) | const
| inlineoverridevirtual

Return the name of the type of a voxel's value (e.g., "float" or "vec3d")

Implements TreeBase.

## ◆ voxelizeActiveTiles()

template<typename RootNodeType >

void voxelizeActiveTiles | ( | bool | threaded = `true` | ) |
| inline

Densify active tiles, i.e., replace them with leaf-level active voxels.

Parameters

  threaded | if true, this operation is multi-threaded (over the internal nodes).

Warning
  This method can explode the tree's memory footprint, especially if it contains active tiles at the upper levels (in particular the root level)!

See also
  denseFill()

## ◆ writeBuffers()

template<typename RootNodeType >

void writeBuffers | ( | std::ostream & | os,
|  | bool | saveFloatAsHalf = `false`
| ) |  | const
| inlineoverridevirtual

Write out all data buffers for this tree.

Implements TreeBase.

## ◆ writeTopology()

template<typename RootNodeType >

void writeTopology | ( | std::ostream & | os,
|  | bool | saveFloatAsHalf = `false`
| ) |  | const
| overridevirtual

Write the tree topology to a stream.

This will write the tree structure and tile values, but not voxel data.

Reimplemented from TreeBase.

## Member Data Documentation

## ◆ DEPTH

template<typename _RootNodeType >

const Index DEPTH = RootNodeType::LEVEL + 1
| static

## ◆ mAccessorRegistry

template<typename _RootNodeType >

AccessorRegistry mAccessorRegistry
| mutableprotected

## ◆ mConstAccessorRegistry

template<typename _RootNodeType >

ConstAccessorRegistry mConstAccessorRegistry
| mutableprotected

## ◆ mRoot

template<typename _RootNodeType >

RootNodeType mRoot
| protected