Pcp module#

Summary: The PrimCache Population module implements core scenegraph composition semantics - behaviors informally referred to as Layering & Referencing.

Classes:

`ArcType`
`Cache`	PcpCache is the context required to make requests of the Pcp composition algorithm and cache the results.
`Dependency`	Description of a dependency.
`DependencyType`
`DynamicFileFormatDependencyData`	Contains the necessary information for storing a prim index's dependency on dynamic file format arguments and determining if a field change affects the prim index.
`ErrorArcCycle`	Arcs between PcpNodes that form a cycle.
`ErrorArcPermissionDenied`	Arcs that were not made between PcpNodes because of permission restrictions.
`ErrorBase`	Base class for all error types.
`ErrorCapacityExceeded`	Exceeded the capacity for composition arcs at a single site.
`ErrorInconsistentAttributeType`	Attributes that have specs with conflicting definitions.
`ErrorInconsistentAttributeVariability`	Attributes that have specs with conflicting variability.
`ErrorInconsistentPropertyType`	Properties that have specs with conflicting definitions.
`ErrorInvalidAssetPath`	Invalid asset paths used by references or payloads.
`ErrorInvalidAssetPathBase`
`ErrorInvalidExternalTargetPath`	Invalid target or connection path in some scope that points to an object outside of that scope.
`ErrorInvalidInstanceTargetPath`	Invalid target or connection path authored in an inherited class that points to an instance of that class.
`ErrorInvalidPrimPath`	Invalid prim paths used by references or payloads.
`ErrorInvalidReferenceOffset`	References or payloads that use invalid layer offsets.
`ErrorInvalidSublayerOffset`	Sublayers that use invalid layer offsets.
`ErrorInvalidSublayerOwnership`	Sibling layers that have the same owner.
`ErrorInvalidSublayerPath`	Asset paths that could not be both resolved and loaded.
`ErrorInvalidTargetPath`	Invalid target or connection path.
`ErrorMutedAssetPath`	Muted asset paths used by references or payloads.
`ErrorOpinionAtRelocationSource`	Opinions were found at a relocation source path.
`ErrorPrimPermissionDenied`	Layers with illegal opinions about private prims.
`ErrorPropertyPermissionDenied`	Layers with illegal opinions about private properties.
`ErrorSublayerCycle`	Layers that recursively sublayer themselves.
`ErrorTargetPathBase`	Base class for composition errors related to target or connection paths.
`ErrorTargetPermissionDenied`	Paths with illegal opinions about private targets.
`ErrorType`
`ErrorUnresolvedPrimPath`	Asset paths that could not be both resolved and loaded.
`InstanceKey`	A PcpInstanceKey identifies instanceable prim indexes that share the same set of opinions.
`LayerStack`	Represents a stack of layers that contribute opinions to composition.
`LayerStackIdentifier`	Arguments used to identify a layer stack.
`LayerStackSite`	A site specifies a path in a layer stack of scene description.
`MapExpression`	An expression that yields a PcpMapFunction value.
`MapFunction`	A function that maps values from one namespace (and time domain) to another.
`NodeRef`	PcpNode represents a node in an expression tree for compositing scene description.
`PrimIndex`	PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific prim, under composition semantics.
`PropertyIndex`	PcpPropertyIndex is an index of all sites in scene description that contribute opinions to a specific property, under composition semantics.
`Site`	A site specifies a path in a layer stack of scene description.

class pxr.Pcp.ArcType#

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()#

allValues = (Pcp.ArcTypeRoot, Pcp.ArcTypeInherit, Pcp.ArcTypeRelocate, Pcp.ArcTypeVariant, Pcp.ArcTypeReference, Pcp.ArcTypePayload, Pcp.ArcTypeSpecialize)#

class pxr.Pcp.Cache#

PcpCache is the context required to make requests of the Pcp composition algorithm and cache the results.

Because the algorithms are recursive making a request typically makes other internal requests to solve subproblems caching subproblem results is required for reasonable performance, and so this cache is the only entrypoint to the algorithms.

There is a set of parameters that affect the composition results:

variant fallbacks: per named variant set, an ordered list of fallback values to use when composing a prim that defines a variant set but does not specify a selection

payload inclusion set: an SdfPath set used to identify which prims should have their payloads included during composition; this is the basis for explicit control over the”working set”of composition

file format target: the file format target that Pcp will request when opening scene description layers

“USD mode”configures the Pcp composition algorithm to provide only a custom, lighter subset of the full feature set, as needed by the Universal Scene Description system There are a number of different computations that can be requested. These include computing a layer stack from a PcpLayerStackIdentifier, computing a prim index or prim stack, and computing a property index.

Methods:

`ComputeAttributeConnectionPaths`(...)	Compute the attribute connection paths for the attribute at `attributePath` into `paths` .
`ComputeLayerStack`(identifier, allErrors)	Returns the layer stack for `identifier` if it exists, otherwise creates a new layer stack for `identifier` .
`ComputePrimIndex`(primPath, allErrors)	Compute and return a reference to the cached result for the prim index for the given path.
`ComputePropertyIndex`(propPath, allErrors)	Compute and return a reference to the cached result for the property index for the given path.
`ComputeRelationshipTargetPaths`(...)	Compute the relationship target paths for the relationship at `relationshipPath` into `paths` .
`FindAllLayerStacksUsingLayer`(layer)	Returns every computed & cached layer stack that includes `layer` .
`FindPrimIndex`(primPath)	Returns a pointer to the cached computed prim index for the given path, or None if it has not been computed.
`FindPropertyIndex`(propPath)	Returns a pointer to the cached computed property index for the given path, or None if it has not been computed.
`FindSiteDependencies`(siteLayerStack, ...)	Returns dependencies on the given site of scene description, as discovered by the cached index computations.
`GetDynamicFileFormatArgumentDependencyData`(...)	Returns the dynamic file format dependency data object for the prim index with the given `primIndexPath` .
`GetLayerStackIdentifier`()	Get the identifier of the layerStack used for composition.
`GetMutedLayers`()	Returns the list of canonical identifiers for muted layers in this cache.
`GetUsedLayers`()	Returns set of all layers used by this cache.
`GetUsedLayersRevision`()	Return a number that can be used to determine whether or not the set of layers used by this cache may have changed or not.
`GetVariantFallbacks`()	Get the list of fallbacks to attempt to use when evaluating variant sets that lack an authored selection.
`HasAnyDynamicFileFormatArgumentDependencies`()	Returns true if any prim index in this cache has a dependency on a dynamic file format argument field.
`HasRootLayerStack`(layerStack)	Return true if this cache's root layer stack is `layerStack` , false otherwise.
`IsInvalidAssetPath`(resolvedAssetPath)	Returns true if `resolvedAssetPath` was used by a prim (e.g.
`IsInvalidSublayerIdentifier`(identifier)	Returns true if `identifier` was used as a sublayer path in a layer stack but did not identify a valid layer.
`IsLayerMuted`(layerIdentifier)	Returns true if the layer specified by `layerIdentifier` is muted in this cache, false otherwise.
`IsPayloadIncluded`(path)	Return true if the payload is included for the given path.
`IsPossibleDynamicFileFormatArgumentField`(field)	Returns true if the given `field` is the name of a field that was composed while generating dynamic file format arguments for any prim index in this cache.
`PrintStatistics`()	Prints various statistics about the data stored in this cache.
`Reload`(changes)	Reload the layers of the layer stack, except session layers and sublayers of session layers.
`RequestLayerMuting`(layersToMute, ...)	Request layers to be muted or unmuted in this cache.
`RequestPayloads`(pathsToInclude, ...)	Request payloads to be included or excluded from composition.
`SetVariantFallbacks`(map, changes)	Set the list of fallbacks to attempt to use when evaluating variant sets that lack an authored selection.
`UsesLayerStack`(layerStack)	Return true if `layerStack` is used by this cache in its composition, false otherwise.

Attributes:

`fileFormatTarget`	str
`layerStack`	LayerStack

ComputeAttributeConnectionPaths( attributePath, paths, localOnly, stopProperty, includeStopProperty, deletedPaths, allErrors, ) → None#

Compute the attribute connection paths for the attribute at attributePath into paths .

If localOnly is true then this will compose attribute connections from local nodes only. If stopProperty is not None then this will stop composing attribute connections at stopProperty , including stopProperty iff includeStopProperty is true . If not None , deletedPaths will be populated with connection paths whose deletion contributed to the computed result. allErrors will contain any errors encountered while performing this operation.

Parameters:

attributePath (Path)
paths (list[Path])
localOnly (bool)
stopProperty (Spec)
includeStopProperty (bool)
deletedPaths (list[Path])
allErrors (list[PcpError])

ComputeLayerStack(identifier, allErrors) → LayerStack#

Returns the layer stack for identifier if it exists, otherwise creates a new layer stack for identifier .

This returns None if identifier is invalid (i.e. its root layer is None ). allErrors will contain any errors encountered while creating a new layer stack. It’ll be unchanged if the layer stack already existed.

Parameters:

identifier (LayerStackIdentifier)
allErrors (list[PcpError])

ComputePrimIndex(primPath, allErrors) → PrimIndex#

Compute and return a reference to the cached result for the prim index for the given path.

allErrors will contain any errors encountered while performing this operation.

Parameters:

primPath (Path)
allErrors (list[PcpError])

ComputePropertyIndex(propPath, allErrors) → PropertyIndex#

Compute and return a reference to the cached result for the property index for the given path.

allErrors will contain any errors encountered while performing this operation.

Parameters:

propPath (Path)
allErrors (list[PcpError])

ComputeRelationshipTargetPaths( relationshipPath, paths, localOnly, stopProperty, includeStopProperty, deletedPaths, allErrors, ) → None#

Compute the relationship target paths for the relationship at relationshipPath into paths .

If localOnly is true then this will compose relationship targets from local nodes only. If stopProperty is not None then this will stop composing relationship targets at stopProperty , including stopProperty iff includeStopProperty is true . If not None , deletedPaths will be populated with target paths whose deletion contributed to the computed result. allErrors will contain any errors encountered while performing this operation.

Parameters:

relationshipPath (Path)
paths (list[Path])
localOnly (bool)
stopProperty (Spec)
includeStopProperty (bool)
deletedPaths (list[Path])
allErrors (list[PcpError])

FindAllLayerStacksUsingLayer(layer) → list[LayerStack]#

Returns every computed & cached layer stack that includes layer .

Parameters:: layer (Layer)

FindPrimIndex(primPath) → PrimIndex#

Returns a pointer to the cached computed prim index for the given path, or None if it has not been computed.

Parameters:: primPath (Path)

FindPropertyIndex(propPath) → PropertyIndex#

Returns a pointer to the cached computed property index for the given path, or None if it has not been computed.

Parameters:: propPath (Path)

FindSiteDependencies( siteLayerStack, sitePath, depMask, recurseOnSite, recurseOnIndex, filterForExistingCachesOnly, ) → list[Dependency]#

Returns dependencies on the given site of scene description, as discovered by the cached index computations.

depMask

specifies what classes of dependency to include; see PcpDependencyFlags for details recurseOnSite

includes incoming dependencies on children of sitePath recurseOnIndex

extends the result to include all PcpCache child indexes below discovered results filterForExistingCachesOnly

filters the results to only paths representing computed prim and property index caches; otherwise a recursively-expanded result can include un-computed paths that are expected to depend on the site

Parameters:

siteLayerStack (LayerStack)
sitePath (Path)
depMask (PcpDependencyFlags)
recurseOnSite (bool)
recurseOnIndex (bool)
filterForExistingCachesOnly (bool)

FindSiteDependencies(siteLayer, sitePath, depMask, recurseOnSite, recurseOnIndex, filterForExistingCachesOnly) -> list[Dependency]

Returns dependencies on the given site of scene description, as discovered by the cached index computations.

This method overload takes a site layer rather than a layer stack. It will check every layer stack using that layer, and apply any relevant sublayer offsets to the map functions in the returned PcpDependencyVector.

See the other method for parameter details.

Parameters:

siteLayer (Layer)
sitePath (Path)
depMask (PcpDependencyFlags)
recurseOnSite (bool)
recurseOnIndex (bool)
filterForExistingCachesOnly (bool)

GetDynamicFileFormatArgumentDependencyData( primIndexPath, ) → DynamicFileFormatDependencyData#

Returns the dynamic file format dependency data object for the prim index with the given primIndexPath .

This will return an empty dependency data if either there is no cache prim index for the path or if the prim index has no dynamic file formats that it depends on.

Parameters:: primIndexPath (Path)

GetLayerStackIdentifier() → LayerStackIdentifier#: Get the identifier of the layerStack used for composition.

GetMutedLayers() → list[str]#

Returns the list of canonical identifiers for muted layers in this cache.

See documentation on RequestLayerMuting for more details.

GetUsedLayers() → SdfLayerHandleSet#: Returns set of all layers used by this cache.

GetUsedLayersRevision() → int#

Return a number that can be used to determine whether or not the set of layers used by this cache may have changed or not.

For example, if one calls GetUsedLayers() and saves the GetUsedLayersRevision() , and then later calls GetUsedLayersRevision() again, if the number is unchanged, then GetUsedLayers() is guaranteed to be unchanged as well.

GetVariantFallbacks() → PcpVariantFallbackMap#: Get the list of fallbacks to attempt to use when evaluating variant sets that lack an authored selection.

HasAnyDynamicFileFormatArgumentDependencies() → bool#: Returns true if any prim index in this cache has a dependency on a dynamic file format argument field.

HasRootLayerStack(layerStack) → bool#

Return true if this cache’s root layer stack is layerStack , false otherwise.

This is functionally equivalent to comparing against the result of GetLayerStack() , but does not require constructing a TfWeakPtr or any refcount operations.

Parameters:: layerStack (LayerStack)

HasRootLayerStack(layerStack) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: layerStack (LayerStack)

IsInvalidAssetPath(resolvedAssetPath) → bool#

Returns true if resolvedAssetPath was used by a prim (e.g.

in a reference) but did not resolve to a valid asset. This is functionally equivalent to examining the values in the map returned by GetInvalidAssetPaths, but more efficient.

Parameters:: resolvedAssetPath (str)

IsInvalidSublayerIdentifier(identifier) → bool#

Returns true if identifier was used as a sublayer path in a layer stack but did not identify a valid layer.

This is functionally equivalent to examining the values in the vector returned by GetInvalidSublayerIdentifiers, but more efficient.

Parameters:: identifier (str)

IsLayerMuted(layerIdentifier) → bool#

Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise.

If layerIdentifier is relative, it is assumed to be relative to this cache’s root layer. See documentation on RequestLayerMuting for more details.

Parameters:: layerIdentifier (str)

IsLayerMuted(anchorLayer, layerIdentifier, canonicalMutedLayerIdentifier) -> bool

Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise.

If layerIdentifier is relative, it is assumed to be relative to anchorLayer . If canonicalMutedLayerIdentifier is supplied, it will be populated with the canonical identifier of the muted layer if this function returns true. See documentation on RequestLayerMuting for more details.

Parameters:

anchorLayer (Layer)
layerIdentifier (str)
canonicalMutedLayerIdentifier (str)

IsPayloadIncluded(path) → bool#

Return true if the payload is included for the given path.

Parameters:: path (Path)

IsPossibleDynamicFileFormatArgumentField(field) → bool#

Returns true if the given field is the name of a field that was composed while generating dynamic file format arguments for any prim index in this cache.

Parameters:: field (str)

PrintStatistics() → None#: Prints various statistics about the data stored in this cache.

Reload(changes) → None#

Reload the layers of the layer stack, except session layers and sublayers of session layers.

This will also try to load sublayers in this cache’s layer stack that could not be loaded previously. It will also try to load any referenced or payloaded layer that could not be loaded previously. Clients should subsequently Apply() changes to use any now- valid layers.

Parameters:: changes (PcpChanges)

RequestLayerMuting( layersToMute, layersToUnmute, changes, newLayersMuted, newLayersUnmuted, ) → None#

Request layers to be muted or unmuted in this cache.

Muted layers are ignored during composition and do not appear in any layer stacks. The root layer of this stage may not be muted; attempting to do so will generate a coding error. If the root layer of a reference or payload layer stack is muted, the behavior is as if the muted layer did not exist, which means a composition error will be generated.

A canonical identifier for each layer in layersToMute will be computed using ArResolver::CreateIdentifier using the cache’s root layer as the anchoring asset. Any layer encountered during composition with the same identifier will be considered muted and ignored.

Note that muting a layer will cause this cache to release all references to that layer. If no other client is holding on to references to that layer, it will be unloaded. In this case, if there are unsaved edits to the muted layer, those edits are lost. Since anonymous layers are not serialized, muting an anonymous layer will cause that layer and its contents to be lost in this case.

If changes is not nullptr , it is adjusted to reflect the changes necessary to see the change in muted layers. Otherwise, those changes are applied immediately.

newLayersMuted and newLayersUnmuted contains the pruned vector of layers which are muted or unmuted by this call to RequestLayerMuting.

Parameters:

layersToMute (list[str])
layersToUnmute (list[str])
changes (PcpChanges)
newLayersMuted (list[str])
newLayersUnmuted (list[str])

RequestPayloads(pathsToInclude, pathsToExclude, changes) → None#

Request payloads to be included or excluded from composition.

pathsToInclude

is a set of paths to add to the set for payload inclusion. pathsToExclude

is a set of paths to remove from the set for payload inclusion. changes

if not None , is adjusted to reflect the changes necessary to see the change in payloads; otherwise those changes are applied immediately.

If a path is listed in both pathsToInclude and pathsToExclude, it will be treated as an inclusion only.

Parameters:

pathsToInclude (SdfPathSet)
pathsToExclude (SdfPathSet)
changes (PcpChanges)

SetVariantFallbacks(map, changes) → None#

Set the list of fallbacks to attempt to use when evaluating variant sets that lack an authored selection.

If changes is not None then it’s adjusted to reflect the changes necessary to see the change in standin preferences, otherwise those changes are applied immediately.

Parameters:

map (PcpVariantFallbackMap)
changes (PcpChanges)

UsesLayerStack(layerStack) → bool#

Return true if layerStack is used by this cache in its composition, false otherwise.

Parameters:: layerStack (LayerStack)

property fileFormatTarget#

str

Returns the file format target this cache is configured for.

Type:: type

property layerStack#

LayerStack

Get the layer stack for GetLayerStackIdentifier() .

Note that this will neither compute the layer stack nor report errors. So if the layer stack has not been computed yet this will return None . Use ComputeLayerStack() if you need to compute the layer stack if it hasn’t been computed already and/or get errors caused by computing the layer stack.

Type:: type

class pxr.Pcp.Dependency#

Description of a dependency.

Attributes:

`indexPath`
`mapFunc`
`sitePath`

property indexPath#

property mapFunc#

property sitePath#

class pxr.Pcp.DependencyType#

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()#

allValues = (Pcp.DependencyTypeNone, Pcp.DependencyTypeRoot, Pcp.DependencyTypePurelyDirect, Pcp.DependencyTypePartlyDirect, Pcp.DependencyTypeDirect, Pcp.DependencyTypeAncestral, Pcp.DependencyTypeVirtual, Pcp.DependencyTypeNonVirtual, Pcp.DependencyTypeAnyNonVirtual, Pcp.DependencyTypeAnyIncludingVirtual)#

class pxr.Pcp.DynamicFileFormatDependencyData#

Contains the necessary information for storing a prim index’s dependency on dynamic file format arguments and determining if a field change affects the prim index. This data structure does not store the prim index or its path itself and is expected to be the data in some other data structure that maps prim indexes to its dependencies.

Methods:

`CanFieldChangeAffectFileFormatArguments`(...)	Given a `field` name and the changed field values in `oldAndNewValues` this return whether this change can affect any of the file format arguments generated by any of the contexts stored in this dependency.
`GetRelevantFieldNames`()	Returns a list of field names that were composed for any of the dependency contexts that were added to this dependency.
`IsEmpty`()	Returns whether this dependency data is empty.

CanFieldChangeAffectFileFormatArguments( fieldName, oldValue, newValue, ) → bool#

Given a field name and the changed field values in oldAndNewValues this return whether this change can affect any of the file format arguments generated by any of the contexts stored in this dependency.

Parameters:

fieldName (str)
oldValue (VtValue)
newValue (VtValue)

GetRelevantFieldNames() → str.Set#: Returns a list of field names that were composed for any of the dependency contexts that were added to this dependency.

IsEmpty() → bool#: Returns whether this dependency data is empty.

class pxr.Pcp.ErrorArcCycle#: Arcs between PcpNodes that form a cycle.

class pxr.Pcp.ErrorArcPermissionDenied#: Arcs that were not made between PcpNodes because of permission restrictions.

class pxr.Pcp.ErrorBase#

Base class for all error types.

Attributes:

errorType

property errorType#

class pxr.Pcp.ErrorCapacityExceeded#: Exceeded the capacity for composition arcs at a single site.

class pxr.Pcp.ErrorInconsistentAttributeType#: Attributes that have specs with conflicting definitions.

class pxr.Pcp.ErrorInconsistentAttributeVariability#: Attributes that have specs with conflicting variability.

class pxr.Pcp.ErrorInconsistentPropertyType#: Properties that have specs with conflicting definitions.

class pxr.Pcp.ErrorInvalidAssetPath#: Invalid asset paths used by references or payloads.

class pxr.Pcp.ErrorInvalidAssetPathBase#

class pxr.Pcp.ErrorInvalidExternalTargetPath#: Invalid target or connection path in some scope that points to an object outside of that scope.

class pxr.Pcp.ErrorInvalidInstanceTargetPath#: Invalid target or connection path authored in an inherited class that points to an instance of that class.

class pxr.Pcp.ErrorInvalidPrimPath#: Invalid prim paths used by references or payloads.

class pxr.Pcp.ErrorInvalidReferenceOffset#: References or payloads that use invalid layer offsets.

class pxr.Pcp.ErrorInvalidSublayerOffset#: Sublayers that use invalid layer offsets.

class pxr.Pcp.ErrorInvalidSublayerOwnership#: Sibling layers that have the same owner.

class pxr.Pcp.ErrorInvalidSublayerPath#: Asset paths that could not be both resolved and loaded.

class pxr.Pcp.ErrorInvalidTargetPath#: Invalid target or connection path.

class pxr.Pcp.ErrorMutedAssetPath#: Muted asset paths used by references or payloads.

class pxr.Pcp.ErrorOpinionAtRelocationSource#: Opinions were found at a relocation source path.

class pxr.Pcp.ErrorPrimPermissionDenied#: Layers with illegal opinions about private prims.

class pxr.Pcp.ErrorPropertyPermissionDenied#: Layers with illegal opinions about private properties.

class pxr.Pcp.ErrorSublayerCycle#: Layers that recursively sublayer themselves.

class pxr.Pcp.ErrorTargetPathBase#: Base class for composition errors related to target or connection paths.

class pxr.Pcp.ErrorTargetPermissionDenied#: Paths with illegal opinions about private targets.

class pxr.Pcp.ErrorType#

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()#

allValues = (Pcp.ErrorType_ArcCycle, Pcp.ErrorType_ArcPermissionDenied, Pcp.ErrorType_IndexCapacityExceeded, Pcp.ErrorType_ArcCapacityExceeded, Pcp.ErrorType_ArcNamespaceDepthCapacityExceeded, Pcp.ErrorType_InconsistentPropertyType, Pcp.ErrorType_InconsistentAttributeType, Pcp.ErrorType_InconsistentAttributeVariability, Pcp.ErrorType_InternalAssetPath, Pcp.ErrorType_InvalidPrimPath, Pcp.ErrorType_InvalidAssetPath, Pcp.ErrorType_InvalidInstanceTargetPath, Pcp.ErrorType_InvalidExternalTargetPath, Pcp.ErrorType_InvalidTargetPath, Pcp.ErrorType_InvalidReferenceOffset, Pcp.ErrorType_InvalidSublayerOffset, Pcp.ErrorType_InvalidSublayerOwnership, Pcp.ErrorType_InvalidSublayerPath, Pcp.ErrorType_InvalidVariantSelection, Pcp.ErrorType_OpinionAtRelocationSource, Pcp.ErrorType_PrimPermissionDenied, Pcp.ErrorType_PropertyPermissionDenied, Pcp.ErrorType_SublayerCycle, Pcp.ErrorType_TargetPermissionDenied, Pcp.ErrorType_UnresolvedPrimPath)#

class pxr.Pcp.ErrorUnresolvedPrimPath#: Asset paths that could not be both resolved and loaded.

class pxr.Pcp.InstanceKey#: A PcpInstanceKey identifies instanceable prim indexes that share the same set of opinions. Instanceable prim indexes with equal instance keys are guaranteed to have the same opinions for name children and properties beneath those name children. They are NOT guaranteed to have the same opinions for direct properties of the prim indexes themselves.

class pxr.Pcp.LayerStack#

Represents a stack of layers that contribute opinions to composition.

Each PcpLayerStack is identified by a PcpLayerStackIdentifier. This identifier contains all of the parameters needed to construct a layer stack, such as the root layer, session layer, and path resolver context.

PcpLayerStacks are constructed and managed by a Pcp_LayerStackRegistry.

Attributes:

`expired`	True if this object has expired, False otherwise.
`identifier`	LayerStackIdentifier
`incrementalRelocatesSourceToTarget`	SdfRelocatesMap
`incrementalRelocatesTargetToSource`	SdfRelocatesMap
`layerOffsets`
`layerTree`	LayerTree
`layers`	list[Layer]
`localErrors`	list[PcpError]
`mutedLayers`	set[str]
`pathsToPrimsWithRelocates`	list[Path]
`relocatesSourceToTarget`	SdfRelocatesMap
`relocatesTargetToSource`	SdfRelocatesMap

property expired#: True if this object has expired, False otherwise.

property identifier#

LayerStackIdentifier

Returns the identifier for this layer stack.

Type:: type

property incrementalRelocatesSourceToTarget#

SdfRelocatesMap

Returns incremental relocation source-to-target mapping for this layer stack.

This map contains the individual relocation entries found across all layers in this layer stack; it does not combine ancestral entries with descendant entries. For instance, if this layer stack contains relocations { /A: /B} and { /A/C: /A/D}, this map will contain { /A: /B} and { /A/C: /A/D}.

Type:: type

property incrementalRelocatesTargetToSource#

SdfRelocatesMap

Returns incremental relocation target-to-source mapping for this layer stack.

See GetIncrementalRelocatesTargetToSource for more details.

Type:: type

property layerOffsets#

property layerTree#

LayerTree

Returns the layer tree representing the structure of this layer stack.

Type:: type

property layers#

list[Layer]

Returns the layers in this layer stack in strong-to-weak order.

Note that this is only the local layer stack it does not include any layers brought in by references inside prims.

Type:: type

property localErrors#

list[PcpError]

Return the list of errors local to this layer stack.

Type:: type

property mutedLayers#

set[str]

Returns the set of layers that were muted in this layer stack.

Type:: type

property pathsToPrimsWithRelocates#

list[Path]

Returns a list of paths to all prims across all layers in this layer stack that contained relocates.

Type:: type

property relocatesSourceToTarget#

SdfRelocatesMap

Returns relocation source-to-target mapping for this layer stack.

This map combines the individual relocation entries found across all layers in this layer stack; multiple entries that affect a single prim will be combined into a single entry. For instance, if this layer stack contains relocations { /A: /B} and { /A/C: /A/D}, this map will contain { /A: /B} and { /B/C: /B/D}. This allows consumers to go from unrelocated namespace to relocated namespace in a single step.

Type:: type

property relocatesTargetToSource#

SdfRelocatesMap

Returns relocation target-to-source mapping for this layer stack.

See GetRelocatesSourceToTarget for more details.

Type:: type

class pxr.Pcp.LayerStackIdentifier#

Arguments used to identify a layer stack.

Objects of this type are immutable.

Attributes:

`pathResolverContext`
`rootLayer`
`sessionLayer`

property pathResolverContext#

property rootLayer#

property sessionLayer#

class pxr.Pcp.LayerStackSite#

A site specifies a path in a layer stack of scene description.

Attributes:

`layerStack`
`path`

property layerStack#

property path#

class pxr.Pcp.MapExpression#

An expression that yields a PcpMapFunction value.

Expressions comprise constant values, variables, and operators applied to sub-expressions. Expressions cache their computed values internally. Assigning a new value to a variable automatically invalidates the cached values of dependent expressions. Common (sub-)expressions are automatically detected and shared.

PcpMapExpression exists solely to support efficient incremental handling of relocates edits. It represents a tree of the namespace mapping operations and their inputs, so we can narrowly redo the computation when one of the inputs changes.

Methods:

`AddRootIdentity`()	Return a new expression representing this expression with an added (if necessary) mapping from</>to</>.
`Compose`(f)	Create a new PcpMapExpression representing the application of f's value, followed by the application of this expression's value.
`Constant`	classmethod Constant(constValue) -> MapExpression
`Evaluate`()	Evaluate this expression, yielding a PcpMapFunction value.
`Identity`	classmethod Identity() -> MapExpression
`Inverse`()	Create a new PcpMapExpression representing the inverse of f.
`MapSourceToTarget`(path)	Map a path in the source namespace to the target.
`MapTargetToSource`(path)	Map a path in the target namespace to the source.

Attributes:

`isIdentity`	bool
`isNull`	bool
`timeOffset`	LayerOffset

AddRootIdentity() → MapExpression#: Return a new expression representing this expression with an added (if necessary) mapping from</>to</>.

Compose(f) → MapExpression#

Create a new PcpMapExpression representing the application of f’s value, followed by the application of this expression’s value.

Parameters:: f (MapExpression)

static Constant()#

classmethod Constant(constValue) -> MapExpression

Create a new constant.

Parameters:: constValue (Value)

Evaluate() → Value#

Evaluate this expression, yielding a PcpMapFunction value.

The computed result is cached. The return value is a reference to the internal cached value. The cache is automatically invalidated as needed.

static Identity()#

classmethod Identity() -> MapExpression

Return an expression representing PcpMapFunction::Identity() .

static Inverse() → MapExpression#: Create a new PcpMapExpression representing the inverse of f.

MapSourceToTarget(path) → Path#

Map a path in the source namespace to the target.

If the path is not in the domain, returns an empty path.

Parameters:: path (Path)

MapTargetToSource(path) → Path#

Map a path in the target namespace to the source.

If the path is not in the co-domain, returns an empty path.

Parameters:: path (Path)

property isIdentity#

bool

Return true if the evaluated map function is the identity function.

For identity, MapSourceToTarget() always returns the path unchanged.

Type:: type

property isNull#

bool

Return true if this is a null expression.

Type:: type

property timeOffset#

LayerOffset

The time offset of the mapping.

Type:: type

class pxr.Pcp.MapFunction#

A function that maps values from one namespace (and time domain) to another. It represents the transformation that an arc such as a reference arc applies as it incorporates values across the arc.

Take the example of a reference arc, where a source path</Model>is referenced as a target path,</Model_1>. The source path</Model>is the source of the opinions; the target path</Model_1>is where they are incorporated in the scene. Values in the model that refer to paths relative to</Model>must be transformed to be relative to</Model_1>instead. The PcpMapFunction for the arc provides this service.

Map functions have a specific domain, or set of values they can operate on. Any values outside the domain cannot be mapped. The domain precisely tracks what areas of namespace can be referred to across various forms of arcs.

Map functions can be chained to represent a series of map operations applied in sequence. The map function represent the cumulative effect as efficiently as possible. For example, in the case of a chained reference from</Model>to</Model>to</Model>to</Model_1>, this is effectively the same as a mapping directly from</Model>to</Model_1>. Representing the cumulative effect of arcs in this way is important for handling larger scenes efficiently.

Map functions can be inverted. Formally, map functions are bijections (one-to-one and onto), which ensures that they can be inverted. Put differently, no information is lost by applying a map function to set of values within its domain; they retain their distinct identities and can always be mapped back.

One analogy that may or may not be helpful: In the same way a geometric transform maps a model’s points in its rest space into the world coordinates for a particular instance, a PcpMapFunction maps values about a referenced model into the composed scene for a particular instance of that model. But rather than translating and rotating points, the map function shifts the values in namespace (and time).

Methods:

`Compose`(f)	Compose this map over the given map function.
`ComposeOffset`(newOffset)	Compose this map function over a hypothetical map function that has an identity path mapping and `offset` .
`GetInverse`()	Return the inverse of this map function.
`Identity`	classmethod Identity() -> MapFunction
`IdentityPathMap`	classmethod IdentityPathMap() -> PathMap
`MapSourceToTarget`(path)	Map a path in the source namespace to the target.
`MapTargetToSource`(path)	Map a path in the target namespace to the source.

Attributes:

`isIdentity`	bool
`isIdentityPathMapping`	bool
`isNull`	bool
`sourceToTargetMap`	PathMap
`timeOffset`	LayerOffset

Compose(f) → MapFunction#

Compose this map over the given map function.

The result will represent the application of f followed by the application of this function.

Parameters:: f (MapFunction)

ComposeOffset(newOffset) → MapFunction#

Compose this map function over a hypothetical map function that has an identity path mapping and offset .

This is equivalent to building such a map function and invoking Compose() , but is faster.

Parameters:: newOffset (LayerOffset)

GetInverse() → MapFunction#

Return the inverse of this map function.

This returns a true inverse inv: for any path p in this function’s domain that it maps to p’, inv(p’) ->p.

static Identity()#

classmethod Identity() -> MapFunction

Construct an identity map function.

static IdentityPathMap()#

classmethod IdentityPathMap() -> PathMap

Returns an identity path mapping.

MapSourceToTarget(path) → Path#

Map a path in the source namespace to the target.

If the path is not in the domain, returns an empty path.

Parameters:: path (Path)

MapTargetToSource(path) → Path#

Map a path in the target namespace to the source.

If the path is not in the co-domain, returns an empty path.

Parameters:: path (Path)

property isIdentity#

bool

Return true if the map function is the identity function.

The identity function has an identity path mapping and time offset.

Type:: type

property isIdentityPathMapping#

bool

Return true if the map function uses the identity path mapping.

If true, MapSourceToTarget() always returns the path unchanged. However, this map function may have a non-identity time offset.

Type:: type

property isNull#

bool

Return true if this map function is the null function.

For a null function, MapSourceToTarget() always returns an empty path.

Type:: type

property sourceToTargetMap#

PathMap

The set of path mappings, from source to target.

Type:: type

property timeOffset#

LayerOffset

The time offset of the mapping.

Type:: type

class pxr.Pcp.NodeRef#

PcpNode represents a node in an expression tree for compositing scene description.

A node represents the opinions from a particular site. In addition, it may have child nodes, representing nested expressions that are composited over/under this node.

Child nodes are stored and composited in strength order.

Each node holds information about the arc to its parent. This captures both the relative strength of the sub-expression as well as any value- mapping needed, such as to rename opinions from a model to use in a particular instance.

Methods:

`CanContributeSpecs`()	Returns true if this node is allowed to contribute opinions for composition, false otherwise.
`GetDepthBelowIntroduction`()	Return the number of levels of namespace this node's site is below the level at which it was introduced by an arc.
`GetIntroPath`()	Get the path that introduced this node.
`GetOriginRootNode`()	Walk up to the root origin node for this node.
`GetPathAtIntroduction`()	Returns the path for this node's site when it was introduced.
`GetRootNode`()	Walk up to the root node of this expression.
`IsDueToAncestor`()
`IsRootNode`()	Returns true if this node is the root node of the prim index graph.

Attributes:

`arcType`	ArcType
`children`
`hasSpecs`	None
`hasSymmetry`	None
`isCulled`	bool
`isInert`	bool
`isRestricted`	bool
`layerStack`	LayerStack
`mapToParent`	MapExpression
`mapToRoot`	MapExpression
`namespaceDepth`	int
`origin`
`parent`
`path`	Path
`permission`	Permission
`siblingNumAtOrigin`	int
`site`	LayerStackSite

CanContributeSpecs() → bool#: Returns true if this node is allowed to contribute opinions for composition, false otherwise.

GetDepthBelowIntroduction() → int#: Return the number of levels of namespace this node’s site is below the level at which it was introduced by an arc.

GetIntroPath() → Path#

Get the path that introduced this node.

Specifically, this is the path the parent node had at the level of namespace where this node was added as a child. For a root node, this returns the absolute root path. See also GetDepthBelowIntroduction() .

GetOriginRootNode() → NodeRef#

Walk up to the root origin node for this node.

This is the very first node that caused this node to be added to the graph. For instance, the root origin node of an implied inherit is the original inherit node.

GetPathAtIntroduction() → Path#: Returns the path for this node’s site when it was introduced.

GetRootNode() → NodeRef#: Walk up to the root node of this expression.

IsDueToAncestor() → bool#

IsRootNode() → bool#: Returns true if this node is the root node of the prim index graph.

property arcType#

ArcType

Returns the type of arc connecting this node to its parent node.

Type:: type

property children#

property hasSpecs#

None

Returns true if this node has opinions authored for composition, false otherwise.

Type:: type

property hasSymmetry#

None

Get/set whether this node provides any symmetry opinions, either directly or from a namespace ancestor.

Type:: type

property isCulled#

bool

Type:: type

property isInert#

bool

Type:: type

property isRestricted#

bool

Type:: type

property layerStack#

LayerStack

Returns the layer stack for the site this node represents.

Type:: type

property mapToParent#

MapExpression

Returns mapping function used to translate paths and values from this node to its parent node.

Type:: type

property mapToRoot#

MapExpression

Returns mapping function used to translate paths and values from this node directly to the root node.

Type:: type

property namespaceDepth#

int

Returns the absolute namespace depth of the node that introduced this node.

Note that this does not count any variant selections.

Type:: type

property origin#

property parent#

property path#

Path

Returns the path for the site this node represents.

Type:: type

property permission#

Permission

type : None

Get/set the permission for this node.

This indicates whether specs on this node can be accessed from other nodes.

Type:: type

property siblingNumAtOrigin#

int

Returns this node’s index among siblings with the same arc type at this node’s origin.

Type:: type

property site#

LayerStackSite

Get the site this node represents.

Type:: type

class pxr.Pcp.PrimIndex#

PcpPrimIndex is an index of the all sites of scene description that contribute opinions to a specific prim, under composition semantics.

PcpComputePrimIndex() builds an index (“indexes”) the given prim site. At any site there may be scene description values expressing arcs that represent instructions to pull in further scene description. PcpComputePrimIndex() recursively follows these arcs, building and ordering the results.

Methods:

`ComposeAuthoredVariantSelections`()	Compose the authored prim variant selections.
`ComputePrimChildNames`(nameOrder, ...)	Compute the prim child names for the given path.
`ComputePrimPropertyNames`(nameOrder)	Compute the prim property names for the given path.
`DumpToDotGraph`(filename, ...)	Dump the prim index in dot format to the file named `filename` .
`DumpToString`(includeInheritOriginInfo, ...)	Dump the prim index contents to a string.
`GetNodeProvidingSpec`(primSpec)	Returns the node that brings opinions from `primSpec` into this prim index.
`GetSelectionAppliedForVariantSet`(variantSet)	Return the variant selection applied for the named variant set.
`IsInstanceable`()	Returns true if this prim index is instanceable.
`IsValid`()	Return true if this index is valid.
`PrintStatistics`()	Prints various statistics about this prim index.

Attributes:

`hasAnyPayloads`
`localErrors`	list[PcpError]
`primStack`
`rootNode`	NodeRef

ComposeAuthoredVariantSelections() → SdfVariantSelectionMap#

Compose the authored prim variant selections.

These are the variant selections expressed in scene description. Note that these selections may not have actually been applied, if they are invalid.

This result is not cached, but computed each time.

ComputePrimChildNames(nameOrder, prohibitedNameSet) → None#

Compute the prim child names for the given path.

errors will contain any errors encountered while performing this operation.

Parameters:

nameOrder (list[str])
prohibitedNameSet (PcpTokenSet)

ComputePrimPropertyNames(nameOrder) → None#

Compute the prim property names for the given path.

errors will contain any errors encountered while performing this operation. The nameOrder vector must not contain any duplicate entries.

Parameters:: nameOrder (list[str])

DumpToDotGraph( filename, includeInheritOriginInfo, includeMaps, ) → None#

Dump the prim index in dot format to the file named filename .

See Dump(...) for information regarding arguments.

Parameters:

filename (str)
includeInheritOriginInfo (bool)
includeMaps (bool)

DumpToString(includeInheritOriginInfo, includeMaps) → str#

Dump the prim index contents to a string.

If includeInheritOriginInfo is true , output for implied inherit nodes will include information about the originating inherit node. If includeMaps is true , output for each node will include the mappings to the parent and root node.

Parameters:

includeInheritOriginInfo (bool)
includeMaps (bool)

GetNodeProvidingSpec(primSpec) → NodeRef#

Returns the node that brings opinions from primSpec into this prim index.

If no such node exists, returns an invalid PcpNodeRef.

Parameters:: primSpec (PrimSpec)

GetNodeProvidingSpec(layer, path) -> NodeRef

Returns the node that brings opinions from the Sd prim spec at layer and path into this prim index.

If no such node exists, returns an invalid PcpNodeRef.

Parameters:

layer (Layer)
path (Path)

GetSelectionAppliedForVariantSet(variantSet) → str#

Return the variant selection applied for the named variant set.

If none was applied, this returns an empty string. This can be different from the authored variant selection; for example, if the authored selection is invalid.

Parameters:: variantSet (str)

IsInstanceable() → bool#

Returns true if this prim index is instanceable.

Instanceable prim indexes with the same instance key are guaranteed to have the same set of opinions, but may not have local opinions about name children.

PcpInstanceKey

IsValid() → bool#

Return true if this index is valid.

A default-constructed index is invalid.

PrintStatistics() → None#: Prints various statistics about this prim index.

property hasAnyPayloads#

property localErrors#

list[PcpError]

Return the list of errors local to this prim.

Type:: type

property primStack#

property rootNode#

NodeRef

Returns the root node of the prim index graph.

Type:: type

class pxr.Pcp.PropertyIndex#

PcpPropertyIndex is an index of all sites in scene description that contribute opinions to a specific property, under composition semantics.

Attributes:

`localErrors`	list[PcpError]
`localPropertyStack`
`propertyStack`

property localErrors#

list[PcpError]

Return the list of errors local to this property.

Type:: type

property localPropertyStack#

property propertyStack#

class pxr.Pcp.Site#

A site specifies a path in a layer stack of scene description.

Attributes:

`layerStack`
`path`

property layerStack#

property path#