UsdCollectionAPI#

Fully qualified name: usdrt::UsdCollectionAPI

class UsdCollectionAPI : public usdrt::UsdAPISchemaBase #

This is a general purpose API schema, used to describe a collection of heterogeneous objects within the scene. “Objects” here may be prims or properties belonging to prims or other collections. It’s an add-on schema that can be applied many times to a prim with different collection names.

A collection allows an enumeration of a set of paths to include and a set of paths to exclude. Whether the descendants of an included path are members of a collection are decided by its expansion rule (see below). If the collection excludes paths that are not descendents of included paths, the collection implicitly includes the root path </>. If such a collection also includes paths that are not descendants of the excluded paths, it is considered invalid, since the intention is ambiguous.

All the properties authored by the schema are namespaced under “collection:”. The given name of the collection provides additional namespacing for the various per-collection properties, which include the following:

uniform token collection::expansionRule - specified how the paths that are included in the collection must be expanded to determine its members. Possible values include:
- explicitOnly - only paths in the includes rel targets and not in the excludes rel targets belong to the collection.
- expandPrims - all the prims at or below the includes rel- targets (and not under the excludes rel-targets) belong to the collection. Any property paths included in the collection would, of course, also be honored. This is the default behavior as it satisfies most use cases.
- expandPrimsAndProperties - like expandPrims, but also includes all properties on all matched prims. We’re still not quite sure what the use cases are for this, but you can use it to capture a whole lot of UsdObjects very concisely.
bool collection::includeRoot - boolean attribute indicating whether the pseudo-root path </> should be counted as one of the included target paths. The fallback is false. This separate attribute is required because relationships cannot directly target the root.
rel collection::includes - specifies a list of targets that are included in the collection. This can target prims or properties directly. A collection can insert the rules of another collection by making its includes relationship target the collection:{collectionName} property on the owning prim of the collection to be included. Such a property may not (and typically does not) exist on the UsdStage, but it is the path that is used to refer to the collection. It is important to note that including another collection does not guarantee the contents of that collection will be in the final collection; instead, the rules are merged. This means, for example, an exclude entry may exclude a portion of the included collection. When a collection includes one or more collections, the order in which targets are added to the includes relationship may become significant, if there are conflicting opinions about the same path. Targets that are added later are considered to be stronger than earlier targets for the same path.
rel collection::excludes - specifies a list of targets that are excluded below the included paths in this collection. This can target prims or properties directly, but cannot target another collection. This is to keep the membership determining logic simple, efficient and easier to reason about. Finally, it is invalid for a collection to exclude paths that are not included in it. The presence of such “orphaned” excluded paths will not affect the set of paths included in the collection, but may affect the performance of querying membership of a path in the collection (see UsdCollectionAPI::MembershipQuery::IsPathIncluded) or of enumerating the objects belonging to the collection (see UsdCollectionAPI::GetIncludedObjects).

Implicit inclusion

In some scenarios it is useful to express a collection that includes everything except certain paths. To support this, a collection that has an exclude that is not a descendent of any include will include the root path </>.

Creating collections in C++

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdTokens. So to set an attribute to the value “rightHanded”, use UsdTokens->rightHanded as the value.

Public Types

using MembershipQuery = UsdCollectionMembershipQuery#: Convenient alias for UsdCollectionMembershipQuery object.

Public Functions

inline explicit UsdCollectionAPI( const UsdPrim &prim = UsdPrim(), const TfToken &name = TfToken(), )#

Construct a UsdCollectionAPI on UsdPrim prim with name name . Equivalent to UsdCollectionAPI::Get( prim.GetStage(), prim.GetPath().AppendProperty( “collection:name”));.

for a valid prim , but will not immediately throw an error for an invalid prim

inline explicit UsdCollectionAPI( const UsdSchemaBase &schemaObj, const TfToken &name, )#: Construct a UsdCollectionAPI on the prim held by schemaObj with name name . Should be preferred over UsdCollectionAPI(schemaObj.GetPrim(), name), as it preserves SchemaBase state.

inline virtual ~UsdCollectionAPI()#: Destructor.

inline TfToken GetName() const#: Returns the name of this multiple-apply schema instance.

inline UsdAttribute GetExpansionRuleAttr() const#

Specifies how the paths that are included in the collection must be expanded to determine its members.


Declaration	`uniform token expansionRule = "expandPrims"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	explicitOnly, expandPrims, expandPrimsAndProperties

inline UsdAttribute CreateExpansionRuleAttr() const#: See GetExpansionRuleAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetIncludeRootAttr() const#

Boolean attribute indicating whether the pseudo-root path </> should be counted as one of the included target paths. The fallback is false. This separate attribute is required because relationships cannot directly target the root.


Declaration	`uniform bool includeRoot`
C++ Type	bool
Usd Type	SdfValueTypeNames->Bool
Variability	SdfVariabilityUniform

inline UsdAttribute CreateIncludeRootAttr() const#: See GetIncludeRootAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdRelationship GetIncludesRel() const#: Specifies a list of targets that are included in the collection. This can target prims or properties directly. A collection can insert the rules of another collection by making its includes relationship target the collection:{collectionName} property on the owning prim of the collection to be included.

inline UsdRelationship CreateIncludesRel() const#: See GetIncludesRel(), and also Create vs Get Property Methods for when to use Get vs Create.

inline UsdRelationship GetExcludesRel() const#: Specifies a list of targets that are excluded below the included paths in this collection. This can target prims or properties directly, but cannot target another collection. This is to keep the membership determining logic simple, efficient and easier to reason about. Finally, it is invalid for a collection to exclude paths that are not included in it. The presence of such “orphaned” excluded paths will not affect the set of paths included in the collection, but may affect the performance of querying membership of a path in the collection (see UsdCollectionAPI::MembershipQuery::IsPathIncluded) or of enumerating the objects belonging to the collection (see UsdCollectionAPI::GetIncludedObjects).

inline UsdRelationship CreateExcludesRel() const#: See GetExcludesRel(), and also Create vs Get Property Methods for when to use Get vs Create.

inline SdfPath GetCollectionPath() const#: Returns the canonical path that represents this collection. This points to a property named “collection:{collectionName}” on the prim defining the collection (which won’t really exist as a property on the UsdStage, but will be used to refer to the collection). This is the path to be used to “include” this collection in another collection.

inline UsdCollectionMembershipQuery ComputeMembershipQuery() const#: Computes and returns a UsdCollectionMembershipQuery object which can be used to query inclusion or exclusion of paths in the collection.

inline void ComputeMembershipQuery( UsdCollectionMembershipQuery *query, ) const#: Populates the UsdCollectionMembershipQuery object with data from this collection, so it can be used to query inclusion or exclusion of paths.

inline bool IncludePath(const SdfPath &pathToInclude) const#

Convenience API for adding or removing prims and properties to (or from) a collection..

Includes or adds the given path, pathToInclude in the collection.

This does nothing if the path is already included in the collection.

This does not modify the expansion-rule of the collection. Hence, if the expansionRule is expandPrims or expandPrimsAndProperties, then the descendants of pathToInclude will be also included in the collection unless explicitly excluded.

inline bool ExcludePath(const SdfPath &pathToExclude) const#

Excludes or removes the given path, pathToExclude from the collection.

If the collection is empty, the collection becomes one that includes all paths except the givne path. Otherwise, this does nothing if the path is not included in the collection.

This does not modify the expansion-rule of the collection. Hence, if the expansionRule is expandPrims or expandPrimsAndProperties, then the descendants of pathToExclude will also be excluded from the collection, unless explicitly included.

UsdPrim GetPrim() const#: Return this schema object’s held prim.

SdfPath GetPath() const#: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const#

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

Returns:: True if the help prim is valid, and the schema object is compatible with its held prim.

Public Static Functions

static inline UsdCollectionAPI Apply( const UsdPrim &prim, const TfToken &name, )#

Applies this multiple-apply API schema to the given prim along with the given instance name, name.

This information is stored by adding “CollectionAPI:<i>name</i>” to the token-valued, listOp metadata apiSchemas on the prim. For example, if name is ‘instance1’, the token ‘CollectionAPI:instance1’ is added to ‘apiSchemas’.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

Returns:: A valid UsdCollectionAPI object is returned upon success. An invalid (or empty) UsdCollectionAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

static inline bool IsCollectionAPIPath( const SdfPath &path, TfToken *name, )#: Checks if the given path path is of an API schema of type CollectionAPI. If so, it stores the instance name of the schema in name and returns true. Otherwise, it returns false.

static inline TfToken GetCollectionPropertyName( const TfToken &name, bool prefixedName = false, const TfToken &baseName = TfToken(), )#: Returns the name of the property, given the name of collection and base name of the attribute. Eg, if collection name is ‘lightLink’ and baseName is ‘includes’, this returns ‘collection:lightLink:includes’.

static inline UsdCollectionMembershipQuery ComputeMembershipQuery( omni::fabric::StageReaderWriterId stageId, const SdfPath &collectionPath, )#: Computes and returns a UsdCollectionMembershipQuery object which can be used to query inclusion or exclusion of paths in the collection.

static inline void ComputeMembershipQuery( omni::fabric::StageReaderWriterId stageId, const SdfPath &collectionPath, UsdCollectionMembershipQuery *query, )#: Populates the UsdCollectionMembershipQuery object with data from this collection, so it can be used to query inclusion or exclusion of paths.

static inline SdfPathSet ComputeIncludedPaths( const UsdCollectionMembershipQuery &query, omni::fabric::StageReaderWriterId stageId, )#: Returns all the paths in the collection represented by the UsdCollectionMembershipQuery object.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::MultipleApplyAPI #

Compile time constant representing what kind of schema this class is.

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const#

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const#

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

inline const TfToken _GetType() const#

Helper for subclasses to get this schema’s type token.

Note

This diverges from Usd and returns a TfToken, since we don’t implements TfType.

Returns:: The token representing the schema’s TfType.