authoring.h File Reference

#include "pxr/pxr.h"
#include "pxr/base/tf/hashset.h"
#include "pxr/usd/usd/collectionAPI.h"
#include "pxr/usd/usd/stage.h"
#include "pxr/usd/usdUtils/api.h"
#include "pxr/usd/sdf/declareHandles.h"

Include dependency graph for authoring.h:

Go to the source code of this file.

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

Functions
PXR_NAMESPACE_OPEN_SCOPE	SDF_DECLARE_HANDLES (SdfLayer)
USDUTILS_API bool	UsdUtilsCopyLayerMetadata (const SdfLayerHandle &source, const SdfLayerHandle &destination, bool skipSublayers=false, bool bakeUnauthoredFallbacks=false)
USDUTILS_API SdfLayerHandleVector	UsdUtilsGetDirtyLayers (UsdStagePtr stage, bool includeClipLayers=true)
	Retrieve a list of all dirty layers from the stage's UsedLayers. More...
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())
USDUTILS_API UsdCollectionAPI	UsdUtilsAuthorCollection (const TfToken &collectionName, const UsdPrim &usdPrim, const SdfPathVector &pathsToInclude, const SdfPathVector &pathsToExclude=SdfPathVector())
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)

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

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

Definition at line 67 of file authoring.h.

Function Documentation

PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES

(

SdfLayer

)

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.

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

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.

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.

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

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