All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdGeomBBoxCache Class Reference

Caches bounds by recursively computing and aggregating bounds of children in world space and aggregating the result back into local space. More...

Public Member Functions

USDGEOM_API UsdGeomBBoxCache (UsdTimeCode time, TfTokenVector includedPurposes, bool useExtentsHint=false, bool ignoreVisibility=false)
 Construct a new BBoxCache for a specific time and set of includedPurposes. More...
 
USDGEOM_API UsdGeomBBoxCache (UsdGeomBBoxCache const &other)
 Copy constructor. More...
 
USDGEOM_API UsdGeomBBoxCacheoperator= (UsdGeomBBoxCache const &other)
 Copy assignment. More...
 
USDGEOM_API GfBBox3d ComputeWorldBound (const UsdPrim &prim)
 Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds. More...
 
USDGEOM_API GfBBox3d ComputeRelativeBound (const UsdPrim &prim, const UsdPrim &relativeToAncestorPrim)
 Compute the bound of the given prim in the space of an ancestor prim, relativeToAncestorPrim, leveraging any pre-existing cached bounds. More...
 
USDGEOM_API GfBBox3d ComputeLocalBound (const UsdPrim &prim)
 Computes the oriented bounding box of the given prim, leveraging any pre-existing, cached bounds. More...
 
USDGEOM_API GfBBox3d ComputeUntransformedBound (const UsdPrim &prim)
 Computes the bound of the prim's children leveraging any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself. More...
 
USDGEOM_API GfBBox3d ComputeUntransformedBound (const UsdPrim &prim, const SdfPathSet &pathsToSkip, const TfHashMap< SdfPath, GfMatrix4d, SdfPath::Hash > &ctmOverrides)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the bound of the prim's descendents while excluding the subtrees rooted at the paths in pathsToSkip. More...
 
USDGEOM_API bool ComputePointInstanceWorldBounds (const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
 Compute the bound of the given point instances in world space. More...
 
GfBBox3d ComputePointInstanceWorldBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
 Compute the bound of the given point instance in world space. More...
 
USDGEOM_API bool ComputePointInstanceRelativeBounds (const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, const UsdPrim &relativeToAncestorPrim, GfBBox3d *result)
 Compute the bounds of the given point instances in the space of an ancestor prim relativeToAncestorPrim. More...
 
GfBBox3d ComputePointInstanceRelativeBound (const UsdGeomPointInstancer &instancer, int64_t instanceId, const UsdPrim &relativeToAncestorPrim)
 Compute the bound of the given point instance in the space of an ancestor prim relativeToAncestorPrim. More...
 
USDGEOM_API bool ComputePointInstanceLocalBounds (const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
 Compute the oriented bounding boxes of the given point instances. More...
 
GfBBox3d ComputePointInstanceLocalBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
 Compute the oriented bounding boxes of the given point instances. More...
 
USDGEOM_API bool ComputePointInstanceUntransformedBounds (const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
 Computes the bound of the given point instances, but does not include the transform (if any) authored on the instancer itself. More...
 
GfBBox3d ComputePointInstanceUntransformedBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
 Computes the bound of the given point instances, but does not include the instancer's transform. More...
 
USDGEOM_API void Clear ()
 Clears all pre-cached values. More...
 
USDGEOM_API void SetIncludedPurposes (const TfTokenVector &includedPurposes)
 Indicate the set of includedPurposes to use when resolving child bounds. More...
 
const TfTokenVectorGetIncludedPurposes ()
 Get the current set of included purposes. More...
 
bool GetUseExtentsHint () const
 Returns whether authored extent hints are used to compute bounding boxes. More...
 
bool GetIgnoreVisibility () const
 Returns whether prim visibility should be ignored when computing bounding boxes. More...
 
USDGEOM_API void SetTime (UsdTimeCode time)
 Use the new time when computing values and may clear any existing values cached for the previous time. More...
 
UsdTimeCode GetTime () const
 Get the current time from which this cache is reading values. More...
 
void SetBaseTime (UsdTimeCode baseTime)
 Set the base time value for this bbox cache. More...
 
UsdTimeCode GetBaseTime () const
 Return the base time if set, otherwise GetTime(). More...
 
void ClearBaseTime ()
 Clear this cache's baseTime if one has been set. More...
 
bool HasBaseTime () const
 Return true if this cache has a baseTime that's been explicitly set, false otherwise. More...
 

Detailed Description

Caches bounds by recursively computing and aggregating bounds of children in world space and aggregating the result back into local space.

The cache is configured for a specific time and UsdGeomImageable::GetPurposeAttr() set of purposes. When querying a bound, transforms and extents are read either from the time specified or UsdTimeCode::Default(), following TimeSamples, Defaults, and Value Resolution standard time-sample value resolution. As noted in SetIncludedPurposes(), changing the included purposes does not invalidate the cache, because we cache purpose along with the geometric data.

Child prims that are invisible at the requested time are excluded when computing a prim's bounds. However, if a bound is requested directly for an excluded prim, it will be computed. Additionally, only prims deriving from UsdGeomImageable are included in child bounds computations.

Unlike standard UsdStage traversals, the traversal performed by the UsdGeomBBoxCache includes prims that are unloaded (see UsdPrim::IsLoaded()). This makes it possible to fetch bounds for a UsdStage that has been opened without forcePopulate , provided the unloaded model prims have authored extent hints (see UsdGeomModelAPI::GetExtentsHint()).

This class is optimized for computing tight untransformed "object" space bounds for component-models. In the absence of component models, bounds are optimized for world-space, since there is no other easily identifiable space for which to optimize, and we cannot optimize for every prim's local space without performing quadratic work.

The TfDebug flag, USDGEOM_BBOX, is provided for debugging.

Warnings:

  • This class should only be used with valid UsdPrim objects.
  • This cache does not listen for change notifications; the user is responsible for clearing the cache when changes occur.
  • Thread safety: instances of this class may not be used concurrently.
  • Plugins may be loaded in order to compute extents for prim types provided by that plugin. See UsdGeomBoundable::ComputeExtentFromPlugins

Definition at line 87 of file bboxCache.h.

Constructor & Destructor Documentation

USDGEOM_API UsdGeomBBoxCache ( UsdTimeCode  time,
TfTokenVector  includedPurposes,
bool  useExtentsHint = false,
bool  ignoreVisibility = false 
)

Construct a new BBoxCache for a specific time and set of includedPurposes.

Only prims with a purpose that matches the includedPurposes will be considered when accumulating child bounds. See UsdGeomImageable for allowed purpose values.

If useExtentsHint is true, then when computing the bounds for any model-root prim, if the prim is visible at time, we will fetch its extents hint (via UsdGeomModelAPI::GetExtentsHint()). If it is authored, we use it to compute the bounding box for the selected combination of includedPurposes by combining bounding box hints that have been cached for various values of purposes.

If ignoreVisibility is true invisible prims will be included during bounds computations.

USDGEOM_API UsdGeomBBoxCache ( UsdGeomBBoxCache const &  other)

Copy constructor.

Member Function Documentation

USDGEOM_API void Clear ( )

Clears all pre-cached values.

void ClearBaseTime ( )
inline

Clear this cache's baseTime if one has been set.

After calling this, the cache will use its time as the baseTime value.

Definition at line 359 of file bboxCache.h.

USDGEOM_API GfBBox3d ComputeLocalBound ( const UsdPrim prim)

Computes the oriented bounding box of the given prim, leveraging any pre-existing, cached bounds.

The computed bound includes the transform authored on the prim itself, but does not include any ancestor transforms (it does not include the local-to-world transform).

See ComputeWorldBound() for notes on performance and error handling.

GfBBox3d ComputePointInstanceLocalBound ( const UsdGeomPointInstancer instancer,
int64_t  instanceId 
)
inline

Compute the oriented bounding boxes of the given point instances.

Definition at line 261 of file bboxCache.h.

USDGEOM_API bool ComputePointInstanceLocalBounds ( const UsdGeomPointInstancer instancer,
int64_t const *  instanceIdBegin,
size_t  numIds,
GfBBox3d result 
)

Compute the oriented bounding boxes of the given point instances.

The computed bounds include the transform authored on the instancer itself, but does not include any ancestor transforms (it does not include the local-to-world transform).

The result pointer must point to numIds GfBBox3d instances to be filled.

GfBBox3d ComputePointInstanceRelativeBound ( const UsdGeomPointInstancer instancer,
int64_t  instanceId,
const UsdPrim relativeToAncestorPrim 
)
inline

Compute the bound of the given point instance in the space of an ancestor prim relativeToAncestorPrim.

Definition at line 233 of file bboxCache.h.

USDGEOM_API bool ComputePointInstanceRelativeBounds ( const UsdGeomPointInstancer instancer,
int64_t const *  instanceIdBegin,
size_t  numIds,
const UsdPrim relativeToAncestorPrim,
GfBBox3d result 
)

Compute the bounds of the given point instances in the space of an ancestor prim relativeToAncestorPrim.

Write the results to result.

The computed bound excludes the local transform at relativeToAncestorPrim. The computed bound may be incorrect if relativeToAncestorPrim is not an ancestor of prim.

The result pointer must point to numIds GfBBox3d instances to be filled.

GfBBox3d ComputePointInstanceUntransformedBound ( const UsdGeomPointInstancer instancer,
int64_t  instanceId 
)
inline

Computes the bound of the given point instances, but does not include the instancer's transform.

Definition at line 291 of file bboxCache.h.

USDGEOM_API bool ComputePointInstanceUntransformedBounds ( const UsdGeomPointInstancer instancer,
int64_t const *  instanceIdBegin,
size_t  numIds,
GfBBox3d result 
)

Computes the bound of the given point instances, but does not include the transform (if any) authored on the instancer itself.

IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().

The result pointer must point to numIds GfBBox3d instances to be filled.

GfBBox3d ComputePointInstanceWorldBound ( const UsdGeomPointInstancer instancer,
int64_t  instanceId 
)
inline

Compute the bound of the given point instance in world space.

Definition at line 204 of file bboxCache.h.

USDGEOM_API bool ComputePointInstanceWorldBounds ( const UsdGeomPointInstancer instancer,
int64_t const *  instanceIdBegin,
size_t  numIds,
GfBBox3d result 
)

Compute the bound of the given point instances in world space.

The bounds of each instance is computed and then transformed to world space. The result pointer must point to numIds GfBBox3d instances to be filled.

USDGEOM_API GfBBox3d ComputeRelativeBound ( const UsdPrim prim,
const UsdPrim relativeToAncestorPrim 
)

Compute the bound of the given prim in the space of an ancestor prim, relativeToAncestorPrim, leveraging any pre-existing cached bounds.

The computed bound excludes the local transform at relativeToAncestorPrim. The computed bound may be incorrect if relativeToAncestorPrim is not an ancestor of prim.

USDGEOM_API GfBBox3d ComputeUntransformedBound ( const UsdPrim prim)

Computes the bound of the prim's children leveraging any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.

IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().

See ComputeWorldBound() for notes on performance and error handling.

USDGEOM_API GfBBox3d ComputeUntransformedBound ( const UsdPrim prim,
const SdfPathSet &  pathsToSkip,
const TfHashMap< SdfPath, GfMatrix4d, SdfPath::Hash > &  ctmOverrides 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the bound of the prim's descendents while excluding the subtrees rooted at the paths in pathsToSkip.

Additionally, the parameter ctmOverrides is used to specify overrides to the CTM values of certain paths underneath the prim. The CTM values in the ctmOverrides map are in the space of the given prim, prim.

This leverages any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.

IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().

See ComputeWorldBound() for notes on performance and error handling.

USDGEOM_API GfBBox3d ComputeWorldBound ( const UsdPrim prim)

Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds.

The bound of the prim is computed, including the transform (if any) authored on the node itself, and then transformed to world space.

Error handling note: No checking of prim validity is performed. If prim is invalid, this method will abort the program; therefore it is the client's responsibility to ensure prim is valid.

UsdTimeCode GetBaseTime ( ) const
inline

Return the base time if set, otherwise GetTime().

Use HasBaseTime() to observe if a base time has been set.

Definition at line 353 of file bboxCache.h.

bool GetIgnoreVisibility ( ) const
inline

Returns whether prim visibility should be ignored when computing bounding boxes.

Definition at line 326 of file bboxCache.h.

const TfTokenVector& GetIncludedPurposes ( )
inline

Get the current set of included purposes.

Definition at line 316 of file bboxCache.h.

UsdTimeCode GetTime ( ) const
inline

Get the current time from which this cache is reading values.

Definition at line 337 of file bboxCache.h.

bool GetUseExtentsHint ( ) const
inline

Returns whether authored extent hints are used to compute bounding boxes.

Definition at line 320 of file bboxCache.h.

bool HasBaseTime ( ) const
inline

Return true if this cache has a baseTime that's been explicitly set, false otherwise.

Definition at line 365 of file bboxCache.h.

USDGEOM_API UsdGeomBBoxCache& operator= ( UsdGeomBBoxCache const &  other)

Copy assignment.

void SetBaseTime ( UsdTimeCode  baseTime)
inline

Set the base time value for this bbox cache.

This value is used only when computing bboxes for point instancer instances (see ComputePointInstanceWorldBounds(), for example). See UsdGeomPointInstancer::ComputeExtentAtTime() for more information. If unset, the bbox cache uses its time (GetTime() / SetTime()) for this value.

Note that setting the base time does not invalidate any cache entries.

Definition at line 347 of file bboxCache.h.

USDGEOM_API void SetIncludedPurposes ( const TfTokenVector includedPurposes)

Indicate the set of includedPurposes to use when resolving child bounds.

Each child's purpose must match one of the elements of this set to be included in the computation; if it does not, child is excluded.

Note the use of child in the docs above, purpose is ignored for the prim for whose bounds are directly queried.

Changing this value does not invalidate existing caches.

USDGEOM_API void SetTime ( UsdTimeCode  time)

Use the new time when computing values and may clear any existing values cached for the previous time.

Setting time to the current time is a no-op.


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