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

#include <bboxCache.h>

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`.

USDGEOM_API	UsdGeomBBoxCache (UsdGeomBBoxCache const &other)
	Copy constructor.

USDGEOM_API UsdGeomBBoxCache &	operator= (UsdGeomBBoxCache const &other)
	Copy assignment.

USDGEOM_API GfBBox3d	ComputeWorldBound (const UsdPrim &prim)
	Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds.

USDGEOM_API GfBBox3d	ComputeWorldBoundWithOverrides (const UsdPrim &prim, const SdfPathSet &pathsToSkip, const GfMatrix4d &primOverride, const TfHashMap< SdfPath, GfMatrix4d, SdfPath::Hash > &ctmOverrides)
	Computes the bound of the prim's descendents in world space while excluding the subtrees rooted at the paths in `pathsToSkip`.

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.

USDGEOM_API GfBBox3d	ComputeLocalBound (const UsdPrim &prim)
	Computes the oriented bounding box of the given prim, leveraging any pre-existing, cached bounds.

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.

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`.

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.

GfBBox3d	ComputePointInstanceWorldBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
	Compute the bound of the given point instance in world space.

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`.

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`.

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.

GfBBox3d	ComputePointInstanceLocalBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
	Compute the oriented bounding boxes of the given point instances.

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.

GfBBox3d	ComputePointInstanceUntransformedBound (const UsdGeomPointInstancer &instancer, int64_t instanceId)
	Computes the bound of the given point instances, but does not include the instancer's transform.

USDGEOM_API void	Clear ()
	Clears all pre-cached values.

USDGEOM_API void	SetIncludedPurposes (const TfTokenVector &includedPurposes)
	Indicate the set of `includedPurposes` to use when resolving child bounds.

const TfTokenVector &	GetIncludedPurposes ()
	Get the current set of included purposes.

bool	GetUseExtentsHint () const
	Returns whether authored extent hints are used to compute bounding boxes.

bool	GetIgnoreVisibility () const
	Returns whether prim visibility should be ignored when computing bounding boxes.

USDGEOM_API void	SetTime (UsdTimeCode time)
	Use the new `time` when computing values and may clear any existing values cached for the previous time.

UsdTimeCode	GetTime () const
	Get the current time from which this cache is reading values.

void	SetBaseTime (UsdTimeCode baseTime)
	Set the base time value for this bbox cache.

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

void	ClearBaseTime ()
	Clear this cache's baseTime if one has been set.

bool	HasBaseTime () const
	Return true if this cache has a baseTime that's been explicitly set, false otherwise.

Friends
template<typename HashState >
void	TfHashAppend (HashState &h, const _PrimContext &key)

size_t	hash_value (const _PrimContext &key)

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

◆ UsdGeomBBoxCache() [1/2]

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.

◆ UsdGeomBBoxCache() [2/2]

USDGEOM_API UsdGeomBBoxCache ( UsdGeomBBoxCache const & other )

Copy constructor.

Member Function Documentation

◆ Clear()

USDGEOM_API void Clear ( )

Clears all pre-cached values.

◆ ClearBaseTime()

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 378 of file bboxCache.h.

◆ ComputeLocalBound()

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.

◆ ComputePointInstanceLocalBound()

GfBBox3d ComputePointInstanceLocalBound	(	const UsdGeomPointInstancer &	instancer,
		int64_t	instanceId
	)

inline

Compute the oriented bounding boxes of the given point instances.

Definition at line 280 of file bboxCache.h.

◆ ComputePointInstanceLocalBounds()

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.

◆ ComputePointInstanceRelativeBound()

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 252 of file bboxCache.h.

◆ ComputePointInstanceRelativeBounds()

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.

◆ ComputePointInstanceUntransformedBound()

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 310 of file bboxCache.h.

◆ ComputePointInstanceUntransformedBounds()

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.

◆ ComputePointInstanceWorldBound()

GfBBox3d ComputePointInstanceWorldBound	(	const UsdGeomPointInstancer &	instancer,
		int64_t	instanceId
	)

inline

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

Definition at line 223 of file bboxCache.h.

◆ ComputePointInstanceWorldBounds()

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.

◆ ComputeRelativeBound()

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.

◆ ComputeUntransformedBound() [1/2]

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.

◆ ComputeUntransformedBound() [2/2]

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.

◆ ComputeWorldBound()

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.

◆ ComputeWorldBoundWithOverrides()

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

Computes the bound of the prim's descendents in world space while excluding the subtrees rooted at the paths in pathsToSkip.

Additionally, the parameter primOverride overrides the local-to-world transform of the prim and ctmOverrides is used to specify overrides the local-to-world transforms of certain paths underneath the prim.

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

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

◆ GetBaseTime()

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 372 of file bboxCache.h.

◆ GetIgnoreVisibility()

bool GetIgnoreVisibility ( ) const

inline

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

Definition at line 345 of file bboxCache.h.

◆ GetIncludedPurposes()

const TfTokenVector & GetIncludedPurposes ( )

inline

Get the current set of included purposes.

Definition at line 335 of file bboxCache.h.

◆ GetTime()

UsdTimeCode GetTime ( ) const

inline

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

Definition at line 356 of file bboxCache.h.

◆ GetUseExtentsHint()

bool GetUseExtentsHint ( ) const

inline

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

Definition at line 339 of file bboxCache.h.

◆ HasBaseTime()

bool HasBaseTime ( ) const

inline

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

Definition at line 384 of file bboxCache.h.

◆ operator=()

USDGEOM_API UsdGeomBBoxCache & operator= ( UsdGeomBBoxCache const & other )

Copy assignment.

◆ SetBaseTime()

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 366 of file bboxCache.h.

◆ SetIncludedPurposes()

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.

◆ SetTime()

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.

Friends And Related Function Documentation

◆ hash_value

size_t hash_value ( const _PrimContext & key )

friend

Definition at line 553 of file bboxCache.h.

◆ TfHashAppend

void TfHashAppend	(	HashState &	h,
		const _PrimContext &	key
	)

friend

Definition at line 546 of file bboxCache.h.

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

pxr/usd/usdGeom/bboxCache.h

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ UsdGeomBBoxCache() [1/2]

◆ UsdGeomBBoxCache() [2/2]

Member Function Documentation

◆ Clear()

◆ ClearBaseTime()

◆ ComputeLocalBound()

◆ ComputePointInstanceLocalBound()

◆ ComputePointInstanceLocalBounds()

◆ ComputePointInstanceRelativeBound()

◆ ComputePointInstanceRelativeBounds()

◆ ComputePointInstanceUntransformedBound()

◆ ComputePointInstanceUntransformedBounds()

◆ ComputePointInstanceWorldBound()

◆ ComputePointInstanceWorldBounds()

◆ ComputeRelativeBound()

◆ ComputeUntransformedBound() [1/2]

◆ ComputeUntransformedBound() [2/2]

◆ ComputeWorldBound()

◆ ComputeWorldBoundWithOverrides()

◆ GetBaseTime()

◆ GetIgnoreVisibility()

◆ GetIncludedPurposes()

◆ GetTime()

◆ GetUseExtentsHint()

◆ HasBaseTime()

◆ operator=()

◆ SetBaseTime()

◆ SetIncludedPurposes()

◆ SetTime()

Friends And Related Function Documentation

◆ hash_value

◆ TfHashAppend