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