OpenVDB: Tree< _RootNodeType > Class Template Reference

OpenVDB 6.0.0

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

`#include <Tree.h>`

Inherits TreeBase.

## 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 | 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 >
using | NodeIter = NodeIteratorBase< Tree, typename RootNodeType::ChildOnIter >
| Iterator over all nodes in this tree. More...
using | NodeCIter = NodeIteratorBase< const Tree, typename RootNodeType::ChildOnCIter >
| Iterator over all nodes in this tree. More...
using | LeafIter = LeafIteratorBase< Tree, typename RootNodeType::ChildOnIter >
| Iterator over all leaf nodes in this tree. More...
using | LeafCIter = LeafIteratorBase< const Tree, typename RootNodeType::ChildOnCIter >
| Iterator over all leaf nodes in this tree. More...

## Public Member Functions
| Tree ()
Tree & | operator= (const Tree &)=delete
| Tree (const Tree &other)
| Deep copy constructor. More...
template<typename OtherRootType >
| Tree (const Tree< OtherRootType > &other)
| Value conversion deep copy constructor. More...
template<typename OtherTreeType >
| Tree (const OtherTreeType &other, const ValueType &inactiveValue, const ValueType &activeValue, TopologyCopy)
| Topology copy constructor from a tree of a different type. More...
template<typename OtherTreeType >
| Tree (const OtherTreeType &other, const ValueType &background, TopologyCopy)
| Topology copy constructor from a tree of a different type. More...
| Tree (const ValueType &background)
| Empty tree constructor. More...
| ~Tree () override
TreeBase::Ptr | copy () const override
| Return a pointer to a deep copy of this tree. More...
Name | valueType () const override
| Return the name of the type of a voxel's value (e.g., "float" or "vec3d") More...
const Name & | type () const override
| Return the name of this type of tree. More...
bool | operator== (const Tree &) const
bool | operator!= (const Tree &) 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`. More...
bool | evalLeafBoundingBox (CoordBBox &bbox) const override
| Return in bbox the axis-aligned bounding box of all leaf nodes and active tiles. More...
bool | evalActiveVoxelBoundingBox (CoordBBox &bbox) const override
| Return in bbox the axis-aligned bounding box of all active voxels and tiles. More...
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. More...
bool | evalLeafDim (Coord &dim) const override
| Return in dim the dimensions of the axis-aligned bounding box of all leaf nodes. More...
void | readTopology (std::istream &, bool saveFloatAsHalf=false) override
| Read the tree topology from a stream. More...
void | writeTopology (std::ostream &, bool saveFloatAsHalf=false) const override
| Write the tree topology to a stream. More...
void | readBuffers (std::istream &, bool saveFloatAsHalf=false) override
| Read all data buffers for this tree. More...
void | readBuffers (std::istream &, const CoordBBox &, bool saveFloatAsHalf=false) override
| Read all of this tree's data buffers that intersect the given bounding box. More...
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). More...
void | writeBuffers (std::ostream &, bool saveFloatAsHalf=false) const override
| Write out all data buffers for this tree. More...
void | print (std::ostream &os=std::cout, int verboseLevel=1) const override
| Print statistics, memory usage and other information about this tree. More...
Index | treeDepth () const override
| Return the depth of this tree. More...
Index32 | leafCount () const override
| Return the number of leaf nodes. More...
Index32 | nonLeafCount () const override
| Return the number of non-leaf nodes. More...
Index64 | activeLeafVoxelCount () const override
| Return the number of active voxels stored in leaf nodes. More...
Index64 | inactiveLeafVoxelCount () const override
| Return the number of inactive voxels stored in leaf nodes. More...
Index64 | activeVoxelCount () const override
| Return the total number of active voxels. More...
Index64 | inactiveVoxelCount () const override
| Return the number of inactive voxels within the bounding box of all active voxels. More...
Index64 | activeTileCount () const override
| Return the total number of active tiles. More...
void | evalMinMax (ValueType &min, ValueType &max) const
| Return the minimum and maximum active values in this tree. More...
Index64 | memUsage () const override
| Return the total amount of memory in bytes occupied by this tree. More...
const ValueType & | getValue (const Coord &xyz) const
| Return the value of the voxel at the given coordinates. More...
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. More...
int | getValueDepth (const Coord &xyz) const
| Return the tree depth (0 = root) at which the value of voxel (x, y, z) resides. More...
void | setActiveState (const Coord &xyz, bool on)
| Set the active state of the voxel at the given coordinates but don't change its value. More...
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. More...
void | setValueOn (const Coord &xyz)
| Mark the voxel at the given coordinates as active but don't change its value. More...
void | setValueOn (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as active. More...
void | setValue (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as active. More...
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. More...
void | setValueOff (const Coord &xyz)
| Mark the voxel at the given coordinates as inactive but don't change its value. More...
void | setValueOff (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as inactive. More...
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. More...
template<typename ModifyOp >
void | modifyValueAndActiveState (const Coord &xyz, const ModifyOp &op)
| Apply a functor to the voxel at the given coordinates. More...
bool | probeValue (const Coord &xyz, ValueType &value) const
| Get the value of the voxel at the given coordinates. More...
bool | isValueOn (const Coord &xyz) const
| Return `true` if the value at the given coordinates is active. More...
bool | isValueOff (const Coord &xyz) const
| Return `true` if the value at the given coordinates is inactive. More...
bool | hasActiveTiles () const
| Return `true` if this tree has any active tiles. More...
void | clip (const CoordBBox &)
| Set all voxels that lie outside the given axis-aligned box to the background. More...
void | clipUnallocatedNodes () override
| Replace with background tiles any nodes whose voxel buffers have not yet been allocated. More...
Index32 | unallocatedLeafCount () const override
| Return the total number of unallocated leaf nodes residing in this tree. More...
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. More...
void | voxelizeActiveTiles (bool threaded=true)
| Densify active tiles, i.e., replace them with leaf-level active voxels. More...
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. More...
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. More...
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). More...
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`. More...
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. More...
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: More...
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. More...
void | clear ()
| Remove all tiles from this tree and all nodes other than the root node. More...
void | clearAllAccessors ()
| Clear all registered accessors. More...
Metadata::Ptr | getBackgroundValue () const override
| Return this tree's background value wrapped as metadata. More...
const ValueType & | background () const
| Return this tree's background value. More...
void | getIndexRange (CoordBBox &bbox) const override
| Min and max are both inclusive. More...
void | merge (Tree &other, MergePolicy=MERGE_ACTIVE_STATES)
| Efficiently merge another tree into this tree using one of several schemes. More...
template<typename OtherRootNodeType >
void | topologyUnion (const Tree< OtherRootNodeType > &other)
| Union this tree's set of active values with the active values of the other tree, whose `ValueType` may be different. More...
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. More...
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. More...
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)
template<typename BBoxOp >
void | visitActiveBBox (BBoxOp &op) const
| Use sparse traversal to call the given functor with bounding box information for all active tiles and leaf nodes or active voxels in the tree. More...
template<typename VisitorOp >
void | visit (VisitorOp &op)
template<typename VisitorOp >
void | visit (const VisitorOp &op)
template<typename VisitorOp >
void | visit (VisitorOp &op) const
template<typename VisitorOp >
void | visit (const VisitorOp &op) const
template<typename OtherTreeType , typename VisitorOp >
void | visit2 (OtherTreeType &other, VisitorOp &op)
template<typename OtherTreeType , typename VisitorOp >
void | visit2 (OtherTreeType &other, const VisitorOp &op)
template<typename OtherTreeType , typename VisitorOp >
void | visit2 (OtherTreeType &other, VisitorOp &op) const
template<typename OtherTreeType , typename VisitorOp >
void | visit2 (OtherTreeType &other, const VisitorOp &op) const
template<typename IterT >
IterT | begin ()
| Return an iterator of type `IterT` (for example, begin<ValueOnIter>() is equivalent to beginValueOn()). More...
template<typename CIterT >
CIterT | cbegin () const
| Return a const iterator of type CIterT (for example, cbegin<ValueOnCIter>() is equivalent to cbeginValueOn()). More...
template<typename IterT >
IterT | cbegin () const
template<typename AccessT >
const RootNodeType::ValueType & | getValue (const Coord &xyz, AccessT &accessor) const
RootNodeType & | root ()
| Return this tree's root node. More...
const RootNodeType & | root () const
| Return this tree's root node. More...
void | sparseFill (const CoordBBox &bbox, const ValueType &value, bool active=true)
| Set all voxels within a given axis-aligned box to a constant value. More...
void | fill (const CoordBBox &bbox, const ValueType &value, bool active=true)
| Set all voxels within a given axis-aligned box to a constant value. More...
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`. More...
template<typename NodeType >
const NodeType * | probeConstNode (const Coord &xyz) const
| Return a pointer to the node of type `NodeType` that contains voxel (x, y, z). If no such node exists, return `nullptr`. More...
template<typename NodeType >
const NodeType * | probeNode (const Coord &xyz) const
| Return a pointer to the node of type `NodeType` that contains voxel (x, y, z). If no such node exists, return `nullptr`. More...
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`. More...
const LeafNodeType * | probeConstLeaf (const Coord &xyz) const
| Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, return `nullptr`. More...
const LeafNodeType * | probeLeaf (const Coord &xyz) const
| Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, return `nullptr`. More...
template<typename ArrayT >
void | getNodes (ArrayT &array)
| Adds all nodes of a certain type to a container with the following API: More...
template<typename ArrayT >
void | getNodes (ArrayT &array) const
| Adds all nodes of a certain type to a container with the following API: More...
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. More...
void | attachAccessor (ValueAccessorBase< const Tree, true > &) const
| Register an accessor for this tree. Registered accessors are automatically cleared whenever one of this tree's nodes is deleted. More...
void | attachAccessor (ValueAccessorBase< Tree, false > &) const
| Dummy implementations. More...
void | attachAccessor (ValueAccessorBase< const Tree, false > &) const
| Dummy implementations. More...
void | releaseAccessor (ValueAccessorBase< Tree, true > &) const
| Deregister an accessor so that it is no longer automatically cleared. More...
void | releaseAccessor (ValueAccessorBase< const Tree, true > &) const
| Deregister an accessor so that it is no longer automatically cleared. More...
void | releaseAccessor (ValueAccessorBase< Tree, false > &) const
| Dummy implementations. More...
void | releaseAccessor (ValueAccessorBase< const Tree, false > &) const
| Dummy implementations. More...
RootNodeType::ChildOnCIter | beginRootChildren () const
| Return an iterator over children of the root node. More...
RootNodeType::ChildOnCIter | cbeginRootChildren () const
| Return an iterator over children of the root node. More...
RootNodeType::ChildOnIter | beginRootChildren ()
| Return an iterator over children of the root node. More...
RootNodeType::ChildOffCIter | beginRootTiles () const
| Return an iterator over non-child entries of the root node's table. More...
RootNodeType::ChildOffCIter | cbeginRootTiles () const
| Return an iterator over non-child entries of the root node's table. More...
RootNodeType::ChildOffIter | beginRootTiles ()
| Return an iterator over non-child entries of the root node's table. More...
RootNodeType::ChildAllCIter | beginRootDense () const
| Return an iterator over all entries of the root node's table. More...
RootNodeType::ChildAllCIter | cbeginRootDense () const
| Return an iterator over all entries of the root node's table. More...
RootNodeType::ChildAllIter | beginRootDense ()
| Return an iterator over all entries of the root node's table. More...
NodeIter | beginNode ()
| Return an iterator over all nodes in this tree. More...
NodeCIter | beginNode () const
| Return an iterator over all nodes in this tree. More...
NodeCIter | cbeginNode () const
| Return an iterator over all nodes in this tree. More...
LeafIter | beginLeaf ()
| Return an iterator over all leaf nodes in this tree. More...
LeafCIter | beginLeaf () const
| Return an iterator over all leaf nodes in this tree. More...
LeafCIter | cbeginLeaf () const
| Return an iterator over all leaf nodes in this tree. More...
ValueAllIter | beginValueAll ()
| Return an iterator over all values (tile and voxel) across all nodes. More...
ValueAllCIter | beginValueAll () const
| Return an iterator over all values (tile and voxel) across all nodes. More...
ValueAllCIter | cbeginValueAll () const
| Return an iterator over all values (tile and voxel) across all nodes. More...
ValueOnIter | beginValueOn ()
| Return an iterator over active values (tile and voxel) across all nodes. More...
ValueOnCIter | beginValueOn () const
| Return an iterator over active values (tile and voxel) across all nodes. More...
ValueOnCIter | cbeginValueOn () const
| Return an iterator over active values (tile and voxel) across all nodes. More...
ValueOffIter | beginValueOff ()
| Return an iterator over inactive values (tile and voxel) across all nodes. More...
ValueOffCIter | beginValueOff () const
| Return an iterator over inactive values (tile and voxel) across all nodes. More...
ValueOffCIter | cbeginValueOff () const
| Return an iterator over inactive values (tile and voxel) across all nodes. More...

## Static Public Member Functions
static const Name & | treeType ()
| Return the name of this type of tree. More...
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. More...

## 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. More...

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

## Static Protected Attributes
static tbb::atomic< const Name * > | sTreeTypeName

## Member Typedef Documentation

## ◆ AccessorRegistry

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

## ◆ BuildType

using BuildType = typename RootNodeType::BuildType

## ◆ ConstAccessorRegistry

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

## ◆ ConstPtr

using ConstPtr = SharedPtr<const Tree>

## ◆ LeafCIter

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

Iterator over all leaf nodes in this tree.

## ◆ LeafIter

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

Iterator over all leaf nodes in this tree.

## ◆ LeafNodeType

using LeafNodeType = typename RootNodeType::LeafNodeType

## ◆ NodeCIter

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

Iterator over all nodes in this tree.

## ◆ NodeIter

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

Iterator over all nodes in this tree.

## ◆ Ptr

using Ptr = SharedPtr<Tree>

## ◆ RootNodeType

using RootNodeType = _RootNodeType

## ◆ ValueAllCIter

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

## ◆ ValueAllIter

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

## ◆ ValueOffCIter

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

## ◆ ValueOffIter

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

## ◆ ValueOnCIter

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

## ◆ ValueOnIter

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

## ◆ ValueType

using ValueType = typename RootNodeType::ValueType

## Constructor & Destructor Documentation

## ◆ Tree() [1/6]

Tree | ( |  | ) |
| inline

## ◆ Tree() [2/6]

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

Deep copy constructor.

## ◆ Tree() [3/6]

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]

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]

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]

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

Empty tree constructor.

## ◆ ~Tree()

~Tree | ( |  | ) |
| inlineoverride

## Member Function Documentation

## ◆ activeLeafVoxelCount()

Index64 activeLeafVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of active voxels stored in leaf nodes.

Implements TreeBase.

## ◆ activeTileCount()

Index64 activeTileCount | ( |  | ) | const
| inlineoverridevirtual

Return the total number of active tiles.

Implements TreeBase.

## ◆ activeVoxelCount()

Index64 activeVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the total number of active voxels.

Implements TreeBase.

## ◆ addLeaf()

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()

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]

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.

## ◆ attachAccessor() [2/4]

void attachAccessor | ( | ValueAccessorBase< const 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.

## ◆ attachAccessor() [3/4]

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

Dummy implementations.

## ◆ attachAccessor() [4/4]

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

Dummy implementations.

## ◆ background()

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()

IterT begin | ( |  | ) |
| inline

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

## ◆ beginLeaf() [1/2]

LeafIter beginLeaf | ( |  | ) |
| inline

Return an iterator over all leaf nodes in this tree.

## ◆ beginLeaf() [2/2]

LeafCIter beginLeaf | ( |  | ) | const
| inline

Return an iterator over all leaf nodes in this tree.

## ◆ beginNode() [1/2]

NodeIter beginNode | ( |  | ) |
| inline

Return an iterator over all nodes in this tree.

## ◆ beginNode() [2/2]

NodeCIter beginNode | ( |  | ) | const
| inline

Return an iterator over all nodes in this tree.

## ◆ beginRootChildren() [1/2]

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

Return an iterator over children of the root node.

## ◆ beginRootChildren() [2/2]

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

Return an iterator over children of the root node.

## ◆ beginRootDense() [1/2]

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

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

## ◆ beginRootDense() [2/2]

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

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

## ◆ beginRootTiles() [1/2]

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

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

## ◆ beginRootTiles() [2/2]

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

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

## ◆ beginValueAll() [1/2]

ValueAllIter beginValueAll | ( |  | ) |
| inline

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

## ◆ beginValueAll() [2/2]

ValueAllCIter beginValueAll | ( |  | ) | const
| inline

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

## ◆ beginValueOff() [1/2]

ValueOffIter beginValueOff | ( |  | ) |
| inline

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

## ◆ beginValueOff() [2/2]

ValueOffCIter beginValueOff | ( |  | ) | const
| inline

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

## ◆ beginValueOn() [1/2]

ValueOnIter beginValueOn | ( |  | ) |
| inline

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

## ◆ beginValueOn() [2/2]

ValueOnCIter beginValueOn | ( |  | ) | const
| inline

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

## ◆ cbegin() [1/2]

CIterT cbegin | ( |  | ) | const

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

## ◆ cbegin() [2/2]

IterT cbegin | ( |  | ) | const
| inline

## ◆ cbeginLeaf()

LeafCIter cbeginLeaf | ( |  | ) | const
| inline

Return an iterator over all leaf nodes in this tree.

## ◆ cbeginNode()

NodeCIter cbeginNode | ( |  | ) | const
| inline

Return an iterator over all nodes in this tree.

## ◆ cbeginRootChildren()

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

Return an iterator over children of the root node.

## ◆ cbeginRootDense()

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

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

## ◆ cbeginRootTiles()

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

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

## ◆ cbeginValueAll()

ValueAllCIter cbeginValueAll | ( |  | ) | const
| inline

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

## ◆ cbeginValueOff()

ValueOffCIter cbeginValueOff | ( |  | ) | const
| inline

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

## ◆ cbeginValueOn()

ValueOnCIter cbeginValueOn | ( |  | ) | const
| inline

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

## ◆ clear()

void clear | ( |  | ) |
| inline

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

## ◆ clearAllAccessors()

void clearAllAccessors | ( |  | ) |
| inline

Clear all registered accessors.

## ◆ clip()

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

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

## ◆ clipUnallocatedNodes()

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]

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]

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

## ◆ combine2() [1/2]

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);
  }

## ◆ combine2() [2/2]

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

## ◆ combine2Extended() [1/2]

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);
  }

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);
  }

## ◆ combine2Extended() [2/2]

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

## ◆ combineExtended() [1/2]

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);
  }

## ◆ combineExtended() [2/2]

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

## ◆ copy()

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

Return a pointer to a deep copy of this tree.

Implements TreeBase.

## ◆ denseFill()

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()

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()

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()

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()

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

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

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()

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()

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

Return the minimum and maximum active values in this tree.

## ◆ fill()

void fill | ( | 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.

## ◆ getBackgroundValue()

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()

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

Min and max are both inclusive.

Implements TreeBase.

## ◆ getNodeLog2Dims()

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]

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]

void getNodes | ( | ArrayT & | array | ) | const
| 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);

## ◆ getValue() [1/3]

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

Return the value of the voxel at the given coordinates.

## ◆ getValue() [2/3]

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]

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

## ◆ getValueDepth()

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()

bool hasActiveTiles | ( |  | ) | const
| inline

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

## ◆ hasSameTopology()

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()

Index64 inactiveLeafVoxelCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of inactive voxels stored in leaf nodes.

Implements TreeBase.

## ◆ inactiveVoxelCount()

Index64 inactiveVoxelCount | ( |  | ) | const
| overridevirtual

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

Implements TreeBase.

## ◆ isValueOff()

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

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

## ◆ isValueOn()

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

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

## ◆ leafCount()

Index32 leafCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of leaf nodes.

Implements TreeBase.

## ◆ memUsage()

Index64 memUsage | ( |  | ) | const
| inlineoverridevirtual

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

Reimplemented from TreeBase.

## ◆ merge()

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()

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

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

See also
  tools::foreach()

## ◆ modifyValueAndActiveState()

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()

## ◆ nonLeafCount()

Index32 nonLeafCount | ( |  | ) | const
| inlineoverridevirtual

Return the number of non-leaf nodes.

Implements TreeBase.

## ◆ operator!=()

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

## ◆ operator=()

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

## ◆ operator==()

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

## ◆ print()

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()

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

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

## ◆ probeConstNode()

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

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

## ◆ probeLeaf() [1/2]

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]

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

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

## ◆ probeNode() [1/2]

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]

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

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

## ◆ probeValue()

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()

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]

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

Read all data buffers for this tree.

Implements TreeBase.

## ◆ readBuffers() [2/2]

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()

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()

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]

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

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

## ◆ releaseAccessor() [2/4]

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

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

## ◆ releaseAccessor() [3/4]

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

Dummy implementations.

## ◆ releaseAccessor() [4/4]

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

Dummy implementations.

## ◆ releaseAllAccessors()

void releaseAllAccessors | ( |  | ) |
| inlineprotected

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

## ◆ root() [1/2]

RootNodeType& root | ( |  | ) |
| inline

Return this tree's root node.

## ◆ root() [2/2]

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

Return this tree's root node.

## ◆ setActiveState()

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]

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]

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]

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

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

## ◆ setValueOff() [2/2]

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]

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

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

## ◆ setValueOn() [2/2]

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()

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()

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()

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]

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]

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

## ◆ topologyDifference()

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()

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 unactive voxels resulting in leaf nodes with no active values. Thus, it is recommended to subsequently call tools::pruneInactive.

## ◆ topologyUnion()

void topologyUnion | ( | const Tree< OtherRootNodeType > & | other | ) |
| 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.

## ◆ touchLeaf()

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()

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()

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

Return the name of this type of tree.

## ◆ type()

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

Return the name of this type of tree.

Implements TreeBase.

## ◆ unallocatedLeafCount()

Index32 unallocatedLeafCount | ( |  | ) | const
| inlineoverridevirtual

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

Implements TreeBase.

## ◆ valueType()

Name valueType | ( |  | ) | const
| inlineoverridevirtual

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

Implements TreeBase.

## ◆ visit() [1/4]

void visit | ( | VisitorOp & | op | ) |
| inline

Traverse this tree in depth-first order, and at each node call the given functor with a `DenseIterator` (see Iterator.h) that points to either a child node or a tile value. If the iterator points to a child node and the functor returns true, do not descend to the child node; instead, continue the traversal at the next iterator position.

Parameters

  op | a functor of the form `template<typename IterT> bool op(IterT&)`, where `IterT` is either a RootNode::ChildAllIter, an InternalNode::ChildAllIter or a LeafNode::ChildAllIter

Note
  There is no iterator that points to a RootNode, so to visit the root node, retrieve the `parent()` of a RootNode::ChildAllIter.

Example:
  Print information about the nodes and tiles of a tree, but not individual voxels.
  namespace {
  template<typename TreeT>
  struct PrintTreeVisitor
  {
  using RootT = typename TreeT::RootNodeType;
  bool visitedRoot;
  PrintTreeVisitor(): visitedRoot(false) {}
  template<typename IterT>
  inline bool operator()(IterT& iter)
  {
  if (!visitedRoot && iter.parent().getLevel() == RootT::LEVEL) {
  visitedRoot = true;
  std::cout << "Level-" << RootT::LEVEL << " node" << std::endl;
  }
  typename IterT::NonConstValueType value;
  typename IterT::ChildNodeType* child = iter.probeChild(value);
  if (child == nullptr) {
  std::cout << "Tile with value " << value << std::endl;
  return true; // no child to visit, so stop descending
  }
  std::cout << "Level-" << child->getLevel() << " node" << std::endl;
  return (child->getLevel() == 0); // don't visit leaf nodes
  }
  // The generic method, above, calls iter.probeChild(), which is not defined
  // for LeafNode::ChildAllIter. These overloads ensure that the generic
  // method template doesn't get instantiated for LeafNode iterators.
  bool operator()(typename TreeT::LeafNodeType::ChildAllIter&) { return true; }
  bool operator()(typename TreeT::LeafNodeType::ChildAllCIter&) { return true; }
  };
  }
  {
  PrintTreeVisitor visitor;
  tree.visit(visitor);
  }

## ◆ visit() [2/4]

void visit | ( | const VisitorOp & | op | ) |
| inline

## ◆ visit() [3/4]

void visit | ( | VisitorOp & | op | ) | const
| inline

Like visit(), but using `const` iterators, i.e., with

Parameters

  op | a functor of the form `template<typename IterT> bool op(IterT&)`, where `IterT` is either a RootNode::ChildAllCIter, an InternalNode::ChildAllCIter or a LeafNode::ChildAllCIter

## ◆ visit() [4/4]

void visit | ( | const VisitorOp & | op | ) | const
| inline

## ◆ visit2() [1/4]

void visit2 | ( | OtherTreeType & | other,
|  | VisitorOp & | op
| ) |  |
| inline

Traverse this tree and another tree in depth-first order, and for corresponding subregions of index space call the given functor with two `DenseIterators` (see Iterator.h), each of which points to either a child node or a tile value of this tree and the other tree. If the A iterator points to a child node and the functor returns a nonzero value with bit 0 set (e.g., 1), do not descend to the child node; instead, continue the traversal at the next A iterator position. Similarly, if the B iterator points to a child node and the functor returns a value with bit 1 set (e.g., 2), continue the traversal at the next B iterator position.

Note
  The other tree must have the same index space and fan-out factors as this tree, but it may have a different `ValueType` and a different topology.

Parameters

  other | a tree of the same type as this tree
  op | a functor of the form `template<class AIterT, class BIterT> int op(AIterT&, BIterT&)`, where `AIterT` and `BIterT` are any combination of a RootNode::ChildAllIter, an InternalNode::ChildAllIter or a LeafNode::ChildAllIter with an `OtherTreeType::RootNode::ChildAllIter`, an `OtherTreeType::InternalNode::ChildAllIter` or an `OtherTreeType::LeafNode::ChildAllIter`

Example:
  Given two trees of the same type, `aTree` and `bTree`, replace leaf nodes of `aTree` with corresponding leaf nodes of `bTree`, leaving `bTree` partially empty.
  namespace {
  template<typename AIterT, typename BIterT>
  inline int stealLeafNodes(AIterT& aIter, BIterT& bIter)
  {
  typename AIterT::NonConstValueType aValue;
  typename AIterT::ChildNodeType* aChild = aIter.probeChild(aValue);
  typename BIterT::NonConstValueType bValue;
  typename BIterT::ChildNodeType* bChild = bIter.probeChild(bValue);
  const Index aLevel = aChild->getLevel(), bLevel = bChild->getLevel();
  if (aChild && bChild && aLevel == 0 && bLevel == 0) { // both are leaf nodes
  aIter.setChild(bChild); // give B's child to A
  bIter.setValue(bValue); // replace B's child with a constant tile value
  }
  // Don't iterate over leaf node voxels of either A or B.
  int skipBranch = (aLevel == 0) ? 1 : 0;
  if (bLevel == 0) skipBranch = skipBranch | 2;
  return skipBranch;
  }
  }
  {
  aTree.visit2(bTree, stealLeafNodes);
  }

## ◆ visit2() [2/4]

void visit2 | ( | OtherTreeType & | other,
|  | const VisitorOp & | op
| ) |  |
| inline

## ◆ visit2() [3/4]

void visit2 | ( | OtherTreeType & | other,
|  | VisitorOp & | op
| ) |  | const
| inline

Like visit2(), but using `const` iterators, i.e., with

Parameters

  other | a tree of the same type as this tree
  op | a functor of the form `template<class AIterT, class BIterT> int op(AIterT&, BIterT&)`, where `AIterT` and `BIterT` are any combination of a RootNode::ChildAllCIter, an InternalNode::ChildAllCIter or a LeafNode::ChildAllCIter with an `OtherTreeType::RootNode::ChildAllCIter`, an `OtherTreeType::InternalNode::ChildAllCIter` or an `OtherTreeType::LeafNode::ChildAllCIter`

## ◆ visit2() [4/4]

void visit2 | ( | OtherTreeType & | other,
|  | const VisitorOp & | op
| ) |  | const
| inline

## ◆ visitActiveBBox()

void visitActiveBBox | ( | BBoxOp & | op | ) | const
| inline

Use sparse traversal to call the given functor with bounding box information for all active tiles and leaf nodes or active voxels in the tree.

Note
  The bounding boxes are guaranteed to be non-overlapping.

Parameters

  op | a functor with a templated call operator of the form `template<Index LEVEL> void operator()(const CoordBBox& bbox)`, where `bbox` is the bounding box of either an active tile (if `LEVEL` > 0), a leaf node or an active voxel. The functor must also provide a templated method of the form `template<Index LEVEL> bool descent()` that returns `false` if bounding boxes below the specified tree level are not to be visited. In such cases of early tree termination, a bounding box is instead derived from each terminating child node.

Example:
  Visit and process all active tiles and leaf nodes in a tree, but don't descend to the active voxels. The smallest bounding boxes that will be visited are those of leaf nodes or level-1 active tiles.
  {
  struct ProcessTilesAndLeafNodes {
  // Descend to leaf nodes, but no further.
  template<Index LEVEL> inline bool descent() { return LEVEL > 0; }
  // Use this version to descend to voxels:
  //template<Index LEVEL> inline bool descent() { return true; }
  template<Index LEVEL>
  inline void operator()(const CoordBBox &bbox) {
  if (LEVEL > 0) {
  // code to process an active tile
  } else {
  // code to process a leaf node
  }
  }
  };
  ProcessTilesAndLeafNodes op;
  aTree.visitActiveBBox(op);
  }

See also
  openvdb/unittest/TestTree.cc for another example.

## ◆ voxelizeActiveTiles()

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()

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

Write out all data buffers for this tree.

Implements TreeBase.

## ◆ writeTopology()

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

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

## ◆ mAccessorRegistry

AccessorRegistry mAccessorRegistry
| mutableprotected

## ◆ mConstAccessorRegistry

ConstAccessorRegistry mConstAccessorRegistry
| mutableprotected

## ◆ mRoot

RootNodeType mRoot
| protected

## ◆ sTreeTypeName

tbb::atomic< const Name * > sTreeTypeName
| staticprotected

The documentation for this class was generated from the following file:

- Tree.h