This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
authoring.h File Reference

A collection of utilities for higher-level authoring and copying scene description than provided by the core Usd and Sdf API's. More...

+ Include dependency graph for authoring.h:

Go to the source code of this file.

Typedefs

using UsdUtilsPathHashSet = TfHashSet< SdfPath, SdfPath::Hash >
 

Functions

 SDF_DECLARE_HANDLES (SdfLayer)
 
USDUTILS_API bool UsdUtilsCopyLayerMetadata (const SdfLayerHandle &source, const SdfLayerHandle &destination, bool skipSublayers=false, bool bakeUnauthoredFallbacks=false)
 Given two layers source and destination, copy the authored metadata from one to the other.
 
USDUTILS_API SdfLayerHandleVector UsdUtilsGetDirtyLayers (UsdStagePtr stage, bool includeClipLayers=true)
 Retrieve a list of all dirty layers from the stage's UsedLayers.
 
API for computing and authoring collections

USDUTILS_API bool UsdUtilsComputeCollectionIncludesAndExcludes (const SdfPathSet &includedRootPaths, const UsdStageWeakPtr &usdStage, SdfPathVector *pathsToInclude, SdfPathVector *pathsToExclude, double minInclusionRatio=0.75, const unsigned int maxNumExcludesBelowInclude=5u, const unsigned int minIncludeExcludeCollectionSize=3u, const UsdUtilsPathHashSet &pathsToIgnore=UsdUtilsPathHashSet())
 Computes the optimal set of paths to include and the set of paths to exclude below includes paths, in order to encode an "expandPrims" collection that contains the subtrees of prims rooted at includedRootPaths.
 
USDUTILS_API UsdCollectionAPI UsdUtilsAuthorCollection (const TfToken &collectionName, const UsdPrim &usdPrim, const SdfPathVector &pathsToInclude, const SdfPathVector &pathsToExclude=SdfPathVector())
 Authors a collection named collectionName on the given prim, usdPrim with the given set of included paths (pathsToInclude) and excluded paths (pathsToExclude).
 
USDUTILS_API std::vector< UsdCollectionAPIUsdUtilsCreateCollections (const std::vector< std::pair< TfToken, SdfPathSet > > &assignments, const UsdPrim &usdPrim, const double minInclusionRatio=0.75, const unsigned int maxNumExcludesBelowInclude=5u, const unsigned int minIncludeExcludeCollectionSize=3u)
 Given a vector of (collection-name, path-set) pairs, assignments, creates and returns a vector of collections that include subtrees of prims rooted at the included paths.
 

Detailed Description

A collection of utilities for higher-level authoring and copying scene description than provided by the core Usd and Sdf API's.

Definition in file authoring.h.

Typedef Documentation

◆ UsdUtilsPathHashSet

using UsdUtilsPathHashSet = TfHashSet<SdfPath, SdfPath::Hash>

Definition at line 50 of file authoring.h.

Function Documentation

◆ UsdUtilsAuthorCollection()

USDUTILS_API UsdCollectionAPI UsdUtilsAuthorCollection ( const TfToken collectionName,
const UsdPrim usdPrim,
const SdfPathVector &  pathsToInclude,
const SdfPathVector &  pathsToExclude = SdfPathVector() 
)

Authors a collection named collectionName on the given prim, usdPrim with the given set of included paths (pathsToInclude) and excluded paths (pathsToExclude).

If a collection with the specified name already exists on usdPrim, its data is appended to. The resulting collection will contain both the old paths and the newly included paths.

◆ UsdUtilsComputeCollectionIncludesAndExcludes()

USDUTILS_API bool UsdUtilsComputeCollectionIncludesAndExcludes ( const SdfPathSet &  includedRootPaths,
const UsdStageWeakPtr &  usdStage,
SdfPathVector *  pathsToInclude,
SdfPathVector *  pathsToExclude,
double  minInclusionRatio = 0.75,
const unsigned int  maxNumExcludesBelowInclude = 5u,
const unsigned int  minIncludeExcludeCollectionSize = 3u,
const UsdUtilsPathHashSet &  pathsToIgnore = UsdUtilsPathHashSet() 
)

Computes the optimal set of paths to include and the set of paths to exclude below includes paths, in order to encode an "expandPrims" collection that contains the subtrees of prims rooted at includedRootPaths.

The algorithm used to determine a compact representation is driven by the following three parameters: minInclusionRatio, maxNumExcludesBelowInclude and minIncludeExcludeCollectionSize. See below for their descriptions.

usdStage is the USD stage to which the paths in includedRootPaths belong. pathsToInclude is populated with the set of paths to include. Any existing paths in the set are cleared before adding paths to it. pathsToExclude is populated with the set of paths to exclude. Any existing paths in the set are cleared before adding paths to it. minInclusionRatio is the minimum value of the ratio between the number of included paths and the sum of the number of included and excluded paths below an ancestor path, at or above which the ancestor path is included in the collection. For example, if an ancestor prim has four children and three out of the four are included in the collection, the inclusion ratio at the ancestor is 0.75. This value should be in the range (0,1), if not, it's clamped to the range. maxNumExcludesBelowInclude is the maximum number of paths that we exclude below any ancestor path that we include in a collection. This parameter only affects paths that have already passed the min-inclusion-ratio test. Setting this to 0 will cause all collections to have includes only (and no excludes). Setting it to a higher number will cause ancestor paths that are higher up in the namespace hierarchy to be included in collections. minIncludeExcludeCollectionSize is the minimum size of a collection (i.e. the number of subtree-root paths included in it), at or above which the algorithm chooses to make a collection with both included and excluded paths, instead of creating a collection with only includes (containing the specified set of paths). UsdCollectionAPI pathsToIgnore is the list of paths to be ignored by the algorithm used to determine the included and excluded paths for each collection. If non-empty, the paths in the hash set don't contribute towards the counts and ratios computed by the algorithm.

Returns false if paths in includedRootPaths (or their common ancestor) can't be found on the given usdStage. parameters has an invalid value.

The python version of this function returns a tuple containing the two lists (pathsToInclude, pathsToExclude).

◆ UsdUtilsCopyLayerMetadata()

USDUTILS_API bool UsdUtilsCopyLayerMetadata ( const SdfLayerHandle &  source,
const SdfLayerHandle &  destination,
bool  skipSublayers = false,
bool  bakeUnauthoredFallbacks = false 
)

Given two layers source and destination, copy the authored metadata from one to the other.

By default, copy all authored metadata; however, you can skip certain classes of metadata with the parameter skipSublayers, which will prevent copying subLayers or subLayerOffsets

Makes no attempt to clear metadata that may already be authored in destination, but any fields that are already in destination but also in source will be replaced.

Certain bits of layer metadata (eg. colorConfiguration and colorManagementSystem) can have their fallback values specified in the plugInfo.json files of plugins. When such metadata is unauthored in the source layer, if bakeUnauthoredFallbacks is set to true, then the fallback values are baked into the destination layer.

Returns
true on success, false on error.

◆ UsdUtilsCreateCollections()

USDUTILS_API std::vector< UsdCollectionAPI > UsdUtilsCreateCollections ( const std::vector< std::pair< TfToken, SdfPathSet > > &  assignments,
const UsdPrim usdPrim,
const double  minInclusionRatio = 0.75,
const unsigned int  maxNumExcludesBelowInclude = 5u,
const unsigned int  minIncludeExcludeCollectionSize = 3u 
)

Given a vector of (collection-name, path-set) pairs, assignments, creates and returns a vector of collections that include subtrees of prims rooted at the included paths.

The collections are created on the given prim, usdPrim.

Based on the paths included in the various collections, this function computes a compact representation for each collection in parallel using UsdUtilsGetCollectionIncludesExcludes(). So, it takes the same set of parameters as that function: minInclusionRatio, maxNumExcludesBelowInclude and minIncludeExcludeCollectionSize.

Note
It is valid for the paths or subtrees specified in assignments to have overlapping subtrees. In this case the overlapping bits will belong to multiple collections.

assignments is a vector of pairs representing collection names and paths to be included in the collection in each collection. usdPrim is the prim on which the collections are created. minInclusionRatio is the minimum value of the ratio between the number of included paths and the sum of the number of included and excluded paths below an ancestor path, at or above which the ancestor path is included in the collection. For example, if an ancestor prim has four children and three out of the four are included in the collection, the inclusion ratio at the ancestor is 0.75. This value should be in the range (0,1), if not, it's clamped to the range. maxNumExcludesBelowInclude is the maximum number of paths that we exclude below any ancestor path that we include in a collection. This parameter only affects paths that have already passed the min-inclusion-ratio test. Setting this to 0 will cause all collections to have includes only (and no excludes). Setting it to a higher number will cause ancestor paths that are higher up in the namespace hierarchy to be included in collections. minIncludeExcludeCollectionSize is the minimum size of a collection (i.e. the number of subtree-root paths included in it), at or above which the algorithm chooses to make a collection with both included and excluded paths, instead of creating a collection with only includes (containing the specified set of paths). UsdCollectionAPI

Returns the vector of UsdCollectionAPI objects that were created. If a collection is empty (i.e. includes no paths), then an empty collection is created for it with the default expansionRule. Hence, the size of the returned vector should match the size of assignments.

◆ UsdUtilsGetDirtyLayers()

USDUTILS_API SdfLayerHandleVector UsdUtilsGetDirtyLayers ( UsdStagePtr  stage,
bool  includeClipLayers = true 
)

Retrieve a list of all dirty layers from the stage's UsedLayers.