1#usda 1.0 2( 3 "WARNING: THIS FILE IS GENERATED BY usdGenSchema. DO NOT EDIT." 4) 5 6class "Imageable" ( 7 doc = """Base class for all prims that may require rendering or 8 visualization of some sort. The primary attributes of Imageable 9 are visibility and purpose, which each provide instructions for 10 what geometry should be included for processing by rendering and other 11 computations. 12 13 \\deprecated Imageable also provides API for accessing primvars, which 14 has been moved to the UsdGeomPrimvarsAPI schema, because primvars can now 15 be applied on non-Imageable prim types. This API is planned 16 to be removed, UsdGeomPrimvarsAPI should be used directly instead.""" 17) 18{ 19 rel proxyPrim ( 20 doc = '''The proxyPrim relationship allows us to link a 21 prim whose purpose is "render" to its (single target) 22 purpose="proxy" prim. This is entirely optional, but can be 23 useful in several scenarios: 24 25 - In a pipeline that does pruning (for complexity management) 26 by deactivating prims composed from asset references, when we 27 deactivate a purpose="render" prim, we will be able to discover 28 and additionally deactivate its associated purpose="proxy" prim, 29 so that preview renders reflect the pruning accurately. 30 31 - DCC importers may be able to make more aggressive optimizations 32 for interactive processing and display if they can discover the proxy 33 for a given render prim. 34 35 - With a little more work, a Hydra-based application will be able 36 to map a picked proxy prim back to its render geometry for selection. 37 38 \\note It is only valid to author the proxyPrim relationship on 39 prims whose purpose is "render".''' 40 ) 41 uniform token purpose = "default" ( 42 allowedTokens = ["default", "render", "proxy", "guide"] 43 doc = """Purpose is a classification of geometry into categories that 44 can each be independently included or excluded from traversals of prims 45 on a stage, such as rendering or bounding-box computation traversals. 46 47 See for more detail about how 48 purpose is computed and used.""" 49 ) 50 token visibility = "inherited" ( 51 allowedTokens = ["inherited", "invisible"] 52 doc = '''Visibility is meant to be the simplest form of "pruning" 53 visibility that is supported by most DCC apps. Visibility is 54 animatable, allowing a sub-tree of geometry to be present for some 55 segment of a shot, and absent from others; unlike the action of 56 deactivating geometry prims, invisible geometry is still 57 available for inspection, for positioning, for defining volumes, etc.''' 58 ) 59} 60 61class "VisibilityAPI" ( 62 doc = ''' 63 UsdGeomVisibilityAPI introduces properties that can be used to author 64 visibility opinions. 65 66 \\note 67 Currently, this schema only introduces the attributes that are used to 68 control purpose visibility. Later, this schema will define _all_ 69 visibility-related properties and UsdGeomImageable will no longer define 70 those properties. 71 72 The purpose visibility attributes added by this schema, 73 _guideVisibility_, _proxyVisibility_, and _renderVisibility_ can each be 74 used to control visibility for geometry of the corresponding purpose 75 values, with the overall _visibility_ attribute acting as an 76 override. I.e., if _visibility_ evaluates to "invisible", purpose 77 visibility is invisible; otherwise, purpose visibility is determined by 78 the corresponding purpose visibility attribute. 79 80 Note that the behavior of _guideVisibility_ is subtly different from the 81 _proxyVisibility_ and _renderVisibility_ attributes, in that "guide" 82 purpose visibility always evaluates to either "invisible" or "visible", 83 whereas the other attributes may yield computed values of "inherited" if 84 there is no authored opinion on the attribute or inherited from an 85 ancestor. This is motivated by the fact that, in Pixar"s user workflows, 86 we have never found a need to have all guides visible in a scene by 87 default, whereas we do find that flexibility useful for "proxy" and 88 "render" geometry. 89 90 This schema can only be applied to UsdGeomImageable prims. The 91 UseGeomImageable schema provides API for computing the purpose visibility 92 values that result from the attributes introduced by this schema. 93 ''' 94) 95{ 96 uniform token guideVisibility = "invisible" ( 97 allowedTokens = ["inherited", "invisible", "visible"] 98 doc = ''' 99 This attribute controls visibility for geometry with purpose "guide". 100 101 Unlike overall _visibility_, _guideVisibility_ is uniform, and 102 therefore cannot be animated. 103 104 Also unlike overall _visibility_, _guideVisibility_ is tri-state, in 105 that a descendant with an opinion of "visible" overrides an ancestor 106 opinion of "invisible". 107 108 The _guideVisibility_ attribute works in concert with the overall 109 _visibility_ attribute: The visibility of a prim with purpose "guide" 110 is determined by the inherited values it receives for the _visibility_ 111 and _guideVisibility_ attributes. If _visibility_ evaluates to 112 "invisible", the prim is invisible. If _visibility_ evaluates to 113 "inherited" and _guideVisibility_ evaluates to "visible", then the 114 prim is visible. __Otherwise, it is invisible.__ 115 ''' 116 ) 117 uniform token proxyVisibility = "inherited" ( 118 allowedTokens = ["inherited", "invisible", "visible"] 119 doc = ''' 120 This attribute controls visibility for geometry with purpose "proxy". 121 122 Unlike overall _visibility_, _proxyVisibility_ is uniform, and 123 therefore cannot be animated. 124 125 Also unlike overall _visibility_, _proxyVisibility_ is tri-state, in 126 that a descendant with an opinion of "visible" overrides an ancestor 127 opinion of "invisible". 128 129 The _proxyVisibility_ attribute works in concert with the overall 130 _visibility_ attribute: The visibility of a prim with purpose "proxy" 131 is determined by the inherited values it receives for the _visibility_ 132 and _proxyVisibility_ attributes. If _visibility_ evaluates to 133 "invisible", the prim is invisible. If _visibility_ evaluates to 134 "inherited" then: If _proxyVisibility_ evaluates to "visible", then 135 the prim is visible; if _proxyVisibility_ evaluates to "invisible", 136 then the prim is invisible; if _proxyVisibility_ evaluates to 137 "inherited", then the prim may either be visible or invisible, 138 depending on a fallback value determined by the calling context. 139 ''' 140 ) 141 uniform token renderVisibility = "inherited" ( 142 allowedTokens = ["inherited", "invisible", "visible"] 143 doc = ''' 144 This attribute controls visibility for geometry with purpose 145 "render". 146 147 Unlike overall _visibility_, _renderVisibility_ is uniform, and 148 therefore cannot be animated. 149 150 Also unlike overall _visibility_, _renderVisibility_ is tri-state, in 151 that a descendant with an opinion of "visible" overrides an ancestor 152 opinion of "invisible". 153 154 The _renderVisibility_ attribute works in concert with the overall 155 _visibility_ attribute: The visibility of a prim with purpose "render" 156 is determined by the inherited values it receives for the _visibility_ 157 and _renderVisibility_ attributes. If _visibility_ evaluates to 158 "invisible", the prim is invisible. If _visibility_ evaluates to 159 "inherited" then: If _renderVisibility_ evaluates to "visible", then 160 the prim is visible; if _renderVisibility_ evaluates to "invisible", 161 then the prim is invisible; if _renderVisibility_ evaluates to 162 "inherited", then the prim may either be visible or invisible, 163 depending on a fallback value determined by the calling context. 164 ''' 165 ) 166} 167 168class "PrimvarsAPI" ( 169 doc = """UsdGeomPrimvarsAPI encodes geometric \"primitive variables\", 170 as UsdGeomPrimvar, which interpolate across a primitive's topology, 171 can override shader inputs, and inherit down namespace. 172 173 Which Method to Use to Retrieve Primvars 174 175 While creating primvars is unambiguous (CreatePrimvar()), there are quite 176 a few methods available for retrieving primvars, making it potentially 177 confusing knowing which one to use. Here are some guidelines: 178 179 - If you are populating a GUI with the primvars already available for 180 authoring values on a prim, use GetPrimvars(). 181 - If you want all of the \"useful\" (e.g. to a renderer) primvars 182 available at a prim, including those inherited from ancestor prims, use 183 FindPrimvarsWithInheritance(). Note that doing so individually for many 184 prims will be inefficient. 185 - To find a particular primvar defined directly on a prim, which may 186 or may not provide a value, use GetPrimvar(). 187 - To find a particular primvar defined on a prim or inherited from 188 ancestors, which may or may not provide a value, use 189 FindPrimvarWithInheritance(). 190 - To *efficiently* query for primvars using the overloads of 191 FindPrimvarWithInheritance() and FindPrimvarsWithInheritance(), one 192 must first cache the results of FindIncrementallyInheritablePrimvars() for 193 each non-leaf prim on the stage. """ 194) 195{ 196} 197 198class "Xformable" ( 199 doc = """Base class for all transformable prims, which allows arbitrary 200 sequences of component affine transformations to be encoded. 201 202 \\note 203 You may find it useful to review while reading 204 this class description. 205 206 <b>Supported Component Transformation Operations</b> 207 208 UsdGeomXformable currently supports arbitrary sequences of the following 209 operations, each of which can be encoded in an attribute of the proper 210 shape in any supported precision: 211 - translate - 3D 212 - scale - 3D 213 - rotateX - 1D angle in degrees 214 - rotateY - 1D angle in degrees 215 - rotateZ - 1D angle in degrees 216 - rotateABC - 3D where ABC can be any combination of the six principle 217 Euler Angle sets: XYZ, XZY, YXZ, YZX, ZXY, ZYX. See 218 \"note on rotation packing order\" 219 - orient - 4D (quaternion) 220 - transform - 4x4D 221 222 <b>Creating a Component Transformation</b> 223 224 To add components to a UsdGeomXformable prim, simply call AddXformOp() 225 with the desired op type, as enumerated in \\ref UsdGeomXformOp::Type, 226 and the desired precision, which is one of \\ref UsdGeomXformOp::Precision. 227 Optionally, you can also provide an \"op suffix\" for the operator that 228 disambiguates it from other components of the same type on the same prim. 229 Application-specific transform schemas can use the suffixes to fill a role 230 similar to that played by AbcGeom::XformOp's \"Hint\" enums for their own 231 round-tripping logic. 232 233 We also provide specific \"Add\" API for each type, for clarity and 234 conciseness, e.g. AddTranslateOp(), AddRotateXYZOp() etc. 235 236 AddXformOp() will return a UsdGeomXformOp object, which is a schema on a 237 newly created UsdAttribute that provides convenience API for authoring 238 and computing the component transformations. The UsdGeomXformOp can then 239 be used to author any number of timesamples and default for the op. 240 241 Each successive call to AddXformOp() adds an operator that will be applied 242 \"more locally\" than the preceding operator, just as if we were pushing 243 transforms onto a transformation stack - which is precisely what should 244 happen when the operators are consumed by a reader. 245 246 \\note 247 If you can, please try to use the UsdGeomXformCommonAPI, which wraps 248 the UsdGeomXformable with an interface in which Op creation is taken 249 care of for you, and there is a much higher chance that the data you 250 author will be importable without flattening into other DCC's, as it 251 conforms to a fixed set of Scale-Rotate-Translate Ops. 252 253 \\sa \"Using the Authoring API\" 254 255 <b>Data Encoding and Op Ordering</b> 256 257 Because there is no \"fixed schema\" of operations, all of the attributes 258 that encode transform operations are dynamic, and are scoped in 259 the namespace \"xformOp\". The second component of an attribute's name provides 260 the type of operation, as listed above. An \"xformOp\" attribute can 261 have additional namespace components derived from the opSuffix argument 262 to the AddXformOp() suite of methods, which provides a preferred way of 263 naming the ops such that we can have multiple \"translate\" ops with unique 264 attribute names. For example, in the attribute named 265 \"xformOp:translate:maya:pivot\", \"translate\" is the type of operation and 266 \"maya:pivot\" is the suffix. 267 268 The following ordered list of attribute declarations in usda 269 define a basic Scale-Rotate-Translate with XYZ Euler angles, wherein the 270 translation is double-precision, and the remainder of the ops are single, 271 in which we will: 272 273 <ol> 274 <li> Scale by 2.0 in each dimension 275 <li> Rotate about the X, Y, and Z axes by 30, 60, and 90 degrees, respectively 276 <li> Translate by 100 units in the Y direction 277 </ol> 278 279 \\code 280 float3 xformOp:rotateXYZ = (30, 60, 90) 281 float3 xformOp:scale = (2, 2, 2) 282 double3 xformOp:translate = (0, 100, 0) 283 uniform token[] xformOpOrder = [ \"xformOp:translate\", \"xformOp:rotateXYZ\", \"xformOp:scale\" ] 284 \\endcode 285 286 The attributes appear in the dictionary order in which USD, by default, 287 sorts them. To ensure the ops are recovered and evaluated in the correct 288 order, the schema introduces the **xformOpOrder** attribute, which 289 contains the names of the op attributes, in the precise sequence in which 290 they should be pushed onto a transform stack. **Note** that the order is 291 opposite to what you might expect, given the matrix algebra described in 292 This also dictates order of op creation, 293 since each call to AddXformOp() adds a new op to the end of the 294 \\b xformOpOrder array, as a new \"most-local\" operation. See 295 \"Example 2 below\" for C++ code that could 296 have produced this USD. 297 298 If it were important for the prim's rotations to be independently 299 overridable, we could equivalently (at some performance cost) encode 300 the transformation also like so: 301 \\code 302 float xformOp:rotateX = 30 303 float xformOp:rotateY = 60 304 float xformOp:rotateZ = 90 305 float3 xformOp:scale = (2, 2, 2) 306 double3 xformOp:translate = (0, 100, 0) 307 uniform token[] xformOpOrder = [ \"xformOp:translate\", \"xformOp:rotateZ\", \"xformOp:rotateY\", \"xformOp:rotateX\", \"xformOp:scale\" ] 308 \\endcode 309 310 Again, note that although we are encoding an XYZ rotation, the three 311 rotations appear in the **xformOpOrder** in the opposite order, with Z, 312 followed, by Y, followed by X. 313 314 Were we to add a Maya-style scalePivot to the above example, it might 315 look like the following: 316 \\code 317 float3 xformOp:rotateXYZ = (30, 60, 90) 318 float3 xformOp:scale = (2, 2, 2) 319 double3 xformOp:translate = (0, 100, 0) 320 double3 xformOp:translate:scalePivot 321 uniform token[] xformOpOrder = [ \"xformOp:translate\", \"xformOp:rotateXYZ\", \"xformOp:translate:scalePivot\", \"xformOp:scale\" ] 322 \\endcode 323 324 <b>Paired \"Inverted\" Ops</b> 325 326 We have been claiming that the ordered list of ops serves as a set 327 of instructions to a transform stack, but you may have noticed in the last 328 example that there is a missing operation - the pivot for the scale op 329 needs to be applied in its inverse-form as a final (most local) op! In the 330 AbcGeom::Xform schema, we would have encoded an actual \"final\" translation 331 op whose value was authored by the exporter as the negation of the pivot's 332 value. However, doing so would be brittle in USD, given that each op can 333 be independently overridden, and the constraint that one attribute must be 334 maintained as the negation of the other in order for successful 335 re-importation of the schema cannot be expressed in USD. 336 337 Our solution leverages the **xformOpOrder** member of the schema, which, 338 in addition to ordering the ops, may also contain one of two special 339 tokens that address the paired op and \"stack resetting\" behavior. 340 341 The \"paired op\" behavior is encoded as an \"!invert!\" prefix in 342 \\b xformOpOrder, as the result of an AddXformOp(isInverseOp=True) call. 343 The \\b xformOpOrder for the last example would look like: 344 \\code 345 uniform token[] xformOpOrder = [ \"xformOp:translate\", \"xformOp:rotateXYZ\", \"xformOp:translate:scalePivot\", \"xformOp:scale\", \"!invert!xformOp:translate:scalePivot\" ] 346 \\endcode 347 348 When asked for its value via UsdGeomXformOp::GetOpTransform(), an 349 \"inverted\" Op (i.e. the \"inverted\" half of a set of paired Ops) will fetch 350 the value of its paired attribute and return its negation. This works for 351 all op types - an error will be issued if a \"transform\" type op is singular 352 and cannot be inverted. When getting the authored value of an inverted op 353 via UsdGeomXformOp::Get(), the raw, uninverted value of the associated 354 attribute is returned. 355 356 For the sake of robustness, <b>setting a value on an inverted op is disallowed.</b> 357 Attempting to set a value on an inverted op will result in a coding error 358 and no value being set. 359 360 <b>Resetting the Transform Stack</b> 361 362 The other special op/token that can appear in xformOpOrder is 363 \"!resetXformStack!\", which, appearing as the first element of 364 xformOpOrder, indicates this prim should not inherit the transformation 365 of its namespace parent. See SetResetXformStack() 366 367 <b>Expected Behavior for \"Missing\" Ops</b> 368 369 If an importer expects Scale-Rotate-Translate operations, but a prim 370 has only translate and rotate ops authored, the importer should assume 371 an identity scale. This allows us to optimize the data a bit, if only 372 a few components of a very rich schema (like Maya's) are authored in the 373 app. 374 375 \\anchor usdGeom_xformableExamples 376 <b>Using the C++ API</b> 377 378 #1. Creating a simple transform matrix encoding 379 \\snippet examples.cpp CreateMatrixWithDefault 380 381 #2. Creating the simple SRT from the example above 382 \\snippet examples.cpp CreateExampleSRT 383 384 #3. Creating a parameterized SRT with pivot using UsdGeomXformCommonAPI 385 \\snippet examples.cpp CreateSRTWithDefaults 386 387 #4. Creating a rotate-only pivot transform with animated 388 rotation and translation 389 \\snippet examples.cpp CreateAnimatedTransform 390 391""" 392) 393{ 394 rel proxyPrim ( 395 doc = '''The proxyPrim relationship allows us to link a 396 prim whose purpose is "render" to its (single target) 397 purpose="proxy" prim. This is entirely optional, but can be 398 useful in several scenarios: 399 400 - In a pipeline that does pruning (for complexity management) 401 by deactivating prims composed from asset references, when we 402 deactivate a purpose="render" prim, we will be able to discover 403 and additionally deactivate its associated purpose="proxy" prim, 404 so that preview renders reflect the pruning accurately. 405 406 - DCC importers may be able to make more aggressive optimizations 407 for interactive processing and display if they can discover the proxy 408 for a given render prim. 409 410 - With a little more work, a Hydra-based application will be able 411 to map a picked proxy prim back to its render geometry for selection. 412 413 \\note It is only valid to author the proxyPrim relationship on 414 prims whose purpose is "render".''' 415 ) 416 uniform token purpose = "default" ( 417 allowedTokens = ["default", "render", "proxy", "guide"] 418 doc = """Purpose is a classification of geometry into categories that 419 can each be independently included or excluded from traversals of prims 420 on a stage, such as rendering or bounding-box computation traversals. 421 422 See for more detail about how 423 purpose is computed and used.""" 424 ) 425 token visibility = "inherited" ( 426 allowedTokens = ["inherited", "invisible"] 427 doc = '''Visibility is meant to be the simplest form of "pruning" 428 visibility that is supported by most DCC apps. Visibility is 429 animatable, allowing a sub-tree of geometry to be present for some 430 segment of a shot, and absent from others; unlike the action of 431 deactivating geometry prims, invisible geometry is still 432 available for inspection, for positioning, for defining volumes, etc.''' 433 ) 434 uniform token[] xformOpOrder ( 435 doc = """Encodes the sequence of transformation operations in the 436 order in which they should be pushed onto a transform stack while 437 visiting a UsdStage's prims in a graph traversal that will effect 438 the desired positioning for this prim and its descendant prims. 439 440 You should rarely, if ever, need to manipulate this attribute directly. 441 It is managed by the AddXformOp(), SetResetXformStack(), and 442 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 443 GetLocalTransformation().""" 444 ) 445} 446 447class Scope "Scope" ( 448 doc = """Scope is the simplest grouping primitive, and does not carry the 449 baggage of transformability. Note that transforms should inherit down 450 through a Scope successfully - it is just a guaranteed no-op from a 451 transformability perspective.""" 452) 453{ 454 rel proxyPrim ( 455 doc = '''The proxyPrim relationship allows us to link a 456 prim whose purpose is "render" to its (single target) 457 purpose="proxy" prim. This is entirely optional, but can be 458 useful in several scenarios: 459 460 - In a pipeline that does pruning (for complexity management) 461 by deactivating prims composed from asset references, when we 462 deactivate a purpose="render" prim, we will be able to discover 463 and additionally deactivate its associated purpose="proxy" prim, 464 so that preview renders reflect the pruning accurately. 465 466 - DCC importers may be able to make more aggressive optimizations 467 for interactive processing and display if they can discover the proxy 468 for a given render prim. 469 470 - With a little more work, a Hydra-based application will be able 471 to map a picked proxy prim back to its render geometry for selection. 472 473 \\note It is only valid to author the proxyPrim relationship on 474 prims whose purpose is "render".''' 475 ) 476 uniform token purpose = "default" ( 477 allowedTokens = ["default", "render", "proxy", "guide"] 478 doc = """Purpose is a classification of geometry into categories that 479 can each be independently included or excluded from traversals of prims 480 on a stage, such as rendering or bounding-box computation traversals. 481 482 See for more detail about how 483 purpose is computed and used.""" 484 ) 485 token visibility = "inherited" ( 486 allowedTokens = ["inherited", "invisible"] 487 doc = '''Visibility is meant to be the simplest form of "pruning" 488 visibility that is supported by most DCC apps. Visibility is 489 animatable, allowing a sub-tree of geometry to be present for some 490 segment of a shot, and absent from others; unlike the action of 491 deactivating geometry prims, invisible geometry is still 492 available for inspection, for positioning, for defining volumes, etc.''' 493 ) 494} 495 496class Xform "Xform" ( 497 doc = "Concrete prim schema for a transform, which implements Xformable " 498) 499{ 500 rel proxyPrim ( 501 doc = '''The proxyPrim relationship allows us to link a 502 prim whose purpose is "render" to its (single target) 503 purpose="proxy" prim. This is entirely optional, but can be 504 useful in several scenarios: 505 506 - In a pipeline that does pruning (for complexity management) 507 by deactivating prims composed from asset references, when we 508 deactivate a purpose="render" prim, we will be able to discover 509 and additionally deactivate its associated purpose="proxy" prim, 510 so that preview renders reflect the pruning accurately. 511 512 - DCC importers may be able to make more aggressive optimizations 513 for interactive processing and display if they can discover the proxy 514 for a given render prim. 515 516 - With a little more work, a Hydra-based application will be able 517 to map a picked proxy prim back to its render geometry for selection. 518 519 \\note It is only valid to author the proxyPrim relationship on 520 prims whose purpose is "render".''' 521 ) 522 uniform token purpose = "default" ( 523 allowedTokens = ["default", "render", "proxy", "guide"] 524 doc = """Purpose is a classification of geometry into categories that 525 can each be independently included or excluded from traversals of prims 526 on a stage, such as rendering or bounding-box computation traversals. 527 528 See for more detail about how 529 purpose is computed and used.""" 530 ) 531 token visibility = "inherited" ( 532 allowedTokens = ["inherited", "invisible"] 533 doc = '''Visibility is meant to be the simplest form of "pruning" 534 visibility that is supported by most DCC apps. Visibility is 535 animatable, allowing a sub-tree of geometry to be present for some 536 segment of a shot, and absent from others; unlike the action of 537 deactivating geometry prims, invisible geometry is still 538 available for inspection, for positioning, for defining volumes, etc.''' 539 ) 540 uniform token[] xformOpOrder ( 541 doc = """Encodes the sequence of transformation operations in the 542 order in which they should be pushed onto a transform stack while 543 visiting a UsdStage's prims in a graph traversal that will effect 544 the desired positioning for this prim and its descendant prims. 545 546 You should rarely, if ever, need to manipulate this attribute directly. 547 It is managed by the AddXformOp(), SetResetXformStack(), and 548 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 549 GetLocalTransformation().""" 550 ) 551} 552 553class "Boundable" ( 554 doc = """Boundable introduces the ability for a prim to persistently 555 cache a rectilinear, local-space, extent. 556 557 Why Extent and not Bounds ? 558 Boundable introduces the notion of \"extent\", which is a cached computation 559 of a prim's local-space 3D range for its resolved attributes <b>at the 560 layer and time in which extent is authored</b>. We have found that with 561 composed scene description, attempting to cache pre-computed bounds at 562 interior prims in a scene graph is very fragile, given the ease with which 563 one can author a single attribute in a stronger layer that can invalidate 564 many authored caches - or with which a re-published, referenced asset can 565 do the same. 566 567 Therefore, we limit to precomputing (generally) leaf-prim extent, which 568 avoids the need to read in large point arrays to compute bounds, and 569 provides UsdGeomBBoxCache the means to efficiently compute and 570 (session-only) cache intermediate bounds. You are free to compute and 571 author intermediate bounds into your scenes, of course, which may work 572 well if you have sufficient locks on your pipeline to guarantee that once 573 authored, the geometry and transforms upon which they are based will 574 remain unchanged, or if accuracy of the bounds is not an ironclad 575 requisite. 576 577 When intermediate bounds are authored on Boundable parents, the child prims 578 will be pruned from BBox computation; the authored extent is expected to 579 incorporate all child bounds.""" 580) 581{ 582 float3[] extent ( 583 doc = """Extent is a three dimensional range measuring the geometric 584 extent of the authored gprim in its own local space (i.e. its own 585 transform not applied), without accounting for any shader-induced 586 displacement. Whenever any geometry-affecting attribute is authored 587 for any gprim in a layer, extent must also be authored at the same 588 timesample; failure to do so will result in incorrect bounds-computation. 589 \\sa \\ref UsdGeom_Boundable_Extent. 590 591 An authored extent on a prim which has children is expected to include 592 the extent of all children, as they will be pruned from BBox computation 593 during traversal.""" 594 ) 595 rel proxyPrim ( 596 doc = '''The proxyPrim relationship allows us to link a 597 prim whose purpose is "render" to its (single target) 598 purpose="proxy" prim. This is entirely optional, but can be 599 useful in several scenarios: 600 601 - In a pipeline that does pruning (for complexity management) 602 by deactivating prims composed from asset references, when we 603 deactivate a purpose="render" prim, we will be able to discover 604 and additionally deactivate its associated purpose="proxy" prim, 605 so that preview renders reflect the pruning accurately. 606 607 - DCC importers may be able to make more aggressive optimizations 608 for interactive processing and display if they can discover the proxy 609 for a given render prim. 610 611 - With a little more work, a Hydra-based application will be able 612 to map a picked proxy prim back to its render geometry for selection. 613 614 \\note It is only valid to author the proxyPrim relationship on 615 prims whose purpose is "render".''' 616 ) 617 uniform token purpose = "default" ( 618 allowedTokens = ["default", "render", "proxy", "guide"] 619 doc = """Purpose is a classification of geometry into categories that 620 can each be independently included or excluded from traversals of prims 621 on a stage, such as rendering or bounding-box computation traversals. 622 623 See for more detail about how 624 purpose is computed and used.""" 625 ) 626 token visibility = "inherited" ( 627 allowedTokens = ["inherited", "invisible"] 628 doc = '''Visibility is meant to be the simplest form of "pruning" 629 visibility that is supported by most DCC apps. Visibility is 630 animatable, allowing a sub-tree of geometry to be present for some 631 segment of a shot, and absent from others; unlike the action of 632 deactivating geometry prims, invisible geometry is still 633 available for inspection, for positioning, for defining volumes, etc.''' 634 ) 635 uniform token[] xformOpOrder ( 636 doc = """Encodes the sequence of transformation operations in the 637 order in which they should be pushed onto a transform stack while 638 visiting a UsdStage's prims in a graph traversal that will effect 639 the desired positioning for this prim and its descendant prims. 640 641 You should rarely, if ever, need to manipulate this attribute directly. 642 It is managed by the AddXformOp(), SetResetXformStack(), and 643 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 644 GetLocalTransformation().""" 645 ) 646} 647 648class "Gprim" ( 649 doc = '''Base class for all geometric primitives. 650 651 Gprim encodes basic graphical properties such as doubleSided and 652 orientation, and provides primvars for "display color" and "display 653 opacity" that travel with geometry to be used as shader overrides. ''' 654) 655{ 656 uniform bool doubleSided = 0 ( 657 doc = """Although some renderers treat all parametric or polygonal 658 surfaces as if they were effectively laminae with outward-facing 659 normals on both sides, some renderers derive significant optimizations 660 by considering these surfaces to have only a single outward side, 661 typically determined by control-point winding order and/or 662 orientation. By doing so they can perform \"backface culling\" to 663 avoid drawing the many polygons of most closed surfaces that face away 664 from the viewer. 665 666 However, it is often advantageous to model thin objects such as paper 667 and cloth as single, open surfaces that must be viewable from both 668 sides, always. Setting a gprim's doubleSided attribute to 669 \\c true instructs all renderers to disable optimizations such as 670 backface culling for the gprim, and attempt (not all renderers are able 671 to do so, but the USD reference GL renderer always will) to provide 672 forward-facing normals on each side of the surface for lighting 673 calculations.""" 674 ) 675 float3[] extent ( 676 doc = """Extent is a three dimensional range measuring the geometric 677 extent of the authored gprim in its own local space (i.e. its own 678 transform not applied), without accounting for any shader-induced 679 displacement. Whenever any geometry-affecting attribute is authored 680 for any gprim in a layer, extent must also be authored at the same 681 timesample; failure to do so will result in incorrect bounds-computation. 682 \\sa \\ref UsdGeom_Boundable_Extent. 683 684 An authored extent on a prim which has children is expected to include 685 the extent of all children, as they will be pruned from BBox computation 686 during traversal.""" 687 ) 688 uniform token orientation = "rightHanded" ( 689 allowedTokens = ["rightHanded", "leftHanded"] 690 doc = """Orientation specifies whether the gprim's surface normal 691 should be computed using the right hand rule, or the left hand rule. 692 Please see for a deeper explanation and 693 generalization of orientation to composed scenes with transformation 694 hierarchies.""" 695 ) 696 color3f[] primvars:displayColor ( 697 doc = '''It is useful to have an "official" colorSet that can be used 698 as a display or modeling color, even in the absence of any specified 699 shader for a gprim. DisplayColor serves this role; because it is a 700 UsdGeomPrimvar, it can also be used as a gprim override for any shader 701 that consumes a displayColor parameter.''' 702 ) 703 float[] primvars:displayOpacity ( 704 doc = """Companion to displayColor that specifies opacity, broken 705 out as an independent attribute rather than an rgba color, both so that 706 each can be independently overridden, and because shaders rarely consume 707 rgba parameters.""" 708 ) 709 rel proxyPrim ( 710 doc = '''The proxyPrim relationship allows us to link a 711 prim whose purpose is "render" to its (single target) 712 purpose="proxy" prim. This is entirely optional, but can be 713 useful in several scenarios: 714 715 - In a pipeline that does pruning (for complexity management) 716 by deactivating prims composed from asset references, when we 717 deactivate a purpose="render" prim, we will be able to discover 718 and additionally deactivate its associated purpose="proxy" prim, 719 so that preview renders reflect the pruning accurately. 720 721 - DCC importers may be able to make more aggressive optimizations 722 for interactive processing and display if they can discover the proxy 723 for a given render prim. 724 725 - With a little more work, a Hydra-based application will be able 726 to map a picked proxy prim back to its render geometry for selection. 727 728 \\note It is only valid to author the proxyPrim relationship on 729 prims whose purpose is "render".''' 730 ) 731 uniform token purpose = "default" ( 732 allowedTokens = ["default", "render", "proxy", "guide"] 733 doc = """Purpose is a classification of geometry into categories that 734 can each be independently included or excluded from traversals of prims 735 on a stage, such as rendering or bounding-box computation traversals. 736 737 See for more detail about how 738 purpose is computed and used.""" 739 ) 740 token visibility = "inherited" ( 741 allowedTokens = ["inherited", "invisible"] 742 doc = '''Visibility is meant to be the simplest form of "pruning" 743 visibility that is supported by most DCC apps. Visibility is 744 animatable, allowing a sub-tree of geometry to be present for some 745 segment of a shot, and absent from others; unlike the action of 746 deactivating geometry prims, invisible geometry is still 747 available for inspection, for positioning, for defining volumes, etc.''' 748 ) 749 uniform token[] xformOpOrder ( 750 doc = """Encodes the sequence of transformation operations in the 751 order in which they should be pushed onto a transform stack while 752 visiting a UsdStage's prims in a graph traversal that will effect 753 the desired positioning for this prim and its descendant prims. 754 755 You should rarely, if ever, need to manipulate this attribute directly. 756 It is managed by the AddXformOp(), SetResetXformStack(), and 757 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 758 GetLocalTransformation().""" 759 ) 760} 761 762class Cube "Cube" ( 763 doc = """Defines a primitive rectilinear cube centered at the origin. 764 765 The fallback values for Cube, Sphere, Cone, and Cylinder are set so that 766 they all pack into the same volume/bounds.""" 767) 768{ 769 uniform bool doubleSided = 0 ( 770 doc = """Although some renderers treat all parametric or polygonal 771 surfaces as if they were effectively laminae with outward-facing 772 normals on both sides, some renderers derive significant optimizations 773 by considering these surfaces to have only a single outward side, 774 typically determined by control-point winding order and/or 775 orientation. By doing so they can perform \"backface culling\" to 776 avoid drawing the many polygons of most closed surfaces that face away 777 from the viewer. 778 779 However, it is often advantageous to model thin objects such as paper 780 and cloth as single, open surfaces that must be viewable from both 781 sides, always. Setting a gprim's doubleSided attribute to 782 \\c true instructs all renderers to disable optimizations such as 783 backface culling for the gprim, and attempt (not all renderers are able 784 to do so, but the USD reference GL renderer always will) to provide 785 forward-facing normals on each side of the surface for lighting 786 calculations.""" 787 ) 788 float3[] extent = [(-1, -1, -1), (1, 1, 1)] ( 789 doc = """Extent is re-defined on Cube only to provide a fallback value. 790 \\sa UsdGeomGprim::GetExtentAttr().""" 791 ) 792 uniform token orientation = "rightHanded" ( 793 allowedTokens = ["rightHanded", "leftHanded"] 794 doc = """Orientation specifies whether the gprim's surface normal 795 should be computed using the right hand rule, or the left hand rule. 796 Please see for a deeper explanation and 797 generalization of orientation to composed scenes with transformation 798 hierarchies.""" 799 ) 800 color3f[] primvars:displayColor ( 801 doc = '''It is useful to have an "official" colorSet that can be used 802 as a display or modeling color, even in the absence of any specified 803 shader for a gprim. DisplayColor serves this role; because it is a 804 UsdGeomPrimvar, it can also be used as a gprim override for any shader 805 that consumes a displayColor parameter.''' 806 ) 807 float[] primvars:displayOpacity ( 808 doc = """Companion to displayColor that specifies opacity, broken 809 out as an independent attribute rather than an rgba color, both so that 810 each can be independently overridden, and because shaders rarely consume 811 rgba parameters.""" 812 ) 813 rel proxyPrim ( 814 doc = '''The proxyPrim relationship allows us to link a 815 prim whose purpose is "render" to its (single target) 816 purpose="proxy" prim. This is entirely optional, but can be 817 useful in several scenarios: 818 819 - In a pipeline that does pruning (for complexity management) 820 by deactivating prims composed from asset references, when we 821 deactivate a purpose="render" prim, we will be able to discover 822 and additionally deactivate its associated purpose="proxy" prim, 823 so that preview renders reflect the pruning accurately. 824 825 - DCC importers may be able to make more aggressive optimizations 826 for interactive processing and display if they can discover the proxy 827 for a given render prim. 828 829 - With a little more work, a Hydra-based application will be able 830 to map a picked proxy prim back to its render geometry for selection. 831 832 \\note It is only valid to author the proxyPrim relationship on 833 prims whose purpose is "render".''' 834 ) 835 uniform token purpose = "default" ( 836 allowedTokens = ["default", "render", "proxy", "guide"] 837 doc = """Purpose is a classification of geometry into categories that 838 can each be independently included or excluded from traversals of prims 839 on a stage, such as rendering or bounding-box computation traversals. 840 841 See for more detail about how 842 purpose is computed and used.""" 843 ) 844 double size = 2 ( 845 doc = """Indicates the length of each edge of the cube. If you 846 author size you must also author extent. 847 848 \\sa GetExtentAttr()""" 849 ) 850 token visibility = "inherited" ( 851 allowedTokens = ["inherited", "invisible"] 852 doc = '''Visibility is meant to be the simplest form of "pruning" 853 visibility that is supported by most DCC apps. Visibility is 854 animatable, allowing a sub-tree of geometry to be present for some 855 segment of a shot, and absent from others; unlike the action of 856 deactivating geometry prims, invisible geometry is still 857 available for inspection, for positioning, for defining volumes, etc.''' 858 ) 859 uniform token[] xformOpOrder ( 860 doc = """Encodes the sequence of transformation operations in the 861 order in which they should be pushed onto a transform stack while 862 visiting a UsdStage's prims in a graph traversal that will effect 863 the desired positioning for this prim and its descendant prims. 864 865 You should rarely, if ever, need to manipulate this attribute directly. 866 It is managed by the AddXformOp(), SetResetXformStack(), and 867 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 868 GetLocalTransformation().""" 869 ) 870} 871 872class Sphere "Sphere" ( 873 doc = """Defines a primitive sphere centered at the origin. 874 875 The fallback values for Cube, Sphere, Cone, and Cylinder are set so that 876 they all pack into the same volume/bounds.""" 877) 878{ 879 uniform bool doubleSided = 0 ( 880 doc = """Although some renderers treat all parametric or polygonal 881 surfaces as if they were effectively laminae with outward-facing 882 normals on both sides, some renderers derive significant optimizations 883 by considering these surfaces to have only a single outward side, 884 typically determined by control-point winding order and/or 885 orientation. By doing so they can perform \"backface culling\" to 886 avoid drawing the many polygons of most closed surfaces that face away 887 from the viewer. 888 889 However, it is often advantageous to model thin objects such as paper 890 and cloth as single, open surfaces that must be viewable from both 891 sides, always. Setting a gprim's doubleSided attribute to 892 \\c true instructs all renderers to disable optimizations such as 893 backface culling for the gprim, and attempt (not all renderers are able 894 to do so, but the USD reference GL renderer always will) to provide 895 forward-facing normals on each side of the surface for lighting 896 calculations.""" 897 ) 898 float3[] extent = [(-1, -1, -1), (1, 1, 1)] ( 899 doc = """Extent is re-defined on Sphere only to provide a fallback 900 value. \\sa UsdGeomGprim::GetExtentAttr().""" 901 ) 902 uniform token orientation = "rightHanded" ( 903 allowedTokens = ["rightHanded", "leftHanded"] 904 doc = """Orientation specifies whether the gprim's surface normal 905 should be computed using the right hand rule, or the left hand rule. 906 Please see for a deeper explanation and 907 generalization of orientation to composed scenes with transformation 908 hierarchies.""" 909 ) 910 color3f[] primvars:displayColor ( 911 doc = '''It is useful to have an "official" colorSet that can be used 912 as a display or modeling color, even in the absence of any specified 913 shader for a gprim. DisplayColor serves this role; because it is a 914 UsdGeomPrimvar, it can also be used as a gprim override for any shader 915 that consumes a displayColor parameter.''' 916 ) 917 float[] primvars:displayOpacity ( 918 doc = """Companion to displayColor that specifies opacity, broken 919 out as an independent attribute rather than an rgba color, both so that 920 each can be independently overridden, and because shaders rarely consume 921 rgba parameters.""" 922 ) 923 rel proxyPrim ( 924 doc = '''The proxyPrim relationship allows us to link a 925 prim whose purpose is "render" to its (single target) 926 purpose="proxy" prim. This is entirely optional, but can be 927 useful in several scenarios: 928 929 - In a pipeline that does pruning (for complexity management) 930 by deactivating prims composed from asset references, when we 931 deactivate a purpose="render" prim, we will be able to discover 932 and additionally deactivate its associated purpose="proxy" prim, 933 so that preview renders reflect the pruning accurately. 934 935 - DCC importers may be able to make more aggressive optimizations 936 for interactive processing and display if they can discover the proxy 937 for a given render prim. 938 939 - With a little more work, a Hydra-based application will be able 940 to map a picked proxy prim back to its render geometry for selection. 941 942 \\note It is only valid to author the proxyPrim relationship on 943 prims whose purpose is "render".''' 944 ) 945 uniform token purpose = "default" ( 946 allowedTokens = ["default", "render", "proxy", "guide"] 947 doc = """Purpose is a classification of geometry into categories that 948 can each be independently included or excluded from traversals of prims 949 on a stage, such as rendering or bounding-box computation traversals. 950 951 See for more detail about how 952 purpose is computed and used.""" 953 ) 954 double radius = 1 ( 955 doc = """Indicates the sphere's radius. If you 956 author radius you must also author extent. 957 958 \\sa GetExtentAttr()""" 959 ) 960 token visibility = "inherited" ( 961 allowedTokens = ["inherited", "invisible"] 962 doc = '''Visibility is meant to be the simplest form of "pruning" 963 visibility that is supported by most DCC apps. Visibility is 964 animatable, allowing a sub-tree of geometry to be present for some 965 segment of a shot, and absent from others; unlike the action of 966 deactivating geometry prims, invisible geometry is still 967 available for inspection, for positioning, for defining volumes, etc.''' 968 ) 969 uniform token[] xformOpOrder ( 970 doc = """Encodes the sequence of transformation operations in the 971 order in which they should be pushed onto a transform stack while 972 visiting a UsdStage's prims in a graph traversal that will effect 973 the desired positioning for this prim and its descendant prims. 974 975 You should rarely, if ever, need to manipulate this attribute directly. 976 It is managed by the AddXformOp(), SetResetXformStack(), and 977 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 978 GetLocalTransformation().""" 979 ) 980} 981 982class Cylinder "Cylinder" ( 983 doc = """Defines a primitive cylinder with closed ends, centered at the 984 origin, whose spine is along the specified axis. 985 986 The fallback values for Cube, Sphere, Cone, and Cylinder are set so that 987 they all pack into the same volume/bounds.""" 988) 989{ 990 uniform token axis = "Z" ( 991 allowedTokens = ["X", "Y", "Z"] 992 doc = "The axis along which the spine of the cylinder is aligned" 993 ) 994 uniform bool doubleSided = 0 ( 995 doc = """Although some renderers treat all parametric or polygonal 996 surfaces as if they were effectively laminae with outward-facing 997 normals on both sides, some renderers derive significant optimizations 998 by considering these surfaces to have only a single outward side, 999 typically determined by control-point winding order and/or 1000 orientation. By doing so they can perform \"backface culling\" to 1001 avoid drawing the many polygons of most closed surfaces that face away 1002 from the viewer. 1003 1004 However, it is often advantageous to model thin objects such as paper 1005 and cloth as single, open surfaces that must be viewable from both 1006 sides, always. Setting a gprim's doubleSided attribute to 1007 \\c true instructs all renderers to disable optimizations such as 1008 backface culling for the gprim, and attempt (not all renderers are able 1009 to do so, but the USD reference GL renderer always will) to provide 1010 forward-facing normals on each side of the surface for lighting 1011 calculations.""" 1012 ) 1013 float3[] extent = [(-1, -1, -1), (1, 1, 1)] ( 1014 doc = """Extent is re-defined on Cylinder only to provide a fallback 1015 value. \\sa UsdGeomGprim::GetExtentAttr().""" 1016 ) 1017 double height = 2 ( 1018 doc = """The size of the cylinder's spine along the specified 1019 axis. If you author height you must also author extent. 1020 1021 \\sa GetExtentAttr()""" 1022 ) 1023 uniform token orientation = "rightHanded" ( 1024 allowedTokens = ["rightHanded", "leftHanded"] 1025 doc = """Orientation specifies whether the gprim's surface normal 1026 should be computed using the right hand rule, or the left hand rule. 1027 Please see for a deeper explanation and 1028 generalization of orientation to composed scenes with transformation 1029 hierarchies.""" 1030 ) 1031 color3f[] primvars:displayColor ( 1032 doc = '''It is useful to have an "official" colorSet that can be used 1033 as a display or modeling color, even in the absence of any specified 1034 shader for a gprim. DisplayColor serves this role; because it is a 1035 UsdGeomPrimvar, it can also be used as a gprim override for any shader 1036 that consumes a displayColor parameter.''' 1037 ) 1038 float[] primvars:displayOpacity ( 1039 doc = """Companion to displayColor that specifies opacity, broken 1040 out as an independent attribute rather than an rgba color, both so that 1041 each can be independently overridden, and because shaders rarely consume 1042 rgba parameters.""" 1043 ) 1044 rel proxyPrim ( 1045 doc = '''The proxyPrim relationship allows us to link a 1046 prim whose purpose is "render" to its (single target) 1047 purpose="proxy" prim. This is entirely optional, but can be 1048 useful in several scenarios: 1049 1050 - In a pipeline that does pruning (for complexity management) 1051 by deactivating prims composed from asset references, when we 1052 deactivate a purpose="render" prim, we will be able to discover 1053 and additionally deactivate its associated purpose="proxy" prim, 1054 so that preview renders reflect the pruning accurately. 1055 1056 - DCC importers may be able to make more aggressive optimizations 1057 for interactive processing and display if they can discover the proxy 1058 for a given render prim. 1059 1060 - With a little more work, a Hydra-based application will be able 1061 to map a picked proxy prim back to its render geometry for selection. 1062 1063 \\note It is only valid to author the proxyPrim relationship on 1064 prims whose purpose is "render".''' 1065 ) 1066 uniform token purpose = "default" ( 1067 allowedTokens = ["default", "render", "proxy", "guide"] 1068 doc = """Purpose is a classification of geometry into categories that 1069 can each be independently included or excluded from traversals of prims 1070 on a stage, such as rendering or bounding-box computation traversals. 1071 1072 See for more detail about how 1073 purpose is computed and used.""" 1074 ) 1075 double radius = 1 ( 1076 doc = """The radius of the cylinder. If you author radius 1077 you must also author extent. 1078 1079 \\sa GetExtentAttr()""" 1080 ) 1081 token visibility = "inherited" ( 1082 allowedTokens = ["inherited", "invisible"] 1083 doc = '''Visibility is meant to be the simplest form of "pruning" 1084 visibility that is supported by most DCC apps. Visibility is 1085 animatable, allowing a sub-tree of geometry to be present for some 1086 segment of a shot, and absent from others; unlike the action of 1087 deactivating geometry prims, invisible geometry is still 1088 available for inspection, for positioning, for defining volumes, etc.''' 1089 ) 1090 uniform token[] xformOpOrder ( 1091 doc = """Encodes the sequence of transformation operations in the 1092 order in which they should be pushed onto a transform stack while 1093 visiting a UsdStage's prims in a graph traversal that will effect 1094 the desired positioning for this prim and its descendant prims. 1095 1096 You should rarely, if ever, need to manipulate this attribute directly. 1097 It is managed by the AddXformOp(), SetResetXformStack(), and 1098 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 1099 GetLocalTransformation().""" 1100 ) 1101} 1102 1103class Capsule "Capsule" ( 1104 doc = """Defines a primitive capsule, i.e. a cylinder capped by two half 1105 spheres, centered at the origin, whose spine is along the specified 1106 axis.""" 1107) 1108{ 1109 uniform token axis = "Z" ( 1110 allowedTokens = ["X", "Y", "Z"] 1111 doc = "The axis along which the spine of the capsule is aligned" 1112 ) 1113 uniform bool doubleSided = 0 ( 1114 doc = """Although some renderers treat all parametric or polygonal 1115 surfaces as if they were effectively laminae with outward-facing 1116 normals on both sides, some renderers derive significant optimizations 1117 by considering these surfaces to have only a single outward side, 1118 typically determined by control-point winding order and/or 1119 orientation. By doing so they can perform \"backface culling\" to 1120 avoid drawing the many polygons of most closed surfaces that face away 1121 from the viewer. 1122 1123 However, it is often advantageous to model thin objects such as paper 1124 and cloth as single, open surfaces that must be viewable from both 1125 sides, always. Setting a gprim's doubleSided attribute to 1126 \\c true instructs all renderers to disable optimizations such as 1127 backface culling for the gprim, and attempt (not all renderers are able 1128 to do so, but the USD reference GL renderer always will) to provide 1129 forward-facing normals on each side of the surface for lighting 1130 calculations.""" 1131 ) 1132 float3[] extent = [(-0.5, -0.5, -1), (0.5, 0.5, 1)] ( 1133 doc = """Extent is re-defined on Capsule only to provide a fallback 1134 value. \\sa UsdGeomGprim::GetExtentAttr().""" 1135 ) 1136 double height = 1 ( 1137 doc = """The size of the capsule's spine along the specified 1138 axis excluding the size of the two half spheres, i.e. 1139 the size of the cylinder portion of the capsule. 1140 If you author height you must also author extent. 1141 \\sa GetExtentAttr()""" 1142 ) 1143 uniform token orientation = "rightHanded" ( 1144 allowedTokens = ["rightHanded", "leftHanded"] 1145 doc = """Orientation specifies whether the gprim's surface normal 1146 should be computed using the right hand rule, or the left hand rule. 1147 Please see for a deeper explanation and 1148 generalization of orientation to composed scenes with transformation 1149 hierarchies.""" 1150 ) 1151 color3f[] primvars:displayColor ( 1152 doc = '''It is useful to have an "official" colorSet that can be used 1153 as a display or modeling color, even in the absence of any specified 1154 shader for a gprim. DisplayColor serves this role; because it is a 1155 UsdGeomPrimvar, it can also be used as a gprim override for any shader 1156 that consumes a displayColor parameter.''' 1157 ) 1158 float[] primvars:displayOpacity ( 1159 doc = """Companion to displayColor that specifies opacity, broken 1160 out as an independent attribute rather than an rgba color, both so that 1161 each can be independently overridden, and because shaders rarely consume 1162 rgba parameters.""" 1163 ) 1164 rel proxyPrim ( 1165 doc = '''The proxyPrim relationship allows us to link a 1166 prim whose purpose is "render" to its (single target) 1167 purpose="proxy" prim. This is entirely optional, but can be 1168 useful in several scenarios: 1169 1170 - In a pipeline that does pruning (for complexity management) 1171 by deactivating prims composed from asset references, when we 1172 deactivate a purpose="render" prim, we will be able to discover 1173 and additionally deactivate its associated purpose="proxy" prim, 1174 so that preview renders reflect the pruning accurately. 1175 1176 - DCC importers may be able to make more aggressive optimizations 1177 for interactive processing and display if they can discover the proxy 1178 for a given render prim. 1179 1180 - With a little more work, a Hydra-based application will be able 1181 to map a picked proxy prim back to its render geometry for selection. 1182 1183 \\note It is only valid to author the proxyPrim relationship on 1184 prims whose purpose is "render".''' 1185 ) 1186 uniform token purpose = "default" ( 1187 allowedTokens = ["default", "render", "proxy", "guide"] 1188 doc = """Purpose is a classification of geometry into categories that 1189 can each be independently included or excluded from traversals of prims 1190 on a stage, such as rendering or bounding-box computation traversals. 1191 1192 See for more detail about how 1193 purpose is computed and used.""" 1194 ) 1195 double radius = 0.5 ( 1196 doc = """The radius of the capsule. If you 1197 author radius you must also author extent. 1198 1199 \\sa GetExtentAttr()""" 1200 ) 1201 token visibility = "inherited" ( 1202 allowedTokens = ["inherited", "invisible"] 1203 doc = '''Visibility is meant to be the simplest form of "pruning" 1204 visibility that is supported by most DCC apps. Visibility is 1205 animatable, allowing a sub-tree of geometry to be present for some 1206 segment of a shot, and absent from others; unlike the action of 1207 deactivating geometry prims, invisible geometry is still 1208 available for inspection, for positioning, for defining volumes, etc.''' 1209 ) 1210 uniform token[] xformOpOrder ( 1211 doc = """Encodes the sequence of transformation operations in the 1212 order in which they should be pushed onto a transform stack while 1213 visiting a UsdStage's prims in a graph traversal that will effect 1214 the desired positioning for this prim and its descendant prims. 1215 1216 You should rarely, if ever, need to manipulate this attribute directly. 1217 It is managed by the AddXformOp(), SetResetXformStack(), and 1218 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 1219 GetLocalTransformation().""" 1220 ) 1221} 1222 1223class Cone "Cone" ( 1224 doc = """Defines a primitive cone, centered at the origin, whose spine 1225 is along the specified axis, with the apex of the cone pointing 1226 in the direction of the positive axis. 1227 1228 The fallback values for Cube, Sphere, Cone, and Cylinder are set so that 1229 they all pack into the same volume/bounds.""" 1230) 1231{ 1232 uniform token axis = "Z" ( 1233 allowedTokens = ["X", "Y", "Z"] 1234 doc = "The axis along which the spine of the cone is aligned" 1235 ) 1236 uniform bool doubleSided = 0 ( 1237 doc = """Although some renderers treat all parametric or polygonal 1238 surfaces as if they were effectively laminae with outward-facing 1239 normals on both sides, some renderers derive significant optimizations 1240 by considering these surfaces to have only a single outward side, 1241 typically determined by control-point winding order and/or 1242 orientation. By doing so they can perform \"backface culling\" to 1243 avoid drawing the many polygons of most closed surfaces that face away 1244 from the viewer. 1245 1246 However, it is often advantageous to model thin objects such as paper 1247 and cloth as single, open surfaces that must be viewable from both 1248 sides, always. Setting a gprim's doubleSided attribute to 1249 \\c true instructs all renderers to disable optimizations such as 1250 backface culling for the gprim, and attempt (not all renderers are able 1251 to do so, but the USD reference GL renderer always will) to provide 1252 forward-facing normals on each side of the surface for lighting 1253 calculations.""" 1254 ) 1255 float3[] extent = [(-1, -1, -1), (1, 1, 1)] ( 1256 doc = """Extent is re-defined on Cone only to provide a fallback 1257 value. \\sa UsdGeomGprim::GetExtentAttr().""" 1258 ) 1259 double height = 2 ( 1260 doc = """The size of the cone's spine along the specified 1261 axis. If you author height you must also author extent. 1262 1263 \\sa GetExtentAttr()""" 1264 ) 1265 uniform token orientation = "rightHanded" ( 1266 allowedTokens = ["rightHanded", "leftHanded"] 1267 doc = """Orientation specifies whether the gprim's surface normal 1268 should be computed using the right hand rule, or the left hand rule. 1269 Please see for a deeper explanation and 1270 generalization of orientation to composed scenes with transformation 1271 hierarchies.""" 1272 ) 1273 color3f[] primvars:displayColor ( 1274 doc = '''It is useful to have an "official" colorSet that can be used 1275 as a display or modeling color, even in the absence of any specified 1276 shader for a gprim. DisplayColor serves this role; because it is a 1277 UsdGeomPrimvar, it can also be used as a gprim override for any shader 1278 that consumes a displayColor parameter.''' 1279 ) 1280 float[] primvars:displayOpacity ( 1281 doc = """Companion to displayColor that specifies opacity, broken 1282 out as an independent attribute rather than an rgba color, both so that 1283 each can be independently overridden, and because shaders rarely consume 1284 rgba parameters.""" 1285 ) 1286 rel proxyPrim ( 1287 doc = '''The proxyPrim relationship allows us to link a 1288 prim whose purpose is "render" to its (single target) 1289 purpose="proxy" prim. This is entirely optional, but can be 1290 useful in several scenarios: 1291 1292 - In a pipeline that does pruning (for complexity management) 1293 by deactivating prims composed from asset references, when we 1294 deactivate a purpose="render" prim, we will be able to discover 1295 and additionally deactivate its associated purpose="proxy" prim, 1296 so that preview renders reflect the pruning accurately. 1297 1298 - DCC importers may be able to make more aggressive optimizations 1299 for interactive processing and display if they can discover the proxy 1300 for a given render prim. 1301 1302 - With a little more work, a Hydra-based application will be able 1303 to map a picked proxy prim back to its render geometry for selection. 1304 1305 \\note It is only valid to author the proxyPrim relationship on 1306 prims whose purpose is "render".''' 1307 ) 1308 uniform token purpose = "default" ( 1309 allowedTokens = ["default", "render", "proxy", "guide"] 1310 doc = """Purpose is a classification of geometry into categories that 1311 can each be independently included or excluded from traversals of prims 1312 on a stage, such as rendering or bounding-box computation traversals. 1313 1314 See for more detail about how 1315 purpose is computed and used.""" 1316 ) 1317 double radius = 1 ( 1318 doc = """The radius of the cone. If you 1319 author radius you must also author extent. 1320 1321 \\sa GetExtentAttr()""" 1322 ) 1323 token visibility = "inherited" ( 1324 allowedTokens = ["inherited", "invisible"] 1325 doc = '''Visibility is meant to be the simplest form of "pruning" 1326 visibility that is supported by most DCC apps. Visibility is 1327 animatable, allowing a sub-tree of geometry to be present for some 1328 segment of a shot, and absent from others; unlike the action of 1329 deactivating geometry prims, invisible geometry is still 1330 available for inspection, for positioning, for defining volumes, etc.''' 1331 ) 1332 uniform token[] xformOpOrder ( 1333 doc = """Encodes the sequence of transformation operations in the 1334 order in which they should be pushed onto a transform stack while 1335 visiting a UsdStage's prims in a graph traversal that will effect 1336 the desired positioning for this prim and its descendant prims. 1337 1338 You should rarely, if ever, need to manipulate this attribute directly. 1339 It is managed by the AddXformOp(), SetResetXformStack(), and 1340 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 1341 GetLocalTransformation().""" 1342 ) 1343} 1344 1345class "PointBased" ( 1346 doc = """Base class for all UsdGeomGprims that possess points, 1347 providing common attributes such as normals and velocities.""" 1348) 1349{ 1350 vector3f[] accelerations ( 1351 doc = """If provided, 'accelerations' should be used with 1352 velocities to compute positions between samples for the 'points' 1353 attribute rather than interpolating between neighboring 'points' 1354 samples. Acceleration is measured in position units per second-squared. 1355 To convert to position units per squared UsdTimeCode, divide by the 1356 square of UsdStage::GetTimeCodesPerSecond().""" 1357 ) 1358 uniform bool doubleSided = 0 ( 1359 doc = """Although some renderers treat all parametric or polygonal 1360 surfaces as if they were effectively laminae with outward-facing 1361 normals on both sides, some renderers derive significant optimizations 1362 by considering these surfaces to have only a single outward side, 1363 typically determined by control-point winding order and/or 1364 orientation. By doing so they can perform \"backface culling\" to 1365 avoid drawing the many polygons of most closed surfaces that face away 1366 from the viewer. 1367 1368 However, it is often advantageous to model thin objects such as paper 1369 and cloth as single, open surfaces that must be viewable from both 1370 sides, always. Setting a gprim's doubleSided attribute to 1371 \\c true instructs all renderers to disable optimizations such as 1372 backface culling for the gprim, and attempt (not all renderers are able 1373 to do so, but the USD reference GL renderer always will) to provide 1374 forward-facing normals on each side of the surface for lighting 1375 calculations.""" 1376 ) 1377 float3[] extent ( 1378 doc = """Extent is a three dimensional range measuring the geometric 1379 extent of the authored gprim in its own local space (i.e. its own 1380 transform not applied), without accounting for any shader-induced 1381 displacement. Whenever any geometry-affecting attribute is authored 1382 for any gprim in a layer, extent must also be authored at the same 1383 timesample; failure to do so will result in incorrect bounds-computation. 1384 \\sa \\ref UsdGeom_Boundable_Extent. 1385 1386 An authored extent on a prim which has children is expected to include 1387 the extent of all children, as they will be pruned from BBox computation 1388 during traversal.""" 1389 ) 1390 normal3f[] normals ( 1391 doc = """Provide an object-space orientation for individual points, 1392 which, depending on subclass, may define a surface, curve, or free 1393 points. Note that 'normals' should not be authored on any Mesh that 1394 is subdivided, since the subdivision algorithm will define its own 1395 normals. 'normals' is not a generic primvar, but the number of elements 1396 in this attribute will be determined by its 'interpolation'. See 1397 . If 'normals' and 'primvars:normals' 1398 are both specified, the latter has precedence.""" 1399 ) 1400 uniform token orientation = "rightHanded" ( 1401 allowedTokens = ["rightHanded", "leftHanded"] 1402 doc = """Orientation specifies whether the gprim's surface normal 1403 should be computed using the right hand rule, or the left hand rule. 1404 Please see for a deeper explanation and 1405 generalization of orientation to composed scenes with transformation 1406 hierarchies.""" 1407 ) 1408 point3f[] points ( 1409 doc = """The primary geometry attribute for all PointBased 1410 primitives, describes points in (local) space.""" 1411 ) 1412 color3f[] primvars:displayColor ( 1413 doc = '''It is useful to have an "official" colorSet that can be used 1414 as a display or modeling color, even in the absence of any specified 1415 shader for a gprim. DisplayColor serves this role; because it is a 1416 UsdGeomPrimvar, it can also be used as a gprim override for any shader 1417 that consumes a displayColor parameter.''' 1418 ) 1419 float[] primvars:displayOpacity ( 1420 doc = """Companion to displayColor that specifies opacity, broken 1421 out as an independent attribute rather than an rgba color, both so that 1422 each can be independently overridden, and because shaders rarely consume 1423 rgba parameters.""" 1424 ) 1425 rel proxyPrim ( 1426 doc = '''The proxyPrim relationship allows us to link a 1427 prim whose purpose is "render" to its (single target) 1428 purpose="proxy" prim. This is entirely optional, but can be 1429 useful in several scenarios: 1430 1431 - In a pipeline that does pruning (for complexity management) 1432 by deactivating prims composed from asset references, when we 1433 deactivate a purpose="render" prim, we will be able to discover 1434 and additionally deactivate its associated purpose="proxy" prim, 1435 so that preview renders reflect the pruning accurately. 1436 1437 - DCC importers may be able to make more aggressive optimizations 1438 for interactive processing and display if they can discover the proxy 1439 for a given render prim. 1440 1441 - With a little more work, a Hydra-based application will be able 1442 to map a picked proxy prim back to its render geometry for selection. 1443 1444 \\note It is only valid to author the proxyPrim relationship on 1445 prims whose purpose is "render".''' 1446 ) 1447 uniform token purpose = "default" ( 1448 allowedTokens = ["default", "render", "proxy", "guide"] 1449 doc = """Purpose is a classification of geometry into categories that 1450 can each be independently included or excluded from traversals of prims 1451 on a stage, such as rendering or bounding-box computation traversals. 1452 1453 See for more detail about how 1454 purpose is computed and used.""" 1455 ) 1456 vector3f[] velocities ( 1457 doc = """If provided, 'velocities' should be used by renderers to 1458 1459 compute positions between samples for the 'points' attribute, rather 1460 than interpolating between neighboring 'points' samples. This is the 1461 only reasonable means of computing motion blur for topologically 1462 varying PointBased primitives. It follows that the length of each 1463 'velocities' sample must match the length of the corresponding 1464 'points' sample. Velocity is measured in position units per second, 1465 as per most simulation software. To convert to position units per 1466 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 1467 1468 See also .""" 1469 ) 1470 token visibility = "inherited" ( 1471 allowedTokens = ["inherited", "invisible"] 1472 doc = '''Visibility is meant to be the simplest form of "pruning" 1473 visibility that is supported by most DCC apps. Visibility is 1474 animatable, allowing a sub-tree of geometry to be present for some 1475 segment of a shot, and absent from others; unlike the action of 1476 deactivating geometry prims, invisible geometry is still 1477 available for inspection, for positioning, for defining volumes, etc.''' 1478 ) 1479 uniform token[] xformOpOrder ( 1480 doc = """Encodes the sequence of transformation operations in the 1481 order in which they should be pushed onto a transform stack while 1482 visiting a UsdStage's prims in a graph traversal that will effect 1483 the desired positioning for this prim and its descendant prims. 1484 1485 You should rarely, if ever, need to manipulate this attribute directly. 1486 It is managed by the AddXformOp(), SetResetXformStack(), and 1487 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 1488 GetLocalTransformation().""" 1489 ) 1490} 1491 1492class Mesh "Mesh" ( 1493 doc = """Encodes a mesh with optional subdivision properties and features. 1494 1495 As a point-based primitive, meshes are defined in terms of points that 1496 are connected into edges and faces. Many references to meshes use the 1497 term 'vertex' in place of or interchangeably with 'points', while some 1498 use 'vertex' to refer to the 'face-vertices' that define a face. To 1499 avoid confusion, the term 'vertex' is intentionally avoided in favor of 1500 'points' or 'face-vertices'. 1501 1502 The connectivity between points, edges and faces is encoded using a 1503 common minimal topological description of the faces of the mesh. Each 1504 face is defined by a set of face-vertices using indices into the Mesh's 1505 _points_ array (inherited from UsdGeomPointBased) and laid out in a 1506 single linear _faceVertexIndices_ array for efficiency. A companion 1507 _faceVertexCounts_ array provides, for each face, the number of 1508 consecutive face-vertices in _faceVertexIndices_ that define the face. 1509 No additional connectivity information is required or constructed, so 1510 no adjacency or neighborhood queries are available. 1511 1512 A key property of this mesh schema is that it encodes both subdivision 1513 surfaces and simpler polygonal meshes. This is achieved by varying the 1514 _subdivisionScheme_ attribute, which is set to specify Catmull-Clark 1515 subdivision by default, so polygonal meshes must always be explicitly 1516 declared. The available subdivision schemes and additional subdivision 1517 features encoded in optional attributes conform to the feature set of 1518 OpenSubdiv 1519 (https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html). 1520 1521 \\anchor UsdGeom_Mesh_Primvars 1522 __A Note About Primvars__ 1523 1524 The following list clarifies the number of elements for and the 1525 interpolation behavior of the different primvar interpolation types 1526 for meshes: 1527 1528 - __constant__: One element for the entire mesh; no interpolation. 1529 - __uniform__: One element for each face of the mesh; elements are 1530 typically not interpolated but are inherited by other faces derived 1531 from a given face (via subdivision, tessellation, etc.). 1532 - __varying__: One element for each point of the mesh; 1533 interpolation of point data is always linear. 1534 - __vertex__: One element for each point of the mesh; 1535 interpolation of point data is applied according to the 1536 _subdivisionScheme_ attribute. 1537 - __faceVarying__: One element for each of the face-vertices that 1538 define the mesh topology; interpolation of face-vertex data may 1539 be smooth or linear, according to the _subdivisionScheme_ and 1540 _faceVaryingLinearInterpolation_ attributes. 1541 1542 Primvar interpolation types and related utilities are described more 1543 generally in \\ref Usd_InterpolationVals. 1544 1545 \\anchor UsdGeom_Mesh_Normals 1546 __A Note About Normals__ 1547 1548 Normals should not be authored on a subdivision mesh, since subdivision 1549 algorithms define their own normals. They should only be authored for 1550 polygonal meshes (_subdivisionScheme_ = \"none\"). 1551 1552 The _normals_ attribute inherited from UsdGeomPointBased is not a generic 1553 primvar, but the number of elements in this attribute will be determined by 1554 its _interpolation_. See . 1555 If _normals_ and _primvars:normals_ are both specified, the latter has 1556 precedence. If a polygonal mesh specifies __neither__ _normals_ nor 1557 _primvars:normals_, then it should be treated and rendered as faceted, 1558 with no attempt to compute smooth normals. 1559 1560 The normals generated for smooth subdivision schemes, e.g. Catmull-Clark 1561 and Loop, will likewise be smooth, but others, e.g. Bilinear, may be 1562 discontinuous between faces and/or within non-planar irregular faces.""" 1563) 1564{ 1565 vector3f[] accelerations ( 1566 doc = """If provided, 'accelerations' should be used with 1567 velocities to compute positions between samples for the 'points' 1568 attribute rather than interpolating between neighboring 'points' 1569 samples. Acceleration is measured in position units per second-squared. 1570 To convert to position units per squared UsdTimeCode, divide by the 1571 square of UsdStage::GetTimeCodesPerSecond().""" 1572 ) 1573 int[] cornerIndices = [] ( 1574 doc = """The indices of points for which a corresponding sharpness 1575 value is specified in _cornerSharpnesses_ (so the size of this array 1576 must match that of _cornerSharpnesses_).""" 1577 ) 1578 float[] cornerSharpnesses = [] ( 1579 doc = """The sharpness values associated with a corresponding set of 1580 points specified in _cornerIndices_ (so the size of this array must 1581 match that of _cornerIndices_). Use the constant `SHARPNESS_INFINITE` 1582 for a perfectly sharp corner.""" 1583 ) 1584 int[] creaseIndices = [] ( 1585 doc = """The indices of points grouped into sets of successive pairs 1586 that identify edges to be creased. The size of this array must be 1587 equal to the sum of all elements of the _creaseLengths_ attribute.""" 1588 ) 1589 int[] creaseLengths = [] ( 1590 doc = """The length of this array specifies the number of creases 1591 (sets of adjacent sharpened edges) on the mesh. Each element gives 1592 the number of points of each crease, whose indices are successively 1593 laid out in the _creaseIndices_ attribute. Since each crease must 1594 be at least one edge long, each element of this array must be at 1595 least two.""" 1596 ) 1597 float[] creaseSharpnesses = [] ( 1598 doc = """The per-crease or per-edge sharpness values for all creases. 1599 Since _creaseLengths_ encodes the number of points in each crease, 1600 the number of elements in this array will be either len(creaseLengths) 1601 or the sum over all X of (creaseLengths[X] - 1). Note that while 1602 the RI spec allows each crease to have either a single sharpness 1603 or a value per-edge, USD will encode either a single sharpness 1604 per crease on a mesh, or sharpnesses for all edges making up 1605 the creases on a mesh. Use the constant `SHARPNESS_INFINITE` for a 1606 perfectly sharp crease.""" 1607 ) 1608 uniform bool doubleSided = 0 ( 1609 doc = """Although some renderers treat all parametric or polygonal 1610 surfaces as if they were effectively laminae with outward-facing 1611 normals on both sides, some renderers derive significant optimizations 1612 by considering these surfaces to have only a single outward side, 1613 typically determined by control-point winding order and/or 1614 orientation. By doing so they can perform \"backface culling\" to 1615 avoid drawing the many polygons of most closed surfaces that face away 1616 from the viewer. 1617 1618 However, it is often advantageous to model thin objects such as paper 1619 and cloth as single, open surfaces that must be viewable from both 1620 sides, always. Setting a gprim's doubleSided attribute to 1621 \\c true instructs all renderers to disable optimizations such as 1622 backface culling for the gprim, and attempt (not all renderers are able 1623 to do so, but the USD reference GL renderer always will) to provide 1624 forward-facing normals on each side of the surface for lighting 1625 calculations.""" 1626 ) 1627 float3[] extent ( 1628 doc = """Extent is a three dimensional range measuring the geometric 1629 extent of the authored gprim in its own local space (i.e. its own 1630 transform not applied), without accounting for any shader-induced 1631 displacement. Whenever any geometry-affecting attribute is authored 1632 for any gprim in a layer, extent must also be authored at the same 1633 timesample; failure to do so will result in incorrect bounds-computation. 1634 \\sa \\ref UsdGeom_Boundable_Extent. 1635 1636 An authored extent on a prim which has children is expected to include 1637 the extent of all children, as they will be pruned from BBox computation 1638 during traversal.""" 1639 ) 1640 token faceVaryingLinearInterpolation = "cornersPlus1" ( 1641 allowedTokens = ["none", "cornersOnly", "cornersPlus1", "cornersPlus2", "boundaries", "all"] 1642 doc = '''Specifies how elements of a primvar of interpolation type 1643 "faceVarying" are interpolated for subdivision surfaces. Interpolation 1644 can be as smooth as a "vertex" primvar or constrained to be linear at 1645 features specified by several options. Valid values correspond to 1646 choices available in OpenSubdiv: 1647 1648 - __none__: No linear constraints or sharpening, smooth everywhere 1649 - __cornersOnly__: Sharpen corners of discontinuous boundaries only, 1650 smooth everywhere else 1651 - __cornersPlus1__: The default, same as "cornersOnly" plus additional 1652 sharpening at points where three or more distinct face-varying 1653 values occur 1654 - __cornersPlus2__: Same as "cornersPlus1" plus additional sharpening 1655 at points with at least one discontinuous boundary corner or 1656 only one discontinuous boundary edge (a dart) 1657 - __boundaries__: Piecewise linear along discontinuous boundaries, 1658 smooth interior 1659 - __all__: Piecewise linear everywhere 1660 1661 These are illustrated and described in more detail in the OpenSubdiv 1662 documentation: 1663 https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#face-varying-interpolation-rules''' 1664 ) 1665 int[] faceVertexCounts ( 1666 doc = """Provides the number of vertices in each face of the mesh, 1667 which is also the number of consecutive indices in _faceVertexIndices_ 1668 that define the face. The length of this attribute is the number of 1669 faces in the mesh. If this attribute has more than 1670 one timeSample, the mesh is considered to be topologically varying.""" 1671 ) 1672 int[] faceVertexIndices ( 1673 doc = """Flat list of the index (into the _points_ attribute) of each 1674 vertex of each face in the mesh. If this attribute has more than 1675 one timeSample, the mesh is considered to be topologically varying.""" 1676 ) 1677 int[] holeIndices = [] ( 1678 doc = """The indices of all faces that should be treated as holes, 1679 i.e. made invisible. This is traditionally a feature of subdivision 1680 surfaces and not generally applied to polygonal meshes.""" 1681 ) 1682 token interpolateBoundary = "edgeAndCorner" ( 1683 allowedTokens = ["none", "edgeOnly", "edgeAndCorner"] 1684 doc = '''Specifies how subdivision is applied for faces adjacent to 1685 boundary edges and boundary points. Valid values correspond to choices 1686 available in OpenSubdiv: 1687 1688 - __none__: No boundary interpolation is applied and boundary faces are 1689 effectively treated as holes 1690 - __edgeOnly__: A sequence of boundary edges defines a smooth curve to 1691 which the edges of subdivided boundary faces converge 1692 - __edgeAndCorner__: The default, similar to "edgeOnly" but the smooth 1693 boundary curve is made sharp at corner points 1694 1695 These are illustrated and described in more detail in the OpenSubdiv 1696 documentation: 1697 https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#boundary-interpolation-rules''' 1698 ) 1699 normal3f[] normals ( 1700 doc = """Provide an object-space orientation for individual points, 1701 which, depending on subclass, may define a surface, curve, or free 1702 points. Note that 'normals' should not be authored on any Mesh that 1703 is subdivided, since the subdivision algorithm will define its own 1704 normals. 'normals' is not a generic primvar, but the number of elements 1705 in this attribute will be determined by its 'interpolation'. See 1706 . If 'normals' and 'primvars:normals' 1707 are both specified, the latter has precedence.""" 1708 ) 1709 uniform token orientation = "rightHanded" ( 1710 allowedTokens = ["rightHanded", "leftHanded"] 1711 doc = """Orientation specifies whether the gprim's surface normal 1712 should be computed using the right hand rule, or the left hand rule. 1713 Please see for a deeper explanation and 1714 generalization of orientation to composed scenes with transformation 1715 hierarchies.""" 1716 ) 1717 point3f[] points ( 1718 doc = """The primary geometry attribute for all PointBased 1719 primitives, describes points in (local) space.""" 1720 ) 1721 color3f[] primvars:displayColor ( 1722 doc = '''It is useful to have an "official" colorSet that can be used 1723 as a display or modeling color, even in the absence of any specified 1724 shader for a gprim. DisplayColor serves this role; because it is a 1725 UsdGeomPrimvar, it can also be used as a gprim override for any shader 1726 that consumes a displayColor parameter.''' 1727 ) 1728 float[] primvars:displayOpacity ( 1729 doc = """Companion to displayColor that specifies opacity, broken 1730 out as an independent attribute rather than an rgba color, both so that 1731 each can be independently overridden, and because shaders rarely consume 1732 rgba parameters.""" 1733 ) 1734 rel proxyPrim ( 1735 doc = '''The proxyPrim relationship allows us to link a 1736 prim whose purpose is "render" to its (single target) 1737 purpose="proxy" prim. This is entirely optional, but can be 1738 useful in several scenarios: 1739 1740 - In a pipeline that does pruning (for complexity management) 1741 by deactivating prims composed from asset references, when we 1742 deactivate a purpose="render" prim, we will be able to discover 1743 and additionally deactivate its associated purpose="proxy" prim, 1744 so that preview renders reflect the pruning accurately. 1745 1746 - DCC importers may be able to make more aggressive optimizations 1747 for interactive processing and display if they can discover the proxy 1748 for a given render prim. 1749 1750 - With a little more work, a Hydra-based application will be able 1751 to map a picked proxy prim back to its render geometry for selection. 1752 1753 \\note It is only valid to author the proxyPrim relationship on 1754 prims whose purpose is "render".''' 1755 ) 1756 uniform token purpose = "default" ( 1757 allowedTokens = ["default", "render", "proxy", "guide"] 1758 doc = """Purpose is a classification of geometry into categories that 1759 can each be independently included or excluded from traversals of prims 1760 on a stage, such as rendering or bounding-box computation traversals. 1761 1762 See for more detail about how 1763 purpose is computed and used.""" 1764 ) 1765 uniform token subdivisionScheme = "catmullClark" ( 1766 allowedTokens = ["catmullClark", "loop", "bilinear", "none"] 1767 doc = '''The subdivision scheme to be applied to the surface. 1768 Valid values are: 1769 1770 - __catmullClark__: The default, Catmull-Clark subdivision; preferred 1771 for quad-dominant meshes (generalizes B-splines); interpolation 1772 of point data is smooth (non-linear) 1773 - __loop__: Loop subdivision; preferred for purely triangular meshes; 1774 interpolation of point data is smooth (non-linear) 1775 - __bilinear__: Subdivision reduces all faces to quads (topologically 1776 similar to "catmullClark"); interpolation of point data is bilinear 1777 - __none__: No subdivision, i.e. a simple polygonal mesh; interpolation 1778 of point data is linear 1779 1780 Polygonal meshes are typically lighter weight and faster to render, 1781 depending on renderer and render mode. Use of "bilinear" will produce 1782 a similar shape to a polygonal mesh and may offer additional guarantees 1783 of watertightness and additional subdivision features (e.g. holes) but 1784 may also not respect authored normals.''' 1785 ) 1786 token triangleSubdivisionRule = "catmullClark" ( 1787 allowedTokens = ["catmullClark", "smooth"] 1788 doc = '''Specifies an option to the subdivision rules for the 1789 Catmull-Clark scheme to try and improve undesirable artifacts when 1790 subdividing triangles. Valid values are "catmullClark" for the 1791 standard rules (the default) and "smooth" for the improvement. 1792 1793 See https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#triangle-subdivision-rule''' 1794 ) 1795 vector3f[] velocities ( 1796 doc = """If provided, 'velocities' should be used by renderers to 1797 1798 compute positions between samples for the 'points' attribute, rather 1799 than interpolating between neighboring 'points' samples. This is the 1800 only reasonable means of computing motion blur for topologically 1801 varying PointBased primitives. It follows that the length of each 1802 'velocities' sample must match the length of the corresponding 1803 'points' sample. Velocity is measured in position units per second, 1804 as per most simulation software. To convert to position units per 1805 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 1806 1807 See also .""" 1808 ) 1809 token visibility = "inherited" ( 1810 allowedTokens = ["inherited", "invisible"] 1811 doc = '''Visibility is meant to be the simplest form of "pruning" 1812 visibility that is supported by most DCC apps. Visibility is 1813 animatable, allowing a sub-tree of geometry to be present for some 1814 segment of a shot, and absent from others; unlike the action of 1815 deactivating geometry prims, invisible geometry is still 1816 available for inspection, for positioning, for defining volumes, etc.''' 1817 ) 1818 uniform token[] xformOpOrder ( 1819 doc = """Encodes the sequence of transformation operations in the 1820 order in which they should be pushed onto a transform stack while 1821 visiting a UsdStage's prims in a graph traversal that will effect 1822 the desired positioning for this prim and its descendant prims. 1823 1824 You should rarely, if ever, need to manipulate this attribute directly. 1825 It is managed by the AddXformOp(), SetResetXformStack(), and 1826 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 1827 GetLocalTransformation().""" 1828 ) 1829} 1830 1831class GeomSubset "GeomSubset" ( 1832 doc = """Encodes a subset of a piece of geometry (i.e. a UsdGeomImageable) 1833 as a set of indices. Currently only supports encoding of face-subsets, but 1834 could be extended in the future to support subsets representing edges, 1835 segments, points etc. 1836 1837 To apply to a geometric prim, a GeomSubset prim must be defined as a 1838 child of it in namespace. This restriction makes it easy and efficient 1839 to discover subsets of a prim. We might want to relax this restriction if 1840 it's common to have multiple <b>families</b> of subsets on a gprim and if 1841 it's useful to be able to organize subsets belonging to a </b>family</b> 1842 under a common scope. See 'familyName' attribute for more info on defining 1843 a family of subsets. 1844 1845 Note that a GeomSubset isn't an imageable (i.e. doesn't derive from 1846 UsdGeomImageable). So, you can't author <b>visibility</b> for it or 1847 override its <b>purpose</b>. 1848 1849 Materials are bound to GeomSubsets just as they are for regular 1850 geometry using API available in UsdShade (UsdShadeMaterial::Bind). 1851""" 1852) 1853{ 1854 uniform token elementType = "face" ( 1855 allowedTokens = ["face"] 1856 doc = '''The type of element that the indices target. Currently only 1857 allows "face" and defaults to it.''' 1858 ) 1859 uniform token familyName = "" ( 1860 doc = '''The name of the family of subsets that this subset belongs to. 1861 This is optional and is primarily useful when there are multiple 1862 families of subsets under a geometric prim. In some cases, this could 1863 also be used for achieving proper roundtripping of subset data between 1864 DCC apps. 1865 When multiple subsets belonging to a prim have the same familyName, they 1866 are said to belong to the family. A <i>familyType</i> value can be 1867 encoded on the owner of a family of subsets as a token using the static 1868 method UsdGeomSubset::SetFamilyType(). "familyType" can have one of the 1869 following values: 1870 <ul><li><b>UsdGeomTokens->partition</b>: implies that every element of 1871 the whole geometry appears exactly once in only one of the subsets 1872 belonging to the family.</li> 1873 <li><b>UsdGeomTokens->nonOverlapping</b>: an element that appears in one 1874 subset may not appear in any other subset belonging to the family.</li> 1875 <li><b>UsdGeomTokens->unrestricted</b>: implies that there are no 1876 restrictions w.r.t. the membership of elements in the subsets. They 1877 could be overlapping and the union of all subsets in the family may 1878 not represent the whole.</li> 1879 </ul> 1880 \\note The validity of subset data is not enforced by the authoring 1881 APIs, however they can be checked using UsdGeomSubset::ValidateFamily(). 1882 ''' 1883 ) 1884 int[] indices = [] ( 1885 doc = """The set of indices included in this subset. The indices need not 1886 be sorted, but the same index should not appear more than once.""" 1887 ) 1888} 1889 1890class NurbsPatch "NurbsPatch" ( 1891 doc = """Encodes a rational or polynomial non-uniform B-spline 1892 surface, with optional trim curves. 1893 1894 The encoding mostly follows that of RiNuPatch and RiTrimCurve: 1895 https://renderman.pixar.com/resources/current/RenderMan/geometricPrimitives.html#rinupatch , with some minor renaming and coalescing for clarity. 1896 1897 The layout of control vertices in the points attribute inherited 1898 from UsdGeomPointBased is row-major with U considered rows, and V columns. 1899 1900 \\anchor UsdGeom_NurbsPatch_Form 1901 <b>NurbsPatch Form</b> 1902 1903 The authored points, orders, knots, weights, and ranges are all that is 1904 required to render the nurbs patch. However, the only way to model closed 1905 surfaces with nurbs is to ensure that the first and last control points 1906 along the given axis are coincident. Similarly, to ensure the surface is 1907 not only closed but also C2 continuous, the last order - 1 control 1908 points must be (correspondingly) coincident with the first order - 1 1909 control points, and also the spacing of the last corresponding knots 1910 must be the same as the first corresponding knots. 1911 1912 <b>Form</b> is provided as an aid to interchange between modeling and 1913 animation applications so that they can robustly identify the intent with 1914 which the surface was modelled, and take measures (if they are able) to 1915 preserve the continuity/concidence constraints as the surface may be rigged 1916 or deformed. 1917 - An open-form NurbsPatch has no continuity constraints. 1918 - A closed-form NurbsPatch expects the first and last control points 1919 to overlap 1920 - A periodic-form NurbsPatch expects the first and last 1921 order - 1 control points to overlap. 1922 1923 <b>Nurbs vs Subdivision Surfaces</b> 1924 1925 Nurbs are an important modeling primitive in CAD/CAM tools and early 1926 computer graphics DCC's. Because they have a natural UV parameterization 1927 they easily support \"trim curves\", which allow smooth shapes to be 1928 carved out of the surface. 1929 1930 However, the topology of the patch is always rectangular, and joining two 1931 nurbs patches together (especially when they have differing numbers of 1932 spans) is difficult to do smoothly. Also, nurbs are not supported by 1933 the Ptex texturing technology (http://ptex.us). 1934 1935 Neither of these limitations are shared by subdivision surfaces; therefore, 1936 although they do not subscribe to trim-curve-based shaping, subdivs are 1937 often considered a more flexible modeling primitive. 1938 """ 1939) 1940{ 1941 vector3f[] accelerations ( 1942 doc = """If provided, 'accelerations' should be used with 1943 velocities to compute positions between samples for the 'points' 1944 attribute rather than interpolating between neighboring 'points' 1945 samples. Acceleration is measured in position units per second-squared. 1946 To convert to position units per squared UsdTimeCode, divide by the 1947 square of UsdStage::GetTimeCodesPerSecond().""" 1948 ) 1949 uniform bool doubleSided = 0 ( 1950 doc = """Although some renderers treat all parametric or polygonal 1951 surfaces as if they were effectively laminae with outward-facing 1952 normals on both sides, some renderers derive significant optimizations 1953 by considering these surfaces to have only a single outward side, 1954 typically determined by control-point winding order and/or 1955 orientation. By doing so they can perform \"backface culling\" to 1956 avoid drawing the many polygons of most closed surfaces that face away 1957 from the viewer. 1958 1959 However, it is often advantageous to model thin objects such as paper 1960 and cloth as single, open surfaces that must be viewable from both 1961 sides, always. Setting a gprim's doubleSided attribute to 1962 \\c true instructs all renderers to disable optimizations such as 1963 backface culling for the gprim, and attempt (not all renderers are able 1964 to do so, but the USD reference GL renderer always will) to provide 1965 forward-facing normals on each side of the surface for lighting 1966 calculations.""" 1967 ) 1968 float3[] extent ( 1969 doc = """Extent is a three dimensional range measuring the geometric 1970 extent of the authored gprim in its own local space (i.e. its own 1971 transform not applied), without accounting for any shader-induced 1972 displacement. Whenever any geometry-affecting attribute is authored 1973 for any gprim in a layer, extent must also be authored at the same 1974 timesample; failure to do so will result in incorrect bounds-computation. 1975 \\sa \\ref UsdGeom_Boundable_Extent. 1976 1977 An authored extent on a prim which has children is expected to include 1978 the extent of all children, as they will be pruned from BBox computation 1979 during traversal.""" 1980 ) 1981 normal3f[] normals ( 1982 doc = """Provide an object-space orientation for individual points, 1983 which, depending on subclass, may define a surface, curve, or free 1984 points. Note that 'normals' should not be authored on any Mesh that 1985 is subdivided, since the subdivision algorithm will define its own 1986 normals. 'normals' is not a generic primvar, but the number of elements 1987 in this attribute will be determined by its 'interpolation'. See 1988 . If 'normals' and 'primvars:normals' 1989 are both specified, the latter has precedence.""" 1990 ) 1991 uniform token orientation = "rightHanded" ( 1992 allowedTokens = ["rightHanded", "leftHanded"] 1993 doc = """Orientation specifies whether the gprim's surface normal 1994 should be computed using the right hand rule, or the left hand rule. 1995 Please see for a deeper explanation and 1996 generalization of orientation to composed scenes with transformation 1997 hierarchies.""" 1998 ) 1999 point3f[] points ( 2000 doc = """The primary geometry attribute for all PointBased 2001 primitives, describes points in (local) space.""" 2002 ) 2003 double[] pointWeights ( 2004 doc = """Optionally provides \"w\" components for each control point, 2005 thus must be the same length as the points attribute. If authored, 2006 the patch will be rational. If unauthored, the patch will be 2007 polynomial, i.e. weight for all points is 1.0. 2008 \\note Some DCC's pre-weight the points, but in this schema, 2009 points are not pre-weighted.""" 2010 ) 2011 color3f[] primvars:displayColor ( 2012 doc = '''It is useful to have an "official" colorSet that can be used 2013 as a display or modeling color, even in the absence of any specified 2014 shader for a gprim. DisplayColor serves this role; because it is a 2015 UsdGeomPrimvar, it can also be used as a gprim override for any shader 2016 that consumes a displayColor parameter.''' 2017 ) 2018 float[] primvars:displayOpacity ( 2019 doc = """Companion to displayColor that specifies opacity, broken 2020 out as an independent attribute rather than an rgba color, both so that 2021 each can be independently overridden, and because shaders rarely consume 2022 rgba parameters.""" 2023 ) 2024 rel proxyPrim ( 2025 doc = '''The proxyPrim relationship allows us to link a 2026 prim whose purpose is "render" to its (single target) 2027 purpose="proxy" prim. This is entirely optional, but can be 2028 useful in several scenarios: 2029 2030 - In a pipeline that does pruning (for complexity management) 2031 by deactivating prims composed from asset references, when we 2032 deactivate a purpose="render" prim, we will be able to discover 2033 and additionally deactivate its associated purpose="proxy" prim, 2034 so that preview renders reflect the pruning accurately. 2035 2036 - DCC importers may be able to make more aggressive optimizations 2037 for interactive processing and display if they can discover the proxy 2038 for a given render prim. 2039 2040 - With a little more work, a Hydra-based application will be able 2041 to map a picked proxy prim back to its render geometry for selection. 2042 2043 \\note It is only valid to author the proxyPrim relationship on 2044 prims whose purpose is "render".''' 2045 ) 2046 uniform token purpose = "default" ( 2047 allowedTokens = ["default", "render", "proxy", "guide"] 2048 doc = """Purpose is a classification of geometry into categories that 2049 can each be independently included or excluded from traversals of prims 2050 on a stage, such as rendering or bounding-box computation traversals. 2051 2052 See for more detail about how 2053 purpose is computed and used.""" 2054 ) 2055 int[] trimCurve:counts ( 2056 doc = '''Each element specifies how many curves are present in each 2057 "loop" of the trimCurve, and the length of the array determines how 2058 many loops the trimCurve contains. The sum of all elements is the 2059 total nuber of curves in the trim, to which we will refer as 2060 nCurves in describing the other trim attributes.''' 2061 ) 2062 double[] trimCurve:knots ( 2063 doc = """Flat list of parametric values for each of the 2064 nCurves curves. There will be as many knots as the sum over 2065 all elements of vertexCounts plus the sum over all elements of 2066 orders.""" 2067 ) 2068 int[] trimCurve:orders ( 2069 doc = "Flat list of orders for each of the nCurves curves." 2070 ) 2071 double3[] trimCurve:points ( 2072 doc = """Flat list of homogeneous 2D points (u, v, w) that comprise 2073 the nCurves curves. The number of points should be equal to the 2074 um over all elements of vertexCounts.""" 2075 ) 2076 double2[] trimCurve:ranges ( 2077 doc = """Flat list of minimum and maximum parametric values 2078 (as defined by knots) for each of the nCurves curves.""" 2079 ) 2080 int[] trimCurve:vertexCounts ( 2081 doc = """Flat list of number of vertices for each of the 2082 nCurves curves.""" 2083 ) 2084 uniform token uForm = "open" ( 2085 allowedTokens = ["open", "closed", "periodic"] 2086 doc = '''Interpret the control grid and knot vectors as representing 2087 an open, geometrically closed, or geometrically closed and C2 continuous 2088 surface along the U dimension. 2089 \\sa "NurbsPatch Form" ''' 2090 ) 2091 double[] uKnots ( 2092 doc = """Knot vector for U direction providing U parameterization. 2093 The length of this array must be ( uVertexCount + uOrder ), and its 2094 entries must take on monotonically increasing values.""" 2095 ) 2096 int uOrder ( 2097 doc = """Order in the U direction. Order must be positive and is 2098 equal to the degree of the polynomial basis to be evaluated, plus 1.""" 2099 ) 2100 double2 uRange ( 2101 doc = """Provides the minimum and maximum parametric values (as defined 2102 by uKnots) over which the surface is actually defined. The minimum 2103 must be less than the maximum, and greater than or equal to the 2104 value of uKnots[uOrder-1]. The maxium must be less than or equal 2105 to the last element's value in uKnots.""" 2106 ) 2107 int uVertexCount ( 2108 doc = """Number of vertices in the U direction. Should be at least as 2109 large as uOrder.""" 2110 ) 2111 vector3f[] velocities ( 2112 doc = """If provided, 'velocities' should be used by renderers to 2113 2114 compute positions between samples for the 'points' attribute, rather 2115 than interpolating between neighboring 'points' samples. This is the 2116 only reasonable means of computing motion blur for topologically 2117 varying PointBased primitives. It follows that the length of each 2118 'velocities' sample must match the length of the corresponding 2119 'points' sample. Velocity is measured in position units per second, 2120 as per most simulation software. To convert to position units per 2121 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 2122 2123 See also .""" 2124 ) 2125 uniform token vForm = "open" ( 2126 allowedTokens = ["open", "closed", "periodic"] 2127 doc = '''Interpret the control grid and knot vectors as representing 2128 an open, geometrically closed, or geometrically closed and C2 continuous 2129 surface along the V dimension. 2130 \\sa "NurbsPatch Form" ''' 2131 ) 2132 token visibility = "inherited" ( 2133 allowedTokens = ["inherited", "invisible"] 2134 doc = '''Visibility is meant to be the simplest form of "pruning" 2135 visibility that is supported by most DCC apps. Visibility is 2136 animatable, allowing a sub-tree of geometry to be present for some 2137 segment of a shot, and absent from others; unlike the action of 2138 deactivating geometry prims, invisible geometry is still 2139 available for inspection, for positioning, for defining volumes, etc.''' 2140 ) 2141 double[] vKnots ( 2142 doc = """Knot vector for V direction providing U parameterization. 2143 The length of this array must be ( vVertexCount + vOrder ), and its 2144 entries must take on monotonically increasing values.""" 2145 ) 2146 int vOrder ( 2147 doc = """Order in the V direction. Order must be positive and is 2148 equal to the degree of the polynomial basis to be evaluated, plus 1.""" 2149 ) 2150 double2 vRange ( 2151 doc = """Provides the minimum and maximum parametric values (as defined 2152 by vKnots) over which the surface is actually defined. The minimum 2153 must be less than the maximum, and greater than or equal to the 2154 value of vKnots[vOrder-1]. The maxium must be less than or equal 2155 to the last element's value in vKnots.""" 2156 ) 2157 int vVertexCount ( 2158 doc = """Number of vertices in the V direction. Should be at least as 2159 large as vOrder.""" 2160 ) 2161 uniform token[] xformOpOrder ( 2162 doc = """Encodes the sequence of transformation operations in the 2163 order in which they should be pushed onto a transform stack while 2164 visiting a UsdStage's prims in a graph traversal that will effect 2165 the desired positioning for this prim and its descendant prims. 2166 2167 You should rarely, if ever, need to manipulate this attribute directly. 2168 It is managed by the AddXformOp(), SetResetXformStack(), and 2169 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 2170 GetLocalTransformation().""" 2171 ) 2172} 2173 2174class "Curves" ( 2175 doc = """Base class for UsdGeomBasisCurves, UsdGeomNurbsCurves, and 2176 UsdGeomHermiteCurves. The BasisCurves schema is designed to be 2177 analagous to offline renderers' notion of batched curves (such as 2178 the classical RIB definition via Basis and Curves statements), 2179 while the NurbsCurve schema is designed to be analgous to the 2180 NURBS curves found in packages like Maya and Houdini while 2181 retaining their consistency with the RenderMan specification for 2182 NURBS Patches. HermiteCurves are useful for the 2183 interchange of animation guides and paths. 2184 2185 It is safe to use the length of the curve vertex count to derive 2186 the number of curves and the number and layout of curve vertices, 2187 but this schema should NOT be used to derive the number of curve 2188 points. While vertex indices are implicit in all shipped 2189 descendent types of this schema, one should not assume that all 2190 internal or future shipped schemas will follow this pattern. Be 2191 sure to key any indexing behavior off the concrete type, not this 2192 abstract type. 2193 """ 2194) 2195{ 2196 vector3f[] accelerations ( 2197 doc = """If provided, 'accelerations' should be used with 2198 velocities to compute positions between samples for the 'points' 2199 attribute rather than interpolating between neighboring 'points' 2200 samples. Acceleration is measured in position units per second-squared. 2201 To convert to position units per squared UsdTimeCode, divide by the 2202 square of UsdStage::GetTimeCodesPerSecond().""" 2203 ) 2204 int[] curveVertexCounts ( 2205 doc = """Curves-derived primitives can represent multiple distinct, 2206 potentially disconnected curves. The length of 'curveVertexCounts' 2207 gives the number of such curves, and each element describes the 2208 number of vertices in the corresponding curve""" 2209 ) 2210 uniform bool doubleSided = 0 ( 2211 doc = """Although some renderers treat all parametric or polygonal 2212 surfaces as if they were effectively laminae with outward-facing 2213 normals on both sides, some renderers derive significant optimizations 2214 by considering these surfaces to have only a single outward side, 2215 typically determined by control-point winding order and/or 2216 orientation. By doing so they can perform \"backface culling\" to 2217 avoid drawing the many polygons of most closed surfaces that face away 2218 from the viewer. 2219 2220 However, it is often advantageous to model thin objects such as paper 2221 and cloth as single, open surfaces that must be viewable from both 2222 sides, always. Setting a gprim's doubleSided attribute to 2223 \\c true instructs all renderers to disable optimizations such as 2224 backface culling for the gprim, and attempt (not all renderers are able 2225 to do so, but the USD reference GL renderer always will) to provide 2226 forward-facing normals on each side of the surface for lighting 2227 calculations.""" 2228 ) 2229 float3[] extent ( 2230 doc = """Extent is a three dimensional range measuring the geometric 2231 extent of the authored gprim in its own local space (i.e. its own 2232 transform not applied), without accounting for any shader-induced 2233 displacement. Whenever any geometry-affecting attribute is authored 2234 for any gprim in a layer, extent must also be authored at the same 2235 timesample; failure to do so will result in incorrect bounds-computation. 2236 \\sa \\ref UsdGeom_Boundable_Extent. 2237 2238 An authored extent on a prim which has children is expected to include 2239 the extent of all children, as they will be pruned from BBox computation 2240 during traversal.""" 2241 ) 2242 normal3f[] normals ( 2243 doc = """Provide an object-space orientation for individual points, 2244 which, depending on subclass, may define a surface, curve, or free 2245 points. Note that 'normals' should not be authored on any Mesh that 2246 is subdivided, since the subdivision algorithm will define its own 2247 normals. 'normals' is not a generic primvar, but the number of elements 2248 in this attribute will be determined by its 'interpolation'. See 2249 . If 'normals' and 'primvars:normals' 2250 are both specified, the latter has precedence.""" 2251 ) 2252 uniform token orientation = "rightHanded" ( 2253 allowedTokens = ["rightHanded", "leftHanded"] 2254 doc = """Orientation specifies whether the gprim's surface normal 2255 should be computed using the right hand rule, or the left hand rule. 2256 Please see for a deeper explanation and 2257 generalization of orientation to composed scenes with transformation 2258 hierarchies.""" 2259 ) 2260 point3f[] points ( 2261 doc = """The primary geometry attribute for all PointBased 2262 primitives, describes points in (local) space.""" 2263 ) 2264 color3f[] primvars:displayColor ( 2265 doc = '''It is useful to have an "official" colorSet that can be used 2266 as a display or modeling color, even in the absence of any specified 2267 shader for a gprim. DisplayColor serves this role; because it is a 2268 UsdGeomPrimvar, it can also be used as a gprim override for any shader 2269 that consumes a displayColor parameter.''' 2270 ) 2271 float[] primvars:displayOpacity ( 2272 doc = """Companion to displayColor that specifies opacity, broken 2273 out as an independent attribute rather than an rgba color, both so that 2274 each can be independently overridden, and because shaders rarely consume 2275 rgba parameters.""" 2276 ) 2277 rel proxyPrim ( 2278 doc = '''The proxyPrim relationship allows us to link a 2279 prim whose purpose is "render" to its (single target) 2280 purpose="proxy" prim. This is entirely optional, but can be 2281 useful in several scenarios: 2282 2283 - In a pipeline that does pruning (for complexity management) 2284 by deactivating prims composed from asset references, when we 2285 deactivate a purpose="render" prim, we will be able to discover 2286 and additionally deactivate its associated purpose="proxy" prim, 2287 so that preview renders reflect the pruning accurately. 2288 2289 - DCC importers may be able to make more aggressive optimizations 2290 for interactive processing and display if they can discover the proxy 2291 for a given render prim. 2292 2293 - With a little more work, a Hydra-based application will be able 2294 to map a picked proxy prim back to its render geometry for selection. 2295 2296 \\note It is only valid to author the proxyPrim relationship on 2297 prims whose purpose is "render".''' 2298 ) 2299 uniform token purpose = "default" ( 2300 allowedTokens = ["default", "render", "proxy", "guide"] 2301 doc = """Purpose is a classification of geometry into categories that 2302 can each be independently included or excluded from traversals of prims 2303 on a stage, such as rendering or bounding-box computation traversals. 2304 2305 See for more detail about how 2306 purpose is computed and used.""" 2307 ) 2308 vector3f[] velocities ( 2309 doc = """If provided, 'velocities' should be used by renderers to 2310 2311 compute positions between samples for the 'points' attribute, rather 2312 than interpolating between neighboring 'points' samples. This is the 2313 only reasonable means of computing motion blur for topologically 2314 varying PointBased primitives. It follows that the length of each 2315 'velocities' sample must match the length of the corresponding 2316 'points' sample. Velocity is measured in position units per second, 2317 as per most simulation software. To convert to position units per 2318 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 2319 2320 See also .""" 2321 ) 2322 token visibility = "inherited" ( 2323 allowedTokens = ["inherited", "invisible"] 2324 doc = '''Visibility is meant to be the simplest form of "pruning" 2325 visibility that is supported by most DCC apps. Visibility is 2326 animatable, allowing a sub-tree of geometry to be present for some 2327 segment of a shot, and absent from others; unlike the action of 2328 deactivating geometry prims, invisible geometry is still 2329 available for inspection, for positioning, for defining volumes, etc.''' 2330 ) 2331 float[] widths ( 2332 doc = """Provides width specification for the curves, whose application 2333 will depend on whether the curve is oriented (normals are defined for 2334 it), in which case widths are \"ribbon width\", or unoriented, in which 2335 case widths are cylinder width. 'widths' is not a generic Primvar, 2336 but the number of elements in this attribute will be determined by 2337 its 'interpolation'. See . If 'widths' 2338 and 'primvars:widths' are both specified, the latter has precedence.""" 2339 ) 2340 uniform token[] xformOpOrder ( 2341 doc = """Encodes the sequence of transformation operations in the 2342 order in which they should be pushed onto a transform stack while 2343 visiting a UsdStage's prims in a graph traversal that will effect 2344 the desired positioning for this prim and its descendant prims. 2345 2346 You should rarely, if ever, need to manipulate this attribute directly. 2347 It is managed by the AddXformOp(), SetResetXformStack(), and 2348 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 2349 GetLocalTransformation().""" 2350 ) 2351} 2352 2353class BasisCurves "BasisCurves" ( 2354 doc = """BasisCurves are a batched curve representation analogous to the 2355 classic RIB definition via Basis and Curves statements. BasisCurves are 2356 often used to render dense aggregate geometry like hair or grass. 2357 2358 A 'matrix' and 'vstep' associated with the basis are used to 2359 interpolate the vertices of a cubic BasisCurves. (The basis attribute 2360 is unused for linear BasisCurves.) 2361 2362 A single prim may have many curves whose count is determined implicitly by 2363 the length of the curveVertexCounts vector. Each individual curve is 2364 composed of one or more segments. Each segment is defined by four vertices 2365 for cubic curves and two vertices for linear curves. See the next section 2366 for more information on how to map curve vertex counts to segment counts. 2367 2368 Segment Indexing 2369 Interpolating a curve requires knowing how to decompose it into its 2370 individual segments. 2371 2372 The segments of a cubic curve are determined by the vertex count, 2373 the wrap (periodicity), and the vstep of the basis. For linear 2374 curves, the basis token is ignored and only the vertex count and 2375 wrap are needed. 2376 2377 cubic basis | vstep 2378 ------------- | ------ 2379 bezier | 3 2380 catmullRom | 1 2381 bspline | 1 2382 2383 The first segment of a cubic (nonperiodic) curve is always defined by its 2384 first four points. The vstep is the increment used to determine what 2385 vertex indices define the next segment. For a two segment (nonperiodic) 2386 bspline basis curve (vstep = 1), the first segment will be defined by 2387 interpolating vertices [0, 1, 2, 3] and the second segment will be defined 2388 by [1, 2, 3, 4]. For a two segment bezier basis curve (vstep = 3), the 2389 first segment will be defined by interpolating vertices [0, 1, 2, 3] and 2390 the second segment will be defined by [3, 4, 5, 6]. If the vstep is not 2391 one, then you must take special care to make sure that the number of cvs 2392 properly divides by your vstep. (The indices described are relative to 2393 the initial vertex index for a batched curve.) 2394 2395 For periodic curves, at least one of the curve's initial vertices are 2396 repeated to close the curve. For cubic curves, the number of vertices 2397 repeated is '4 - vstep'. For linear curves, only one vertex is repeated 2398 to close the loop. 2399 2400 Pinned curves are a special case of nonperiodic curves that only affects 2401 the behavior of cubic Bspline and Catmull-Rom curves. To evaluate or render 2402 pinned curves, a client must effectively add 'phantom points' at the 2403 beginning and end of every curve in a batch. These phantom points 2404 are injected to ensure that the interpolated curve begins at P[0] and 2405 ends at P[n-1]. 2406 2407 For a curve with initial point P[0] and last point P[n-1], the phantom 2408 points are defined as. 2409 P[-1] = 2 * P[0] - P[1] 2410 P[n] = 2 * P[n-1] - P[n-2] 2411 2412 Pinned cubic curves will (usually) have to be unpacked into the standard 2413 nonperiodic representation before rendering. This unpacking can add some 2414 additional overhead. However, using pinned curves reduces the amount of 2415 data recorded in a scene and (more importantly) better records the 2416 authors' intent for interchange. 2417 2418 \\note The additional phantom points mean that the minimum curve vertex 2419 count for cubic bspline and catmullRom curves is 2. 2420 2421 Linear curve segments are defined by two vertices. 2422 A two segment linear curve's first segment would be defined by 2423 interpolating vertices [0, 1]. The second segment would be defined by 2424 vertices [1, 2]. (Again, for a batched curve, indices are relative to 2425 the initial vertex index.) 2426 2427 When validating curve topology, each renderable entry in the 2428 curveVertexCounts vector must pass this check. 2429 2430 type | wrap | validitity 2431 ------- | --------------------------- | ---------------- 2432 linear | nonperiodic | curveVertexCounts[i] > 2 2433 linear | periodic | curveVertexCounts[i] > 3 2434 cubic | nonperiodic | (curveVertexCounts[i] - 4) % vstep == 0 2435 cubic | periodic | (curveVertexCounts[i]) % vstep == 0 2436 cubic | pinned (catmullRom/bspline) | (curveVertexCounts[i] - 2) >= 0 2437 2438 Cubic Vertex Interpolation 2439 2440 \\image html USDCurveBasisMatrix.png width=750 2441 2442 Linear Vertex Interpolation 2443 2444 Linear interpolation is always used on curves of type linear. 2445 't' with domain [0, 1], the curve is defined by the equation 2446 P0 * (1-t) + P1 * t. t at 0 describes the first point and t at 1 describes 2447 the end point. 2448 2449 Primvar Interpolation 2450 2451 For cubic curves, primvar data can be either interpolated cubically between 2452 vertices or linearly across segments. The corresponding token 2453 for cubic interpolation is 'vertex' and for linear interpolation is 2454 'varying'. Per vertex data should be the same size as the number 2455 of vertices in your curve. Segment varying data is dependent on the 2456 wrap (periodicity) and number of segments in your curve. For linear curves, 2457 varying and vertex data would be interpolated the same way. By convention 2458 varying is the preferred interpolation because of the association of 2459 varying with linear interpolation. 2460 2461 \\image html USDCurvePrimvars.png 2462 2463 To convert an entry in the curveVertexCounts vector into a segment count 2464 for an individual curve, apply these rules. Sum up all the results in 2465 order to compute how many total segments all curves have. 2466 2467 The following tables describe the expected segment count for the 'i'th 2468 curve in a curve batch as well as the entire batch. Python syntax 2469 like '[:]' (to describe all members of an array) and 'len(...)' 2470 (to describe the length of an array) are used. 2471 2472 type | wrap | curve segment count | batch segment count 2473 ------- | --------------------------- | -------------------------------------- | -------------------------- 2474 linear | nonperiodic | curveVertexCounts[i] - 1 | sum(curveVertexCounts[:]) - len(curveVertexCounts) 2475 linear | periodic | curveVertexCounts[i] | sum(curveVertexCounts[:]) 2476 cubic | nonperiodic | (curveVertexCounts[i] - 4) / vstep + 1 | sum(curveVertexCounts[:] - 4) / vstep + len(curveVertexCounts) 2477 cubic | periodic | curveVertexCounts[i] / vstep | sum(curveVertexCounts[:]) / vstep 2478 cubic | pinned (catmullRom/bspline) | (curveVertexCounts[i] - 2) + 1 | sum(curveVertexCounts[:] - 2) + len(curveVertexCounts) 2479 2480 The following table descrives the expected size of varying 2481 (linearly interpolated) data, derived from the segment counts computed 2482 above. 2483 2484 wrap | curve varying count | batch varying count 2485 ------------------- | ---------------------------- | ------------------------------------------------ 2486 nonperiodic/pinned | segmentCounts[i] + 1 | sum(segmentCounts[:]) + len(curveVertexCounts) 2487 periodic | segmentCounts[i] | sum(segmentCounts[:]) 2488 2489 Both curve types additionally define 'constant' interpolation for the 2490 entire prim and 'uniform' interpolation as per curve data. 2491 2492 2493 \\note Take care when providing support for linearly interpolated data for 2494 cubic curves. Its shape doesn't provide a one to one mapping with either 2495 the number of curves (like 'uniform') or the number of vertices (like 2496 'vertex') and so it is often overlooked. This is the only primitive in 2497 UsdGeom (as of this writing) where this is true. For meshes, while they 2498 use different interpolation methods, 'varying' and 'vertex' are both 2499 specified per point. It's common to assume that curves follow a similar 2500 pattern and build in structures and language for per primitive, per 2501 element, and per point data only to come upon these arrays that don't 2502 quite fit into either of those categories. It is 2503 also common to conflate 'varying' with being per segment data and use the 2504 segmentCount rules table instead of its neighboring varying data table 2505 rules. We suspect that this is because for the common case of 2506 nonperiodic cubic curves, both the provided segment count and varying data 2507 size formula end with '+ 1'. While debugging, users may look at the double 2508 '+ 1' as a mistake and try to remove it. We take this time to enumerate 2509 these issues because we've fallen into them before and hope that we save 2510 others time in their own implementations. 2511 2512 As an example of deriving per curve segment and varying primvar data counts from 2513 the wrap, type, basis, and curveVertexCount, the following table is provided. 2514 2515 wrap | type | basis | curveVertexCount | curveSegmentCount | varyingDataCount 2516 ------------- | ------- | ------- | ----------------- | ------------------ | ------------------------- 2517 nonperiodic | linear | N/A | [2 3 2 5] | [1 2 1 4] | [2 3 2 5] 2518 nonperiodic | cubic | bezier | [4 7 10 4 7] | [1 2 3 1 2] | [2 3 4 2 3] 2519 nonperiodic | cubic | bspline | [5 4 6 7] | [2 1 3 4] | [3 2 4 5] 2520 periodic | cubic | bezier | [6 9 6] | [2 3 2] | [2 3 2] 2521 periodic | linear | N/A | [3 7] | [3 7] | [3 7] 2522 2523 Tubes and Ribbons 2524 2525 The strictest definition of a curve as an infinitely thin wire is not 2526 particularly useful for describing production scenes. The additional 2527 widths and normals attributes can be used to describe cylindrical 2528 tubes and or flat oriented ribbons. 2529 2530 Curves with only widths defined are imaged as tubes with radius 2531 'width / 2'. Curves with both widths and normals are imaged as ribbons 2532 oriented in the direction of the interpolated normal vectors. 2533 2534 While not technically UsdGeomPrimvars, widths and normals 2535 also have interpolation metadata. It's common for authored widths to have 2536 constant, varying, or vertex interpolation 2537 (see UsdGeomCurves::GetWidthsInterpolation()). It's common for 2538 authored normals to have varying interpolation 2539 (see UsdGeomPointBased::GetNormalsInterpolation()). 2540 2541 \\image html USDCurveHydra.png 2542 2543 The file used to generate these curves can be found in 2544 pxr/extras/examples/usdGeomExamples/basisCurves.usda. It's provided 2545 as a reference on how to properly image both tubes and ribbons. The first 2546 row of curves are linear; the second are cubic bezier. (We aim in future 2547 releases of HdSt to fix the discontinuity seen with broken tangents to 2548 better match offline renderers like RenderMan.) The yellow and violet 2549 cubic curves represent cubic vertex width interpolation for which there is 2550 no equivalent for linear curves. 2551 2552 \\note How did this prim type get its name? This prim is a portmanteau of 2553 two different statements in the original RenderMan specification: 2554 'Basis' and 'Curves'. 2555""" 2556) 2557{ 2558 vector3f[] accelerations ( 2559 doc = """If provided, 'accelerations' should be used with 2560 velocities to compute positions between samples for the 'points' 2561 attribute rather than interpolating between neighboring 'points' 2562 samples. Acceleration is measured in position units per second-squared. 2563 To convert to position units per squared UsdTimeCode, divide by the 2564 square of UsdStage::GetTimeCodesPerSecond().""" 2565 ) 2566 uniform token basis = "bezier" ( 2567 allowedTokens = ["bezier", "bspline", "catmullRom"] 2568 doc = """The basis specifies the vstep and matrix used for cubic 2569 interpolation. \\note The 'hermite' and 'power' tokens have been 2570 removed. We've provided UsdGeomHermiteCurves 2571 as an alternative for the 'hermite' basis.""" 2572 ) 2573 int[] curveVertexCounts ( 2574 doc = """Curves-derived primitives can represent multiple distinct, 2575 potentially disconnected curves. The length of 'curveVertexCounts' 2576 gives the number of such curves, and each element describes the 2577 number of vertices in the corresponding curve""" 2578 ) 2579 uniform bool doubleSided = 0 ( 2580 doc = """Although some renderers treat all parametric or polygonal 2581 surfaces as if they were effectively laminae with outward-facing 2582 normals on both sides, some renderers derive significant optimizations 2583 by considering these surfaces to have only a single outward side, 2584 typically determined by control-point winding order and/or 2585 orientation. By doing so they can perform \"backface culling\" to 2586 avoid drawing the many polygons of most closed surfaces that face away 2587 from the viewer. 2588 2589 However, it is often advantageous to model thin objects such as paper 2590 and cloth as single, open surfaces that must be viewable from both 2591 sides, always. Setting a gprim's doubleSided attribute to 2592 \\c true instructs all renderers to disable optimizations such as 2593 backface culling for the gprim, and attempt (not all renderers are able 2594 to do so, but the USD reference GL renderer always will) to provide 2595 forward-facing normals on each side of the surface for lighting 2596 calculations.""" 2597 ) 2598 float3[] extent ( 2599 doc = """Extent is a three dimensional range measuring the geometric 2600 extent of the authored gprim in its own local space (i.e. its own 2601 transform not applied), without accounting for any shader-induced 2602 displacement. Whenever any geometry-affecting attribute is authored 2603 for any gprim in a layer, extent must also be authored at the same 2604 timesample; failure to do so will result in incorrect bounds-computation. 2605 \\sa \\ref UsdGeom_Boundable_Extent. 2606 2607 An authored extent on a prim which has children is expected to include 2608 the extent of all children, as they will be pruned from BBox computation 2609 during traversal.""" 2610 ) 2611 normal3f[] normals ( 2612 doc = """Provide an object-space orientation for individual points, 2613 which, depending on subclass, may define a surface, curve, or free 2614 points. Note that 'normals' should not be authored on any Mesh that 2615 is subdivided, since the subdivision algorithm will define its own 2616 normals. 'normals' is not a generic primvar, but the number of elements 2617 in this attribute will be determined by its 'interpolation'. See 2618 . If 'normals' and 'primvars:normals' 2619 are both specified, the latter has precedence.""" 2620 ) 2621 uniform token orientation = "rightHanded" ( 2622 allowedTokens = ["rightHanded", "leftHanded"] 2623 doc = """Orientation specifies whether the gprim's surface normal 2624 should be computed using the right hand rule, or the left hand rule. 2625 Please see for a deeper explanation and 2626 generalization of orientation to composed scenes with transformation 2627 hierarchies.""" 2628 ) 2629 point3f[] points ( 2630 doc = """The primary geometry attribute for all PointBased 2631 primitives, describes points in (local) space.""" 2632 ) 2633 color3f[] primvars:displayColor ( 2634 doc = '''It is useful to have an "official" colorSet that can be used 2635 as a display or modeling color, even in the absence of any specified 2636 shader for a gprim. DisplayColor serves this role; because it is a 2637 UsdGeomPrimvar, it can also be used as a gprim override for any shader 2638 that consumes a displayColor parameter.''' 2639 ) 2640 float[] primvars:displayOpacity ( 2641 doc = """Companion to displayColor that specifies opacity, broken 2642 out as an independent attribute rather than an rgba color, both so that 2643 each can be independently overridden, and because shaders rarely consume 2644 rgba parameters.""" 2645 ) 2646 rel proxyPrim ( 2647 doc = '''The proxyPrim relationship allows us to link a 2648 prim whose purpose is "render" to its (single target) 2649 purpose="proxy" prim. This is entirely optional, but can be 2650 useful in several scenarios: 2651 2652 - In a pipeline that does pruning (for complexity management) 2653 by deactivating prims composed from asset references, when we 2654 deactivate a purpose="render" prim, we will be able to discover 2655 and additionally deactivate its associated purpose="proxy" prim, 2656 so that preview renders reflect the pruning accurately. 2657 2658 - DCC importers may be able to make more aggressive optimizations 2659 for interactive processing and display if they can discover the proxy 2660 for a given render prim. 2661 2662 - With a little more work, a Hydra-based application will be able 2663 to map a picked proxy prim back to its render geometry for selection. 2664 2665 \\note It is only valid to author the proxyPrim relationship on 2666 prims whose purpose is "render".''' 2667 ) 2668 uniform token purpose = "default" ( 2669 allowedTokens = ["default", "render", "proxy", "guide"] 2670 doc = """Purpose is a classification of geometry into categories that 2671 can each be independently included or excluded from traversals of prims 2672 on a stage, such as rendering or bounding-box computation traversals. 2673 2674 See for more detail about how 2675 purpose is computed and used.""" 2676 ) 2677 uniform token type = "cubic" ( 2678 allowedTokens = ["linear", "cubic"] 2679 doc = """Linear curves interpolate linearly between two vertices. 2680 Cubic curves use a basis matrix with four vertices to interpolate a segment.""" 2681 ) 2682 vector3f[] velocities ( 2683 doc = """If provided, 'velocities' should be used by renderers to 2684 2685 compute positions between samples for the 'points' attribute, rather 2686 than interpolating between neighboring 'points' samples. This is the 2687 only reasonable means of computing motion blur for topologically 2688 varying PointBased primitives. It follows that the length of each 2689 'velocities' sample must match the length of the corresponding 2690 'points' sample. Velocity is measured in position units per second, 2691 as per most simulation software. To convert to position units per 2692 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 2693 2694 See also .""" 2695 ) 2696 token visibility = "inherited" ( 2697 allowedTokens = ["inherited", "invisible"] 2698 doc = '''Visibility is meant to be the simplest form of "pruning" 2699 visibility that is supported by most DCC apps. Visibility is 2700 animatable, allowing a sub-tree of geometry to be present for some 2701 segment of a shot, and absent from others; unlike the action of 2702 deactivating geometry prims, invisible geometry is still 2703 available for inspection, for positioning, for defining volumes, etc.''' 2704 ) 2705 float[] widths ( 2706 doc = """Provides width specification for the curves, whose application 2707 will depend on whether the curve is oriented (normals are defined for 2708 it), in which case widths are \"ribbon width\", or unoriented, in which 2709 case widths are cylinder width. 'widths' is not a generic Primvar, 2710 but the number of elements in this attribute will be determined by 2711 its 'interpolation'. See . If 'widths' 2712 and 'primvars:widths' are both specified, the latter has precedence.""" 2713 ) 2714 uniform token wrap = "nonperiodic" ( 2715 allowedTokens = ["nonperiodic", "periodic", "pinned"] 2716 doc = """If wrap is set to periodic, the curve when rendered will 2717 repeat the initial vertices (dependent on the vstep) to close the 2718 curve. If wrap is set to 'pinned', phantom points may be created 2719 to ensure that the curve interpolation starts at P[0] and ends at P[n-1]. 2720 """ 2721 ) 2722 uniform token[] xformOpOrder ( 2723 doc = """Encodes the sequence of transformation operations in the 2724 order in which they should be pushed onto a transform stack while 2725 visiting a UsdStage's prims in a graph traversal that will effect 2726 the desired positioning for this prim and its descendant prims. 2727 2728 You should rarely, if ever, need to manipulate this attribute directly. 2729 It is managed by the AddXformOp(), SetResetXformStack(), and 2730 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 2731 GetLocalTransformation().""" 2732 ) 2733} 2734 2735class NurbsCurves "NurbsCurves" ( 2736 doc = """This schema is analagous to NURBS Curves in packages like Maya 2737 and Houdini, often used for interchange of rigging and modeling curves. 2738 Unlike Maya, this curve spec supports batching of multiple curves into a 2739 single prim, widths, and normals in the schema. Additionally, we require 2740 'numSegments + 2 * degree + 1' knots (2 more than maya does). This is to 2741 be more consistent with RenderMan's NURBS patch specification. 2742 2743 To express a periodic curve: 2744 - knot[0] = knot[1] - (knots[-2] - knots[-3]; 2745 - knot[-1] = knot[-2] + (knot[2] - knots[1]); 2746 2747 To express a nonperiodic curve: 2748 - knot[0] = knot[1]; 2749 - knot[-1] = knot[-2]; 2750 2751 In spite of these slight differences in the spec, curves generated in Maya 2752 should be preserved when roundtripping. 2753 2754 order and range, when representing a batched NurbsCurve should be 2755 authored one value per curve. knots should be the concatentation of 2756 all batched curves.""" 2757) 2758{ 2759 vector3f[] accelerations ( 2760 doc = """If provided, 'accelerations' should be used with 2761 velocities to compute positions between samples for the 'points' 2762 attribute rather than interpolating between neighboring 'points' 2763 samples. Acceleration is measured in position units per second-squared. 2764 To convert to position units per squared UsdTimeCode, divide by the 2765 square of UsdStage::GetTimeCodesPerSecond().""" 2766 ) 2767 int[] curveVertexCounts ( 2768 doc = """Curves-derived primitives can represent multiple distinct, 2769 potentially disconnected curves. The length of 'curveVertexCounts' 2770 gives the number of such curves, and each element describes the 2771 number of vertices in the corresponding curve""" 2772 ) 2773 uniform bool doubleSided = 0 ( 2774 doc = """Although some renderers treat all parametric or polygonal 2775 surfaces as if they were effectively laminae with outward-facing 2776 normals on both sides, some renderers derive significant optimizations 2777 by considering these surfaces to have only a single outward side, 2778 typically determined by control-point winding order and/or 2779 orientation. By doing so they can perform \"backface culling\" to 2780 avoid drawing the many polygons of most closed surfaces that face away 2781 from the viewer. 2782 2783 However, it is often advantageous to model thin objects such as paper 2784 and cloth as single, open surfaces that must be viewable from both 2785 sides, always. Setting a gprim's doubleSided attribute to 2786 \\c true instructs all renderers to disable optimizations such as 2787 backface culling for the gprim, and attempt (not all renderers are able 2788 to do so, but the USD reference GL renderer always will) to provide 2789 forward-facing normals on each side of the surface for lighting 2790 calculations.""" 2791 ) 2792 float3[] extent ( 2793 doc = """Extent is a three dimensional range measuring the geometric 2794 extent of the authored gprim in its own local space (i.e. its own 2795 transform not applied), without accounting for any shader-induced 2796 displacement. Whenever any geometry-affecting attribute is authored 2797 for any gprim in a layer, extent must also be authored at the same 2798 timesample; failure to do so will result in incorrect bounds-computation. 2799 \\sa \\ref UsdGeom_Boundable_Extent. 2800 2801 An authored extent on a prim which has children is expected to include 2802 the extent of all children, as they will be pruned from BBox computation 2803 during traversal.""" 2804 ) 2805 double[] knots ( 2806 doc = """Knot vector providing curve parameterization. 2807 The length of the slice of the array for the ith curve 2808 must be ( curveVertexCount[i] + order[i] ), and its 2809 entries must take on monotonically increasing values.""" 2810 ) 2811 normal3f[] normals ( 2812 doc = """Provide an object-space orientation for individual points, 2813 which, depending on subclass, may define a surface, curve, or free 2814 points. Note that 'normals' should not be authored on any Mesh that 2815 is subdivided, since the subdivision algorithm will define its own 2816 normals. 'normals' is not a generic primvar, but the number of elements 2817 in this attribute will be determined by its 'interpolation'. See 2818 . If 'normals' and 'primvars:normals' 2819 are both specified, the latter has precedence.""" 2820 ) 2821 int[] order = [] ( 2822 doc = """Order of the curve. Order must be positive and is 2823 equal to the degree of the polynomial basis to be evaluated, plus 1. 2824 Its value for the 'i'th curve must be less than or equal to 2825 curveVertexCount[i]""" 2826 ) 2827 uniform token orientation = "rightHanded" ( 2828 allowedTokens = ["rightHanded", "leftHanded"] 2829 doc = """Orientation specifies whether the gprim's surface normal 2830 should be computed using the right hand rule, or the left hand rule. 2831 Please see for a deeper explanation and 2832 generalization of orientation to composed scenes with transformation 2833 hierarchies.""" 2834 ) 2835 point3f[] points ( 2836 doc = """The primary geometry attribute for all PointBased 2837 primitives, describes points in (local) space.""" 2838 ) 2839 color3f[] primvars:displayColor ( 2840 doc = '''It is useful to have an "official" colorSet that can be used 2841 as a display or modeling color, even in the absence of any specified 2842 shader for a gprim. DisplayColor serves this role; because it is a 2843 UsdGeomPrimvar, it can also be used as a gprim override for any shader 2844 that consumes a displayColor parameter.''' 2845 ) 2846 float[] primvars:displayOpacity ( 2847 doc = """Companion to displayColor that specifies opacity, broken 2848 out as an independent attribute rather than an rgba color, both so that 2849 each can be independently overridden, and because shaders rarely consume 2850 rgba parameters.""" 2851 ) 2852 rel proxyPrim ( 2853 doc = '''The proxyPrim relationship allows us to link a 2854 prim whose purpose is "render" to its (single target) 2855 purpose="proxy" prim. This is entirely optional, but can be 2856 useful in several scenarios: 2857 2858 - In a pipeline that does pruning (for complexity management) 2859 by deactivating prims composed from asset references, when we 2860 deactivate a purpose="render" prim, we will be able to discover 2861 and additionally deactivate its associated purpose="proxy" prim, 2862 so that preview renders reflect the pruning accurately. 2863 2864 - DCC importers may be able to make more aggressive optimizations 2865 for interactive processing and display if they can discover the proxy 2866 for a given render prim. 2867 2868 - With a little more work, a Hydra-based application will be able 2869 to map a picked proxy prim back to its render geometry for selection. 2870 2871 \\note It is only valid to author the proxyPrim relationship on 2872 prims whose purpose is "render".''' 2873 ) 2874 uniform token purpose = "default" ( 2875 allowedTokens = ["default", "render", "proxy", "guide"] 2876 doc = """Purpose is a classification of geometry into categories that 2877 can each be independently included or excluded from traversals of prims 2878 on a stage, such as rendering or bounding-box computation traversals. 2879 2880 See for more detail about how 2881 purpose is computed and used.""" 2882 ) 2883 double2[] ranges ( 2884 doc = """Provides the minimum and maximum parametric values (as defined 2885 by knots) over which the curve is actually defined. The minimum must 2886 be less than the maximum, and greater than or equal to the value of the 2887 knots['i'th curve slice][order[i]-1]. The maxium must be less 2888 than or equal to the last element's value in knots['i'th curve slice]. 2889\tRange maps to (vmin, vmax) in the RenderMan spec.""" 2890 ) 2891 vector3f[] velocities ( 2892 doc = """If provided, 'velocities' should be used by renderers to 2893 2894 compute positions between samples for the 'points' attribute, rather 2895 than interpolating between neighboring 'points' samples. This is the 2896 only reasonable means of computing motion blur for topologically 2897 varying PointBased primitives. It follows that the length of each 2898 'velocities' sample must match the length of the corresponding 2899 'points' sample. Velocity is measured in position units per second, 2900 as per most simulation software. To convert to position units per 2901 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 2902 2903 See also .""" 2904 ) 2905 token visibility = "inherited" ( 2906 allowedTokens = ["inherited", "invisible"] 2907 doc = '''Visibility is meant to be the simplest form of "pruning" 2908 visibility that is supported by most DCC apps. Visibility is 2909 animatable, allowing a sub-tree of geometry to be present for some 2910 segment of a shot, and absent from others; unlike the action of 2911 deactivating geometry prims, invisible geometry is still 2912 available for inspection, for positioning, for defining volumes, etc.''' 2913 ) 2914 float[] widths ( 2915 doc = """Provides width specification for the curves, whose application 2916 will depend on whether the curve is oriented (normals are defined for 2917 it), in which case widths are \"ribbon width\", or unoriented, in which 2918 case widths are cylinder width. 'widths' is not a generic Primvar, 2919 but the number of elements in this attribute will be determined by 2920 its 'interpolation'. See . If 'widths' 2921 and 'primvars:widths' are both specified, the latter has precedence.""" 2922 ) 2923 uniform token[] xformOpOrder ( 2924 doc = """Encodes the sequence of transformation operations in the 2925 order in which they should be pushed onto a transform stack while 2926 visiting a UsdStage's prims in a graph traversal that will effect 2927 the desired positioning for this prim and its descendant prims. 2928 2929 You should rarely, if ever, need to manipulate this attribute directly. 2930 It is managed by the AddXformOp(), SetResetXformStack(), and 2931 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 2932 GetLocalTransformation().""" 2933 ) 2934} 2935 2936class Points "Points" ( 2937 doc = """Points are analogous to the <A HREF=\"https://renderman.pixar.com/resources/current/RenderMan/appnote.18.html\">RiPoints spec</A>. 2938 2939 Points can be an efficient means of storing and rendering particle 2940 effects comprised of thousands or millions of small particles. Points 2941 generally receive a single shading sample each, which should take 2942 normals into account, if present. 2943 2944 While not technically UsdGeomPrimvars, the widths and normals also 2945 have interpolation metadata. It's common for authored widths and normals 2946 to have constant or varying interpolation.""" 2947) 2948{ 2949 vector3f[] accelerations ( 2950 doc = """If provided, 'accelerations' should be used with 2951 velocities to compute positions between samples for the 'points' 2952 attribute rather than interpolating between neighboring 'points' 2953 samples. Acceleration is measured in position units per second-squared. 2954 To convert to position units per squared UsdTimeCode, divide by the 2955 square of UsdStage::GetTimeCodesPerSecond().""" 2956 ) 2957 uniform bool doubleSided = 0 ( 2958 doc = """Although some renderers treat all parametric or polygonal 2959 surfaces as if they were effectively laminae with outward-facing 2960 normals on both sides, some renderers derive significant optimizations 2961 by considering these surfaces to have only a single outward side, 2962 typically determined by control-point winding order and/or 2963 orientation. By doing so they can perform \"backface culling\" to 2964 avoid drawing the many polygons of most closed surfaces that face away 2965 from the viewer. 2966 2967 However, it is often advantageous to model thin objects such as paper 2968 and cloth as single, open surfaces that must be viewable from both 2969 sides, always. Setting a gprim's doubleSided attribute to 2970 \\c true instructs all renderers to disable optimizations such as 2971 backface culling for the gprim, and attempt (not all renderers are able 2972 to do so, but the USD reference GL renderer always will) to provide 2973 forward-facing normals on each side of the surface for lighting 2974 calculations.""" 2975 ) 2976 float3[] extent ( 2977 doc = """Extent is a three dimensional range measuring the geometric 2978 extent of the authored gprim in its own local space (i.e. its own 2979 transform not applied), without accounting for any shader-induced 2980 displacement. Whenever any geometry-affecting attribute is authored 2981 for any gprim in a layer, extent must also be authored at the same 2982 timesample; failure to do so will result in incorrect bounds-computation. 2983 \\sa \\ref UsdGeom_Boundable_Extent. 2984 2985 An authored extent on a prim which has children is expected to include 2986 the extent of all children, as they will be pruned from BBox computation 2987 during traversal.""" 2988 ) 2989 int64[] ids ( 2990 doc = """Ids are optional; if authored, the ids array should be the same 2991 length as the points array, specifying (at each timesample if 2992 point identities are changing) the id of each point. The 2993 type is signed intentionally, so that clients can encode some 2994 binary state on Id'd points without adding a separate 2995 primvar.""" 2996 ) 2997 normal3f[] normals ( 2998 doc = """Provide an object-space orientation for individual points, 2999 which, depending on subclass, may define a surface, curve, or free 3000 points. Note that 'normals' should not be authored on any Mesh that 3001 is subdivided, since the subdivision algorithm will define its own 3002 normals. 'normals' is not a generic primvar, but the number of elements 3003 in this attribute will be determined by its 'interpolation'. See 3004 . If 'normals' and 'primvars:normals' 3005 are both specified, the latter has precedence.""" 3006 ) 3007 uniform token orientation = "rightHanded" ( 3008 allowedTokens = ["rightHanded", "leftHanded"] 3009 doc = """Orientation specifies whether the gprim's surface normal 3010 should be computed using the right hand rule, or the left hand rule. 3011 Please see for a deeper explanation and 3012 generalization of orientation to composed scenes with transformation 3013 hierarchies.""" 3014 ) 3015 point3f[] points ( 3016 doc = """The primary geometry attribute for all PointBased 3017 primitives, describes points in (local) space.""" 3018 ) 3019 color3f[] primvars:displayColor ( 3020 doc = '''It is useful to have an "official" colorSet that can be used 3021 as a display or modeling color, even in the absence of any specified 3022 shader for a gprim. DisplayColor serves this role; because it is a 3023 UsdGeomPrimvar, it can also be used as a gprim override for any shader 3024 that consumes a displayColor parameter.''' 3025 ) 3026 float[] primvars:displayOpacity ( 3027 doc = """Companion to displayColor that specifies opacity, broken 3028 out as an independent attribute rather than an rgba color, both so that 3029 each can be independently overridden, and because shaders rarely consume 3030 rgba parameters.""" 3031 ) 3032 rel proxyPrim ( 3033 doc = '''The proxyPrim relationship allows us to link a 3034 prim whose purpose is "render" to its (single target) 3035 purpose="proxy" prim. This is entirely optional, but can be 3036 useful in several scenarios: 3037 3038 - In a pipeline that does pruning (for complexity management) 3039 by deactivating prims composed from asset references, when we 3040 deactivate a purpose="render" prim, we will be able to discover 3041 and additionally deactivate its associated purpose="proxy" prim, 3042 so that preview renders reflect the pruning accurately. 3043 3044 - DCC importers may be able to make more aggressive optimizations 3045 for interactive processing and display if they can discover the proxy 3046 for a given render prim. 3047 3048 - With a little more work, a Hydra-based application will be able 3049 to map a picked proxy prim back to its render geometry for selection. 3050 3051 \\note It is only valid to author the proxyPrim relationship on 3052 prims whose purpose is "render".''' 3053 ) 3054 uniform token purpose = "default" ( 3055 allowedTokens = ["default", "render", "proxy", "guide"] 3056 doc = """Purpose is a classification of geometry into categories that 3057 can each be independently included or excluded from traversals of prims 3058 on a stage, such as rendering or bounding-box computation traversals. 3059 3060 See for more detail about how 3061 purpose is computed and used.""" 3062 ) 3063 vector3f[] velocities ( 3064 doc = """If provided, 'velocities' should be used by renderers to 3065 3066 compute positions between samples for the 'points' attribute, rather 3067 than interpolating between neighboring 'points' samples. This is the 3068 only reasonable means of computing motion blur for topologically 3069 varying PointBased primitives. It follows that the length of each 3070 'velocities' sample must match the length of the corresponding 3071 'points' sample. Velocity is measured in position units per second, 3072 as per most simulation software. To convert to position units per 3073 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 3074 3075 See also .""" 3076 ) 3077 token visibility = "inherited" ( 3078 allowedTokens = ["inherited", "invisible"] 3079 doc = '''Visibility is meant to be the simplest form of "pruning" 3080 visibility that is supported by most DCC apps. Visibility is 3081 animatable, allowing a sub-tree of geometry to be present for some 3082 segment of a shot, and absent from others; unlike the action of 3083 deactivating geometry prims, invisible geometry is still 3084 available for inspection, for positioning, for defining volumes, etc.''' 3085 ) 3086 float[] widths ( 3087 doc = """Widths are defined as the diameter of the points, in 3088 object space. 'widths' is not a generic Primvar, but 3089 the number of elements in this attribute will be determined by 3090 its 'interpolation'. See . If 3091 'widths' and 'primvars:widths' are both specified, the latter 3092 has precedence.""" 3093 ) 3094 uniform token[] xformOpOrder ( 3095 doc = """Encodes the sequence of transformation operations in the 3096 order in which they should be pushed onto a transform stack while 3097 visiting a UsdStage's prims in a graph traversal that will effect 3098 the desired positioning for this prim and its descendant prims. 3099 3100 You should rarely, if ever, need to manipulate this attribute directly. 3101 It is managed by the AddXformOp(), SetResetXformStack(), and 3102 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 3103 GetLocalTransformation().""" 3104 ) 3105} 3106 3107class PointInstancer "PointInstancer" ( 3108 doc = """Encodes vectorized instancing of multiple, potentially 3109 animated, prototypes (object/instance masters), which can be arbitrary 3110 prims/subtrees on a UsdStage. 3111 3112 PointInstancer is a \"multi instancer\", as it allows multiple prototypes 3113 to be scattered among its \"points\". We use a UsdRelationship 3114 prototypes to identify and order all of the possible prototypes, by 3115 targeting the root prim of each prototype. The ordering imparted by 3116 relationships associates a zero-based integer with each prototype, and 3117 it is these integers we use to identify the prototype of each instance, 3118 compactly, and allowing prototypes to be swapped out without needing to 3119 reauthor all of the per-instance data. 3120 3121 The PointInstancer schema is designed to scale to billions of instances, 3122 which motivates the choice to split the per-instance transformation into 3123 position, (quaternion) orientation, and scales, rather than a 3124 4x4 matrix per-instance. In addition to requiring fewer bytes even if 3125 all elements are authored (32 bytes vs 64 for a single-precision 4x4 3126 matrix), we can also be selective about which attributes need to animate 3127 over time, for substantial data reduction in many cases. 3128 3129 Note that PointInstancer is not a Gprim, since it is not a graphical 3130 primitive by any stretch of the imagination. It is, however, 3131 Boundable, since we will sometimes want to treat the entire PointInstancer 3132 similarly to a procedural, from the perspective of inclusion or framing. 3133 3134 Varying Instance Identity over Time 3135 3136 PointInstancers originating from simulations often have the characteristic 3137 that points/instances are \"born\", move around for some time period, and then 3138 die (or leave the area of interest). In such cases, billions of instances 3139 may be birthed over time, while at any specific time, only a much 3140 smaller number are actually alive. To encode this situation efficiently, 3141 the simulator may re-use indices in the instance arrays, when a particle 3142 dies, its index will be taken over by a new particle that may be birthed in 3143 a much different location. This presents challenges both for 3144 identity-tracking, and for motion-blur. 3145 3146 We facilitate identity tracking by providing an optional, animatable 3147 ids attribute, that specifies the 64 bit integer ID of the particle 3148 at each index, at each point in time. If the simulator keeps monotonically 3149 increasing a particle-count each time a new particle is birthed, it will 3150 serve perfectly as particle ids. 3151 3152 We facilitate motion blur for varying-topology particle streams by 3153 optionally allowing per-instance velocities and angularVelocities 3154 to be authored. If instance transforms are requested at a time between 3155 samples and either of the velocity attributes is authored, then we will 3156 not attempt to interpolate samples of positions or orientations. 3157 If not authored, and the bracketing samples have the same length, then we 3158 will interpolate. 3159 3160 Computing an Instance Transform 3161 3162 Each instance's transformation is a combination of the SRT affine transform 3163 described by its scale, orientation, and position, applied after 3164 (i.e. less locally) than the transformation computed at the root of the 3165 prototype it is instancing. In other words, to put an instance of a 3166 PointInstancer into the space of the PointInstancer's parent prim: 3167 3168 1. Apply (most locally) the authored transformation for 3169 <em>prototypes[protoIndices[i]]</em> 3170 2. If *scales* is authored, next apply the scaling matrix from *scales[i]* 3171 3. If *orientations* is authored: **if *angularVelocities* is authored**, 3172 first multiply *orientations[i]* by the unit quaternion derived by scaling 3173 *angularVelocities[i]* by the \"time differential\" 3174 from the left-bracketing timeSample for *orientation* to the requested 3175 evaluation time *t*, storing the result in *R*, **else** assign *R* 3176 directly from *orientations[i]*. Apply the rotation matrix derived 3177 from *R*. 3178 4. Apply the translation derived from *positions[i]*. If *velocities* is 3179 authored, apply the translation deriving from *velocities[i]* scaled by 3180 the time differential from the left-bracketing timeSample for *positions* 3181 to the requested evaluation time *t*. 3182 5. Least locally, apply the transformation authored on the PointInstancer 3183 prim itself (or the UsdGeomImageable::ComputeLocalToWorldTransform() of the 3184 PointInstancer to put the instance directly into world space) 3185 3186 If neither *velocities* nor *angularVelocities* are authored, we fallback to 3187 standard position and orientation computation logic (using linear 3188 interpolation between timeSamples) as described by 3189 . 3190 3191 \\anchor UsdGeom_PITimeScaling 3192 <b>Scaling Velocities for Interpolation</b> 3193 3194 When computing time-differentials by which to apply velocity or 3195 angularVelocity to positions or orientations, we must scale by 3196 ( 1.0 / UsdStage::GetTimeCodesPerSecond() ), because velocities are recorded 3197 in units/second, while we are interpolating in UsdTimeCode ordinates. 3198 3199 Additionally, if *motion:velocityScale* is authored or inherited (see 3200 UsdGeomMotionAPI::ComputeVelocityScale()), it is used to scale both the 3201 velocity and angular velocity by a constant value during computation. The 3202 *motion:velocityScale* attribute is encoded by UsdGeomMotionAPI. 3203 3204 We provide both high and low-level API's for dealing with the 3205 transformation as a matrix, both will compute the instance matrices using 3206 multiple threads; the low-level API allows the client to cache unvarying 3207 inputs so that they need not be read duplicately when computing over 3208 time. 3209 3210 See also . 3211 3212 Primvars on PointInstancer 3213 3214 \"Primvars\" authored on a PointInstancer prim should 3215 always be applied to each instance with constant interpolation at 3216 the root of the instance. When you are authoring primvars on a 3217 PointInstancer, think about it as if you were authoring them on a 3218 point-cloud (e.g. a UsdGeomPoints gprim). The same 3219 <A HREF=\"http://renderman.pixar.com/resources/current/rps/appnote.22.html#classSpecifiers\">interpolation rules for points</A> apply here, substituting 3220 \"instance\" for \"point\". 3221 3222 In other words, the (constant) value extracted for each instance 3223 from the authored primvar value depends on the authored interpolation 3224 and elementSize of the primvar, as follows: 3225 - <b>constant</b> or <b>uniform</b> : the entire authored value of the 3226 primvar should be applied exactly to each instance. 3227 - <b>varying</b>, <b>vertex</b>, or <b>faceVarying</b>: the first 3228 elementSize elements of the authored primvar array should be assigned to 3229 instance zero, the second elementSize elements should be assigned to 3230 instance one, and so forth. 3231 3232 3233 Masking Instances: \"Deactivating\" and Invising 3234 3235 Often a PointInstancer is created \"upstream\" in a graphics pipeline, and 3236 the needs of \"downstream\" clients necessitate eliminating some of the 3237 instances from further consideration. Accomplishing this pruning by 3238 re-authoring all of the per-instance attributes is not very attractive, 3239 since it may mean destructively editing a large quantity of data. We 3240 therefore provide means of \"masking\" instances by ID, such that the 3241 instance data is unmolested, but per-instance transform and primvar data 3242 can be retrieved with the no-longer-desired instances eliminated from the 3243 (smaller) arrays. PointInstancer allows two independent means of masking 3244 instances by ID, each with different features that meet the needs of 3245 various clients in a pipeline. Both pruning features' lists of ID's are 3246 combined to produce the mask returned by ComputeMaskAtTime(). 3247 3248 \\note If a PointInstancer has no authored ids attribute, the masking 3249 features will still be available, with the integers specifying element 3250 position in the protoIndices array rather than ID. 3251 3252 \\subsection UsdGeomPointInstancer_inactiveIds InactiveIds: List-edited, Unvarying Masking 3253 3254 The first masking feature encodes a list of IDs in a list-editable metadatum 3255 called inactiveIds, which, although it does not have any similar 3256 impact to stage population as \"prim activation\", 3257 it shares with that feature that its application is uniform over all time. 3258 Because it is list-editable, we can sparsely add and remove instances 3259 from it in many layers. 3260 3261 This sparse application pattern makes inactiveIds a good choice when 3262 further downstream clients may need to reverse masking decisions made 3263 upstream, in a manner that is robust to many kinds of future changes to 3264 the upstream data. 3265 3266 See ActivateId(), ActivateIds(), DeactivateId(), DeactivateIds(), 3267 ActivateAllIds() 3268 3269 \\subsection UsdGeomPointInstancer_invisibleIds invisibleIds: Animatable Masking 3270 3271 The second masking feature encodes a list of IDs in a time-varying 3272 Int64Array-valued UsdAttribute called invisibleIds , since it shares 3273 with \"Imageable visibility\" 3274 the ability to animate object visibility. 3275 3276 Unlike inactiveIds, overriding a set of opinions for invisibleIds 3277 is not at all straightforward, because one will, in general need to 3278 reauthor (in the overriding layer) **all** timeSamples for the attribute 3279 just to change one Id's visibility state, so it cannot be authored 3280 sparsely. But it can be a very useful tool for situations like encoding 3281 pre-computed camera-frustum culling of geometry when either or both of 3282 the instances or the camera is animated. 3283 3284 See VisId(), VisIds(), InvisId(), InvisIds(), VisAllIds() 3285 3286 Processing and Not Processing Prototypes 3287 3288 Any prim in the scenegraph can be targeted as a prototype by the 3289 prototypes relationship. We do not, however, provide a specific 3290 mechanism for identifying prototypes as geometry that should not be drawn 3291 (or processed) in their own, local spaces in the scenegraph. We 3292 encourage organizing all prototypes as children of the PointInstancer 3293 prim that consumes them, and pruning \"raw\" processing and drawing 3294 traversals when they encounter a PointInstancer prim; this is what the 3295 UsdGeomBBoxCache and UsdImaging engines do. 3296 3297 There is a pattern one can deploy for organizing the prototypes 3298 such that they will automatically be skipped by basic UsdPrim::GetChildren() 3299 or UsdPrimRange traversals. Usd prims each have a 3300 \"specifier\" of \"def\", \"over\", or \"class\". The 3301 default traversals skip over prims that are \"pure overs\" or classes. So 3302 to protect prototypes from all generic traversals and processing, place 3303 them under a prim that is just an \"over\". For example, 3304 \\code 3305 01 def PointInstancer \"Crowd_Mid\" 3306 02 { 3307 03 rel prototypes = [ </Crowd_Mid/Prototypes/MaleThin_Business>, </Crowd_Mid/Prototypes/MaleTine_Casual> ] 3308 04 3309 05 over \"Prototypes\" 3310 06 { 3311 07 def \"MaleThin_Business\" ( 3312 08 references = [@MaleGroupA/usd/MaleGroupA.usd@</MaleGroupA>] 3313 09 variants = { 3314 10 string modelingVariant = \"Thin\" 3315 11 string costumeVariant = \"BusinessAttire\" 3316 12 } 3317 13 ) 3318 14 { ... } 3319 15 3320 16 def \"MaleThin_Casual\" 3321 17 ... 3322 18 } 3323 19 } 3324 \\endcode 3325 """ 3326) 3327{ 3328 vector3f[] accelerations ( 3329 doc = """If authored, per-instance 'accelerations' will be used with 3330 velocities to compute positions between samples for the 'positions' 3331 attribute rather than interpolating between neighboring 'positions' 3332 samples. Acceleration is measured in position units per second-squared. 3333 To convert to position units per squared UsdTimeCode, divide by the 3334 square of UsdStage::GetTimeCodesPerSecond().""" 3335 ) 3336 vector3f[] angularVelocities ( 3337 doc = """If authored, per-instance angular velocity vector to be used for 3338 interoplating orientations. Angular velocities should be considered 3339 mandatory if both protoIndices and orientations are animated. 3340 Angular velocity is measured in <b>degrees</b> per second. To convert 3341 to degrees per UsdTimeCode, divide by 3342 UsdStage::GetTimeCodesPerSecond(). 3343 3344 See also .""" 3345 ) 3346 float3[] extent ( 3347 doc = """Extent is a three dimensional range measuring the geometric 3348 extent of the authored gprim in its own local space (i.e. its own 3349 transform not applied), without accounting for any shader-induced 3350 displacement. Whenever any geometry-affecting attribute is authored 3351 for any gprim in a layer, extent must also be authored at the same 3352 timesample; failure to do so will result in incorrect bounds-computation. 3353 \\sa \\ref UsdGeom_Boundable_Extent. 3354 3355 An authored extent on a prim which has children is expected to include 3356 the extent of all children, as they will be pruned from BBox computation 3357 during traversal.""" 3358 ) 3359 int64[] ids ( 3360 doc = """Ids are optional; if authored, the ids array should be the same 3361 length as the protoIndices array, specifying (at each timeSample if 3362 instance identities are changing) the id of each instance. The 3363 type is signed intentionally, so that clients can encode some 3364 binary state on Id'd instances without adding a separate primvar. 3365 See also \\ref UsdGeomPointInstancer_varyingTopo""" 3366 ) 3367 int64[] invisibleIds = [] ( 3368 doc = """A list of id's to make invisible at the evaluation time. 3369 See .""" 3370 ) 3371 quath[] orientations ( 3372 doc = """If authored, per-instance orientation of each instance about its 3373 prototype's origin, represented as a unit length quaternion, which 3374 allows us to encode it with sufficient precision in a compact GfQuath. 3375 3376 It is client's responsibility to ensure that authored quaternions are 3377 unit length; the convenience API below for authoring orientations from 3378 rotation matrices will ensure that quaternions are unit length, though 3379 it will not make any attempt to select the \"better (for interpolation 3380 with respect to neighboring samples)\" of the two possible quaternions 3381 that encode the rotation. 3382 3383 See also .""" 3384 ) 3385 point3f[] positions ( 3386 doc = """<b>Required property</b>. Per-instance position. See also 3387 .""" 3388 ) 3389 int[] protoIndices ( 3390 doc = """<b>Required property</b>. Per-instance index into 3391 prototypes relationship that identifies what geometry should be 3392 drawn for each instance. <b>Topology attribute</b> - can be animated, 3393 but at a potential performance impact for streaming.""" 3394 ) 3395 rel prototypes ( 3396 doc = """<b>Required property</b>. Orders and targets the prototype root 3397 prims, which can be located anywhere in the scenegraph that is convenient, 3398 although we promote organizing prototypes as children of the 3399 PointInstancer. The position of a prototype in this relationship defines 3400 the value an instance would specify in the protoIndices attribute to 3401 instance that prototype. Since relationships are uniform, this property 3402 cannot be animated.""" 3403 ) 3404 rel proxyPrim ( 3405 doc = '''The proxyPrim relationship allows us to link a 3406 prim whose purpose is "render" to its (single target) 3407 purpose="proxy" prim. This is entirely optional, but can be 3408 useful in several scenarios: 3409 3410 - In a pipeline that does pruning (for complexity management) 3411 by deactivating prims composed from asset references, when we 3412 deactivate a purpose="render" prim, we will be able to discover 3413 and additionally deactivate its associated purpose="proxy" prim, 3414 so that preview renders reflect the pruning accurately. 3415 3416 - DCC importers may be able to make more aggressive optimizations 3417 for interactive processing and display if they can discover the proxy 3418 for a given render prim. 3419 3420 - With a little more work, a Hydra-based application will be able 3421 to map a picked proxy prim back to its render geometry for selection. 3422 3423 \\note It is only valid to author the proxyPrim relationship on 3424 prims whose purpose is "render".''' 3425 ) 3426 uniform token purpose = "default" ( 3427 allowedTokens = ["default", "render", "proxy", "guide"] 3428 doc = """Purpose is a classification of geometry into categories that 3429 can each be independently included or excluded from traversals of prims 3430 on a stage, such as rendering or bounding-box computation traversals. 3431 3432 See for more detail about how 3433 purpose is computed and used.""" 3434 ) 3435 float3[] scales ( 3436 doc = """If authored, per-instance scale to be applied to 3437 each instance, before any rotation is applied. 3438 3439 See also .""" 3440 ) 3441 vector3f[] velocities ( 3442 doc = """If provided, per-instance 'velocities' will be used to 3443 compute positions between samples for the 'positions' attribute, 3444 rather than interpolating between neighboring 'positions' samples. 3445 Velocities should be considered mandatory if both protoIndices 3446 and positions are animated. Velocity is measured in position 3447 units per second, as per most simulation software. To convert to 3448 position units per UsdTimeCode, divide by 3449 UsdStage::GetTimeCodesPerSecond(). 3450 3451 See also 3452 .""" 3453 ) 3454 token visibility = "inherited" ( 3455 allowedTokens = ["inherited", "invisible"] 3456 doc = '''Visibility is meant to be the simplest form of "pruning" 3457 visibility that is supported by most DCC apps. Visibility is 3458 animatable, allowing a sub-tree of geometry to be present for some 3459 segment of a shot, and absent from others; unlike the action of 3460 deactivating geometry prims, invisible geometry is still 3461 available for inspection, for positioning, for defining volumes, etc.''' 3462 ) 3463 uniform token[] xformOpOrder ( 3464 doc = """Encodes the sequence of transformation operations in the 3465 order in which they should be pushed onto a transform stack while 3466 visiting a UsdStage's prims in a graph traversal that will effect 3467 the desired positioning for this prim and its descendant prims. 3468 3469 You should rarely, if ever, need to manipulate this attribute directly. 3470 It is managed by the AddXformOp(), SetResetXformStack(), and 3471 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 3472 GetLocalTransformation().""" 3473 ) 3474} 3475 3476class Camera "Camera" ( 3477 doc = """Transformable camera. 3478 3479 Describes optical properties of a camera via a common set of attributes 3480 that provide control over the camera's frustum as well as its depth of 3481 field. For stereo, the left and right camera are individual prims tagged 3482 through the \"stereoRole attribute\". 3483 3484 There is a corresponding class GfCamera, which can hold the state of a 3485 camera (at a particular time). and 3486 convert between a USD camera prim and 3487 a GfCamera. 3488 3489 To obtain the camera's location in world space, call the following on a 3490 UsdGeomCamera 'camera': 3491 \\code 3492 GfMatrix4d camXform = camera.ComputeLocalToWorldTransform(time); 3493 \\endcode 3494 \\note 3495 <b>Cameras in USD are always \"Y up\", regardless of the stage's orientation 3496 (i.e. UsdGeomGetStageUpAxis()).</b> This means that the inverse of 3497 'camXform' (the VIEW half of the <A HREF=\"http://www.glprogramming.com/red/chapter03.html#name2\">MODELVIEW transform in OpenGL parlance</A>) 3498 will transform the world such that the camera is at the origin, looking 3499 down the -Z axis, with +Y as the up axis, and +X pointing to the right. 3500 This describes a __right handed coordinate system__. 3501 3502 \\sa \\ref UsdGeom_LinAlgBasics 3503 """ 3504) 3505{ 3506 float4[] clippingPlanes = [] ( 3507 doc = """Additional, arbitrarily oriented clipping planes. 3508 A vector (a,b,c,d) encodes a clipping plane that cuts off 3509 (x,y,z) with a * x + b * y + c * z + d * 1 < 0 where (x,y,z) 3510 are the coordinates in the camera's space.""" 3511 ) 3512 float2 clippingRange = (1, 1000000) ( 3513 doc = """Near and far clipping distances in centimeters (or, more 3514 general, world units).""" 3515 ) 3516 float exposure = 0 ( 3517 doc = """Exposure adjustment, as a log base-2 value. The default 3518 of 0.0 has no effect. A value of 1.0 will double the 3519 image-plane intensities in a rendered image; a value of 3520 -1.0 will halve them.""" 3521 ) 3522 float focalLength = 50 ( 3523 doc = """Perspective focal length in millimeters (or, more general, 3524 tenths of a world unit).""" 3525 ) 3526 float focusDistance = 0 ( 3527 doc = """Distance from the camera to the focus plane in centimeters (or 3528 more general, world units).""" 3529 ) 3530 float fStop = 0 ( 3531 doc = "Lens aperture. Defaults to 0.0, which turns off focusing." 3532 ) 3533 float horizontalAperture = 20.955 ( 3534 doc = """Horizontal aperture in millimeters (or, more general, tenths 3535 of a world unit). 3536 Defaults to the standard 35mm spherical projector aperture.""" 3537 ) 3538 float horizontalApertureOffset = 0 ( 3539 doc = """Horizontal aperture offset in the same units as 3540 horizontalAperture. Defaults to 0.""" 3541 ) 3542 token projection = "perspective" ( 3543 allowedTokens = ["perspective", "orthographic"] 3544 ) 3545 rel proxyPrim ( 3546 doc = '''The proxyPrim relationship allows us to link a 3547 prim whose purpose is "render" to its (single target) 3548 purpose="proxy" prim. This is entirely optional, but can be 3549 useful in several scenarios: 3550 3551 - In a pipeline that does pruning (for complexity management) 3552 by deactivating prims composed from asset references, when we 3553 deactivate a purpose="render" prim, we will be able to discover 3554 and additionally deactivate its associated purpose="proxy" prim, 3555 so that preview renders reflect the pruning accurately. 3556 3557 - DCC importers may be able to make more aggressive optimizations 3558 for interactive processing and display if they can discover the proxy 3559 for a given render prim. 3560 3561 - With a little more work, a Hydra-based application will be able 3562 to map a picked proxy prim back to its render geometry for selection. 3563 3564 \\note It is only valid to author the proxyPrim relationship on 3565 prims whose purpose is "render".''' 3566 ) 3567 uniform token purpose = "default" ( 3568 allowedTokens = ["default", "render", "proxy", "guide"] 3569 doc = """Purpose is a classification of geometry into categories that 3570 can each be independently included or excluded from traversals of prims 3571 on a stage, such as rendering or bounding-box computation traversals. 3572 3573 See for more detail about how 3574 purpose is computed and used.""" 3575 ) 3576 double shutter:close = 0 ( 3577 doc = """Frame relative shutter close time, analogous comments from 3578 shutter:open apply. A value greater or equal to shutter:open 3579 should be authored, otherwise there is no exposure and a 3580 renderer should produce a black image.""" 3581 ) 3582 double shutter:open = 0 ( 3583 doc = """Frame relative shutter open time in UsdTimeCode units (negative 3584 value indicates that the shutter opens before the current 3585 frame time). Used for motion blur.""" 3586 ) 3587 uniform token stereoRole = "mono" ( 3588 allowedTokens = ["mono", "left", "right"] 3589 doc = """If different from mono, the camera is intended to be the left 3590 or right camera of a stereo setup.""" 3591 ) 3592 float verticalAperture = 15.2908 ( 3593 doc = """Vertical aperture in millimeters (or, more general, tenths of 3594 a world unit). 3595 Defaults to the standard 35mm spherical projector aperture.""" 3596 ) 3597 float verticalApertureOffset = 0 ( 3598 doc = """Vertical aperture offset in the same units as 3599 verticalAperture. Defaults to 0.""" 3600 ) 3601 token visibility = "inherited" ( 3602 allowedTokens = ["inherited", "invisible"] 3603 doc = '''Visibility is meant to be the simplest form of "pruning" 3604 visibility that is supported by most DCC apps. Visibility is 3605 animatable, allowing a sub-tree of geometry to be present for some 3606 segment of a shot, and absent from others; unlike the action of 3607 deactivating geometry prims, invisible geometry is still 3608 available for inspection, for positioning, for defining volumes, etc.''' 3609 ) 3610 uniform token[] xformOpOrder ( 3611 doc = """Encodes the sequence of transformation operations in the 3612 order in which they should be pushed onto a transform stack while 3613 visiting a UsdStage's prims in a graph traversal that will effect 3614 the desired positioning for this prim and its descendant prims. 3615 3616 You should rarely, if ever, need to manipulate this attribute directly. 3617 It is managed by the AddXformOp(), SetResetXformStack(), and 3618 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 3619 GetLocalTransformation().""" 3620 ) 3621} 3622 3623class "GeomModelAPI" ( 3624 doc = """UsdGeomModelAPI extends the generic UsdModelAPI schema with 3625 geometry specific concepts such as cached extents for the entire model, 3626 constraint targets, and geometry-inspired extensions to the payload 3627 lofting process. 3628 3629 As described in GetExtentsHint() below, it is useful to cache extents 3630 at the model level. UsdGeomModelAPI provides schema for computing and 3631 storing these cached extents, which can be consumed by UsdGeomBBoxCache to 3632 provide fast access to precomputed extents that will be used as the model's 3633 bounds ( see UsdGeomBBoxCache::UsdGeomBBoxCache() ). 3634 3635 Draw Modes 3636 3637 Draw modes provide optional alternate imaging behavior for USD subtrees with 3638 kind model. model:drawMode (which is inheritable) and 3639 model:applyDrawMode (which is not) are resolved into a decision to stop 3640 traversing the scene graph at a certain point, and replace a USD subtree 3641 with proxy geometry. 3642 3643 The value of model:drawMode determines the type of proxy geometry: 3644 - origin - Draw the model-space basis vectors of the replaced prim. 3645 - bounds - Draw the model-space bounding box of the replaced prim. 3646 - cards - Draw textured quads as a placeholder for the replaced prim. 3647 - default - An explicit opinion to draw the USD subtree as normal. 3648 - inherited - Defer to the parent opinion. 3649 3650 model:drawMode falls back to _inherited_ so that a whole scene, 3651 a large group, or all prototypes of a model hierarchy PointInstancer can 3652 be assigned a draw mode with a single attribute edit. If no draw mode is 3653 explicitly set in a hierarchy, the resolved value is _default_. 3654 3655 model:applyDrawMode is meant to be written when an asset is authored, 3656 and provides flexibility for different asset types. For example, 3657 a character assembly (composed of character, clothes, etc) might have 3658 model:applyDrawMode set at the top of the subtree so the whole group 3659 can be drawn as a single card object. An effects subtree might have 3660 model:applyDrawMode set at a lower level so each particle 3661 group draws individually. 3662 3663 Models of kind component are treated as if model:applyDrawMode 3664 were true. This means a prim is drawn with proxy geometry when: the 3665 prim has kind component, and/or model:applyDrawMode is set; and 3666 the prim's resolved value for model:drawMode is not _default_. 3667 3668 Cards Geometry 3669 3670 The specific geometry used in cards mode is controlled by the 3671 model:cardGeometry attribute: 3672 - cross - Generate a quad normal to each basis direction and negative. 3673 Locate each quad so that it bisects the model extents. 3674 - box - Generate a quad normal to each basis direction and negative. 3675 Locate each quad on a face of the model extents, facing out. 3676 - fromTexture - Generate a quad for each supplied texture from 3677 attributes stored in that texture's metadata. 3678 3679 For cross and box mode, the extents are calculated for purposes 3680 default, proxy, and render, at their earliest authored time. 3681 If the model has no textures, all six card faces are rendered using 3682 model:drawModeColor. If one or more textures are present, only axes 3683 with one or more textures assigned are drawn. For each axis, if both 3684 textures (positive and negative) are specified, they'll be used on the 3685 corresponding card faces; if only one texture is specified, it will be 3686 mapped to the opposite card face after being flipped on the texture's 3687 s-axis. Any card faces with invalid asset paths will be drawn with 3688 model:drawModeColor. 3689 3690 Both model:cardGeometry and model:drawModeColor should be 3691 authored on the prim where the draw mode takes effect, since these 3692 attributes are not inherited. 3693 3694 For fromTexture mode, only card faces with valid textures assigned 3695 are drawn. The geometry is generated by pulling the worldtoscreen 3696 attribute out of texture metadata. This is expected to be a 4x4 matrix 3697 mapping the model-space position of the card quad to the clip-space quad 3698 with corners (-1,-1,0) and (1,1,0). The card vertices are generated by 3699 transforming the clip-space corners by the inverse of worldtoscreen. 3700 Textures are mapped so that (s) and (t) map to (+x) and (+y) in clip space. 3701 If the metadata cannot be read in the right format, or the matrix can't 3702 be inverted, the card face is not drawn. 3703 3704 All card faces are drawn and textured as single-sided. 3705 3706 \\todo CreatePayload() """ 3707) 3708{ 3709 uniform bool model:applyDrawMode = 0 ( 3710 doc = """If true, and the resolved value of model:drawMode is 3711 non-default, apply an alternate imaging mode to this prim. See 3712 \\ref UsdGeomModelAPI_drawMode.""" 3713 ) 3714 uniform token model:cardGeometry = "cross" ( 3715 allowedTokens = ["cross", "box", "fromTexture"] 3716 doc = """The geometry to generate for imaging prims inserted for \\em 3717 cards imaging mode. See for 3718 geometry descriptions.""" 3719 ) 3720 asset model:cardTextureXNeg ( 3721 doc = """In cards imaging mode, the texture applied to the X- quad. 3722 The texture axes (s,t) are mapped to model-space axes (y, -z).""" 3723 ) 3724 asset model:cardTextureXPos ( 3725 doc = """In cards imaging mode, the texture applied to the X+ quad. 3726 The texture axes (s,t) are mapped to model-space axes (-y, -z).""" 3727 ) 3728 asset model:cardTextureYNeg ( 3729 doc = """In cards imaging mode, the texture applied to the Y- quad. 3730 The texture axes (s,t) are mapped to model-space axes (-x, -z).""" 3731 ) 3732 asset model:cardTextureYPos ( 3733 doc = """In cards imaging mode, the texture applied to the Y+ quad. 3734 The texture axes (s,t) are mapped to model-space axes (x, -z).""" 3735 ) 3736 asset model:cardTextureZNeg ( 3737 doc = """In cards imaging mode, the texture applied to the Z- quad. 3738 The texture axes (s,t) are mapped to model-space axes (-x, -y).""" 3739 ) 3740 asset model:cardTextureZPos ( 3741 doc = """In cards imaging mode, the texture applied to the Z+ quad. 3742 The texture axes (s,t) are mapped to model-space axes (x, -y).""" 3743 ) 3744 uniform token model:drawMode = "inherited" ( 3745 allowedTokens = ["origin", "bounds", "cards", "default", "inherited"] 3746 doc = """Alternate imaging mode; applied to this prim or child prims 3747 where model:applyDrawMode is true, or where the prim 3748 has kind component. See \\ref UsdGeomModelAPI_drawMode 3749 for mode descriptions.""" 3750 ) 3751 uniform float3 model:drawModeColor = (0.18, 0.18, 0.18) ( 3752 doc = """The base color of imaging prims inserted for alternate 3753 imaging modes. For origin and bounds modes, this 3754 controls line color; for cards mode, this controls the 3755 fallback quad color.""" 3756 ) 3757} 3758 3759class "MotionAPI" ( 3760 doc = """UsdGeomMotionAPI encodes data that can live on any prim that 3761 may affect computations involving: 3762 - computed motion for motion blur 3763 - sampling for motion blur 3764 3765 For example, UsdGeomMotionAPI provides *velocityScale* 3766 (GetVelocityScaleAttr()) for controlling how motion-blur samples should 3767 be computed by velocity-consuming schemas.""" 3768) 3769{ 3770 float motion:velocityScale = 1 ( 3771 doc = """VelocityScale is an **inherited** float attribute that 3772 velocity-based schemas (e.g. PointBased, PointInstancer) can consume 3773 to compute interpolated positions and orientations by applying 3774 velocity and angularVelocity, which is required for interpolating 3775 between samples when topology is varying over time. Although these 3776 quantities are generally physically computed by a simulator, sometimes 3777 we require more or less motion-blur to achieve the desired look. 3778 VelocityScale allows artists to dial-in, as a post-sim correction, 3779 a scale factor to be applied to the velocity prior to computing 3780 interpolated positions from it. 3781 3782 See also ComputeVelocityScale()""" 3783 ) 3784} 3785 3786class "XformCommonAPI" ( 3787 doc = """This class provides API for authoring and retrieving a standard set 3788 of component transformations which include a scale, a rotation, a 3789 scale-rotate pivot and a translation. The goal of the API is to enhance 3790 component-wise interchange. It achieves this by limiting the set of allowed 3791 basic ops and by specifying the order in which they are applied. In addition 3792 to the basic set of ops, the 'resetXformStack' bit can also be set to 3793 indicate whether the underlying xformable resets the parent transformation 3794 (i.e. does not inherit it's parent's transformation). 3795 3796 \\sa UsdGeomXformCommonAPI::GetResetXformStack() 3797 \\sa UsdGeomXformCommonAPI::SetResetXformStack() 3798 3799 The operator-bool for the class will inform you whether an existing 3800 xformable is compatible with this API. 3801 3802 The scale-rotate pivot is represented by a pair of (translate, 3803 inverse-translate) xformOps around the scale and rotate operations. 3804 The rotation operation can be any of the six allowed Euler angle sets. 3805 \\sa UsdGeomXformOp::Type. 3806 3807 The xformOpOrder of an xformable that has all of the supported basic ops 3808 is as follows: 3809 [\"xformOp:translate\", \"xformOp:translate:pivot\", \"xformOp:rotateXYZ\", 3810 \"xformOp:scale\", \"!invert!xformOp:translate:pivot\"]. 3811 3812 It is worth noting that all of the ops are optional. For example, an 3813 xformable may have only a translate or a rotate. It would still be 3814 considered as compatible with this API. Individual SetTranslate(), 3815 SetRotate(), SetScale() and SetPivot() methods are provided by this API 3816 to allow such sparse authoring.""" 3817) 3818{ 3819} 3820 3821class HermiteCurves "HermiteCurves" ( 3822 doc = """This schema specifies a cubic hermite interpolated curve batch as 3823 sometimes used for defining guides for animation. While hermite curves can 3824 be useful because they interpolate through their control points, they are 3825 not well supported by high-end renderers for imaging. Therefore, while we 3826 include this schema for interchange, we strongly recommend the use of 3827 UsdGeomBasisCurves as the representation of curves intended to be rendered 3828 (ie. hair or grass). Hermite curves can be converted to a Bezier 3829 representation (though not from Bezier back to Hermite in general). 3830 3831 Point Interpolation 3832 3833 The initial cubic curve segment is defined by the first two points and 3834 first two tangents. Additional segments are defined by additional 3835 point / tangent pairs. The number of segments for each non-batched hermite 3836 curve would be len(curve.points) - 1. The total number of segments 3837 for the batched UsdGeomHermiteCurves representation is 3838 len(points) - len(curveVertexCounts). 3839 3840 Primvar, Width, and Normal Interpolation 3841 3842 Primvar interpolation is not well specified for this type as it is not 3843 intended as a rendering representation. We suggest that per point 3844 primvars would be linearly interpolated across each segment and should 3845 be tagged as 'varying'. 3846 3847 It is not immediately clear how to specify cubic or 'vertex' interpolation 3848 for this type, as we lack a specification for primvar tangents. This 3849 also means that width and normal interpolation should be restricted to 3850 varying (linear), uniform (per curve element), or constant (per prim). 3851 """ 3852) 3853{ 3854 vector3f[] accelerations ( 3855 doc = """If provided, 'accelerations' should be used with 3856 velocities to compute positions between samples for the 'points' 3857 attribute rather than interpolating between neighboring 'points' 3858 samples. Acceleration is measured in position units per second-squared. 3859 To convert to position units per squared UsdTimeCode, divide by the 3860 square of UsdStage::GetTimeCodesPerSecond().""" 3861 ) 3862 int[] curveVertexCounts ( 3863 doc = """Curves-derived primitives can represent multiple distinct, 3864 potentially disconnected curves. The length of 'curveVertexCounts' 3865 gives the number of such curves, and each element describes the 3866 number of vertices in the corresponding curve""" 3867 ) 3868 uniform bool doubleSided = 0 ( 3869 doc = """Although some renderers treat all parametric or polygonal 3870 surfaces as if they were effectively laminae with outward-facing 3871 normals on both sides, some renderers derive significant optimizations 3872 by considering these surfaces to have only a single outward side, 3873 typically determined by control-point winding order and/or 3874 orientation. By doing so they can perform \"backface culling\" to 3875 avoid drawing the many polygons of most closed surfaces that face away 3876 from the viewer. 3877 3878 However, it is often advantageous to model thin objects such as paper 3879 and cloth as single, open surfaces that must be viewable from both 3880 sides, always. Setting a gprim's doubleSided attribute to 3881 \\c true instructs all renderers to disable optimizations such as 3882 backface culling for the gprim, and attempt (not all renderers are able 3883 to do so, but the USD reference GL renderer always will) to provide 3884 forward-facing normals on each side of the surface for lighting 3885 calculations.""" 3886 ) 3887 float3[] extent ( 3888 doc = """Extent is a three dimensional range measuring the geometric 3889 extent of the authored gprim in its own local space (i.e. its own 3890 transform not applied), without accounting for any shader-induced 3891 displacement. Whenever any geometry-affecting attribute is authored 3892 for any gprim in a layer, extent must also be authored at the same 3893 timesample; failure to do so will result in incorrect bounds-computation. 3894 \\sa \\ref UsdGeom_Boundable_Extent. 3895 3896 An authored extent on a prim which has children is expected to include 3897 the extent of all children, as they will be pruned from BBox computation 3898 during traversal.""" 3899 ) 3900 normal3f[] normals ( 3901 doc = """Provide an object-space orientation for individual points, 3902 which, depending on subclass, may define a surface, curve, or free 3903 points. Note that 'normals' should not be authored on any Mesh that 3904 is subdivided, since the subdivision algorithm will define its own 3905 normals. 'normals' is not a generic primvar, but the number of elements 3906 in this attribute will be determined by its 'interpolation'. See 3907 . If 'normals' and 'primvars:normals' 3908 are both specified, the latter has precedence.""" 3909 ) 3910 uniform token orientation = "rightHanded" ( 3911 allowedTokens = ["rightHanded", "leftHanded"] 3912 doc = """Orientation specifies whether the gprim's surface normal 3913 should be computed using the right hand rule, or the left hand rule. 3914 Please see for a deeper explanation and 3915 generalization of orientation to composed scenes with transformation 3916 hierarchies.""" 3917 ) 3918 point3f[] points ( 3919 doc = """The primary geometry attribute for all PointBased 3920 primitives, describes points in (local) space.""" 3921 ) 3922 color3f[] primvars:displayColor ( 3923 doc = '''It is useful to have an "official" colorSet that can be used 3924 as a display or modeling color, even in the absence of any specified 3925 shader for a gprim. DisplayColor serves this role; because it is a 3926 UsdGeomPrimvar, it can also be used as a gprim override for any shader 3927 that consumes a displayColor parameter.''' 3928 ) 3929 float[] primvars:displayOpacity ( 3930 doc = """Companion to displayColor that specifies opacity, broken 3931 out as an independent attribute rather than an rgba color, both so that 3932 each can be independently overridden, and because shaders rarely consume 3933 rgba parameters.""" 3934 ) 3935 rel proxyPrim ( 3936 doc = '''The proxyPrim relationship allows us to link a 3937 prim whose purpose is "render" to its (single target) 3938 purpose="proxy" prim. This is entirely optional, but can be 3939 useful in several scenarios: 3940 3941 - In a pipeline that does pruning (for complexity management) 3942 by deactivating prims composed from asset references, when we 3943 deactivate a purpose="render" prim, we will be able to discover 3944 and additionally deactivate its associated purpose="proxy" prim, 3945 so that preview renders reflect the pruning accurately. 3946 3947 - DCC importers may be able to make more aggressive optimizations 3948 for interactive processing and display if they can discover the proxy 3949 for a given render prim. 3950 3951 - With a little more work, a Hydra-based application will be able 3952 to map a picked proxy prim back to its render geometry for selection. 3953 3954 \\note It is only valid to author the proxyPrim relationship on 3955 prims whose purpose is "render".''' 3956 ) 3957 uniform token purpose = "default" ( 3958 allowedTokens = ["default", "render", "proxy", "guide"] 3959 doc = """Purpose is a classification of geometry into categories that 3960 can each be independently included or excluded from traversals of prims 3961 on a stage, such as rendering or bounding-box computation traversals. 3962 3963 See for more detail about how 3964 purpose is computed and used.""" 3965 ) 3966 vector3f[] tangents = [] ( 3967 doc = """Defines the outgoing trajectory tangent for each point. 3968 Tangents should be the same size as the points attribute.""" 3969 ) 3970 vector3f[] velocities ( 3971 doc = """If provided, 'velocities' should be used by renderers to 3972 3973 compute positions between samples for the 'points' attribute, rather 3974 than interpolating between neighboring 'points' samples. This is the 3975 only reasonable means of computing motion blur for topologically 3976 varying PointBased primitives. It follows that the length of each 3977 'velocities' sample must match the length of the corresponding 3978 'points' sample. Velocity is measured in position units per second, 3979 as per most simulation software. To convert to position units per 3980 UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond(). 3981 3982 See also .""" 3983 ) 3984 token visibility = "inherited" ( 3985 allowedTokens = ["inherited", "invisible"] 3986 doc = '''Visibility is meant to be the simplest form of "pruning" 3987 visibility that is supported by most DCC apps. Visibility is 3988 animatable, allowing a sub-tree of geometry to be present for some 3989 segment of a shot, and absent from others; unlike the action of 3990 deactivating geometry prims, invisible geometry is still 3991 available for inspection, for positioning, for defining volumes, etc.''' 3992 ) 3993 float[] widths ( 3994 doc = """Provides width specification for the curves, whose application 3995 will depend on whether the curve is oriented (normals are defined for 3996 it), in which case widths are \"ribbon width\", or unoriented, in which 3997 case widths are cylinder width. 'widths' is not a generic Primvar, 3998 but the number of elements in this attribute will be determined by 3999 its 'interpolation'. See . If 'widths' 4000 and 'primvars:widths' are both specified, the latter has precedence.""" 4001 ) 4002 uniform token[] xformOpOrder ( 4003 doc = """Encodes the sequence of transformation operations in the 4004 order in which they should be pushed onto a transform stack while 4005 visiting a UsdStage's prims in a graph traversal that will effect 4006 the desired positioning for this prim and its descendant prims. 4007 4008 You should rarely, if ever, need to manipulate this attribute directly. 4009 It is managed by the AddXformOp(), SetResetXformStack(), and 4010 SetXformOpOrder(), and consulted by GetOrderedXformOps() and 4011 GetLocalTransformation().""" 4012 ) 4013} 4014 4015