HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
authoring.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_UTILS_AUTHORING_H
25 #define PXR_USD_USD_UTILS_AUTHORING_H
26 
27 /// \file usdUtils/authoring.h
28 ///
29 /// A collection of utilities for higher-level authoring and copying scene
30 /// description than provided by the core Usd and Sdf API's
31 
32 #include "pxr/pxr.h"
33 
34 #include "pxr/base/tf/hashset.h"
35 
37 #include "pxr/usd/usd/stage.h"
38 #include "pxr/usd/usdUtils/api.h"
40 
42 
44 
45 /// Given two layers \p source and \p destination, copy the authored metadata
46 /// from one to the other. By default, copy **all** authored metadata;
47 /// however, you can skip certain classes of metadata with the parameter
48 /// \p skipSublayers, which will prevent copying subLayers or subLayerOffsets
49 ///
50 /// Makes no attempt to clear metadata that may already be authored in
51 /// \p destination, but any fields that are already in \p destination but also
52 /// in \p source will be replaced.
53 ///
54 /// Certain bits of layer metadata (eg. colorConfiguration and
55 /// colorManagementSystem) can have their fallback values specified in the
56 /// plugInfo.json files of plugins. When such metadata is unauthored in the
57 /// source layer, if \p bakeUnauthoredFallbacks is set to true, then the
58 /// fallback values are baked into the destination layer.
59 ///
60 /// \return \c true on success, \c false on error.
62 bool UsdUtilsCopyLayerMetadata(const SdfLayerHandle &source,
63  const SdfLayerHandle &destination,
64  bool skipSublayers = false,
65  bool bakeUnauthoredFallbacks = false);
66 
68 
69 /// \anchor UsdUtilsAuthoring_Collections
70 /// \name API for computing and authoring collections
71 /// @{
72 
73 /// Computes the optimal set of paths to include and the set of paths to
74 /// exclude below includes paths, in order to encode an "expandPrims"
75 /// collection that contains the subtrees of prims rooted at
76 /// \p includedRootPaths.
77 ///
78 /// The algorithm used to determine a compact representation is driven
79 /// by the following three parameters: \p minInclusionRatio,
80 /// \p maxNumExcludesBelowInclude and \p minIncludeExcludeCollectionSize.
81 /// See below for their descriptions.
82 ///
83 /// \p usdStage is the USD stage to which the paths in \p includedRootPaths
84 /// belong.
85 /// \p pathsToInclude is populated with the set of paths to include. Any
86 /// existing paths in the set are cleared before adding paths to it.
87 /// \p pathsToExclude is populated with the set of paths to exclude. Any
88 /// existing paths in the set are cleared before adding paths to it.
89 /// \p minInclusionRatio is the minimum value of the ratio between the number
90 /// of included paths and the sum of the number of included and excluded paths
91 /// below an ancestor path, at or above which the ancestor path is included in
92 /// the collection. For example, if an ancestor prim has four children and
93 /// three out of the four are included in the collection, the inclusion ratio
94 /// at the ancestor is 0.75. This value should be in the range (0,1), if not,
95 /// it's clamped to the range.
96 /// \p maxNumExcludesBelowInclude is the maximum number of paths that we exclude
97 /// below any ancestor path that we include in a collection. This parameter only
98 /// affects paths that have already passed the min-inclusion-ratio test.
99 /// Setting this to 0 will cause all collections to have includes only (and no
100 /// excludes). Setting it to a higher number will cause ancestor paths that are
101 /// higher up in the namespace hierarchy to be included in collections.
102 /// \p minIncludeExcludeCollectionSize is the minimum size of a collection
103 /// (i.e. the number of subtree-root paths included in it), at or
104 /// above which the algorithm chooses to make a collection with both included
105 /// and excluded paths, instead of creating a collection with only includes
106 /// (containing the specified set of paths). \ref UsdCollectionAPI
107 /// \p pathsToIgnore is the list of paths to be ignored by the algorithm used
108 /// to determine the included and excluded paths for each collection. If
109 /// non-empty, the paths in the hash set don't contribute towards the counts and
110 /// ratios computed by the algorithm.
111 ///
112 /// Returns false if paths in \p includedRootPaths (or their common ancestor)
113 /// can't be found on the given \p usdStage.
114 /// parameters has an invalid value.
115 ///
116 /// The python version of this function returns a tuple containing the
117 /// two lists (pathsToInclude, pathsToExclude).
120  const SdfPathSet &includedRootPaths,
121  const UsdStageWeakPtr &usdStage,
122  SdfPathVector *pathsToInclude,
123  SdfPathVector *pathsToExclude,
124  double minInclusionRatio=0.75,
125  const unsigned int maxNumExcludesBelowInclude=5u,
126  const unsigned int minIncludeExcludeCollectionSize=3u,
127  const UsdUtilsPathHashSet &pathsToIgnore=UsdUtilsPathHashSet());
128 
129 /// Authors a collection named \p collectionName on the given prim,
130 /// \p usdPrim with the given set of included paths (\p pathsToInclude)
131 /// and excluded paths (\p pathsToExclude).
132 ///
133 /// If a collection with the specified name already exists on \p usdPrim,
134 /// its data is appended to. The resulting collection will contain
135 /// both the old paths and the newly included paths.
138  const TfToken &collectionName,
139  const UsdPrim &usdPrim,
140  const SdfPathVector &pathsToInclude,
141  const SdfPathVector &pathsToExclude=SdfPathVector());
142 
143 /// Given a vector of (collection-name, path-set) pairs, \p assignments,
144 /// creates and returns a vector of collections that include subtrees of prims
145 /// rooted at the included paths. The collections are created on the given prim,
146 /// \p usdPrim.
147 ///
148 /// Based on the paths included in the various collections, this function
149 /// computes a compact representation for each collection in parallel
150 /// using UsdUtilsGetCollectionIncludesExcludes(). So, it takes the
151 /// same set of parameters as that function: \p minInclusionRatio,
152 /// \p maxNumExcludesBelowInclude and \p minIncludeExcludeCollectionSize.
153 ///
154 /// \note It is valid for the paths or subtrees specified in \p assignments
155 /// to have overlapping subtrees. In this case the overlapping bits will belong
156 /// to multiple collections.
157 ///
158 /// \p assignments is a vector of pairs representing collection names and paths
159 /// to be included in the collection in each collection.
160 /// \p usdPrim is the prim on which the collections are created.
161 /// \p minInclusionRatio is the minimum value of the ratio between the number
162 /// of included paths and the sum of the number of included and excluded paths
163 /// below an ancestor path, at or above which the ancestor path is included in
164 /// the collection. For example, if an ancestor prim has four children and
165 /// three out of the four are included in the collection, the inclusion ratio
166 /// at the ancestor is 0.75. This value should be in the range (0,1), if not,
167 /// it's clamped to the range.
168 /// \p maxNumExcludesBelowInclude is the maximum number of paths that we exclude
169 /// below any ancestor path that we include in a collection. This parameter only
170 /// affects paths that have already passed the min-inclusion-ratio test.
171 /// Setting this to 0 will cause all collections to have includes only (and no
172 /// excludes). Setting it to a higher number will cause ancestor paths that are
173 /// higher up in the namespace hierarchy to be included in collections.
174 /// \p minIncludeExcludeCollectionSize is the minimum size of a collection
175 /// (i.e. the number of subtree-root paths included in it), at or
176 /// above which the algorithm chooses to make a collection with both included
177 /// and excluded paths, instead of creating a collection with only includes
178 /// (containing the specified set of paths). \ref UsdCollectionAPI
179 ///
180 /// Returns the vector of UsdCollectionAPI objects that were created.
181 /// If a collection is empty (i.e. includes no paths), then an empty collection
182 /// is created for it with the default expansionRule. Hence, the size of the
183 /// returned vector should match the size of \p assignments.
185 std::vector<UsdCollectionAPI> UsdUtilsCreateCollections(
186  const std::vector<std::pair<TfToken, SdfPathSet>> &assignments,
187  const UsdPrim &usdPrim,
188  const double minInclusionRatio=0.75,
189  const unsigned int maxNumExcludesBelowInclude=5u,
190  const unsigned int minIncludeExcludeCollectionSize=3u);
191 
192 /// @}
193 
194 /// Retrieve a list of all dirty layers from the stage's UsedLayers.
196 SdfLayerHandleVector UsdUtilsGetDirtyLayers(UsdStagePtr stage,
197  bool includeClipLayers = true);
198 
200 
201 #endif /* PXR_USD_USD_UTILS_AUTHORING_H */
Definition: layer.h:93
USDUTILS_API SdfLayerHandleVector UsdUtilsGetDirtyLayers(UsdStagePtr stage, bool includeClipLayers=true)
Retrieve a list of all dirty layers from the stage's UsedLayers.
GLsizei GLsizei GLchar * source
Definition: glew.h:1832
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
Definition: token.h:87
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)
Definition: prim.h:132
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())
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:207
UsdStagePtr UsdStageWeakPtr
Definition: common.h:55
USDUTILS_API UsdCollectionAPI UsdUtilsAuthorCollection(const TfToken &collectionName, const UsdPrim &usdPrim, const SdfPathVector &pathsToInclude, const SdfPathVector &pathsToExclude=SdfPathVector())
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TfHashSet< SdfPath, SdfPath::Hash > UsdUtilsPathHashSet
Definition: authoring.h:67
#define USDUTILS_API
Definition: api.h:40
USDUTILS_API bool UsdUtilsCopyLayerMetadata(const SdfLayerHandle &source, const SdfLayerHandle &destination, bool skipSublayers=false, bool bakeUnauthoredFallbacks=false)