Loading...
Searching...
No Matches
UsdPrimRange Class Reference

An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first order. More...

#include <primRange.h>

Classes

class  EndSentinel
 This class lets us represent past-the-end without the full weight of an iterator. More...
 
class  iterator
 A forward iterator into a UsdPrimRange. More...
 

Public Types

using const_iterator = iterator
 

Public Member Functions

 UsdPrimRange (const UsdPrim &start)
 Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate).
 
 UsdPrimRange (const UsdPrim &start, const Usd_PrimFlagsPredicate &predicate)
 Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate.
 
iterator begin () const
 Return an iterator to the start of this range.
 
const_iterator cbegin () const
 Return a const_iterator to the start of this range.
 
UsdPrim front () const
 Return the first element of this range. The range must not be empty().
 
iterator end () const
 Return the past-the-end iterator for this range.
 
const_iterator cend () const
 Return the past-the-end const_iterator for this range.
 
void increment_begin ()
 Modify this range by advancing the beginning by one.
 
void set_begin (iterator const &newBegin)
 Set the start of this range to newBegin.
 
bool empty () const
 Return true if this range contains no prims, false otherwise.
 
 operator bool () const
 Return true if this range contains one or more prims, false otherwise.
 
bool operator== (UsdPrimRange const &other) const
 Return true if this range is equivalent to other.
 
bool operator!= (UsdPrimRange const &other) const
 Return true if this range is not equivalent to other.
 

Static Public Member Functions

static UsdPrimRange PreAndPostVisit (const UsdPrim &start)
 Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate) with pre- and post-order visitation.
 
static UsdPrimRange PreAndPostVisit (const UsdPrim &start, const Usd_PrimFlagsPredicate &predicate)
 Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate with pre- and post-order visitation.
 
static UsdPrimRange AllPrims (const UsdPrim &start)
 Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims).
 
static UsdPrimRange AllPrimsPreAndPostVisit (const UsdPrim &start)
 Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims) with pre- and post-order visitation.
 
static USD_API UsdPrimRange Stage (const UsdStagePtr &stage, const Usd_PrimFlagsPredicate &predicate=UsdPrimDefaultPredicate)
 Create a PrimRange that traverses all the prims on stage, and visits those that pass the default predicate (as defined by UsdPrimDefaultPredicate).
 

Detailed Description

An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first order.

In addition to depth-first order, UsdPrimRange provides the optional ability to traverse in depth-first pre- and post-order wher prims appear twice in the range; first before all descendants and then again immediately after all descendants. This is useful for maintaining state associated with subtrees, in a stack-like fashion. See UsdPrimRange::iterator::IsPostVisit() to detect when an iterator is visiting a prim for the second time.

There are several constructors providing different levels of configurability; ultimately, one can provide a prim predicate for a custom iteration, just as one would use UsdPrim::GetFilteredChildren() in a custom recursion.

Why would one want to use a UsdPrimRange rather than just iterating over the results of UsdPrim::GetFilteredDescendants() ? Primarily, if one of the following applies:

Using UsdPrimRange in C++

UsdPrimRange provides standard container-like semantics. For example:

// simple range-for iteration
for (UsdPrim prim: UsdPrimRange(rootPrim)) {
ProcessPrim(prim);
}
// using stl algorithms
std::vector<UsdPrim> meshes;
auto range = stage->Traverse();
std::copy_if(range.begin(), range.end(), std::back_inserter(meshes),
[](UsdPrim const &) { return prim.IsA<UsdGeomMesh>(); });
// iterator-based iterating, with subtree pruning
UsdPrimRange range(rootPrim);
for (auto iter = range.begin(); iter != range.end(); ++iter) {
if (UsdModelAPI(*iter).GetKind() == KindTokens->component) {
iter.PruneChildren();
}
else {
nonComponents.push_back(*iter);
}
}
UsdModelAPI is an API schema that provides an interface to a prim's model qualities,...
Definition: modelAPI.h:73
USD_API bool GetKind(TfToken *kind) const
Retrieve the authored kind for this prim.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first ord...
Definition: primRange.h:119

Using Usd.PrimRange in python

The python wrapping for PrimRange is python-iterable, so it can used directly as the object of a "for x in..." clause; however in that usage one loses access to PrimRange methods such as PruneChildren() and IsPostVisit(). Simply create the iterator outside the loop to overcome this limitation. Finally, in python, prim predicates must be combined with bit-wise operators rather than logical operators because the latter are not overridable.

# simple iteration
for prim in Usd.PrimRange(rootPrim):
ProcessPrim(prim)
# filtered range using iterator to invoke iterator methods
it = iter(Usd.PrimRange.Stage(stage, Usd.PrimIsLoaded & ~Usd.PrimIsAbstract))
for prim in it:
if Usd.ModelAPI(prim).GetKind() == Kind.Tokens.component:
it.PruneChildren()
else:
nonComponents.append(prim)

Finally, since iterators in python are not directly dereferencable, we provide the python only methods GetCurrentPrim() and IsValid(), documented in the python help system.

Definition at line 118 of file primRange.h.

Member Typedef Documentation

◆ const_iterator

Definition at line 244 of file primRange.h.

Constructor & Destructor Documentation

◆ UsdPrimRange() [1/3]

UsdPrimRange ( )
inline

Definition at line 246 of file primRange.h.

◆ UsdPrimRange() [2/3]

UsdPrimRange ( const UsdPrim start)
inlineexplicit

Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate).

Definition at line 255 of file primRange.h.

◆ UsdPrimRange() [3/3]

UsdPrimRange ( const UsdPrim start,
const Usd_PrimFlagsPredicate &  predicate 
)
inline

Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate.

Definition at line 262 of file primRange.h.

Member Function Documentation

◆ AllPrims()

static UsdPrimRange AllPrims ( const UsdPrim start)
inlinestatic

Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims).

Definition at line 307 of file primRange.h.

◆ AllPrimsPreAndPostVisit()

static UsdPrimRange AllPrimsPreAndPostVisit ( const UsdPrim start)
inlinestatic

Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims) with pre- and post-order visitation.

Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().

Definition at line 321 of file primRange.h.

◆ begin()

iterator begin ( ) const
inline

Return an iterator to the start of this range.

Definition at line 334 of file primRange.h.

◆ cbegin()

const_iterator cbegin ( ) const
inline

Return a const_iterator to the start of this range.

Definition at line 338 of file primRange.h.

◆ cend()

const_iterator cend ( ) const
inline

Return the past-the-end const_iterator for this range.

Definition at line 352 of file primRange.h.

◆ empty()

bool empty ( ) const
inline

Return true if this range contains no prims, false otherwise.

Definition at line 371 of file primRange.h.

◆ end()

iterator end ( ) const
inline

Return the past-the-end iterator for this range.

Definition at line 350 of file primRange.h.

◆ front()

UsdPrim front ( ) const
inline

Return the first element of this range. The range must not be empty().

Definition at line 343 of file primRange.h.

◆ increment_begin()

void increment_begin ( )
inline

Modify this range by advancing the beginning by one.

The range must not be empty, and the range must not be a pre- and post-order range.

Definition at line 356 of file primRange.h.

◆ operator bool()

operator bool ( ) const
inlineexplicit

Return true if this range contains one or more prims, false otherwise.

Definition at line 374 of file primRange.h.

◆ operator!=()

bool operator!= ( UsdPrimRange const &  other) const
inline

Return true if this range is not equivalent to other.

Definition at line 388 of file primRange.h.

◆ operator==()

bool operator== ( UsdPrimRange const &  other) const
inline

Return true if this range is equivalent to other.

Definition at line 377 of file primRange.h.

◆ PreAndPostVisit() [1/2]

static UsdPrimRange PreAndPostVisit ( const UsdPrim start)
inlinestatic

Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate) with pre- and post-order visitation.

Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().

Definition at line 280 of file primRange.h.

◆ PreAndPostVisit() [2/2]

static UsdPrimRange PreAndPostVisit ( const UsdPrim start,
const Usd_PrimFlagsPredicate &  predicate 
)
inlinestatic

Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate with pre- and post-order visitation.

Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().

Definition at line 296 of file primRange.h.

◆ set_begin()

void set_begin ( iterator const &  newBegin)
inline

Set the start of this range to newBegin.

The newBegin iterator must be within this range's begin() and end(), and must not have UsdPrimRange::iterator::IsPostVisit() be true.

Definition at line 363 of file primRange.h.

◆ Stage()

static USD_API UsdPrimRange Stage ( const UsdStagePtr &  stage,
const Usd_PrimFlagsPredicate &  predicate = UsdPrimDefaultPredicate 
)
static

Create a PrimRange that traverses all the prims on stage, and visits those that pass the default predicate (as defined by UsdPrimDefaultPredicate).


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