UsdGeom module
Summary: The UsdGeom module defines 3D graphics-related prim and property schemas that form a basis for geometry interchange.
Classes:
Caches bounds by recursively computing and aggregating bounds of children in world space and aggregating the result back into local space. |
|
BasisCurves are a batched curve representation analogous to the classic RIB definition via Basis and Curves statements. |
|
Boundable introduces the ability for a prim to persistently cache a rectilinear, local-space, extent. |
|
Transformable camera. |
|
Defines a primitive capsule, i.e. a cylinder capped by two half spheres, centered at the origin, whose spine is along the specified axis. |
|
Defines a primitive cone, centered at the origin, whose spine is along the specified axis, with the apex of the cone pointing in the direction of the positive axis. |
|
Schema wrapper for UsdAttribute for authoring and introspecting attributes that are constraint targets. |
|
Defines a primitive rectilinear cube centered at the origin. |
|
Base class for UsdGeomBasisCurves, UsdGeomNurbsCurves, and UsdGeomHermiteCurves. |
|
Defines a primitive cylinder with closed ends, centered at the origin, whose spine is along the specified axis. |
|
Base class for all geometric primitives. |
|
This schema specifies a cubic hermite interpolated curve batch as sometimes used for defining guides for animation. |
|
Base class for all prims that may require rendering or visualization of some sort. |
|
Encodes a mesh with optional subdivision properties and features. |
|
UsdGeomModelAPI extends the generic UsdModelAPI schema with geometry specific concepts such as cached extents for the entire model, constraint targets, and geometry-inspired extensions to the payload lofting process. |
|
UsdGeomMotionAPI encodes data that can live on any prim that may affect computations involving: |
|
This schema is analagous to NURBS Curves in packages like Maya and Houdini, often used for interchange of rigging and modeling curves. |
|
Encodes a rational or polynomial non-uniform B-spline surface, with optional trim curves. |
|
Defines a primitive plane, centered at the origin, and is defined by a cardinal axis, width, and length. |
|
Base class for all UsdGeomGprims that possess points, providing common attributes such as normals and velocities. |
|
Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters), which can be arbitrary prims/subtrees on a UsdStage. |
|
Points are analogous to the RiPoints spec. |
|
Schema wrapper for UsdAttribute for authoring and introspecting attributes that are primvars. |
|
UsdGeomPrimvarsAPI encodes geometric"primitive variables", as UsdGeomPrimvar, which interpolate across a primitive's topology, can override shader inputs, and inherit down namespace. |
|
Scope is the simplest grouping primitive, and does not carry the baggage of transformability. |
|
Defines a primitive sphere centered at the origin. |
|
Encodes a subset of a piece of geometry (i.e. |
|
UsdGeomVisibilityAPI introduces properties that can be used to author visibility opinions. |
|
Concrete prim schema for a transform, which implements Xformable |
|
A caching mechanism for transform matrices. |
|
This class provides API for authoring and retrieving a standard set of component transformations which include a scale, a rotation, a scale- rotate pivot and a translation. |
|
Schema wrapper for UsdAttribute for authoring and computing transformation operations, as consumed by UsdGeomXformable schema. |
|
Base class for all transformable prims, which allows arbitrary sequences of component affine transformations to be encoded. |
- class pxr.UsdGeom.BBoxCache
Caches bounds by recursively computing and aggregating bounds of children in world space and aggregating the result back into local space.
The cache is configured for a specific time and UsdGeomImageable::GetPurposeAttr() set of purposes. When querying a bound, transforms and extents are read either from the time specified or UsdTimeCode::Default() , following TimeSamples, Defaults, and Value Resolution standard time-sample value resolution. As noted in SetIncludedPurposes() , changing the included purposes does not invalidate the cache, because we cache purpose along with the geometric data.
Child prims that are invisible at the requested time are excluded when computing a prim’s bounds. However, if a bound is requested directly for an excluded prim, it will be computed. Additionally, only prims deriving from UsdGeomImageable are included in child bounds computations.
Unlike standard UsdStage traversals, the traversal performed by the UsdGeomBBoxCache includesprims that are unloaded (see UsdPrim::IsLoaded() ). This makes it possible to fetch bounds for a UsdStage that has been opened without forcePopulate, provided the unloaded model prims have authored extent hints (see UsdGeomModelAPI::GetExtentsHint() ).
This class is optimized for computing tight untransformed”object”space bounds for component-models. In the absence of component models, bounds are optimized for world-space, since there is no other easily identifiable space for which to optimize, and we cannot optimize for every prim’s local space without performing quadratic work.
The TfDebug flag, USDGEOM_BBOX, is provided for debugging.
Warning
This class should only be used with valid UsdPrim objects.
This cache does not listen for change notifications; the user is responsible for clearing the cache when changes occur.
Thread safety: instances of this class may not be used concurrently.
Plugins may be loaded in order to compute extents for prim types provided by that plugin. See UsdGeomBoundable::ComputeExtentFromPlugins
Methods:
Clear
()Clears all pre-cached values.
Clear this cache's baseTime if one has been set.
ComputeLocalBound
(prim)Computes the oriented bounding box of the given prim, leveraging any pre-existing, cached bounds.
ComputePointInstanceLocalBound
(instancer, ...)Compute the oriented bounding boxes of the given point instances.
ComputePointInstanceLocalBounds
(instancer, ...)Compute the oriented bounding boxes of the given point instances.
ComputePointInstanceRelativeBound
(instancer, ...)Compute the bound of the given point instance in the space of an ancestor prim
relativeToAncestorPrim
.Compute the bounds of the given point instances in the space of an ancestor prim
relativeToAncestorPrim
.Computes the bound of the given point instances, but does not include the instancer's transform.
Computes the bound of the given point instances, but does not include the transform (if any) authored on the instancer itself.
ComputePointInstanceWorldBound
(instancer, ...)Compute the bound of the given point instance in world space.
ComputePointInstanceWorldBounds
(instancer, ...)Compute the bound of the given point instances in world space.
ComputeRelativeBound
(prim, ...)Compute the bound of the given prim in the space of an ancestor prim,
relativeToAncestorPrim
, leveraging any pre-existing cached bounds.Computes the bound of the prim's children leveraging any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.
ComputeWorldBound
(prim)Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds.
ComputeWorldBoundWithOverrides
(prim, ...)Computes the bound of the prim's descendents in world space while excluding the subtrees rooted at the paths in
pathsToSkip
.Return the base time if set, otherwise GetTime() .
Get the current set of included purposes.
GetTime
()Get the current time from which this cache is reading values.
Returns whether authored extent hints are used to compute bounding boxes.
Return true if this cache has a baseTime that's been explicitly set, false otherwise.
SetBaseTime
(baseTime)Set the base time value for this bbox cache.
SetIncludedPurposes
(includedPurposes)Indicate the set of
includedPurposes
to use when resolving child bounds.SetTime
(time)Use the new
time
when computing values and may clear any existing values cached for the previous time.- ClearBaseTime() None
Clear this cache’s baseTime if one has been set.
After calling this, the cache will use its time as the baseTime value.
- ComputeLocalBound(prim) BBox3d
Computes the oriented bounding box of the given prim, leveraging any pre-existing, cached bounds.
The computed bound includes the transform authored on the prim itself, but does not include any ancestor transforms (it does not include the local-to-world transform).
See ComputeWorldBound() for notes on performance and error handling.
- Parameters
prim (Prim) –
- ComputePointInstanceLocalBound(instancer, instanceId) BBox3d
Compute the oriented bounding boxes of the given point instances.
- Parameters
instancer (PointInstancer) –
instanceId (int) –
- ComputePointInstanceLocalBounds(instancer, instanceIdBegin, numIds, result) bool
Compute the oriented bounding boxes of the given point instances.
The computed bounds include the transform authored on the instancer itself, but does not include any ancestor transforms (it does not include the local-to-world transform).
The
result
pointer must point tonumIds
GfBBox3d instances to be filled.- Parameters
instancer (PointInstancer) –
instanceIdBegin (int) –
numIds (int) –
result (BBox3d) –
- ComputePointInstanceRelativeBound(instancer, instanceId, relativeToAncestorPrim) BBox3d
Compute the bound of the given point instance in the space of an ancestor prim
relativeToAncestorPrim
.- Parameters
instancer (PointInstancer) –
instanceId (int) –
relativeToAncestorPrim (Prim) –
- ComputePointInstanceRelativeBounds(instancer, instanceIdBegin, numIds, relativeToAncestorPrim, result) bool
Compute the bounds of the given point instances in the space of an ancestor prim
relativeToAncestorPrim
.Write the results to
result
.The computed bound excludes the local transform at
relativeToAncestorPrim
. The computed bound may be incorrect ifrelativeToAncestorPrim
is not an ancestor ofprim
.The
result
pointer must point tonumIds
GfBBox3d instances to be filled.- Parameters
instancer (PointInstancer) –
instanceIdBegin (int) –
numIds (int) –
relativeToAncestorPrim (Prim) –
result (BBox3d) –
- ComputePointInstanceUntransformedBound(instancer, instanceId) BBox3d
Computes the bound of the given point instances, but does not include the instancer’s transform.
- Parameters
instancer (PointInstancer) –
instanceId (int) –
- ComputePointInstanceUntransformedBounds(instancer, instanceIdBegin, numIds, result) bool
Computes the bound of the given point instances, but does not include the transform (if any) authored on the instancer itself.
IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().
The
result
pointer must point tonumIds
GfBBox3d instances to be filled.- Parameters
instancer (PointInstancer) –
instanceIdBegin (int) –
numIds (int) –
result (BBox3d) –
- ComputePointInstanceWorldBound(instancer, instanceId) BBox3d
Compute the bound of the given point instance in world space.
- Parameters
instancer (PointInstancer) –
instanceId (int) –
- ComputePointInstanceWorldBounds(instancer, instanceIdBegin, numIds, result) bool
Compute the bound of the given point instances in world space.
The bounds of each instance is computed and then transformed to world space. The
result
pointer must point tonumIds
GfBBox3d instances to be filled.- Parameters
instancer (PointInstancer) –
instanceIdBegin (int) –
numIds (int) –
result (BBox3d) –
- ComputeRelativeBound(prim, relativeToAncestorPrim) BBox3d
Compute the bound of the given prim in the space of an ancestor prim,
relativeToAncestorPrim
, leveraging any pre-existing cached bounds.The computed bound excludes the local transform at
relativeToAncestorPrim
. The computed bound may be incorrect ifrelativeToAncestorPrim
is not an ancestor ofprim
.
- ComputeUntransformedBound(prim) BBox3d
Computes the bound of the prim’s children leveraging any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.
IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().
See ComputeWorldBound() for notes on performance and error handling.
- Parameters
prim (Prim) –
ComputeUntransformedBound(prim, pathsToSkip, ctmOverrides) -> BBox3d
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the bound of the prim’s descendents while excluding the subtrees rooted at the paths in
pathsToSkip
.Additionally, the parameter
ctmOverrides
is used to specify overrides to the CTM values of certain paths underneath the prim. The CTM values in thectmOverrides
map are in the space of the given prim,prim
.This leverages any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.
IMPORTANT: while the BBox does not contain the local transformation, in general it may still contain a non-identity transformation matrix to put the bounds in the correct space. Therefore, to obtain the correct axis-aligned bounding box, the client must call ComputeAlignedRange().
See ComputeWorldBound() for notes on performance and error handling.
- ComputeWorldBound(prim) BBox3d
Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds.
The bound of the prim is computed, including the transform (if any) authored on the node itself, and then transformed to world space.
Error handling note: No checking of
prim
validity is performed. Ifprim
is invalid, this method will abort the program; therefore it is the client’s responsibility to ensureprim
is valid.- Parameters
prim (Prim) –
- ComputeWorldBoundWithOverrides(prim, pathsToSkip, primOverride, ctmOverrides) BBox3d
Computes the bound of the prim’s descendents in world space while excluding the subtrees rooted at the paths in
pathsToSkip
.Additionally, the parameter
primOverride
overrides the local-to- world transform of the prim andctmOverrides
is used to specify overrides the local-to-world transforms of certain paths underneath the prim.This leverages any pre-existing, cached bounds, but does not include the transform (if any) authored on the prim itself.
See ComputeWorldBound() for notes on performance and error handling.
- GetBaseTime() TimeCode
Return the base time if set, otherwise GetTime() .
Use HasBaseTime() to observe if a base time has been set.
- GetIncludedPurposes() list[str]
Get the current set of included purposes.
- GetUseExtentsHint() bool
Returns whether authored extent hints are used to compute bounding boxes.
- HasBaseTime() bool
Return true if this cache has a baseTime that’s been explicitly set, false otherwise.
- SetBaseTime(baseTime) None
Set the base time value for this bbox cache.
This value is used only when computing bboxes for point instancer instances (see ComputePointInstanceWorldBounds() , for example). See UsdGeomPointInstancer::ComputeExtentAtTime() for more information. If unset, the bbox cache uses its time ( GetTime() / SetTime() ) for this value.
Note that setting the base time does not invalidate any cache entries.
- Parameters
baseTime (TimeCode) –
- SetIncludedPurposes(includedPurposes) None
Indicate the set of
includedPurposes
to use when resolving child bounds.Each child’s purpose must match one of the elements of this set to be included in the computation; if it does not, child is excluded.
Note the use of child in the docs above, purpose is ignored for the prim for whose bounds are directly queried.
Changing this value does not invalidate existing caches.
- Parameters
includedPurposes (list[str]) –
- class pxr.UsdGeom.BasisCurves
BasisCurves are a batched curve representation analogous to the classic RIB definition via Basis and Curves statements. BasisCurves are often used to render dense aggregate geometry like hair or grass.
A’matrix’and’vstep’associated with the basis are used to interpolate the vertices of a cubic BasisCurves. (The basis attribute is unused for linear BasisCurves.)
A single prim may have many curves whose count is determined implicitly by the length of the curveVertexCounts vector. Each individual curve is composed of one or more segments. Each segment is defined by four vertices for cubic curves and two vertices for linear curves. See the next section for more information on how to map curve vertex counts to segment counts.
Segment Indexing
Interpolating a curve requires knowing how to decompose it into its individual segments.
The segments of a cubic curve are determined by the vertex count, the wrap (periodicity), and the vstep of the basis. For linear curves, the basis token is ignored and only the vertex count and wrap are needed.
cubic basis
vstep
bezier
3
catmullRom
1
bspline
1
The first segment of a cubic (nonperiodic) curve is always defined by its first four points. The vstep is the increment used to determine what vertex indices define the next segment. For a two segment (nonperiodic) bspline basis curve (vstep = 1), the first segment will be defined by interpolating vertices [0, 1, 2, 3] and the second segment will be defined by [1, 2, 3, 4]. For a two segment bezier basis curve (vstep = 3), the first segment will be defined by interpolating vertices [0, 1, 2, 3] and the second segment will be defined by [3, 4, 5, 6]. If the vstep is not one, then you must take special care to make sure that the number of cvs properly divides by your vstep. (The indices described are relative to the initial vertex index for a batched curve.)
For periodic curves, at least one of the curve’s initial vertices are repeated to close the curve. For cubic curves, the number of vertices repeated is’4 - vstep’. For linear curves, only one vertex is repeated to close the loop.
Pinned curves are a special case of nonperiodic curves that only affects the behavior of cubic Bspline and Catmull-Rom curves. To evaluate or render pinned curves, a client must effectively add’phantom points’at the beginning and end of every curve in a batch. These phantom points are injected to ensure that the interpolated curve begins at P[0] and ends at P[n-1].
For a curve with initial point P[0] and last point P[n-1], the phantom points are defined as. P[-1] = 2 * P[0] - P[1] P[n] = 2 * P[n-1] - P[n-2]
Pinned cubic curves will (usually) have to be unpacked into the standard nonperiodic representation before rendering. This unpacking can add some additional overhead. However, using pinned curves reduces the amount of data recorded in a scene and (more importantly) better records the authors’intent for interchange.
The additional phantom points mean that the minimum curve vertex count for cubic bspline and catmullRom curves is 2. Linear curve segments are defined by two vertices. A two segment linear curve’s first segment would be defined by interpolating vertices [0, 1]. The second segment would be defined by vertices [1, 2]. (Again, for a batched curve, indices are relative to the initial vertex index.)
When validating curve topology, each renderable entry in the curveVertexCounts vector must pass this check.
type
wrap
validitity
linear
nonperiodic
curveVertexCounts[i]>2
linear
periodic
curveVertexCounts[i]>3
cubic
nonperiodic
(curveVertexCounts[i] - 4) % vstep == 0
cubic
periodic
(curveVertexCounts[i]) % vstep == 0
cubic
pinned (catmullRom/bspline)
(curveVertexCounts[i] - 2)>= 0
Cubic Vertex Interpolation
Linear Vertex Interpolation
Linear interpolation is always used on curves of type linear.’t’with domain [0, 1], the curve is defined by the equation P0 * (1-t) + P1 * t. t at 0 describes the first point and t at 1 describes the end point.
Primvar Interpolation
For cubic curves, primvar data can be either interpolated cubically between vertices or linearly across segments. The corresponding token for cubic interpolation is’vertex’and for linear interpolation is’varying’. Per vertex data should be the same size as the number of vertices in your curve. Segment varying data is dependent on the wrap (periodicity) and number of segments in your curve. For linear curves, varying and vertex data would be interpolated the same way. By convention varying is the preferred interpolation because of the association of varying with linear interpolation.
To convert an entry in the curveVertexCounts vector into a segment count for an individual curve, apply these rules. Sum up all the results in order to compute how many total segments all curves have.
The following tables describe the expected segment count for the’i’th curve in a curve batch as well as the entire batch. Python syntax like’[:]’(to describe all members of an array) and’len(...)’(to describe the length of an array) are used.
type
wrap
curve segment count
batch segment count
linear
nonperiodic
curveVertexCounts[i] - 1
sum(curveVertexCounts[:]) - len(curveVertexCounts)
linear
periodic
curveVertexCounts[i]
sum(curveVertexCounts[:])
cubic
nonperiodic
(curveVertexCounts[i] - 4) / vstep + 1
sum(curveVertexCounts[:] - 4) / vstep + len(curveVertexCounts)
cubic
periodic
curveVertexCounts[i] / vstep
sum(curveVertexCounts[:]) / vstep
cubic
pinned (catmullRom/bspline)
(curveVertexCounts[i] - 2) + 1
sum(curveVertexCounts[:] - 2) + len(curveVertexCounts)
The following table descrives the expected size of varying (linearly interpolated) data, derived from the segment counts computed above.
wrap
curve varying count
batch varying count
nonperiodic/pinned
segmentCounts[i] + 1
sum(segmentCounts[:]) + len(curveVertexCounts)
periodic
segmentCounts[i]
sum(segmentCounts[:])
Both curve types additionally define’constant’interpolation for the entire prim and’uniform’interpolation as per curve data.
Take care when providing support for linearly interpolated data for cubic curves. Its shape doesn’t provide a one to one mapping with either the number of curves (like’uniform’) or the number of vertices (like’vertex’) and so it is often overlooked. This is the only primitive in UsdGeom (as of this writing) where this is true. For meshes, while they use different interpolation methods,’varying’and’vertex’are both specified per point. It’s common to assume that curves follow a similar pattern and build in structures and language for per primitive, per element, and per point data only to come upon these arrays that don’t quite fit into either of those categories. It is also common to conflate’varying’with being per segment data and use the segmentCount rules table instead of its neighboring varying data table rules. We suspect that this is because for the common case of nonperiodic cubic curves, both the provided segment count and varying data size formula end with’+ 1’. While debugging, users may look at the double’+ 1’as a mistake and try to remove it. We take this time to enumerate these issues because we’ve fallen into them before and hope that we save others time in their own implementations. As an example of deriving per curve segment and varying primvar data counts from the wrap, type, basis, and curveVertexCount, the following table is provided.
wrap
type
basis
curveVertexCount
curveSegmentCount
varyingDataCount
nonperiodic
linear
N/A
[2 3 2 5]
[1 2 1 4]
[2 3 2 5]
nonperiodic
cubic
bezier
[4 7 10 4 7]
[1 2 3 1 2]
[2 3 4 2 3]
nonperiodic
cubic
bspline
[5 4 6 7]
[2 1 3 4]
[3 2 4 5]
periodic
cubic
bezier
[6 9 6]
[2 3 2]
[2 3 2]
periodic
linear
N/A
[3 7]
[3 7]
[3 7]
Tubes and Ribbons
The strictest definition of a curve as an infinitely thin wire is not particularly useful for describing production scenes. The additional widths and normals attributes can be used to describe cylindrical tubes and or flat oriented ribbons.
Curves with only widths defined are imaged as tubes with radius’width / 2’. Curves with both widths and normals are imaged as ribbons oriented in the direction of the interpolated normal vectors.
While not technically UsdGeomPrimvars, widths and normals also have interpolation metadata. It’s common for authored widths to have constant, varying, or vertex interpolation (see UsdGeomCurves::GetWidthsInterpolation() ). It’s common for authored normals to have varying interpolation (see UsdGeomPointBased::GetNormalsInterpolation() ).
The file used to generate these curves can be found in pxr/extras/examples/usdGeomExamples/basisCurves.usda. It’s provided as a reference on how to properly image both tubes and ribbons. The first row of curves are linear; the second are cubic bezier. (We aim in future releases of HdSt to fix the discontinuity seen with broken tangents to better match offline renderers like RenderMan.) The yellow and violet cubic curves represent cubic vertex width interpolation for which there is no equivalent for linear curves.
How did this prim type get its name? This prim is a portmanteau of two different statements in the original RenderMan specification:’Basis’and’Curves’. For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
ComputeInterpolationForSize
(n, timeCode, info)Computes interpolation token for
n
.ComputeUniformDataSize
(timeCode)Computes the expected size for data with"uniform"interpolation.
ComputeVaryingDataSize
(timeCode)Computes the expected size for data with"varying"interpolation.
ComputeVertexDataSize
(timeCode)Computes the expected size for data with"vertex"interpolation.
CreateBasisAttr
(defaultValue, writeSparsely)See GetBasisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTypeAttr
(defaultValue, writeSparsely)See GetTypeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateWrapAttr
(defaultValue, writeSparsely)See GetWrapAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> BasisCurves
classmethod Get(stage, path) -> BasisCurves
The basis specifies the vstep and matrix used for cubic interpolation.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Linear curves interpolate linearly between two vertices.
If wrap is set to periodic, the curve when rendered will repeat the initial vertices (dependent on the vstep) to close the curve.
- ComputeInterpolationForSize(n, timeCode, info) str
Computes interpolation token for
n
.If this returns an empty token and
info
was non-None, it’ll contain the expected value for each token.The topology is determined using
timeCode
.- Parameters
n (int) –
timeCode (TimeCode) –
info (ComputeInterpolationInfo) –
- ComputeUniformDataSize(timeCode) int
Computes the expected size for data with”uniform”interpolation.
If you’re trying to determine what interpolation to use, it is more efficient to use
ComputeInterpolationForSize
- Parameters
timeCode (TimeCode) –
- ComputeVaryingDataSize(timeCode) int
Computes the expected size for data with”varying”interpolation.
If you’re trying to determine what interpolation to use, it is more efficient to use
ComputeInterpolationForSize
- Parameters
timeCode (TimeCode) –
- ComputeVertexDataSize(timeCode) int
Computes the expected size for data with”vertex”interpolation.
If you’re trying to determine what interpolation to use, it is more efficient to use
ComputeInterpolationForSize
- Parameters
timeCode (TimeCode) –
- CreateBasisAttr(defaultValue, writeSparsely) Attribute
See GetBasisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTypeAttr(defaultValue, writeSparsely) Attribute
See GetTypeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateWrapAttr(defaultValue, writeSparsely) Attribute
See GetWrapAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> BasisCurves
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> BasisCurves
Return a UsdGeomBasisCurves holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomBasisCurves(stage->GetPrimAtPath(path));
- GetBasisAttr() Attribute
The basis specifies the vstep and matrix used for cubic interpolation.
The’hermite’and’power’tokens have been removed. We’ve provided UsdGeomHermiteCurves as an alternative for the’hermite’basis.
Declaration
uniform token basis ="bezier"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
bezier, bspline, catmullRom
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetTypeAttr() Attribute
Linear curves interpolate linearly between two vertices.
Cubic curves use a basis matrix with four vertices to interpolate a segment.
Declaration
uniform token type ="cubic"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
linear, cubic
- GetWrapAttr() Attribute
If wrap is set to periodic, the curve when rendered will repeat the initial vertices (dependent on the vstep) to close the curve.
If wrap is set to’pinned’, phantom points may be created to ensure that the curve interpolation starts at P[0] and ends at P[n-1].
Declaration
uniform token wrap ="nonperiodic"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
nonperiodic, periodic, pinned
- class pxr.UsdGeom.Boundable
Boundable introduces the ability for a prim to persistently cache a rectilinear, local-space, extent.
Why Extent and not Bounds ?
Boundable introduces the notion of”extent”, which is a cached computation of a prim’s local-space 3D range for its resolved attributes at the layer and time in which extent is authored. We have found that with composed scene description, attempting to cache pre-computed bounds at interior prims in a scene graph is very fragile, given the ease with which one can author a single attribute in a stronger layer that can invalidate many authored caches - or with which a re-published, referenced asset can do the same.
Therefore, we limit to precomputing (generally) leaf-prim extent, which avoids the need to read in large point arrays to compute bounds, and provides UsdGeomBBoxCache the means to efficiently compute and (session-only) cache intermediate bounds. You are free to compute and author intermediate bounds into your scenes, of course, which may work well if you have sufficient locks on your pipeline to guarantee that once authored, the geometry and transforms upon which they are based will remain unchanged, or if accuracy of the bounds is not an ironclad requisite.
When intermediate bounds are authored on Boundable parents, the child prims will be pruned from BBox computation; the authored extent is expected to incorporate all child bounds.
Methods:
classmethod ComputeExtent(radius, extent) -> bool
classmethod ComputeExtentFromPlugins(boundable, time, extent) -> bool
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> Boundable
Extent is a three dimensional range measuring the geometric extent of the authored gprim in its own local space (i.e.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- ComputeExtent()
classmethod ComputeExtent(radius, extent) -> bool
Compute the extent for the sphere defined by the radius.
true upon success, false if unable to calculate extent. On success, extent will contain an approximate axis-aligned bounding box of the sphere defined by the radius.
This function is to provide easy authoring of extent for usd authoring tools, hence it is static and acts outside a specific prim (as in attribute based methods).
- Parameters
radius (float) –
extent (Vec3fArray) –
ComputeExtent(radius, transform, extent) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
radius (float) –
transform (Matrix4d) –
extent (Vec3fArray) –
- static ComputeExtentFromPlugins()
classmethod ComputeExtentFromPlugins(boundable, time, extent) -> bool
Compute the extent for the Boundable prim
boundable
at timetime
.If successful, populates
extent
with the result and returnstrue
, otherwise returnsfalse
.The extent computation is based on the concrete type of the prim represented by
boundable
. Plugins that provide a Boundable prim type may implement and register an extent computation for that type using UsdGeomRegisterComputeExtentFunction. ComputeExtentFromPlugins will use this function to compute extents for all prims of that type. If no function has been registered for a prim type, but a function has been registered for one of its base types, that function will be used instead.This function may load plugins in order to access the extent computation for a prim type.
- Parameters
boundable (Boundable) –
time (TimeCode) –
extent (Vec3fArray) –
ComputeExtentFromPlugins(boundable, time, transform, extent) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
boundable (Boundable) –
time (TimeCode) –
transform (Matrix4d) –
extent (Vec3fArray) –
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> Boundable
Return a UsdGeomBoundable holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomBoundable(stage->GetPrimAtPath(path));
- GetExtentAttr() Attribute
Extent is a three dimensional range measuring the geometric extent of the authored gprim in its own local space (i.e.
its own transform not applied), without accounting for any shader- induced displacement. If any extent value has been authored for a given Boundable, then it should be authored at every timeSample at which geometry-affecting properties are authored, to ensure correct evaluation via ComputeExtent() . If no extent value has been authored, then ComputeExtent() will call the Boundable’s registered ComputeExtentFunction(), which may be expensive, which is why we strongly encourage proper authoring of extent.
ComputeExtent()
Why Extent and not Bounds? . An authored extent on a prim which has children is expected to include the extent of all children, as they will be pruned from BBox computation during traversal.
Declaration
float3[] extent
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Camera
Transformable camera.
Describes optical properties of a camera via a common set of attributes that provide control over the camera’s frustum as well as its depth of field. For stereo, the left and right camera are individual prims tagged through the stereoRole attribute.
There is a corresponding class GfCamera, which can hold the state of a camera (at a particular time). UsdGeomCamera::GetCamera() and UsdGeomCamera::SetFromCamera() convert between a USD camera prim and a GfCamera.
To obtain the camera’s location in world space, call the following on a UsdGeomCamera ‘camera’:
GfMatrix4d camXform = camera.ComputeLocalToWorldTransform(time);
Cameras in USD are always”Y up”, regardless of the stage’s orientation (i.e. UsdGeomGetStageUpAxis() ). This means that the inverse of’camXform’(the VIEW half of the MODELVIEW transform in OpenGL parlance) will transform the world such that the camera is at the origin, looking down the -Z axis, with +Y as the up axis, and +X pointing to the right. This describes a right handed coordinate system.
Units of Measure for Camera Properties
Despite the familiarity of millimeters for specifying some physical camera properties, UsdGeomCamera opts for greater consistency with all other UsdGeom schemas, which measure geometric properties in scene units, as determined by UsdGeomGetStageMetersPerUnit() . We do make a concession, however, in that lens and filmback properties are measured in tenths of a scene unit rather than”raw”scene units. This means that with the fallback value of.01 for metersPerUnit - i.e. scene unit of centimeters - then these”tenth of scene unit”properties are effectively millimeters.
If one adds a Camera prim to a UsdStage whose scene unit is not centimeters, the fallback values for filmback properties will be incorrect (or at the least, unexpected) in an absolute sense; however, proper imaging through a”default camera”with focusing disabled depends only on ratios of the other properties, so the camera is still usable. However, it follows that if even one property is authored in the correct scene units, then they all must be.
Linear Algebra in UsdGeom For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateClippingPlanesAttr
(defaultValue, ...)See GetClippingPlanesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateClippingRangeAttr
(defaultValue, ...)See GetClippingRangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateExposureAttr
(defaultValue, writeSparsely)See GetExposureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFStopAttr
(defaultValue, writeSparsely)See GetFStopAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFocalLengthAttr
(defaultValue, ...)See GetFocalLengthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFocusDistanceAttr
(defaultValue, ...)See GetFocusDistanceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateHorizontalApertureAttr
(defaultValue, ...)See GetHorizontalApertureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetHorizontalApertureOffsetAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateProjectionAttr
(defaultValue, writeSparsely)See GetProjectionAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateShutterCloseAttr
(defaultValue, ...)See GetShutterCloseAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateShutterOpenAttr
(defaultValue, ...)See GetShutterOpenAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateStereoRoleAttr
(defaultValue, writeSparsely)See GetStereoRoleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVerticalApertureAttr
(defaultValue, ...)See GetVerticalApertureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetVerticalApertureOffsetAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Camera
classmethod Get(stage, path) -> Camera
GetCamera
(time)Creates a GfCamera object from the attribute values at
time
.Additional, arbitrarily oriented clipping planes.
Near and far clipping distances in scene units; see Units of Measure for Camera Properties.
Exposure adjustment, as a log base-2 value.
Lens aperture.
Perspective focal length in tenths of a scene unit; see Units of Measure for Camera Properties.
Distance from the camera to the focus plane in scene units; see Units of Measure for Camera Properties.
Horizontal aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
Horizontal aperture offset in the same units as horizontalAperture.
Declaration
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Frame relative shutter close time, analogous comments from shutter:open apply.
Frame relative shutter open time in UsdTimeCode units (negative value indicates that the shutter opens before the current frame time).
If different from mono, the camera is intended to be the left or right camera of a stereo setup.
Vertical aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
Vertical aperture offset in the same units as verticalAperture.
SetFromCamera
(camera, time)Write attribute values from
camera
fortime
.- CreateClippingPlanesAttr(defaultValue, writeSparsely) Attribute
See GetClippingPlanesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateClippingRangeAttr(defaultValue, writeSparsely) Attribute
See GetClippingRangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateExposureAttr(defaultValue, writeSparsely) Attribute
See GetExposureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFStopAttr(defaultValue, writeSparsely) Attribute
See GetFStopAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFocalLengthAttr(defaultValue, writeSparsely) Attribute
See GetFocalLengthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFocusDistanceAttr(defaultValue, writeSparsely) Attribute
See GetFocusDistanceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHorizontalApertureAttr(defaultValue, writeSparsely) Attribute
See GetHorizontalApertureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHorizontalApertureOffsetAttr(defaultValue, writeSparsely) Attribute
See GetHorizontalApertureOffsetAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateProjectionAttr(defaultValue, writeSparsely) Attribute
See GetProjectionAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateShutterCloseAttr(defaultValue, writeSparsely) Attribute
See GetShutterCloseAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateShutterOpenAttr(defaultValue, writeSparsely) Attribute
See GetShutterOpenAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateStereoRoleAttr(defaultValue, writeSparsely) Attribute
See GetStereoRoleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVerticalApertureAttr(defaultValue, writeSparsely) Attribute
See GetVerticalApertureAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVerticalApertureOffsetAttr(defaultValue, writeSparsely) Attribute
See GetVerticalApertureOffsetAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Camera
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Camera
Return a UsdGeomCamera holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCamera(stage->GetPrimAtPath(path));
- GetCamera(time) Camera
Creates a GfCamera object from the attribute values at
time
.- Parameters
time (TimeCode) –
- GetClippingPlanesAttr() Attribute
Additional, arbitrarily oriented clipping planes.
A vector (a,b,c,d) encodes a clipping plane that cuts off (x,y,z) with a * x + b * y + c * z + d * 1<0 where (x,y,z) are the coordinates in the camera’s space.
Declaration
float4[] clippingPlanes = []
C++ Type
VtArray<GfVec4f>
Usd Type
SdfValueTypeNames->Float4Array
- GetClippingRangeAttr() Attribute
Near and far clipping distances in scene units; see Units of Measure for Camera Properties.
Declaration
float2 clippingRange = (1, 1000000)
C++ Type
GfVec2f
Usd Type
SdfValueTypeNames->Float2
- GetExposureAttr() Attribute
Exposure adjustment, as a log base-2 value.
The default of 0.0 has no effect. A value of 1.0 will double the image-plane intensities in a rendered image; a value of -1.0 will halve them.
Declaration
float exposure = 0
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetFStopAttr() Attribute
Lens aperture.
Defaults to 0.0, which turns off focusing.
Declaration
float fStop = 0
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetFocalLengthAttr() Attribute
Perspective focal length in tenths of a scene unit; see Units of Measure for Camera Properties.
Declaration
float focalLength = 50
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetFocusDistanceAttr() Attribute
Distance from the camera to the focus plane in scene units; see Units of Measure for Camera Properties.
Declaration
float focusDistance = 0
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetHorizontalApertureAttr() Attribute
Horizontal aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
Default is the equivalent of the standard 35mm spherical projector aperture.
Declaration
float horizontalAperture = 20.955
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetHorizontalApertureOffsetAttr() Attribute
Horizontal aperture offset in the same units as horizontalAperture.
Defaults to 0.
Declaration
float horizontalApertureOffset = 0
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetProjectionAttr() Attribute
Declaration
token projection ="perspective"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Allowed Values
perspective, orthographic
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetShutterCloseAttr() Attribute
Frame relative shutter close time, analogous comments from shutter:open apply.
A value greater or equal to shutter:open should be authored, otherwise there is no exposure and a renderer should produce a black image.
Declaration
double shutter:close = 0
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- GetShutterOpenAttr() Attribute
Frame relative shutter open time in UsdTimeCode units (negative value indicates that the shutter opens before the current frame time).
Used for motion blur.
Declaration
double shutter:open = 0
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- GetStereoRoleAttr() Attribute
If different from mono, the camera is intended to be the left or right camera of a stereo setup.
Declaration
uniform token stereoRole ="mono"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
mono, left, right
- GetVerticalApertureAttr() Attribute
Vertical aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
Default is the equivalent of the standard 35mm spherical projector aperture.
Declaration
float verticalAperture = 15.2908
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetVerticalApertureOffsetAttr() Attribute
Vertical aperture offset in the same units as verticalAperture.
Defaults to 0.
Declaration
float verticalApertureOffset = 0
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- SetFromCamera(camera, time) None
Write attribute values from
camera
fortime
.These attributes will be updated:
projection
horizontalAperture
horizontalApertureOffset
verticalAperture
verticalApertureOffset
focalLength
clippingRange
clippingPlanes
fStop
focalDistance
xformOpOrder and xformOp:transform
This will clear any existing xformOpOrder and replace it with a single xformOp:transform entry. The xformOp:transform property is created or updated here to match the transform on
camera
. This operation will fail if there are stronger xform op opinions in the composed layer stack that are stronger than that of the current edit target.
- class pxr.UsdGeom.Capsule
Defines a primitive capsule, i.e. a cylinder capped by two half spheres, centered at the origin, whose spine is along the specified axis.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateAxisAttr
(defaultValue, writeSparsely)See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateHeightAttr
(defaultValue, writeSparsely)See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateRadiusAttr
(defaultValue, writeSparsely)See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Capsule
classmethod Get(stage, path) -> Capsule
The axis along which the spine of the capsule is aligned.
Extent is re-defined on Capsule only to provide a fallback value.
The size of the capsule's spine along the specified axis excluding the size of the two half spheres, i.e.
The radius of the capsule.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateAxisAttr(defaultValue, writeSparsely) Attribute
See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHeightAttr(defaultValue, writeSparsely) Attribute
See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateRadiusAttr(defaultValue, writeSparsely) Attribute
See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Capsule
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Capsule
Return a UsdGeomCapsule holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCapsule(stage->GetPrimAtPath(path));
- GetAxisAttr() Attribute
The axis along which the spine of the capsule is aligned.
Declaration
uniform token axis ="Z"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
X, Y, Z
- GetExtentAttr() Attribute
Extent is re-defined on Capsule only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-0.5, -0.5, -1), (0.5, 0.5, 1)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- GetHeightAttr() Attribute
The size of the capsule’s spine along the specified axis excluding the size of the two half spheres, i.e.
the size of the cylinder portion of the capsule. If you author height you must also author extent.
GetExtentAttr()
Declaration
double height = 1
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- GetRadiusAttr() Attribute
The radius of the capsule.
If you author radius you must also author extent.
GetExtentAttr()
Declaration
double radius = 0.5
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Cone
Defines a primitive cone, centered at the origin, whose spine is along the specified axis, with the apex of the cone pointing in the direction of the positive axis.
The fallback values for Cube, Sphere, Cone, and Cylinder are set so that they all pack into the same volume/bounds.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateAxisAttr
(defaultValue, writeSparsely)See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateHeightAttr
(defaultValue, writeSparsely)See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateRadiusAttr
(defaultValue, writeSparsely)See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Cone
classmethod Get(stage, path) -> Cone
The axis along which the spine of the cone is aligned.
Extent is re-defined on Cone only to provide a fallback value.
The size of the cone's spine along the specified axis.
The radius of the cone.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateAxisAttr(defaultValue, writeSparsely) Attribute
See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHeightAttr(defaultValue, writeSparsely) Attribute
See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateRadiusAttr(defaultValue, writeSparsely) Attribute
See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Cone
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Cone
Return a UsdGeomCone holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCone(stage->GetPrimAtPath(path));
- GetAxisAttr() Attribute
The axis along which the spine of the cone is aligned.
Declaration
uniform token axis ="Z"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
X, Y, Z
- GetExtentAttr() Attribute
Extent is re-defined on Cone only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-1, -1, -1), (1, 1, 1)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- GetHeightAttr() Attribute
The size of the cone’s spine along the specified axis.
If you author height you must also author extent.
GetExtentAttr()
Declaration
double height = 2
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- GetRadiusAttr() Attribute
The radius of the cone.
If you author radius you must also author extent.
GetExtentAttr()
Declaration
double radius = 1
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.ConstraintTarget
Schema wrapper for UsdAttribute for authoring and introspecting attributes that are constraint targets.
Constraint targets correspond roughly to what some DCC’s call locators. They are coordinate frames, represented as (animated or static) GfMatrix4d values. We represent them as attributes in USD rather than transformable prims because generally we require no other coordinated information about a constraint target other than its name and its matrix value, and because attributes are more concise than prims.
Because consumer clients often care only about the identity and value of constraint targets and may be able to usefully consume them without caring about the actual geometry with which they may logically correspond, UsdGeom aggregates all constraint targets onto a model’s root prim, assuming that an exporter will use property namespacing within the constraint target attribute’s name to indicate a path to a prim within the model with which the constraint target may correspond.
To facilitate instancing, and also position-tweaking of baked assets, we stipulate that constraint target values always be recorded in model-relative transformation space. In other words, to get the world-space value of a constraint target, transform it by the local- to-world transformation of the prim on which it is recorded. ComputeInWorldSpace() will perform this calculation.
Methods:
ComputeInWorldSpace
(time, xfCache)Computes the value of the constraint target in world space.
Get
(value, time)Get the attribute value of the ConstraintTarget at
time
.GetAttr
()Explicit UsdAttribute extractor.
classmethod GetConstraintAttrName(constraintName) -> str
Get the stored identifier unique to the enclosing model's namespace for this constraint target.
Return true if the wrapped UsdAttribute::IsDefined() , and in addition the attribute is identified as a ConstraintTarget.
classmethod IsValid(attr) -> bool
Set
(value, time)Set the attribute value of the ConstraintTarget at
time
.SetIdentifier
(identifier)Explicitly sets the stored identifier to the given string.
- ComputeInWorldSpace(time, xfCache) Matrix4d
Computes the value of the constraint target in world space.
If a valid UsdGeomXformCache is provided in the argument
xfCache
, it is used to evaluate the CTM of the model to which the constraint target belongs.To get the constraint value in model-space (or local space), simply use UsdGeomConstraintTarget::Get() , since the authored values must already be in model-space.
- Parameters
time (TimeCode) –
xfCache (XformCache) –
- Get(value, time) bool
Get the attribute value of the ConstraintTarget at
time
.
- static GetConstraintAttrName()
classmethod GetConstraintAttrName(constraintName) -> str
Returns the fully namespaced constraint attribute name, given the constraint name.
- Parameters
constraintName (str) –
- GetIdentifier() str
Get the stored identifier unique to the enclosing model’s namespace for this constraint target.
SetIdentifier()
- IsDefined() bool
Return true if the wrapped UsdAttribute::IsDefined() , and in addition the attribute is identified as a ConstraintTarget.
- IsValid()
classmethod IsValid(attr) -> bool
Test whether a given UsdAttribute represents valid ConstraintTarget, which implies that creating a UsdGeomConstraintTarget from the attribute will succeed.
Success implies that
attr.IsDefined()
is true.- Parameters
attr (Attribute) –
- Set(value, time) bool
Set the attribute value of the ConstraintTarget at
time
.
- class pxr.UsdGeom.Cube
Defines a primitive rectilinear cube centered at the origin.
The fallback values for Cube, Sphere, Cone, and Cylinder are set so that they all pack into the same volume/bounds.
Methods:
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateSizeAttr
(defaultValue, writeSparsely)See GetSizeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Cube
classmethod Get(stage, path) -> Cube
Extent is re-defined on Cube only to provide a fallback value.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Indicates the length of each edge of the cube.
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateSizeAttr(defaultValue, writeSparsely) Attribute
See GetSizeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Cube
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Cube
Return a UsdGeomCube holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCube(stage->GetPrimAtPath(path));
- GetExtentAttr() Attribute
Extent is re-defined on Cube only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-1, -1, -1), (1, 1, 1)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Curves
Base class for UsdGeomBasisCurves, UsdGeomNurbsCurves, and UsdGeomHermiteCurves. The BasisCurves schema is designed to be analagous to offline renderers’notion of batched curves (such as the classical RIB definition via Basis and Curves statements), while the NurbsCurve schema is designed to be analgous to the NURBS curves found in packages like Maya and Houdini while retaining their consistency with the RenderMan specification for NURBS Patches. HermiteCurves are useful for the interchange of animation guides and paths.
It is safe to use the length of the curve vertex count to derive the number of curves and the number and layout of curve vertices, but this schema should NOT be used to derive the number of curve points. While vertex indices are implicit in all shipped descendent types of this schema, one should not assume that all internal or future shipped schemas will follow this pattern. Be sure to key any indexing behavior off the concrete type, not this abstract type.
Methods:
classmethod ComputeExtent(points, widths, extent) -> bool
CreateCurveVertexCountsAttr
(defaultValue, ...)See GetCurveVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateWidthsAttr
(defaultValue, writeSparsely)See GetWidthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> Curves
GetCurveCount
(timeCode)Returns the number of curves as defined by the size of the curveVertexCounts array at timeCode.
Curves-derived primitives can represent multiple distinct, potentially disconnected curves.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Provides width specification for the curves, whose application will depend on whether the curve is oriented (normals are defined for it), in which case widths are"ribbon width", or unoriented, in which case widths are cylinder width.
Get the interpolation for the widths attribute.
SetWidthsInterpolation
(interpolation)Set the interpolation for the widths attribute.
- static ComputeExtent()
classmethod ComputeExtent(points, widths, extent) -> bool
Compute the extent for the curves defined by points and widths.
true upon success, false if unable to calculate extent. On success, extent will contain an approximate axis-aligned bounding box of the curve defined by points with the given widths.
This function is to provide easy authoring of extent for usd authoring tools, hence it is static and acts outside a specific prim (as in attribute based methods).
- Parameters
points (Vec3fArray) –
widths (FloatArray) –
extent (Vec3fArray) –
ComputeExtent(points, widths, transform, extent) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
points (Vec3fArray) –
widths (FloatArray) –
transform (Matrix4d) –
extent (Vec3fArray) –
- CreateCurveVertexCountsAttr(defaultValue, writeSparsely) Attribute
See GetCurveVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateWidthsAttr(defaultValue, writeSparsely) Attribute
See GetWidthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> Curves
Return a UsdGeomCurves holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCurves(stage->GetPrimAtPath(path));
- GetCurveCount(timeCode) int
Returns the number of curves as defined by the size of the curveVertexCounts array at timeCode.
For most code, this check will be performant. When using file formats where the cost of attribute reading is high and the time sampled array will be read into memory later, it may be better to explicitly read the value once and check the size of the array directly.
GetCurveVertexCountsAttr()
- Parameters
timeCode (TimeCode) –
- GetCurveVertexCountsAttr() Attribute
Curves-derived primitives can represent multiple distinct, potentially disconnected curves.
The length of’curveVertexCounts’gives the number of such curves, and each element describes the number of vertices in the corresponding curve
Declaration
int[] curveVertexCounts
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetWidthsAttr() Attribute
Provides width specification for the curves, whose application will depend on whether the curve is oriented (normals are defined for it), in which case widths are”ribbon width”, or unoriented, in which case widths are cylinder width.
‘widths’is not a generic Primvar, but the number of elements in this attribute will be determined by its’interpolation’. See SetWidthsInterpolation() . If’widths’and’primvars:widths’are both specified, the latter has precedence.
Declaration
float[] widths
C++ Type
VtArray<float>
Usd Type
SdfValueTypeNames->FloatArray
- GetWidthsInterpolation() str
Get the interpolation for the widths attribute.
Although’widths’is not classified as a generic UsdGeomPrimvar (and will not be included in the results of UsdGeomPrimvarsAPI::GetPrimvars() ) it does require an interpolation specification. The fallback interpolation, if left unspecified, is UsdGeomTokens->vertex, which means a width value is specified at the end of each curve segment.
- SetWidthsInterpolation(interpolation) bool
Set the interpolation for the widths attribute.
true upon success, false if
interpolation
is not a legal value as defined by UsdPrimvar::IsValidInterpolation(), or if there was a problem setting the value. No attempt is made to validate that the widths attr’s value contains the right number of elements to match its interpolation to its prim’s topology.GetWidthsInterpolation()
- Parameters
interpolation (str) –
- class pxr.UsdGeom.Cylinder
Defines a primitive cylinder with closed ends, centered at the origin, whose spine is along the specified axis.
The fallback values for Cube, Sphere, Cone, and Cylinder are set so that they all pack into the same volume/bounds.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateAxisAttr
(defaultValue, writeSparsely)See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateHeightAttr
(defaultValue, writeSparsely)See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateRadiusAttr
(defaultValue, writeSparsely)See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Cylinder
classmethod Get(stage, path) -> Cylinder
The axis along which the spine of the cylinder is aligned.
Extent is re-defined on Cylinder only to provide a fallback value.
The size of the cylinder's spine along the specified axis.
The radius of the cylinder.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateAxisAttr(defaultValue, writeSparsely) Attribute
See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHeightAttr(defaultValue, writeSparsely) Attribute
See GetHeightAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateRadiusAttr(defaultValue, writeSparsely) Attribute
See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Cylinder
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Cylinder
Return a UsdGeomCylinder holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomCylinder(stage->GetPrimAtPath(path));
- GetAxisAttr() Attribute
The axis along which the spine of the cylinder is aligned.
Declaration
uniform token axis ="Z"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
X, Y, Z
- GetExtentAttr() Attribute
Extent is re-defined on Cylinder only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-1, -1, -1), (1, 1, 1)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- GetHeightAttr() Attribute
The size of the cylinder’s spine along the specified axis.
If you author height you must also author extent.
GetExtentAttr()
Declaration
double height = 2
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- GetRadiusAttr() Attribute
The radius of the cylinder.
If you author radius you must also author extent.
GetExtentAttr()
Declaration
double radius = 1
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Gprim
Base class for all geometric primitives.
Gprim encodes basic graphical properties such as doubleSided and orientation, and provides primvars for”display color”and”displayopacity”that travel with geometry to be used as shader overrides.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateDisplayColorAttr
(defaultValue, ...)See GetDisplayColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateDisplayColorPrimvar
(interpolation, ...)Convenience function to create the displayColor primvar, optionally specifying interpolation and elementSize.
CreateDisplayOpacityAttr
(defaultValue, ...)See GetDisplayOpacityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateDisplayOpacityPrimvar
(interpolation, ...)Convenience function to create the displayOpacity primvar, optionally specifying interpolation and elementSize.
CreateDoubleSidedAttr
(defaultValue, ...)See GetDoubleSidedAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateOrientationAttr
(defaultValue, ...)See GetOrientationAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> Gprim
It is useful to have an"official"colorSet that can be used as a display or modeling color, even in the absence of any specified shader for a gprim.
Convenience function to get the displayColor Attribute as a Primvar.
Companion to displayColor that specifies opacity, broken out as an independent attribute rather than an rgba color, both so that each can be independently overridden, and because shaders rarely consume rgba parameters.
Convenience function to get the displayOpacity Attribute as a Primvar.
Although some renderers treat all parametric or polygonal surfaces as if they were effectively laminae with outward-facing normals on both sides, some renderers derive significant optimizations by considering these surfaces to have only a single outward side, typically determined by control-point winding order and/or orientation.
Orientation specifies whether the gprim's surface normal should be computed using the right hand rule, or the left hand rule.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateDisplayColorAttr(defaultValue, writeSparsely) Attribute
See GetDisplayColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateDisplayColorPrimvar(interpolation, elementSize) Primvar
Convenience function to create the displayColor primvar, optionally specifying interpolation and elementSize.
CreateDisplayColorAttr() , GetDisplayColorPrimvar()
- Parameters
interpolation (str) –
elementSize (int) –
- CreateDisplayOpacityAttr(defaultValue, writeSparsely) Attribute
See GetDisplayOpacityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateDisplayOpacityPrimvar(interpolation, elementSize) Primvar
Convenience function to create the displayOpacity primvar, optionally specifying interpolation and elementSize.
CreateDisplayOpacityAttr() , GetDisplayOpacityPrimvar()
- Parameters
interpolation (str) –
elementSize (int) –
- CreateDoubleSidedAttr(defaultValue, writeSparsely) Attribute
See GetDoubleSidedAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateOrientationAttr(defaultValue, writeSparsely) Attribute
See GetOrientationAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> Gprim
Return a UsdGeomGprim holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomGprim(stage->GetPrimAtPath(path));
- GetDisplayColorAttr() Attribute
It is useful to have an”official”colorSet that can be used as a display or modeling color, even in the absence of any specified shader for a gprim.
DisplayColor serves this role; because it is a UsdGeomPrimvar, it can also be used as a gprim override for any shader that consumes a displayColor parameter.
Declaration
color3f[] primvars:displayColor
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Color3fArray
- GetDisplayColorPrimvar() Primvar
Convenience function to get the displayColor Attribute as a Primvar.
GetDisplayColorAttr() , CreateDisplayColorPrimvar()
- GetDisplayOpacityAttr() Attribute
Companion to displayColor that specifies opacity, broken out as an independent attribute rather than an rgba color, both so that each can be independently overridden, and because shaders rarely consume rgba parameters.
Declaration
float[] primvars:displayOpacity
C++ Type
VtArray<float>
Usd Type
SdfValueTypeNames->FloatArray
- GetDisplayOpacityPrimvar() Primvar
Convenience function to get the displayOpacity Attribute as a Primvar.
GetDisplayOpacityAttr() , CreateDisplayOpacityPrimvar()
- GetDoubleSidedAttr() Attribute
Although some renderers treat all parametric or polygonal surfaces as if they were effectively laminae with outward-facing normals on both sides, some renderers derive significant optimizations by considering these surfaces to have only a single outward side, typically determined by control-point winding order and/or orientation.
By doing so they can perform”backface culling”to avoid drawing the many polygons of most closed surfaces that face away from the viewer.
However, it is often advantageous to model thin objects such as paper and cloth as single, open surfaces that must be viewable from both sides, always. Setting a gprim’s doubleSided attribute to
true
instructs all renderers to disable optimizations such as backface culling for the gprim, and attempt (not all renderers are able to do so, but the USD reference GL renderer always will) to provide forward- facing normals on each side of the surface for lighting calculations.Declaration
uniform bool doubleSided = 0
C++ Type
bool
Usd Type
SdfValueTypeNames->Bool
Variability
SdfVariabilityUniform
- GetOrientationAttr() Attribute
Orientation specifies whether the gprim’s surface normal should be computed using the right hand rule, or the left hand rule.
Please see Coordinate System, Winding Order, Orientation, and Surface Normals for a deeper explanation and generalization of orientation to composed scenes with transformation hierarchies.
Declaration
uniform token orientation ="rightHanded"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
rightHanded, leftHanded
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.HermiteCurves
This schema specifies a cubic hermite interpolated curve batch as sometimes used for defining guides for animation. While hermite curves can be useful because they interpolate through their control points, they are not well supported by high-end renderers for imaging. Therefore, while we include this schema for interchange, we strongly recommend the use of UsdGeomBasisCurves as the representation of curves intended to be rendered (ie. hair or grass). Hermite curves can be converted to a Bezier representation (though not from Bezier back to Hermite in general).
Point Interpolation
The initial cubic curve segment is defined by the first two points and first two tangents. Additional segments are defined by additional point / tangent pairs. The number of segments for each non-batched hermite curve would be len(curve.points) - 1. The total number of segments for the batched UsdGeomHermiteCurves representation is len(points) - len(curveVertexCounts).
Primvar, Width, and Normal Interpolation
Primvar interpolation is not well specified for this type as it is not intended as a rendering representation. We suggest that per point primvars would be linearly interpolated across each segment and should be tagged as’varying’.
It is not immediately clear how to specify cubic or’vertex’interpolation for this type, as we lack a specification for primvar tangents. This also means that width and normal interpolation should be restricted to varying (linear), uniform (per curve element), or constant (per prim).
Classes:
Methods:
CreateTangentsAttr
(defaultValue, writeSparsely)See GetTangentsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> HermiteCurves
classmethod Get(stage, path) -> HermiteCurves
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Defines the outgoing trajectory tangent for each point.
- class PointAndTangentArrays
Methods:
- GetPoints()
- GetTangents()
- Interleave()
- IsEmpty()
- static Separate()
- CreateTangentsAttr(defaultValue, writeSparsely) Attribute
See GetTangentsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> HermiteCurves
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> HermiteCurves
Return a UsdGeomHermiteCurves holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomHermiteCurves(stage->GetPrimAtPath(path));
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Imageable
Base class for all prims that may require rendering or visualization of some sort. The primary attributes of Imageable are visibility and purpose, which each provide instructions for what geometry should be included for processing by rendering and other computations.
Deprecated
Imageable also provides API for accessing primvars, which has been moved to the UsdGeomPrimvarsAPI schema, because primvars can now be applied on non-Imageable prim types. This API is planned to be removed, UsdGeomPrimvarsAPI should be used directly instead.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Classes:
Methods:
ComputeEffectiveVisibility
(purpose, time)Calculate the effective purpose visibility of this prim for the given
purpose
, taking into account opinions for the corresponding purpose attribute, along with overall visibility opinions.ComputeLocalBound
(time, purpose1, purpose2, ...)Compute the bound of this prim in local space, at the specified
time
, and for the specified purposes.Compute the transformation matrix for this prim at the given time, including the transform authored on the Prim itself, if present.
Compute the transformation matrix for this prim at the given time, NOT including the transform authored on the prim itself.
Returns None if neither this prim nor any of its ancestors has a valid renderProxy prim.
Calculate the effective purpose information about this prim.
Calculate the effective purpose information about this prim which includes final computed purpose value of the prim as well as whether the purpose value should be inherited by namespace children without their own purpose opinions.
ComputeUntransformedBound
(time, purpose1, ...)Compute the untransformed bound of this prim, at the specified
time
, and for the specified purposes.ComputeVisibility
(time)Calculate the effective visibility of this prim, as defined by its most ancestral authored"invisible"opinion, if any.
ComputeWorldBound
(time, purpose1, purpose2, ...)Compute the bound of this prim in world space, at the specified
time
, and for the specified purposes.See GetProxyPrimRel() , and also Create vs Get Property Methods for when to use Get vs Create.
CreatePurposeAttr
(defaultValue, writeSparsely)See GetPurposeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVisibilityAttr
(defaultValue, writeSparsely)See GetVisibilityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> Imageable
classmethod GetOrderedPurposeTokens() -> list[str]
The proxyPrim relationship allows us to link a prim whose purpose is"render"to its (single target) purpose="proxy"prim.
Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals.
GetPurposeVisibilityAttr
(purpose)Return the attribute that is used for expressing visibility opinions for the given
purpose
.classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Visibility is meant to be the simplest form of"pruning"visibility that is supported by most DCC apps.
MakeInvisible
(time)Makes the imageable invisible if it is visible at the given time.
MakeVisible
(time)Make the imageable visible if it is invisible at the given time.
SetProxyPrim
(proxy)Convenience function for authoring the renderProxy rel on this prim to target the given
proxy
prim.- class PurposeInfo
Methods:
Attributes:
- GetInheritablePurpose()
- property isInheritable
- property purpose
- ComputeEffectiveVisibility(purpose, time) str
Calculate the effective purpose visibility of this prim for the given
purpose
, taking into account opinions for the corresponding purpose attribute, along with overall visibility opinions.If ComputeVisibility() returns”invisible”, then ComputeEffectiveVisibility() is”invisible”for all purpose values. Otherwise, ComputeEffectiveVisibility() returns the value of the nearest ancestral authored opinion for the corresponding purpose visibility attribute, as retured by GetPurposeVisibilityAttr(purpose).
Note that the value returned here can be”invisible”(indicating the prim is invisible for the given purpose),”visible”(indicating that it’s visible), or”inherited”(indicating that the purpose visibility is context-dependent and the fallback behavior must be determined by the caller.
This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub- problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage visibility on a stack as you traverse.
UsdGeomVisibilityAPI
GetPurposeVisibilityAttr()
ComputeVisibility()
- Parameters
purpose (str) –
time (TimeCode) –
- ComputeLocalBound(time, purpose1, purpose2, purpose3, purpose4) BBox3d
Compute the bound of this prim in local space, at the specified
time
, and for the specified purposes.The bound of the prim is computed, including the transform (if any) authored on the node itself.
It is an error to not specify any purposes, which will result in the return of an empty box.
If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.
- Parameters
time (TimeCode) –
purpose1 (str) –
purpose2 (str) –
purpose3 (str) –
purpose4 (str) –
- ComputeLocalToWorldTransform(time) Matrix4d
Compute the transformation matrix for this prim at the given time, including the transform authored on the Prim itself, if present.
If you need to compute the transform for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomXformCache and query it directly; doing so will reuse sub- computations shared by the prims.
- Parameters
time (TimeCode) –
- ComputeParentToWorldTransform(time) Matrix4d
Compute the transformation matrix for this prim at the given time, NOT including the transform authored on the prim itself.
If you need to compute the transform for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomXformCache and query it directly; doing so will reuse sub- computations shared by the prims.
- Parameters
time (TimeCode) –
- ComputeProxyPrim()
Returns None if neither this prim nor any of its ancestors has a valid renderProxy prim. Otherwise, returns a tuple of (proxyPrim, renderPrimWithAuthoredProxyPrimRel)
- ComputePurpose() str
Calculate the effective purpose information about this prim.
This is equivalent to extracting the purpose from the value returned by ComputePurposeInfo() .
This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub- problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage purpose, along with visibility, on a stack as you traverse.
GetPurposeAttr() , Imageable Purpose
- ComputePurposeInfo() PurposeInfo
Calculate the effective purpose information about this prim which includes final computed purpose value of the prim as well as whether the purpose value should be inherited by namespace children without their own purpose opinions.
This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub- problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage purpose, along with visibility, on a stack as you traverse.
GetPurposeAttr() , Imageable Purpose
ComputePurposeInfo(parentPurposeInfo) -> PurposeInfo
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculates the effective purpose information about this prim, given the computed purpose information of its parent prim.
This can be much more efficient than using CommputePurposeInfo() when PurposeInfo values are properly computed and cached for a hierarchy of prims using this function.
GetPurposeAttr() , Imageable Purpose
- Parameters
parentPurposeInfo (PurposeInfo) –
- ComputeUntransformedBound(time, purpose1, purpose2, purpose3, purpose4) BBox3d
Compute the untransformed bound of this prim, at the specified
time
, and for the specified purposes.The bound of the prim is computed in its object space, ignoring any transforms authored on or above the prim.
It is an error to not specify any purposes, which will result in the return of an empty box.
If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.
- Parameters
time (TimeCode) –
purpose1 (str) –
purpose2 (str) –
purpose3 (str) –
purpose4 (str) –
- ComputeVisibility(time) str
Calculate the effective visibility of this prim, as defined by its most ancestral authored”invisible”opinion, if any.
A prim is considered visible at the current
time
if none of its Imageable ancestors express an authored”invisible”opinion, which is what leads to the”simple pruning”behavior described in GetVisibilityAttr() .This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub- problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage visibility on a stack as you traverse.
GetVisibilityAttr()
- Parameters
time (TimeCode) –
- ComputeWorldBound(time, purpose1, purpose2, purpose3, purpose4) BBox3d
Compute the bound of this prim in world space, at the specified
time
, and for the specified purposes.The bound of the prim is computed, including the transform (if any) authored on the node itself, and then transformed to world space.
It is an error to not specify any purposes, which will result in the return of an empty box.
If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.
- Parameters
time (TimeCode) –
purpose1 (str) –
purpose2 (str) –
purpose3 (str) –
purpose4 (str) –
- CreateProxyPrimRel() Relationship
See GetProxyPrimRel() , and also Create vs Get Property Methods for when to use Get vs Create.
- CreatePurposeAttr(defaultValue, writeSparsely) Attribute
See GetPurposeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVisibilityAttr(defaultValue, writeSparsely) Attribute
See GetVisibilityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> Imageable
Return a UsdGeomImageable holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomImageable(stage->GetPrimAtPath(path));
- static GetOrderedPurposeTokens()
classmethod GetOrderedPurposeTokens() -> list[str]
Returns an ordered list of allowed values of the purpose attribute.
The ordering is important because it defines the protocol between UsdGeomModelAPI and UsdGeomBBoxCache for caching and retrieving extents hints by purpose.
The order is: [default, render, proxy, guide]
See
UsdGeomModelAPI::GetExtentsHint() .
GetOrderedPurposeTokens()
- GetProxyPrimRel() Relationship
The proxyPrim relationship allows us to link a prim whose purpose is”render”to its (single target) purpose=”proxy”prim.
This is entirely optional, but can be useful in several scenarios:
In a pipeline that does pruning (for complexity management) by deactivating prims composed from asset references, when we deactivate a purpose=”render”prim, we will be able to discover and additionally deactivate its associated purpose=”proxy”prim, so that preview renders reflect the pruning accurately.
DCC importers may be able to make more aggressive optimizations for interactive processing and display if they can discover the proxy for a given render prim.
With a little more work, a Hydra-based application will be able to map a picked proxy prim back to its render geometry for selection.
It is only valid to author the proxyPrim relationship on prims whose purpose is”render”.
- GetPurposeAttr() Attribute
Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals.
See Imageable Purpose for more detail about how purpose is computed and used.
Declaration
uniform token purpose ="default"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
default, render, proxy, guide
- GetPurposeVisibilityAttr(purpose) Attribute
Return the attribute that is used for expressing visibility opinions for the given
purpose
.For”default”purpose, return the overall visibility attribute. For”guide”,”proxy”, or”render”purpose, return guideVisibility, proxyVisibility, or renderVisibility if UsdGeomVisibilityAPI is applied to the prim. If UsdGeomvVisibiltyAPI is not applied, an empty attribute is returned for purposes other than default.
UsdGeomVisibilityAPI::Apply
UsdGeomVisibilityAPI::GetPurposeVisibilityAttr
- Parameters
purpose (str) –
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetVisibilityAttr() Attribute
Visibility is meant to be the simplest form of”pruning”visibility that is supported by most DCC apps.
Visibility is animatable, allowing a sub-tree of geometry to be present for some segment of a shot, and absent from others; unlike the action of deactivating geometry prims, invisible geometry is still available for inspection, for positioning, for defining volumes, etc.
Declaration
token visibility ="inherited"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Allowed Values
inherited, invisible
- MakeInvisible(time) None
Makes the imageable invisible if it is visible at the given time.
When visibility is animated, this only works when it is invoked sequentially at increasing time samples. If visibility is already authored and animated in the scene, calling MakeVisible() at an arbitrary (in-between) frame isn’t guaranteed to work.
Be sure to set the edit target to the layer containing the strongest visibility opinion or to a stronger layer.
MakeVisible()
ComputeVisibility()
- Parameters
time (TimeCode) –
- MakeVisible(time) None
Make the imageable visible if it is invisible at the given time.
Since visibility is pruning, this may need to override some ancestor’s visibility and all-but-one of the ancestor’s children’s visibility, for all the ancestors of this prim up to the highest ancestor that is explicitly invisible, to preserve the visibility state.
If MakeVisible() (or MakeInvisible() ) is going to be applied to all the prims on a stage, ancestors must be processed prior to descendants to get the correct behavior.
When visibility is animated, this only works when it is invoked sequentially at increasing time samples. If visibility is already authored and animated in the scene, calling MakeVisible() at an arbitrary (in-between) frame isn’t guaranteed to work.
This will only work properly if all ancestor prims of the imageable are defined, as the imageable schema is only valid on defined prims.
Be sure to set the edit target to the layer containing the strongest visibility opinion or to a stronger layer.
MakeInvisible()
ComputeVisibility()
- Parameters
time (TimeCode) –
- SetProxyPrim(proxy) bool
Convenience function for authoring the renderProxy rel on this prim to target the given
proxy
prim.To facilitate authoring on sparse or unloaded stages, we do not perform any validation of this prim’s purpose or the type or purpose of the specified prim.
ComputeProxyPrim() , GetProxyPrimRel()
- Parameters
proxy (Prim) –
SetProxyPrim(proxy) -> bool
- Parameters
proxy (SchemaBase) –
- class pxr.UsdGeom.LinearUnits
Attributes:
- centimeters = 0.01
- feet = 0.3048
- inches = 0.0254
- kilometers = 1000.0
- lightYears = 9460730472580800.0
- meters = 1.0
- micrometers = 1e-06
- miles = 1609.344
- millimeters = 0.001
- nanometers = 1e-09
- yards = 0.9144
- class pxr.UsdGeom.Mesh
Encodes a mesh with optional subdivision properties and features.
As a point-based primitive, meshes are defined in terms of points that are connected into edges and faces. Many references to meshes use the term’vertex’in place of or interchangeably with’points’, while some use’vertex’to refer to the’face-vertices’that define a face. To avoid confusion, the term’vertex’is intentionally avoided in favor of’points’or’face-vertices’.
The connectivity between points, edges and faces is encoded using a common minimal topological description of the faces of the mesh. Each face is defined by a set of face-vertices using indices into the Mesh’s points array (inherited from UsdGeomPointBased) and laid out in a single linear faceVertexIndices array for efficiency. A companion faceVertexCounts array provides, for each face, the number of consecutive face-vertices in faceVertexIndices that define the face. No additional connectivity information is required or constructed, so no adjacency or neighborhood queries are available.
A key property of this mesh schema is that it encodes both subdivision surfaces and simpler polygonal meshes. This is achieved by varying the subdivisionScheme attribute, which is set to specify Catmull-Clark subdivision by default, so polygonal meshes must always be explicitly declared. The available subdivision schemes and additional subdivision features encoded in optional attributes conform to the feature set of OpenSubdiv ( https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html).
A Note About Primvars
The following list clarifies the number of elements for and the interpolation behavior of the different primvar interpolation types for meshes:
constant : One element for the entire mesh; no interpolation.
uniform : One element for each face of the mesh; elements are typically not interpolated but are inherited by other faces derived from a given face (via subdivision, tessellation, etc.).
varying : One element for each point of the mesh; interpolation of point data is always linear.
vertex : One element for each point of the mesh; interpolation of point data is applied according to the subdivisionScheme attribute.
faceVarying : One element for each of the face-vertices that define the mesh topology; interpolation of face-vertex data may be smooth or linear, according to the subdivisionScheme and faceVaryingLinearInterpolation attributes.
Primvar interpolation types and related utilities are described more generally in Interpolation of Geometric Primitive Variables.
A Note About Normals
Normals should not be authored on a subdivision mesh, since subdivision algorithms define their own normals. They should only be authored for polygonal meshes ( subdivisionScheme =”none”).
The normals attribute inherited from UsdGeomPointBased is not a generic primvar, but the number of elements in this attribute will be determined by its interpolation. See UsdGeomPointBased::GetNormalsInterpolation() . If normals and primvars:normals are both specified, the latter has precedence. If a polygonal mesh specifies neither normals nor primvars:normals, then it should be treated and rendered as faceted, with no attempt to compute smooth normals.
The normals generated for smooth subdivision schemes, e.g. Catmull- Clark and Loop, will likewise be smooth, but others, e.g. Bilinear, may be discontinuous between faces and/or within non-planar irregular faces.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateCornerIndicesAttr
(defaultValue, ...)See GetCornerIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateCornerSharpnessesAttr
(defaultValue, ...)See GetCornerSharpnessesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateCreaseIndicesAttr
(defaultValue, ...)See GetCreaseIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateCreaseLengthsAttr
(defaultValue, ...)See GetCreaseLengthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateCreaseSharpnessesAttr
(defaultValue, ...)See GetCreaseSharpnessesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetFaceVaryingLinearInterpolationAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFaceVertexCountsAttr
(defaultValue, ...)See GetFaceVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFaceVertexIndicesAttr
(defaultValue, ...)See GetFaceVertexIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateHoleIndicesAttr
(defaultValue, ...)See GetHoleIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateInterpolateBoundaryAttr
(defaultValue, ...)See GetInterpolateBoundaryAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateSubdivisionSchemeAttr
(defaultValue, ...)See GetSubdivisionSchemeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetTriangleSubdivisionRuleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Mesh
classmethod Get(stage, path) -> Mesh
The indices of points for which a corresponding sharpness value is specified in cornerSharpnesses (so the size of this array must match that of cornerSharpnesses).
The sharpness values associated with a corresponding set of points specified in cornerIndices (so the size of this array must match that of cornerIndices).
The indices of points grouped into sets of successive pairs that identify edges to be creased.
The length of this array specifies the number of creases (sets of adjacent sharpened edges) on the mesh.
The per-crease or per-edge sharpness values for all creases.
GetFaceCount
(timeCode)Returns the number of faces as defined by the size of the faceVertexCounts array at timeCode.
Specifies how elements of a primvar of interpolation type"faceVarying"are interpolated for subdivision surfaces.
Provides the number of vertices in each face of the mesh, which is also the number of consecutive indices in faceVertexIndices that define the face.
Flat list of the index (into the points attribute) of each vertex of each face in the mesh.
The indices of all faces that should be treated as holes, i.e.
Specifies how subdivision is applied for faces adjacent to boundary edges and boundary points.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
The subdivision scheme to be applied to the surface.
Specifies an option to the subdivision rules for the Catmull-Clark scheme to try and improve undesirable artifacts when subdividing triangles.
classmethod ValidateTopology(faceVertexIndices, faceVertexCounts, numPoints, reason) -> bool
Attributes:
- CreateCornerIndicesAttr(defaultValue, writeSparsely) Attribute
See GetCornerIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateCornerSharpnessesAttr(defaultValue, writeSparsely) Attribute
See GetCornerSharpnessesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateCreaseIndicesAttr(defaultValue, writeSparsely) Attribute
See GetCreaseIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateCreaseLengthsAttr(defaultValue, writeSparsely) Attribute
See GetCreaseLengthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateCreaseSharpnessesAttr(defaultValue, writeSparsely) Attribute
See GetCreaseSharpnessesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFaceVaryingLinearInterpolationAttr(defaultValue, writeSparsely) Attribute
See GetFaceVaryingLinearInterpolationAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFaceVertexCountsAttr(defaultValue, writeSparsely) Attribute
See GetFaceVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFaceVertexIndicesAttr(defaultValue, writeSparsely) Attribute
See GetFaceVertexIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateHoleIndicesAttr(defaultValue, writeSparsely) Attribute
See GetHoleIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateInterpolateBoundaryAttr(defaultValue, writeSparsely) Attribute
See GetInterpolateBoundaryAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateSubdivisionSchemeAttr(defaultValue, writeSparsely) Attribute
See GetSubdivisionSchemeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTriangleSubdivisionRuleAttr(defaultValue, writeSparsely) Attribute
See GetTriangleSubdivisionRuleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Mesh
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Mesh
Return a UsdGeomMesh holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomMesh(stage->GetPrimAtPath(path));
- GetCornerIndicesAttr() Attribute
The indices of points for which a corresponding sharpness value is specified in cornerSharpnesses (so the size of this array must match that of cornerSharpnesses).
Declaration
int[] cornerIndices = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetCornerSharpnessesAttr() Attribute
The sharpness values associated with a corresponding set of points specified in cornerIndices (so the size of this array must match that of cornerIndices).
Use the constant
SHARPNESS_INFINITE
for a perfectly sharp corner.Declaration
float[] cornerSharpnesses = []
C++ Type
VtArray<float>
Usd Type
SdfValueTypeNames->FloatArray
- GetCreaseIndicesAttr() Attribute
The indices of points grouped into sets of successive pairs that identify edges to be creased.
The size of this array must be equal to the sum of all elements of the creaseLengths attribute.
Declaration
int[] creaseIndices = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetCreaseLengthsAttr() Attribute
The length of this array specifies the number of creases (sets of adjacent sharpened edges) on the mesh.
Each element gives the number of points of each crease, whose indices are successively laid out in the creaseIndices attribute. Since each crease must be at least one edge long, each element of this array must be at least two.
Declaration
int[] creaseLengths = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetCreaseSharpnessesAttr() Attribute
The per-crease or per-edge sharpness values for all creases.
Since creaseLengths encodes the number of points in each crease, the number of elements in this array will be either len(creaseLengths) or the sum over all X of (creaseLengths[X] - 1). Note that while the RI spec allows each crease to have either a single sharpness or a value per-edge, USD will encode either a single sharpness per crease on a mesh, or sharpnesses for all edges making up the creases on a mesh. Use the constant
SHARPNESS_INFINITE
for a perfectly sharp crease.Declaration
float[] creaseSharpnesses = []
C++ Type
VtArray<float>
Usd Type
SdfValueTypeNames->FloatArray
- GetFaceCount(timeCode) int
Returns the number of faces as defined by the size of the faceVertexCounts array at timeCode.
For most code, this check will be performant. When using file formats where the cost of attribute reading is high and the time sampled array will be read into memory later, it may be better to explicitly read the value once and check the size of the array directly.
GetFaceVertexCountsAttr()
- Parameters
timeCode (TimeCode) –
- GetFaceVaryingLinearInterpolationAttr() Attribute
Specifies how elements of a primvar of interpolation type”faceVarying”are interpolated for subdivision surfaces.
Interpolation can be as smooth as a”vertex”primvar or constrained to be linear at features specified by several options. Valid values correspond to choices available in OpenSubdiv:
none : No linear constraints or sharpening, smooth everywhere
cornersOnly : Sharpen corners of discontinuous boundaries only, smooth everywhere else
cornersPlus1 : The default, same as”cornersOnly”plus additional sharpening at points where three or more distinct face- varying values occur
cornersPlus2 : Same as”cornersPlus1”plus additional sharpening at points with at least one discontinuous boundary corner or only one discontinuous boundary edge (a dart)
boundaries : Piecewise linear along discontinuous boundaries, smooth interior
all : Piecewise linear everywhere
These are illustrated and described in more detail in the OpenSubdiv documentation: https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#face- varying-interpolation-rules
Declaration
token faceVaryingLinearInterpolation ="cornersPlus1"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Allowed Values
none, cornersOnly, cornersPlus1, cornersPlus2, boundaries, all
- GetFaceVertexCountsAttr() Attribute
Provides the number of vertices in each face of the mesh, which is also the number of consecutive indices in faceVertexIndices that define the face.
The length of this attribute is the number of faces in the mesh. If this attribute has more than one timeSample, the mesh is considered to be topologically varying.
Declaration
int[] faceVertexCounts
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetFaceVertexIndicesAttr() Attribute
Flat list of the index (into the points attribute) of each vertex of each face in the mesh.
If this attribute has more than one timeSample, the mesh is considered to be topologically varying.
Declaration
int[] faceVertexIndices
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetHoleIndicesAttr() Attribute
The indices of all faces that should be treated as holes, i.e.
made invisible. This is traditionally a feature of subdivision surfaces and not generally applied to polygonal meshes.
Declaration
int[] holeIndices = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetInterpolateBoundaryAttr() Attribute
Specifies how subdivision is applied for faces adjacent to boundary edges and boundary points.
Valid values correspond to choices available in OpenSubdiv:
none : No boundary interpolation is applied and boundary faces are effectively treated as holes
edgeOnly : A sequence of boundary edges defines a smooth curve to which the edges of subdivided boundary faces converge
edgeAndCorner : The default, similar to”edgeOnly”but the smooth boundary curve is made sharp at corner points
These are illustrated and described in more detail in the OpenSubdiv documentation: https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#boundary- interpolation-rules
Declaration
token interpolateBoundary ="edgeAndCorner"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Allowed Values
none, edgeOnly, edgeAndCorner
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetSubdivisionSchemeAttr() Attribute
The subdivision scheme to be applied to the surface.
Valid values are:
catmullClark : The default, Catmull-Clark subdivision; preferred for quad-dominant meshes (generalizes B-splines); interpolation of point data is smooth (non-linear)
loop : Loop subdivision; preferred for purely triangular meshes; interpolation of point data is smooth (non-linear)
bilinear : Subdivision reduces all faces to quads (topologically similar to”catmullClark”); interpolation of point data is bilinear
none : No subdivision, i.e. a simple polygonal mesh; interpolation of point data is linear
Polygonal meshes are typically lighter weight and faster to render, depending on renderer and render mode. Use of”bilinear”will produce a similar shape to a polygonal mesh and may offer additional guarantees of watertightness and additional subdivision features (e.g. holes) but may also not respect authored normals.
Declaration
uniform token subdivisionScheme ="catmullClark"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
catmullClark, loop, bilinear, none
- GetTriangleSubdivisionRuleAttr() Attribute
Specifies an option to the subdivision rules for the Catmull-Clark scheme to try and improve undesirable artifacts when subdividing triangles.
Valid values are”catmullClark”for the standard rules (the default) and”smooth”for the improvement.
See https://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html#triangle- subdivision-rule
Declaration
token triangleSubdivisionRule ="catmullClark"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Allowed Values
catmullClark, smooth
- static ValidateTopology()
classmethod ValidateTopology(faceVertexIndices, faceVertexCounts, numPoints, reason) -> bool
Validate the topology of a mesh.
This validates that the sum of
faceVertexCounts
is equal to the size of thefaceVertexIndices
array, and that all face vertex indices in thefaceVertexIndices
array are in the range [0, numPoints). Returns true if the topology is valid, or false otherwise. If the topology is invalid andreason
is non-null, an error message describing the validation error will be set.
- SHARPNESS_INFINITE = 10.0
- class pxr.UsdGeom.ModelAPI
UsdGeomModelAPI extends the generic UsdModelAPI schema with geometry specific concepts such as cached extents for the entire model, constraint targets, and geometry-inspired extensions to the payload lofting process.
As described in GetExtentsHint() below, it is useful to cache extents at the model level. UsdGeomModelAPI provides schema for computing and storing these cached extents, which can be consumed by UsdGeomBBoxCache to provide fast access to precomputed extents that will be used as the model’s bounds ( see UsdGeomBBoxCache::UsdGeomBBoxCache() ).
Draw Modes
Draw modes provide optional alternate imaging behavior for USD subtrees with kind model. model:drawMode (which is inheritable) and model:applyDrawMode (which is not) are resolved into a decision to stop traversing the scene graph at a certain point, and replace a USD subtree with proxy geometry.
The value of model:drawMode determines the type of proxy geometry:
origin - Draw the model-space basis vectors of the replaced prim.
bounds - Draw the model-space bounding box of the replaced prim.
cards - Draw textured quads as a placeholder for the replaced prim.
default - An explicit opinion to draw the USD subtree as normal.
inherited - Defer to the parent opinion.
model:drawMode falls back to inherited so that a whole scene, a large group, or all prototypes of a model hierarchy PointInstancer can be assigned a draw mode with a single attribute edit. If no draw mode is explicitly set in a hierarchy, the resolved value is default.
model:applyDrawMode is meant to be written when an asset is authored, and provides flexibility for different asset types. For example, a character assembly (composed of character, clothes, etc) might have model:applyDrawMode set at the top of the subtree so the whole group can be drawn as a single card object. An effects subtree might have model:applyDrawMode set at a lower level so each particle group draws individually.
Models of kind component are treated as if model:applyDrawMode were true. This means a prim is drawn with proxy geometry when: the prim has kind component, and/or model:applyDrawMode is set; and the prim’s resolved value for model:drawMode is not default.
Cards Geometry
The specific geometry used in cards mode is controlled by the model:cardGeometry attribute:
cross - Generate a quad normal to each basis direction and negative. Locate each quad so that it bisects the model extents.
box - Generate a quad normal to each basis direction and negative. Locate each quad on a face of the model extents, facing out.
fromTexture - Generate a quad for each supplied texture from attributes stored in that texture’s metadata.
For cross and box mode, the extents are calculated for purposes default, proxy, and render, at their earliest authored time. If the model has no textures, all six card faces are rendered using model:drawModeColor. If one or more textures are present, only axes with one or more textures assigned are drawn. For each axis, if both textures (positive and negative) are specified, they’ll be used on the corresponding card faces; if only one texture is specified, it will be mapped to the opposite card face after being flipped on the texture’s s-axis. Any card faces with invalid asset paths will be drawn with model:drawModeColor.
Both model:cardGeometry and model:drawModeColor should be authored on the prim where the draw mode takes effect, since these attributes are not inherited.
For fromTexture mode, only card faces with valid textures assigned are drawn. The geometry is generated by pulling the worldtoscreen attribute out of texture metadata. This is expected to be a 4x4 matrix mapping the model-space position of the card quad to the clip-space quad with corners (-1,-1,0) and (1,1,0). The card vertices are generated by transforming the clip-space corners by the inverse of worldtoscreen. Textures are mapped so that (s) and (t) map to (+x) and (+y) in clip space. If the metadata cannot be read in the right format, or the matrix can’t be inverted, the card face is not drawn.
All card faces are drawn and textured as single-sided.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
classmethod Apply(prim) -> ModelAPI
classmethod CanApply(prim, whyNot) -> bool
ComputeExtentsHint
(bboxCache)For the given model, compute the value for the extents hint with the given
bboxCache
.ComputeModelDrawMode
(parentDrawMode)Calculate the effective model:drawMode of this prim.
CreateConstraintTarget
(constraintName)Creates a new constraint target with the given name,
constraintName
.CreateModelApplyDrawModeAttr
(defaultValue, ...)See GetModelApplyDrawModeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardGeometryAttr
(defaultValue, ...)See GetModelCardGeometryAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureXNegAttr
(defaultValue, ...)See GetModelCardTextureXNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureXPosAttr
(defaultValue, ...)See GetModelCardTextureXPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureYNegAttr
(defaultValue, ...)See GetModelCardTextureYNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureYPosAttr
(defaultValue, ...)See GetModelCardTextureYPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureZNegAttr
(defaultValue, ...)See GetModelCardTextureZNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelCardTextureZPosAttr
(defaultValue, ...)See GetModelCardTextureZPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelDrawModeAttr
(defaultValue, ...)See GetModelDrawModeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateModelDrawModeColorAttr
(defaultValue, ...)See GetModelDrawModeColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> ModelAPI
GetConstraintTarget
(constraintName)Get the constraint target with the given name,
constraintName
.Returns all the constraint targets belonging to the model.
GetExtentsHint
(extents, time)Retrieve the authored value (if any) of this model's"extentsHint".
Returns the custom'extentsHint'attribute if it exits.
If true, and the resolved value of model:drawMode is non-default, apply an alternate imaging mode to this prim.
The geometry to generate for imaging prims inserted for cards imaging mode.
In cards imaging mode, the texture applied to the X- quad.
In cards imaging mode, the texture applied to the X+ quad.
In cards imaging mode, the texture applied to the Y- quad.
In cards imaging mode, the texture applied to the Y+ quad.
In cards imaging mode, the texture applied to the Z- quad.
In cards imaging mode, the texture applied to the Z+ quad.
Alternate imaging mode; applied to this prim or child prims where model:applyDrawMode is true, or where the prim has kind component.
The base color of imaging prims inserted for alternate imaging modes.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
SetExtentsHint
(extents, time)Authors the extentsHint array for this model at the given time.
- static Apply()
classmethod Apply(prim) -> ModelAPI
Applies this single-apply API schema to the given
prim
.This information is stored by adding”GeomModelAPI”to the token-valued, listOp metadata apiSchemas on the prim.
A valid UsdGeomModelAPI object is returned upon success. An invalid (or empty) UsdGeomModelAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()
- Parameters
prim (Prim) –
- static CanApply()
classmethod CanApply(prim, whyNot) -> bool
Returns true if this single-apply API schema can be applied to the given
prim
.If this schema can not be a applied to the prim, this returns false and, if provided, populates
whyNot
with the reason it can not be applied.Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()
- Parameters
prim (Prim) –
whyNot (str) –
- ComputeExtentsHint(bboxCache) Vec3fArray
For the given model, compute the value for the extents hint with the given
bboxCache
.bboxCache
should be setup with the appropriate time. After calling this function, thebboxCache
may have it’s included purposes changed.bboxCache
should not be in use by any other thread while this method is using it in a thread.- Parameters
bboxCache (BBoxCache) –
- ComputeModelDrawMode(parentDrawMode) str
Calculate the effective model:drawMode of this prim.
If the draw mode is authored on this prim, it’s used. Otherwise, the fallback value is”inherited”, which defers to the parent opinion. The first non-inherited opinion found walking from this prim towards the root is used. If the attribute isn’t set on any ancestors, we return”default”(meaning, disable”drawMode”geometry).
If this function is being called in a traversal context to compute the draw mode of an entire hierarchy of prims, it would be beneficial to cache and pass in the computed parent draw-mode via the
parentDrawMode
parameter. This avoids repeated upward traversal to look for ancestor opinions.When
parentDrawMode
is empty (or unspecified), this function does an upward traversal to find the closest ancestor with an authored model:drawMode.GetModelDrawModeAttr()
- Parameters
parentDrawMode (str) –
- CreateConstraintTarget(constraintName) ConstraintTarget
Creates a new constraint target with the given name,
constraintName
.If the constraint target already exists, then the existing target is returned. If it does not exist, a new one is created and returned.
- Parameters
constraintName (str) –
- CreateModelApplyDrawModeAttr(defaultValue, writeSparsely) Attribute
See GetModelApplyDrawModeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardGeometryAttr(defaultValue, writeSparsely) Attribute
See GetModelCardGeometryAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureXNegAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureXNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureXPosAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureXPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureYNegAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureYNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureYPosAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureYPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureZNegAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureZNegAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelCardTextureZPosAttr(defaultValue, writeSparsely) Attribute
See GetModelCardTextureZPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelDrawModeAttr(defaultValue, writeSparsely) Attribute
See GetModelDrawModeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateModelDrawModeColorAttr(defaultValue, writeSparsely) Attribute
See GetModelDrawModeColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> ModelAPI
Return a UsdGeomModelAPI holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomModelAPI(stage->GetPrimAtPath(path));
- GetConstraintTarget(constraintName) ConstraintTarget
Get the constraint target with the given name,
constraintName
.If the requested constraint target does not exist, then an invalid UsdConstraintTarget object is returned.
- Parameters
constraintName (str) –
- GetConstraintTargets() list[ConstraintTarget]
Returns all the constraint targets belonging to the model.
Only valid constraint targets in the”constraintTargets”namespace are returned by this method.
- GetExtentsHint(extents, time) bool
Retrieve the authored value (if any) of this model’s”extentsHint”.
Persistent caching of bounds in USD is a potentially perilous endeavor, given that:
It is very easy to add overrides in new super-layers that invalidate the cached bounds, and no practical way to automatically detect when this happens
It is possible for references to be allowed to”float”, so that asset updates can flow directly into cached scenes. Such changes in referenced scene description can also invalidate cached bounds in referencing layers. For these reasons, as a general rule, we only persistently cache leaf gprim extents in object space. However, even with cached gprim extents, computing bounds can be expensive. Since model-level bounds are so useful to many graphics applications, we make an exception, with some caveats. The”extentsHint”should be considered entirely optional (whereas gprim extent is not); if authored, it should contains the extents for various values of gprim purposes. The extents for different values of purpose are stored in a linear Vec3f array as pairs of GfVec3f values in the order specified by UsdGeomImageable::GetOrderedPurposeTokens() . This list is trimmed to only include non-empty extents. i.e., if a model has only default and render geoms, then it will only have 4 GfVec3f values in its extentsHint array. We do not skip over zero extents, so if a model has only default and proxy geom, we will author six GfVec3f ‘s, the middle two representing an zero extent for render geometry.
A UsdGeomBBoxCache can be configured to first consult the cached extents when evaluating model roots, rather than descending into the models for the full computation. This is not the default behavior, and gives us a convenient way to validate that the cached extentsHint is still valid.
true
if a value was fetched;false
if no value was authored, or on error. It is an error to make this query of a prim that is not a model root.UsdGeomImageable::GetPurposeAttr() , UsdGeomImageable::GetOrderedPurposeTokens()
- Parameters
extents (Vec3fArray) –
time (TimeCode) –
- GetModelApplyDrawModeAttr() Attribute
If true, and the resolved value of model:drawMode is non-default, apply an alternate imaging mode to this prim.
See Draw Modes.
Declaration
uniform bool model:applyDrawMode = 0
C++ Type
bool
Usd Type
SdfValueTypeNames->Bool
Variability
SdfVariabilityUniform
- GetModelCardGeometryAttr() Attribute
The geometry to generate for imaging prims inserted for cards imaging mode.
See Cards Geometry for geometry descriptions.
Declaration
uniform token model:cardGeometry ="cross"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
cross, box, fromTexture
- GetModelCardTextureXNegAttr() Attribute
In cards imaging mode, the texture applied to the X- quad.
The texture axes (s,t) are mapped to model-space axes (y, -z).
Declaration
asset model:cardTextureXNeg
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelCardTextureXPosAttr() Attribute
In cards imaging mode, the texture applied to the X+ quad.
The texture axes (s,t) are mapped to model-space axes (-y, -z).
Declaration
asset model:cardTextureXPos
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelCardTextureYNegAttr() Attribute
In cards imaging mode, the texture applied to the Y- quad.
The texture axes (s,t) are mapped to model-space axes (-x, -z).
Declaration
asset model:cardTextureYNeg
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelCardTextureYPosAttr() Attribute
In cards imaging mode, the texture applied to the Y+ quad.
The texture axes (s,t) are mapped to model-space axes (x, -z).
Declaration
asset model:cardTextureYPos
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelCardTextureZNegAttr() Attribute
In cards imaging mode, the texture applied to the Z- quad.
The texture axes (s,t) are mapped to model-space axes (-x, -y).
Declaration
asset model:cardTextureZNeg
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelCardTextureZPosAttr() Attribute
In cards imaging mode, the texture applied to the Z+ quad.
The texture axes (s,t) are mapped to model-space axes (x, -y).
Declaration
asset model:cardTextureZPos
C++ Type
SdfAssetPath
Usd Type
SdfValueTypeNames->Asset
- GetModelDrawModeAttr() Attribute
Alternate imaging mode; applied to this prim or child prims where model:applyDrawMode is true, or where the prim has kind component.
See Draw Modes for mode descriptions.
Declaration
uniform token model:drawMode ="inherited"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
origin, bounds, cards, default, inherited
- GetModelDrawModeColorAttr() Attribute
The base color of imaging prims inserted for alternate imaging modes.
For origin and bounds modes, this controls line color; for cards mode, this controls the fallback quad color.
Declaration
uniform float3 model:drawModeColor = (0.18, 0.18, 0.18)
C++ Type
GfVec3f
Usd Type
SdfValueTypeNames->Float3
Variability
SdfVariabilityUniform
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- SetExtentsHint(extents, time) bool
Authors the extentsHint array for this model at the given time.
GetExtentsHint()
- Parameters
extents (Vec3fArray) –
time (TimeCode) –
- class pxr.UsdGeom.MotionAPI
UsdGeomMotionAPI encodes data that can live on any prim that may affect computations involving:
computed motion for motion blur
sampling for motion blur
The motion:blurScale attribute allows artists to scale the amount of motion blur to be rendered for parts of the scene without changing the recorded animation. See Effectively Applying motion:blurScale for use and implementation details.
Methods:
classmethod Apply(prim) -> MotionAPI
classmethod CanApply(prim, whyNot) -> bool
ComputeMotionBlurScale
(time)Compute the inherited value of motion:blurScale at
time
, i.e.Compute the inherited value of nonlinearSampleCount at
time
, i.e.ComputeVelocityScale
(time)Deprecated
CreateMotionBlurScaleAttr
(defaultValue, ...)See GetMotionBlurScaleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateNonlinearSampleCountAttr
(defaultValue, ...)See GetNonlinearSampleCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVelocityScaleAttr
(defaultValue, ...)See GetVelocityScaleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> MotionAPI
BlurScale is an inherited float attribute that stipulates the rendered motion blur (as typically specified via UsdGeomCamera 's shutter:open and shutter:close properties) should be scaled for all objects at and beneath the prim in namespace on which the motion:blurScale value is specified.
Determines the number of position or transformation samples created when motion is described by attributes contributing non-linear terms.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Deprecated
- static Apply()
classmethod Apply(prim) -> MotionAPI
Applies this single-apply API schema to the given
prim
.This information is stored by adding”MotionAPI”to the token-valued, listOp metadata apiSchemas on the prim.
A valid UsdGeomMotionAPI object is returned upon success. An invalid (or empty) UsdGeomMotionAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()
- Parameters
prim (Prim) –
- static CanApply()
classmethod CanApply(prim, whyNot) -> bool
Returns true if this single-apply API schema can be applied to the given
prim
.If this schema can not be a applied to the prim, this returns false and, if provided, populates
whyNot
with the reason it can not be applied.Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()
- Parameters
prim (Prim) –
whyNot (str) –
- ComputeMotionBlurScale(time) float
Compute the inherited value of motion:blurScale at
time
, i.e.the authored value on the prim closest to this prim in namespace, resolved upwards through its ancestors in namespace.
the inherited value, or 1.0 if neither the prim nor any of its ancestors possesses an authored value.
this is a reference implementation that is not particularly efficient if evaluating over many prims, because it does not share inherited results.
- Parameters
time (TimeCode) –
- ComputeNonlinearSampleCount(time) int
Compute the inherited value of nonlinearSampleCount at
time
, i.e.the authored value on the prim closest to this prim in namespace, resolved upwards through its ancestors in namespace.
the inherited value, or 3 if neither the prim nor any of its ancestors possesses an authored value.
this is a reference implementation that is not particularly efficient if evaluating over many prims, because it does not share inherited results.
- Parameters
time (TimeCode) –
- ComputeVelocityScale(time) float
Deprecated
Compute the inherited value of velocityScale at
time
, i.e. the authored value on the prim closest to this prim in namespace, resolved upwards through its ancestors in namespace.the inherited value, or 1.0 if neither the prim nor any of its ancestors possesses an authored value.
this is a reference implementation that is not particularly efficient if evaluating over many prims, because it does not share inherited results.
- Parameters
time (TimeCode) –
- CreateMotionBlurScaleAttr(defaultValue, writeSparsely) Attribute
See GetMotionBlurScaleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateNonlinearSampleCountAttr(defaultValue, writeSparsely) Attribute
See GetNonlinearSampleCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVelocityScaleAttr(defaultValue, writeSparsely) Attribute
See GetVelocityScaleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> MotionAPI
Return a UsdGeomMotionAPI holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomMotionAPI(stage->GetPrimAtPath(path));
- GetMotionBlurScaleAttr() Attribute
BlurScale is an inherited float attribute that stipulates the rendered motion blur (as typically specified via UsdGeomCamera ‘s shutter:open and shutter:close properties) should be scaled for all objects at and beneath the prim in namespace on which the motion:blurScale value is specified.
Without changing any other data in the scene, blurScale allows artists to”dial in”the amount of blur on a per-object basis. A blurScale value of zero removes all blur, a value of 0.5 reduces blur by half, and a value of 2.0 doubles the blur. The legal range for blurScale is [0, inf), although very high values may result in extremely expensive renders, and may exceed the capabilities of some renderers.
Although renderers are free to implement this feature however they see fit, see Effectively Applying motion:blurScale for our guidance on implementing the feature universally and efficiently.
ComputeMotionBlurScale()
Declaration
float motion:blurScale = 1
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- GetNonlinearSampleCountAttr() Attribute
Determines the number of position or transformation samples created when motion is described by attributes contributing non-linear terms.
To give an example, imagine an application (such as a renderer) consuming’points’and the USD document also contains’accelerations’for the same prim. Unless the application can consume these’accelerations’itself, an intermediate layer has to compute samples within the sampling interval for the point positions based on the value of’points’,’velocities’and’accelerations’. The number of these samples is given by’nonlinearSampleCount’. The samples are equally spaced within the sampling interval.
Another example involves the PointInstancer where’nonlinearSampleCount’is relevant when’angularVelocities’or’accelerations’are authored.
‘nonlinearSampleCount’is an inherited attribute, also see ComputeNonlinearSampleCount()
Declaration
int motion:nonlinearSampleCount = 3
C++ Type
int
Usd Type
SdfValueTypeNames->Int
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetVelocityScaleAttr() Attribute
Deprecated
VelocityScale is an inherited float attribute that velocity-based schemas (e.g. PointBased, PointInstancer) can consume to compute interpolated positions and orientations by applying velocity and angularVelocity, which is required for interpolating between samples when topology is varying over time. Although these quantities are generally physically computed by a simulator, sometimes we require more or less motion-blur to achieve the desired look. VelocityScale allows artists to dial-in, as a post-sim correction, a scale factor to be applied to the velocity prior to computing interpolated positions from it.
Declaration
float motion:velocityScale = 1
C++ Type
float
Usd Type
SdfValueTypeNames->Float
- class pxr.UsdGeom.NurbsCurves
This schema is analagous to NURBS Curves in packages like Maya and Houdini, often used for interchange of rigging and modeling curves. Unlike Maya, this curve spec supports batching of multiple curves into a single prim, widths, and normals in the schema. Additionally, we require’numSegments + 2 * degree + 1’knots (2 more than maya does). This is to be more consistent with RenderMan’s NURBS patch specification.
To express a periodic curve:
knot[0] = knot[1] - (knots[-2] - knots[-3];
knot[-1] = knot[-2] + (knot[2] - knots[1]);
To express a nonperiodic curve:
knot[0] = knot[1];
knot[-1] = knot[-2];
In spite of these slight differences in the spec, curves generated in Maya should be preserved when roundtripping.
order and range, when representing a batched NurbsCurve should be authored one value per curve. knots should be the concatentation of all batched curves.
NurbsCurve Form
Form is provided as an aid to interchange between modeling and animation applications so that they can robustly identify the intent with which the surface was modelled, and take measures (if they are able) to preserve the continuity/concidence constraints as the surface may be rigged or deformed.
An open-form NurbsCurve has no continuity constraints.
A closed-form NurbsCurve expects the first and last control points to overlap
A periodic-form NurbsCurve expects the first and last order - 1 control points to overlap. For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateFormAttr
(defaultValue, writeSparsely)See GetFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateKnotsAttr
(defaultValue, writeSparsely)See GetKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateOrderAttr
(defaultValue, writeSparsely)See GetOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreatePointWeightsAttr
(defaultValue, ...)See GetPointWeightsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateRangesAttr
(defaultValue, writeSparsely)See GetRangesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> NurbsCurves
classmethod Get(stage, path) -> NurbsCurves
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous curve.
Knot vector providing curve parameterization.
Order of the curve.
Optionally provides"w"components for each control point, thus must be the same length as the points attribute.
Provides the minimum and maximum parametric values (as defined by knots) over which the curve is actually defined.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateFormAttr(defaultValue, writeSparsely) Attribute
See GetFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateKnotsAttr(defaultValue, writeSparsely) Attribute
See GetKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateOrderAttr(defaultValue, writeSparsely) Attribute
See GetOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreatePointWeightsAttr(defaultValue, writeSparsely) Attribute
See GetPointWeightsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateRangesAttr(defaultValue, writeSparsely) Attribute
See GetRangesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> NurbsCurves
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> NurbsCurves
Return a UsdGeomNurbsCurves holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomNurbsCurves(stage->GetPrimAtPath(path));
- GetFormAttr() Attribute
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous curve.
NurbsCurve Form
Declaration
uniform token form ="open"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
open, closed, periodic
- GetKnotsAttr() Attribute
Knot vector providing curve parameterization.
The length of the slice of the array for the ith curve must be ( curveVertexCount[i] + order[i] ), and its entries must take on monotonically increasing values.
Declaration
double[] knots
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- GetOrderAttr() Attribute
Order of the curve.
Order must be positive and is equal to the degree of the polynomial basis to be evaluated, plus 1. Its value for the’i’th curve must be less than or equal to curveVertexCount[i]
Declaration
int[] order = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetPointWeightsAttr() Attribute
Optionally provides”w”components for each control point, thus must be the same length as the points attribute.
If authored, the patch will be rational. If unauthored, the patch will be polynomial, i.e. weight for all points is 1.0.
Some DCC’s pre-weight the points, but in this schema, points are not pre-weighted.
Declaration
double[] pointWeights
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- GetRangesAttr() Attribute
Provides the minimum and maximum parametric values (as defined by knots) over which the curve is actually defined.
The minimum must be less than the maximum, and greater than or equal to the value of the knots[‘i’th curve slice][order[i]-1]. The maxium must be less than or equal to the last element’s value in knots[‘i’th curve slice]. Range maps to (vmin, vmax) in the RenderMan spec.
Declaration
double2[] ranges
C++ Type
VtArray<GfVec2d>
Usd Type
SdfValueTypeNames->Double2Array
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.NurbsPatch
Encodes a rational or polynomial non-uniform B-spline surface, with optional trim curves.
The encoding mostly follows that of RiNuPatch and RiTrimCurve: https://renderman.pixar.com/resources/current/RenderMan/geometricPrimitives.html#rinupatch, with some minor renaming and coalescing for clarity.
The layout of control vertices in the points attribute inherited from UsdGeomPointBased is row-major with U considered rows, and V columns.
NurbsPatch Form
The authored points, orders, knots, weights, and ranges are all that is required to render the nurbs patch. However, the only way to model closed surfaces with nurbs is to ensure that the first and last control points along the given axis are coincident. Similarly, to ensure the surface is not only closed but also C2 continuous, the last order - 1 control points must be (correspondingly) coincident with the first order - 1 control points, and also the spacing of the last corresponding knots must be the same as the first corresponding knots.
Form is provided as an aid to interchange between modeling and animation applications so that they can robustly identify the intent with which the surface was modelled, and take measures (if they are able) to preserve the continuity/concidence constraints as the surface may be rigged or deformed.
An open-form NurbsPatch has no continuity constraints.
A closed-form NurbsPatch expects the first and last control points to overlap
A periodic-form NurbsPatch expects the first and last order - 1 control points to overlap. Nurbs vs Subdivision Surfaces
Nurbs are an important modeling primitive in CAD/CAM tools and early computer graphics DCC’s. Because they have a natural UV parameterization they easily support”trim curves”, which allow smooth shapes to be carved out of the surface.
However, the topology of the patch is always rectangular, and joining two nurbs patches together (especially when they have differing numbers of spans) is difficult to do smoothly. Also, nurbs are not supported by the Ptex texturing technology ( http://ptex.us).
Neither of these limitations are shared by subdivision surfaces; therefore, although they do not subscribe to trim-curve-based shaping, subdivs are often considered a more flexible modeling primitive.
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreatePointWeightsAttr
(defaultValue, ...)See GetPointWeightsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTrimCurveCountsAttr
(defaultValue, ...)See GetTrimCurveCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTrimCurveKnotsAttr
(defaultValue, ...)See GetTrimCurveKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTrimCurveOrdersAttr
(defaultValue, ...)See GetTrimCurveOrdersAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTrimCurvePointsAttr
(defaultValue, ...)See GetTrimCurvePointsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateTrimCurveRangesAttr
(defaultValue, ...)See GetTrimCurveRangesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetTrimCurveVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateUFormAttr
(defaultValue, writeSparsely)See GetUFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateUKnotsAttr
(defaultValue, writeSparsely)See GetUKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateUOrderAttr
(defaultValue, writeSparsely)See GetUOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateURangeAttr
(defaultValue, writeSparsely)See GetURangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateUVertexCountAttr
(defaultValue, ...)See GetUVertexCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVFormAttr
(defaultValue, writeSparsely)See GetVFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVKnotsAttr
(defaultValue, writeSparsely)See GetVKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVOrderAttr
(defaultValue, writeSparsely)See GetVOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVRangeAttr
(defaultValue, writeSparsely)See GetVRangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVVertexCountAttr
(defaultValue, ...)See GetVVertexCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> NurbsPatch
classmethod Get(stage, path) -> NurbsPatch
Optionally provides"w"components for each control point, thus must be the same length as the points attribute.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Each element specifies how many curves are present in each"loop"of the trimCurve, and the length of the array determines how many loops the trimCurve contains.
Flat list of parametric values for each of the nCurves curves.
Flat list of orders for each of the nCurves curves.
Flat list of homogeneous 2D points (u, v, w) that comprise the nCurves curves.
Flat list of minimum and maximum parametric values (as defined by knots) for each of the nCurves curves.
Flat list of number of vertices for each of the nCurves curves.
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the U dimension.
Knot vector for U direction providing U parameterization.
Order in the U direction.
Provides the minimum and maximum parametric values (as defined by uKnots) over which the surface is actually defined.
Number of vertices in the U direction.
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the V dimension.
Knot vector for V direction providing U parameterization.
Order in the V direction.
Provides the minimum and maximum parametric values (as defined by vKnots) over which the surface is actually defined.
Number of vertices in the V direction.
- CreatePointWeightsAttr(defaultValue, writeSparsely) Attribute
See GetPointWeightsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurveCountsAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurveCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurveKnotsAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurveKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurveOrdersAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurveOrdersAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurvePointsAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurvePointsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurveRangesAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurveRangesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateTrimCurveVertexCountsAttr(defaultValue, writeSparsely) Attribute
See GetTrimCurveVertexCountsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateUFormAttr(defaultValue, writeSparsely) Attribute
See GetUFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateUKnotsAttr(defaultValue, writeSparsely) Attribute
See GetUKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateUOrderAttr(defaultValue, writeSparsely) Attribute
See GetUOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateURangeAttr(defaultValue, writeSparsely) Attribute
See GetURangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateUVertexCountAttr(defaultValue, writeSparsely) Attribute
See GetUVertexCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVFormAttr(defaultValue, writeSparsely) Attribute
See GetVFormAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVKnotsAttr(defaultValue, writeSparsely) Attribute
See GetVKnotsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVOrderAttr(defaultValue, writeSparsely) Attribute
See GetVOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVRangeAttr(defaultValue, writeSparsely) Attribute
See GetVRangeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVVertexCountAttr(defaultValue, writeSparsely) Attribute
See GetVVertexCountAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> NurbsPatch
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> NurbsPatch
Return a UsdGeomNurbsPatch holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomNurbsPatch(stage->GetPrimAtPath(path));
- GetPointWeightsAttr() Attribute
Optionally provides”w”components for each control point, thus must be the same length as the points attribute.
If authored, the patch will be rational. If unauthored, the patch will be polynomial, i.e. weight for all points is 1.0.
Some DCC’s pre-weight the points, but in this schema, points are not pre-weighted.
Declaration
double[] pointWeights
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetTrimCurveCountsAttr() Attribute
Each element specifies how many curves are present in each”loop”of the trimCurve, and the length of the array determines how many loops the trimCurve contains.
The sum of all elements is the total nuber of curves in the trim, to which we will refer as nCurves in describing the other trim attributes.
Declaration
int[] trimCurve:counts
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetTrimCurveKnotsAttr() Attribute
Flat list of parametric values for each of the nCurves curves.
There will be as many knots as the sum over all elements of vertexCounts plus the sum over all elements of orders.
Declaration
double[] trimCurve:knots
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- GetTrimCurveOrdersAttr() Attribute
Flat list of orders for each of the nCurves curves.
Declaration
int[] trimCurve:orders
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetTrimCurvePointsAttr() Attribute
Flat list of homogeneous 2D points (u, v, w) that comprise the nCurves curves.
The number of points should be equal to the um over all elements of vertexCounts.
Declaration
double3[] trimCurve:points
C++ Type
VtArray<GfVec3d>
Usd Type
SdfValueTypeNames->Double3Array
- GetTrimCurveRangesAttr() Attribute
Flat list of minimum and maximum parametric values (as defined by knots) for each of the nCurves curves.
Declaration
double2[] trimCurve:ranges
C++ Type
VtArray<GfVec2d>
Usd Type
SdfValueTypeNames->Double2Array
- GetTrimCurveVertexCountsAttr() Attribute
Flat list of number of vertices for each of the nCurves curves.
Declaration
int[] trimCurve:vertexCounts
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetUFormAttr() Attribute
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the U dimension.
NurbsPatch Form
Declaration
uniform token uForm ="open"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
open, closed, periodic
- GetUKnotsAttr() Attribute
Knot vector for U direction providing U parameterization.
The length of this array must be ( uVertexCount + uOrder), and its entries must take on monotonically increasing values.
Declaration
double[] uKnots
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- GetUOrderAttr() Attribute
Order in the U direction.
Order must be positive and is equal to the degree of the polynomial basis to be evaluated, plus 1.
Declaration
int uOrder
C++ Type
int
Usd Type
SdfValueTypeNames->Int
- GetURangeAttr() Attribute
Provides the minimum and maximum parametric values (as defined by uKnots) over which the surface is actually defined.
The minimum must be less than the maximum, and greater than or equal to the value of uKnots[uOrder-1]. The maxium must be less than or equal to the last element’s value in uKnots.
Declaration
double2 uRange
C++ Type
GfVec2d
Usd Type
SdfValueTypeNames->Double2
- GetUVertexCountAttr() Attribute
Number of vertices in the U direction.
Should be at least as large as uOrder.
Declaration
int uVertexCount
C++ Type
int
Usd Type
SdfValueTypeNames->Int
- GetVFormAttr() Attribute
Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the V dimension.
NurbsPatch Form
Declaration
uniform token vForm ="open"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
open, closed, periodic
- GetVKnotsAttr() Attribute
Knot vector for V direction providing U parameterization.
The length of this array must be ( vVertexCount + vOrder), and its entries must take on monotonically increasing values.
Declaration
double[] vKnots
C++ Type
VtArray<double>
Usd Type
SdfValueTypeNames->DoubleArray
- GetVOrderAttr() Attribute
Order in the V direction.
Order must be positive and is equal to the degree of the polynomial basis to be evaluated, plus 1.
Declaration
int vOrder
C++ Type
int
Usd Type
SdfValueTypeNames->Int
- GetVRangeAttr() Attribute
Provides the minimum and maximum parametric values (as defined by vKnots) over which the surface is actually defined.
The minimum must be less than the maximum, and greater than or equal to the value of vKnots[vOrder-1]. The maxium must be less than or equal to the last element’s value in vKnots.
Declaration
double2 vRange
C++ Type
GfVec2d
Usd Type
SdfValueTypeNames->Double2
- class pxr.UsdGeom.Plane
Defines a primitive plane, centered at the origin, and is defined by a cardinal axis, width, and length. The plane is double-sided by default.
The axis of width and length are perpendicular to the plane’s axis:
axis
width
length
X
z-axis
y-axis
Y
x-axis
z-axis
Z
x-axis
y-axis
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateAxisAttr
(defaultValue, writeSparsely)See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateDoubleSidedAttr
(defaultValue, ...)See GetDoubleSidedAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateLengthAttr
(defaultValue, writeSparsely)See GetLengthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateWidthAttr
(defaultValue, writeSparsely)See GetWidthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Plane
classmethod Get(stage, path) -> Plane
The axis along which the surface of the plane is aligned.
Planes are double-sided by default.
Extent is re-defined on Plane only to provide a fallback value.
The length of the plane, which aligns to the y-axis when axis is'Z'or'X', or to the z-axis when axis is'Y'.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
The width of the plane, which aligns to the x-axis when axis is'Z'or'Y', or to the z-axis when axis is'X'.
- CreateAxisAttr(defaultValue, writeSparsely) Attribute
See GetAxisAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateDoubleSidedAttr(defaultValue, writeSparsely) Attribute
See GetDoubleSidedAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateLengthAttr(defaultValue, writeSparsely) Attribute
See GetLengthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateWidthAttr(defaultValue, writeSparsely) Attribute
See GetWidthAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Plane
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Plane
Return a UsdGeomPlane holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomPlane(stage->GetPrimAtPath(path));
- GetAxisAttr() Attribute
The axis along which the surface of the plane is aligned.
When set to’Z’the plane is in the xy-plane; when axis is’X’the plane is in the yz-plane, and when axis is’Y’the plane is in the xz-plane.
UsdGeomGprim::GetAxisAttr().
Declaration
uniform token axis ="Z"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
X, Y, Z
- GetDoubleSidedAttr() Attribute
Planes are double-sided by default.
Clients may also support single-sided planes.
UsdGeomGprim::GetDoubleSidedAttr()
Declaration
uniform bool doubleSided = 1
C++ Type
bool
Usd Type
SdfValueTypeNames->Bool
Variability
SdfVariabilityUniform
- GetExtentAttr() Attribute
Extent is re-defined on Plane only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-1, -1, 0), (1, 1, 0)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- GetLengthAttr() Attribute
The length of the plane, which aligns to the y-axis when axis is’Z’or’X’, or to the z-axis when axis is’Y’.
If you author length you must also author extent.
UsdGeomGprim::GetExtentAttr()
Declaration
double length = 2
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.PointBased
Base class for all UsdGeomGprims that possess points, providing common attributes such as normals and velocities.
Methods:
classmethod ComputeExtent(points, extent) -> bool
classmethod ComputePointsAtTime(points, time, baseTime) -> bool
ComputePointsAtTimes
(pointsArray, times, ...)Compute points as in ComputePointsAtTime, but using multiple sample times.
CreateAccelerationsAttr
(defaultValue, ...)See GetAccelerationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateNormalsAttr
(defaultValue, writeSparsely)See GetNormalsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreatePointsAttr
(defaultValue, writeSparsely)See GetPointsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVelocitiesAttr
(defaultValue, writeSparsely)See GetVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Get(stage, path) -> PointBased
If provided,'accelerations'should be used with velocities to compute positions between samples for the'points'attribute rather than interpolating between neighboring'points'samples.
Provide an object-space orientation for individual points, which, depending on subclass, may define a surface, curve, or free points.
Get the interpolation for the normals attribute.
The primary geometry attribute for all PointBased primitives, describes points in (local) space.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
If provided,'velocities'should be used by renderers to.
SetNormalsInterpolation
(interpolation)Set the interpolation for the normals attribute.
- static ComputeExtent()
classmethod ComputeExtent(points, extent) -> bool
Compute the extent for the point cloud defined by points.
true on success, false if extents was unable to be calculated. On success, extent will contain the axis-aligned bounding box of the point cloud defined by points.
This function is to provide easy authoring of extent for usd authoring tools, hence it is static and acts outside a specific prim (as in attribute based methods).
- Parameters
points (Vec3fArray) –
extent (Vec3fArray) –
ComputeExtent(points, transform, extent) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
points (Vec3fArray) –
transform (Matrix4d) –
extent (Vec3fArray) –
- ComputePointsAtTime()
classmethod ComputePointsAtTime(points, time, baseTime) -> bool
Compute points given the positions, velocities and accelerations at
time
.This will return
false
and leavepoints
untouched if:points
is Noneone of
time
andbaseTime
is numeric and the other is UsdTimeCode::Default() (they must either both be numeric or both be default)there is no authored points attribute
If there is no error, we will return
true
andpoints
will contain the computed points.points
- the out parameter for the new points. Its size will depend on the authored data. time
- UsdTimeCode at which we want to evaluate the transforms baseTime
- required for correct interpolation between samples when velocities or accelerations are present. If there are samples for positions and velocities at t1 and t2, normal value resolution would attempt to interpolate between the two samples, and if they could not be interpolated because they differ in size (common in cases where velocity is authored), will choose the sample at t1. When sampling for the purposes of motion-blur, for example, it is common, when rendering the frame at t2, to sample at [ t2-shutter/2, t2+shutter/2 ] for a shutter interval of shutter. The first sample falls between t1 and t2, but we must sample at t2 and apply velocity-based interpolation based on those samples to get a correct result. In such scenarios, one should provide a
baseTime
of t2 when querying both samples. If your application does not care about off-sample interpolation, it can supply the same value forbaseTime
that it does fortime
. WhenbaseTime
is less than or equal totime
, we will choose the lower bracketing timeSample.
ComputePointsAtTime(points, stage, time, positions, velocities, velocitiesSampleTime, accelerations, velocityScale) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Perform the point computation.
This does the same computation as the non-static ComputePointsAtTime method, but takes all data as parameters rather than accessing authored data.
points
- the out parameter for the computed points. Its size will depend on the given data. stage
- the UsdStage time
- time at which we want to evaluate the transforms positions
- array containing all current points. velocities
- array containing all velocities. This array must be either the same size as
positions
or empty. If it is empty, points are computed as if all velocities were zero in all dimensions. velocitiesSampleTime- time at which the samples from
velocities
were taken. accelerations- array containing all accelerations. This array must be either the same size as
positions
or empty. If it is empty, points are computed as if all accelerations were zero in all dimensions. velocityScale- Deprecated
- Parameters
points (VtArray[Vec3f]) –
stage (UsdStageWeak) –
time (TimeCode) –
positions (Vec3fArray) –
velocities (Vec3fArray) –
velocitiesSampleTime (TimeCode) –
accelerations (Vec3fArray) –
velocityScale (float) –
- ComputePointsAtTimes(pointsArray, times, baseTime) bool
Compute points as in ComputePointsAtTime, but using multiple sample times.
An array of vector arrays is returned where each vector array contains the points for the corresponding time in
times
.times
- A vector containing the UsdTimeCodes at which we want to sample.
- CreateAccelerationsAttr(defaultValue, writeSparsely) Attribute
See GetAccelerationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateNormalsAttr(defaultValue, writeSparsely) Attribute
See GetNormalsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreatePointsAttr(defaultValue, writeSparsely) Attribute
See GetPointsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVelocitiesAttr(defaultValue, writeSparsely) Attribute
See GetVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Get()
classmethod Get(stage, path) -> PointBased
Return a UsdGeomPointBased holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomPointBased(stage->GetPrimAtPath(path));
- GetAccelerationsAttr() Attribute
If provided,’accelerations’should be used with velocities to compute positions between samples for the’points’attribute rather than interpolating between neighboring’points’samples.
Acceleration is measured in position units per second-squared. To convert to position units per squared UsdTimeCode, divide by the square of UsdStage::GetTimeCodesPerSecond() .
Declaration
vector3f[] accelerations
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Vector3fArray
- GetNormalsAttr() Attribute
Provide an object-space orientation for individual points, which, depending on subclass, may define a surface, curve, or free points.
Note that’normals’should not be authored on any Mesh that is subdivided, since the subdivision algorithm will define its own normals.’normals’is not a generic primvar, but the number of elements in this attribute will be determined by its’interpolation’. See SetNormalsInterpolation() . If’normals’and’primvars:normals’are both specified, the latter has precedence.
Declaration
normal3f[] normals
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Normal3fArray
- GetNormalsInterpolation() str
Get the interpolation for the normals attribute.
Although’normals’is not classified as a generic UsdGeomPrimvar (and will not be included in the results of UsdGeomPrimvarsAPI::GetPrimvars() ) it does require an interpolation specification. The fallback interpolation, if left unspecified, is UsdGeomTokens->vertex, which will generally produce smooth shading on a polygonal mesh. To achieve partial or fully faceted shading of a polygonal mesh with normals, one should use UsdGeomTokens->faceVarying or UsdGeomTokens->uniform interpolation.
- GetPointsAttr() Attribute
The primary geometry attribute for all PointBased primitives, describes points in (local) space.
Declaration
point3f[] points
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Point3fArray
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetVelocitiesAttr() Attribute
If provided,’velocities’should be used by renderers to.
compute positions between samples for the’points’attribute, rather than interpolating between neighboring’points’samples. This is the only reasonable means of computing motion blur for topologically varying PointBased primitives. It follows that the length of each’velocities’sample must match the length of the corresponding’points’sample. Velocity is measured in position units per second, as per most simulation software. To convert to position units per UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond() .
See also Applying Timesampled Velocities to Geometry.
Declaration
vector3f[] velocities
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Vector3fArray
- SetNormalsInterpolation(interpolation) bool
Set the interpolation for the normals attribute.
true upon success, false if
interpolation
is not a legal value as defined by UsdGeomPrimvar::IsValidInterpolation() , or if there was a problem setting the value. No attempt is made to validate that the normals attr’s value contains the right number of elements to match its interpolation to its prim’s topology.GetNormalsInterpolation()
- Parameters
interpolation (str) –
- class pxr.UsdGeom.PointInstancer
Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters), which can be arbitrary prims/subtrees on a UsdStage.
PointInstancer is a”multi instancer”, as it allows multiple prototypes to be scattered among its”points”. We use a UsdRelationship prototypes to identify and order all of the possible prototypes, by targeting the root prim of each prototype. The ordering imparted by relationships associates a zero-based integer with each prototype, and it is these integers we use to identify the prototype of each instance, compactly, and allowing prototypes to be swapped out without needing to reauthor all of the per-instance data.
The PointInstancer schema is designed to scale to billions of instances, which motivates the choice to split the per-instance transformation into position, (quaternion) orientation, and scales, rather than a 4x4 matrix per-instance. In addition to requiring fewer bytes even if all elements are authored (32 bytes vs 64 for a single- precision 4x4 matrix), we can also be selective about which attributes need to animate over time, for substantial data reduction in many cases.
Note that PointInstancer is not a Gprim, since it is not a graphical primitive by any stretch of the imagination. It is, however, Boundable, since we will sometimes want to treat the entire PointInstancer similarly to a procedural, from the perspective of inclusion or framing.
Varying Instance Identity over Time
PointInstancers originating from simulations often have the characteristic that points/instances are”born”, move around for some time period, and then die (or leave the area of interest). In such cases, billions of instances may be birthed over time, while at any specific time, only a much smaller number are actually alive. To encode this situation efficiently, the simulator may re-use indices in the instance arrays, when a particle dies, its index will be taken over by a new particle that may be birthed in a much different location. This presents challenges both for identity-tracking, and for motion-blur.
We facilitate identity tracking by providing an optional, animatable ids attribute, that specifies the 64 bit integer ID of the particle at each index, at each point in time. If the simulator keeps monotonically increasing a particle-count each time a new particle is birthed, it will serve perfectly as particle ids.
We facilitate motion blur for varying-topology particle streams by optionally allowing per-instance velocities and angularVelocities to be authored. If instance transforms are requested at a time between samples and either of the velocity attributes is authored, then we will not attempt to interpolate samples of positions or orientations. If not authored, and the bracketing samples have the same length, then we will interpolate.
Computing an Instance Transform
Each instance’s transformation is a combination of the SRT affine transform described by its scale, orientation, and position, applied after (i.e. less locally) than the transformation computed at the root of the prototype it is instancing. In other words, to put an instance of a PointInstancer into the space of the PointInstancer’s parent prim:
Apply (most locally) the authored transformation for prototypes[protoIndices[i]]
If scales is authored, next apply the scaling matrix from scales[i]
If orientations is authored: if *angularVelocities* is authored, first multiply orientations[i] by the unit quaternion derived by scaling angularVelocities[i] by the time differential from the left-bracketing timeSample for orientation to the requested evaluation time t, storing the result in R, else assign R directly from orientations[i]. Apply the rotation matrix derived from R.
Apply the translation derived from positions[i]. If velocities is authored, apply the translation deriving from velocities[i] scaled by the time differential from the left- bracketing timeSample for positions to the requested evaluation time t.
Least locally, apply the transformation authored on the PointInstancer prim itself (or the UsdGeomImageable::ComputeLocalToWorldTransform() of the PointInstancer to put the instance directly into world space)
If neither velocities nor angularVelocities are authored, we fallback to standard position and orientation computation logic (using linear interpolation between timeSamples) as described by Applying Timesampled Velocities to Geometry.
Scaling Velocities for Interpolation
When computing time-differentials by which to apply velocity or angularVelocity to positions or orientations, we must scale by ( 1.0 / UsdStage::GetTimeCodesPerSecond() ), because velocities are recorded in units/second, while we are interpolating in UsdTimeCode ordinates.
We provide both high and low-level API’s for dealing with the transformation as a matrix, both will compute the instance matrices using multiple threads; the low-level API allows the client to cache unvarying inputs so that they need not be read duplicately when computing over time.
See also Applying Timesampled Velocities to Geometry.
Primvars on PointInstancer
Primvars authored on a PointInstancer prim should always be applied to each instance with constant interpolation at the root of the instance. When you are authoring primvars on a PointInstancer, think about it as if you were authoring them on a point-cloud (e.g. a UsdGeomPoints gprim). The same interpolation rules for points apply here, substituting”instance”for”point”.
In other words, the (constant) value extracted for each instance from the authored primvar value depends on the authored interpolation and elementSize of the primvar, as follows:
constant or uniform : the entire authored value of the primvar should be applied exactly to each instance.
varying, vertex, or faceVarying : the first elementSize elements of the authored primvar array should be assigned to instance zero, the second elementSize elements should be assigned to instance one, and so forth.
Masking Instances:”Deactivating”and Invising
Often a PointInstancer is created”upstream”in a graphics pipeline, and the needs of”downstream”clients necessitate eliminating some of the instances from further consideration. Accomplishing this pruning by re-authoring all of the per-instance attributes is not very attractive, since it may mean destructively editing a large quantity of data. We therefore provide means of”masking”instances by ID, such that the instance data is unmolested, but per-instance transform and primvar data can be retrieved with the no-longer-desired instances eliminated from the (smaller) arrays. PointInstancer allows two independent means of masking instances by ID, each with different features that meet the needs of various clients in a pipeline. Both pruning features’lists of ID’s are combined to produce the mask returned by ComputeMaskAtTime() .
If a PointInstancer has no authored ids attribute, the masking features will still be available, with the integers specifying element position in the protoIndices array rather than ID.
The first masking feature encodes a list of IDs in a list-editable metadatum called inactiveIds, which, although it does not have any similar impact to stage population as prim activation, it shares with that feature that its application is uniform over all time. Because it is list-editable, we can sparsely add and remove instances from it in many layers.
This sparse application pattern makes inactiveIds a good choice when further downstream clients may need to reverse masking decisions made upstream, in a manner that is robust to many kinds of future changes to the upstream data.
See ActivateId() , ActivateIds() , DeactivateId() , DeactivateIds() , ActivateAllIds()
The second masking feature encodes a list of IDs in a time-varying Int64Array-valued UsdAttribute called invisibleIds, since it shares with Imageable visibility the ability to animate object visibility.
Unlike inactiveIds, overriding a set of opinions for invisibleIds is not at all straightforward, because one will, in general need to reauthor (in the overriding layer) all timeSamples for the attribute just to change one Id’s visibility state, so it cannot be authored sparsely. But it can be a very useful tool for situations like encoding pre-computed camera-frustum culling of geometry when either or both of the instances or the camera is animated.
See VisId() , VisIds() , InvisId() , InvisIds() , VisAllIds()
Processing and Not Processing Prototypes
Any prim in the scenegraph can be targeted as a prototype by the prototypes relationship. We do not, however, provide a specific mechanism for identifying prototypes as geometry that should not be drawn (or processed) in their own, local spaces in the scenegraph. We encourage organizing all prototypes as children of the PointInstancer prim that consumes them, and pruning”raw”processing and drawing traversals when they encounter a PointInstancer prim; this is what the UsdGeomBBoxCache and UsdImaging engines do.
There is a pattern one can deploy for organizing the prototypes such that they will automatically be skipped by basic UsdPrim::GetChildren() or UsdPrimRange traversals. Usd prims each have a specifier of”def”,”over”, or”class”. The default traversals skip over prims that are”pure overs”or classes. So to protect prototypes from all generic traversals and processing, place them under a prim that is just an”over”. For example,
01 def PointInstancer "Crowd_Mid" 02 { 03 rel prototypes = [ </Crowd_Mid/Prototypes/MaleThin_Business>, </Crowd_Mid/Prototypes/MaleThin_Casual> ] 04 05 over "Prototypes" 06 { 07 def "MaleThin_Business" ( 08 references = [@MaleGroupA/usd/MaleGroupA.usd@</MaleGroupA>] 09 variants = { 10 string modelingVariant = "Thin" 11 string costumeVariant = "BusinessAttire" 12 } 13 ) 14 { \.\.\. } 15 16 def "MaleThin_Casual" 17 \.\.\. 18 } 19 }
Classes:
Encodes whether to evaluate and apply the PointInstancer's mask to computed results.
Encodes whether to include each prototype's root prim's transformation as the most-local component of computed instance transforms.
Methods:
Ensure that all instances are active over all time.
ActivateId
(id)Ensure that the instance identified by
id
is active over all time.ActivateIds
(ids)Ensure that the instances identified by
ids
are active over all time.ComputeExtentAtTime
(extent, time, baseTime)Compute the extent of the point instancer based on the per- instance,"PointInstancer relative"transforms at
time
, as described in Computing an Instance Transform.ComputeExtentAtTimes
(extents, times, baseTime)Compute the extent of the point instancer as in ComputeExtentAtTime, but across multiple
times
.classmethod ComputeInstanceTransformsAtTime(xforms, time, baseTime, doProtoXforms, applyMask) -> bool
Compute the per-instance transforms as in ComputeInstanceTransformsAtTime, but using multiple sample times.
ComputeMaskAtTime
(time, ids)Computes a presence mask to be applied to per-instance data arrays based on authored inactiveIds, invisibleIds, and ids.
CreateAccelerationsAttr
(defaultValue, ...)See GetAccelerationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateAngularVelocitiesAttr
(defaultValue, ...)See GetAngularVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateIdsAttr
(defaultValue, writeSparsely)See GetIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateInvisibleIdsAttr
(defaultValue, ...)See GetInvisibleIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateOrientationsAttr
(defaultValue, ...)See GetOrientationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreatePositionsAttr
(defaultValue, writeSparsely)See GetPositionsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateProtoIndicesAttr
(defaultValue, ...)See GetProtoIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
See GetPrototypesRel() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateScalesAttr
(defaultValue, writeSparsely)See GetScalesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateVelocitiesAttr
(defaultValue, writeSparsely)See GetVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
DeactivateId
(id)Ensure that the instance identified by
id
is inactive over all time.DeactivateIds
(ids)Ensure that the instances identified by
ids
are inactive over all time.classmethod Define(stage, path) -> PointInstancer
classmethod Get(stage, path) -> PointInstancer
If authored, per-instance'accelerations'will be used with velocities to compute positions between samples for the'positions'attribute rather than interpolating between neighboring'positions'samples.
If authored, per-instance angular velocity vector to be used for interoplating orientations.
Ids are optional; if authored, the ids array should be the same length as the protoIndices array, specifying (at each timeSample if instance identities are changing) the id of each instance.
GetInstanceCount
(timeCode)Returns the number of instances as defined by the size of the protoIndices array at timeCode.
A list of id's to make invisible at the evaluation time.
If authored, per-instance orientation of each instance about its prototype's origin, represented as a unit length quaternion, which allows us to encode it with sufficient precision in a compact GfQuath.
Required property.
Required property.
Required property.
If authored, per-instance scale to be applied to each instance, before any rotation is applied.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
If provided, per-instance'velocities'will be used to compute positions between samples for the'positions'attribute, rather than interpolating between neighboring'positions'samples.
InvisId
(id, time)Ensure that the instance identified by
id
is invisible attime
InvisIds
(ids, time)Ensure that the instances identified by
ids
are invisible attime
.VisAllIds
(time)Ensure that all instances are visible at
time
.VisId
(id, time)Ensure that the instance identified by
id
is visible attime
.VisIds
(ids, time)Ensure that the instances identified by
ids
are visible attime
.Attributes:
- class MaskApplication
Encodes whether to evaluate and apply the PointInstancer’s mask to computed results.
ComputeMaskAtTime()
Methods:
Attributes:
- static GetValueFromName()
- allValues = (UsdGeom.PointInstancer.ApplyMask, UsdGeom.PointInstancer.IgnoreMask)
- class ProtoXformInclusion
Encodes whether to include each prototype’s root prim’s transformation as the most-local component of computed instance transforms.
Methods:
Attributes:
- static GetValueFromName()
- allValues = (UsdGeom.PointInstancer.IncludeProtoXform, UsdGeom.PointInstancer.ExcludeProtoXform)
- ActivateAllIds() bool
Ensure that all instances are active over all time.
This does not guarantee that the instances will be rendered, because each may still be”invisible”due to its presence in the invisibleIds attribute (see VisId() , InvisId() )
- ActivateId(id) bool
Ensure that the instance identified by
id
is active over all time.This activation is encoded sparsely, affecting no other instances.
This does not guarantee that the instance will be rendered, because it may still be”invisible”due to
id
being present in the invisibleIds attribute (see VisId() , InvisId() )- Parameters
id (int) –
- ActivateIds(ids) bool
Ensure that the instances identified by
ids
are active over all time.This activation is encoded sparsely, affecting no other instances.
This does not guarantee that the instances will be rendered, because each may still be”invisible”due to its presence in the invisibleIds attribute (see VisId() , InvisId() )
- Parameters
ids (Int64Array) –
- ComputeExtentAtTime(extent, time, baseTime) bool
Compute the extent of the point instancer based on the per- instance,”PointInstancer relative”transforms at
time
, as described in Computing an Instance Transform.If there is no error, we return
true
andextent
will be the tightest bounds we can compute efficiently. If an error occurs,false
will be returned andextent
will be left untouched.For now, this uses a UsdGeomBBoxCache with the”default”,”proxy”, and”render”purposes.
extent
- the out parameter for the extent. On success, it will contain two elements representing the min and max. time
- UsdTimeCode at which we want to evaluate the extent baseTime
- required for correct interpolation between samples when velocities or angularVelocities are present. If there are samples for positions and velocities at t1 and t2, normal value resolution would attempt to interpolate between the two samples, and if they could not be interpolated because they differ in size (common in cases where velocity is authored), will choose the sample at t1. When sampling for the purposes of motion-blur, for example, it is common, when rendering the frame at t2, to sample at [ t2-shutter/2, t2+shutter/2 ] for a shutter interval of shutter. The first sample falls between t1 and t2, but we must sample at t2 and apply velocity- based interpolation based on those samples to get a correct result. In such scenarios, one should provide a
baseTime
of t2 when querying both samples. If your application does not care about off-sample interpolation, it can supply the same value forbaseTime
that it does fortime
. WhenbaseTime
is less than or equal totime
, we will choose the lower bracketing timeSample.- Parameters
extent (Vec3fArray) –
time (TimeCode) –
baseTime (TimeCode) –
ComputeExtentAtTime(extent, time, baseTime, transform) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
extent (Vec3fArray) –
time (TimeCode) –
baseTime (TimeCode) –
transform (Matrix4d) –
- ComputeExtentAtTimes(extents, times, baseTime) bool
Compute the extent of the point instancer as in ComputeExtentAtTime, but across multiple
times
.This is equivalent to, but more efficient than, calling ComputeExtentAtTime several times. Each element in
extents
is the computed extent at the corresponding time intimes
.As in ComputeExtentAtTime, if there is no error, we return
true
andextents
will be the tightest bounds we can compute efficiently. If an error occurs computing the extent at any time,false
will be returned andextents
will be left untouched.times
- A vector containing the UsdTimeCodes at which we want to sample.
- Parameters
extents (list[Vec3fArray]) –
times (list[TimeCode]) –
baseTime (TimeCode) –
ComputeExtentAtTimes(extents, times, baseTime, transform) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied at each time.- Parameters
extents (list[Vec3fArray]) –
times (list[TimeCode]) –
baseTime (TimeCode) –
transform (Matrix4d) –
- ComputeInstanceTransformsAtTime()
classmethod ComputeInstanceTransformsAtTime(xforms, time, baseTime, doProtoXforms, applyMask) -> bool
Compute the per-instance,”PointInstancer relative”transforms given the positions, scales, orientations, velocities and angularVelocities at
time
, as described in Computing an Instance Transform.This will return
false
and leavexforms
untouched if:xforms
is Noneone of
time
andbaseTime
is numeric and the other is UsdTimeCode::Default() (they must either both be numeric or both be default)there is no authored protoIndices attribute or positions attribute
the size of any of the per-instance attributes does not match the size of protoIndices
doProtoXforms
isIncludeProtoXform
but an index value in protoIndices is outside the range [0, prototypes.size())applyMask
isApplyMask
and a mask is set but the size of the mask does not match the size of protoIndices.
If there is no error, we will return
true
andxforms
will contain the computed transformations.xforms
- the out parameter for the transformations. Its size will depend on the authored data and
applyMask
time- UsdTimeCode at which we want to evaluate the transforms baseTime
- required for correct interpolation between samples when velocities or angularVelocities are present. If there are samples for positions and velocities at t1 and t2, normal value resolution would attempt to interpolate between the two samples, and if they could not be interpolated because they differ in size (common in cases where velocity is authored), will choose the sample at t1. When sampling for the purposes of motion-blur, for example, it is common, when rendering the frame at t2, to sample at [ t2-shutter/2, t2+shutter/2 ] for a shutter interval of shutter. The first sample falls between t1 and t2, but we must sample at t2 and apply velocity- based interpolation based on those samples to get a correct result. In such scenarios, one should provide a
baseTime
of t2 when querying both samples. If your application does not care about off-sample interpolation, it can supply the same value forbaseTime
that it does fortime
. WhenbaseTime
is less than or equal totime
, we will choose the lower bracketing timeSample. Selecting sample times with respect to baseTime will be performed independently for positions and orientations. doProtoXforms- specifies whether to include the root transformation of each instance’s prototype in the instance’s transform. Default is to include it, but some clients may want to apply the proto transform as part of the prototype itself, so they can specify
ExcludeProtoXform
instead. applyMask- specifies whether to apply ApplyMaskToArray() to the computed result. The default is
ApplyMask
.- Parameters
xforms (VtArray[Matrix4d]) –
time (TimeCode) –
baseTime (TimeCode) –
doProtoXforms (ProtoXformInclusion) –
applyMask (MaskApplication) –
ComputeInstanceTransformsAtTime(xforms, stage, time, protoIndices, positions, velocities, velocitiesSampleTime, accelerations, scales, orientations, angularVelocities, angularVelocitiesSampleTime, protoPaths, mask, velocityScale) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Perform the per-instance transform computation as described in Computing an Instance Transform.
This does the same computation as the non-static ComputeInstanceTransformsAtTime method, but takes all data as parameters rather than accessing authored data.
xforms
- the out parameter for the transformations. Its size will depend on the given data and
applyMask
stage- the UsdStage time
- time at which we want to evaluate the transforms protoIndices
- array containing all instance prototype indices. positions
- array containing all instance positions. This array must be the same size as
protoIndices
. velocities- array containing all instance velocities. This array must be either the same size as
protoIndices
or empty. If it is empty, transforms are computed as if all velocities were zero in all dimensions. velocitiesSampleTime- time at which the samples from
velocities
were taken. accelerations- array containing all instance accelerations. This array must be either the same size as
protoIndicesor
empty. If it is empty, transforms are computed as if all accelerations were zero in all dimensions. scales- array containing all instance scales. This array must be either the same size as
protoIndices
or empty. If it is empty, transforms are computed with no change in scale. orientations- array containing all instance orientations. This array must be either the same size as
protoIndices
or empty. If it is empty, transforms are computed with no change in orientation angularVelocities- array containing all instance angular velocities. This array must be either the same size as
protoIndices
or empty. If it is empty, transforms are computed as if all angular velocities were zero in all dimensions. angularVelocitiesSampleTime- time at which the samples from
angularVelocities
were taken. protoPaths- array containing the paths for all instance prototypes. If this array is not empty, prototype transforms are applied to the instance transforms. mask
- vector containing a mask to apply to the computed result. This vector must be either the same size as
protoIndices
or empty. If it is empty, no mask is applied. velocityScale- Deprecated
- Parameters
xforms (VtArray[Matrix4d]) –
stage (UsdStageWeak) –
time (TimeCode) –
protoIndices (IntArray) –
positions (Vec3fArray) –
velocities (Vec3fArray) –
velocitiesSampleTime (TimeCode) –
accelerations (Vec3fArray) –
scales (Vec3fArray) –
orientations (QuathArray) –
angularVelocities (Vec3fArray) –
angularVelocitiesSampleTime (TimeCode) –
protoPaths (list[Path]) –
mask (list[bool]) –
velocityScale (float) –
- ComputeInstanceTransformsAtTimes(xformsArray, times, baseTime, doProtoXforms, applyMask) bool
Compute the per-instance transforms as in ComputeInstanceTransformsAtTime, but using multiple sample times.
An array of matrix arrays is returned where each matrix array contains the instance transforms for the corresponding time in
times
.times
- A vector containing the UsdTimeCodes at which we want to sample.
- Parameters
xformsArray (list[VtArray[Matrix4d]]) –
times (list[TimeCode]) –
baseTime (TimeCode) –
doProtoXforms (ProtoXformInclusion) –
applyMask (MaskApplication) –
- ComputeMaskAtTime(time, ids) list[bool]
Computes a presence mask to be applied to per-instance data arrays based on authored inactiveIds, invisibleIds, and ids.
If no ids attribute has been authored, then the values in inactiveIds and invisibleIds will be interpreted directly as indices of protoIndices.
If
ids
is non-None, it is assumed to be the id-mapping to apply, and must match the length of protoIndices attime
. If None, we will call GetIdsAttr() .Get(time)If all”live”instances at UsdTimeCode
time
pass the mask, we will return an empty mask so that clients can trivially recognize the common”no masking”case. The returned mask can be used with ApplyMaskToArray() , and will contain atrue
value for every element that should survive.- Parameters
time (TimeCode) –
ids (Int64Array) –
- CreateAccelerationsAttr(defaultValue, writeSparsely) Attribute
See GetAccelerationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateAngularVelocitiesAttr(defaultValue, writeSparsely) Attribute
See GetAngularVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateIdsAttr(defaultValue, writeSparsely) Attribute
See GetIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateInvisibleIdsAttr(defaultValue, writeSparsely) Attribute
See GetInvisibleIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateOrientationsAttr(defaultValue, writeSparsely) Attribute
See GetOrientationsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreatePositionsAttr(defaultValue, writeSparsely) Attribute
See GetPositionsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateProtoIndicesAttr(defaultValue, writeSparsely) Attribute
See GetProtoIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreatePrototypesRel() Relationship
See GetPrototypesRel() , and also Create vs Get Property Methods for when to use Get vs Create.
- CreateScalesAttr(defaultValue, writeSparsely) Attribute
See GetScalesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateVelocitiesAttr(defaultValue, writeSparsely) Attribute
See GetVelocitiesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- DeactivateId(id) bool
Ensure that the instance identified by
id
is inactive over all time.This deactivation is encoded sparsely, affecting no other instances.
A deactivated instance is guaranteed not to render if the renderer honors masking.
- Parameters
id (int) –
- DeactivateIds(ids) bool
Ensure that the instances identified by
ids
are inactive over all time.This deactivation is encoded sparsely, affecting no other instances.
A deactivated instance is guaranteed not to render if the renderer honors masking.
- Parameters
ids (Int64Array) –
- static Define()
classmethod Define(stage, path) -> PointInstancer
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> PointInstancer
Return a UsdGeomPointInstancer holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomPointInstancer(stage->GetPrimAtPath(path));
- GetAccelerationsAttr() Attribute
If authored, per-instance’accelerations’will be used with velocities to compute positions between samples for the’positions’attribute rather than interpolating between neighboring’positions’samples.
Acceleration is measured in position units per second-squared. To convert to position units per squared UsdTimeCode, divide by the square of UsdStage::GetTimeCodesPerSecond() .
Declaration
vector3f[] accelerations
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Vector3fArray
- GetAngularVelocitiesAttr() Attribute
If authored, per-instance angular velocity vector to be used for interoplating orientations.
Angular velocities should be considered mandatory if both protoIndices and orientations are animated. Angular velocity is measured in degrees per second. To convert to degrees per UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond() .
See also Computing an Instance Transform.
Declaration
vector3f[] angularVelocities
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Vector3fArray
- GetIdsAttr() Attribute
Ids are optional; if authored, the ids array should be the same length as the protoIndices array, specifying (at each timeSample if instance identities are changing) the id of each instance.
The type is signed intentionally, so that clients can encode some binary state on Id’d instances without adding a separate primvar. See also Varying Instance Identity over Time
Declaration
int64[] ids
C++ Type
VtArray<int64_t>
Usd Type
SdfValueTypeNames->Int64Array
- GetInstanceCount(timeCode) int
Returns the number of instances as defined by the size of the protoIndices array at timeCode.
For most code, this check will be performant. When using file formats where the cost of attribute reading is high and the time sampled array will be read into memory later, it may be better to explicitly read the value once and check the size of the array directly.
GetProtoIndicesAttr()
- Parameters
timeCode (TimeCode) –
- GetInvisibleIdsAttr() Attribute
A list of id’s to make invisible at the evaluation time.
See invisibleIds: Animatable Masking.
Declaration
int64[] invisibleIds = []
C++ Type
VtArray<int64_t>
Usd Type
SdfValueTypeNames->Int64Array
- GetOrientationsAttr() Attribute
If authored, per-instance orientation of each instance about its prototype’s origin, represented as a unit length quaternion, which allows us to encode it with sufficient precision in a compact GfQuath.
It is client’s responsibility to ensure that authored quaternions are unit length; the convenience API below for authoring orientations from rotation matrices will ensure that quaternions are unit length, though it will not make any attempt to select the”better (for interpolationwith respect to neighboring samples)”of the two possible quaternions that encode the rotation.
See also Computing an Instance Transform.
Declaration
quath[] orientations
C++ Type
VtArray<GfQuath>
Usd Type
SdfValueTypeNames->QuathArray
- GetPositionsAttr() Attribute
Required property.
Per-instance position. See also Computing an Instance Transform.
Declaration
point3f[] positions
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Point3fArray
- GetProtoIndicesAttr() Attribute
Required property.
Per-instance index into prototypes relationship that identifies what geometry should be drawn for each instance. Topology attribute - can be animated, but at a potential performance impact for streaming.
Declaration
int[] protoIndices
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- GetPrototypesRel() Relationship
Required property.
Orders and targets the prototype root prims, which can be located anywhere in the scenegraph that is convenient, although we promote organizing prototypes as children of the PointInstancer. The position of a prototype in this relationship defines the value an instance would specify in the protoIndices attribute to instance that prototype. Since relationships are uniform, this property cannot be animated.
- GetScalesAttr() Attribute
If authored, per-instance scale to be applied to each instance, before any rotation is applied.
See also Computing an Instance Transform.
Declaration
float3[] scales
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetVelocitiesAttr() Attribute
If provided, per-instance’velocities’will be used to compute positions between samples for the’positions’attribute, rather than interpolating between neighboring’positions’samples.
Velocities should be considered mandatory if both protoIndices and positions are animated. Velocity is measured in position units per second, as per most simulation software. To convert to position units per UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond() .
See also Computing an Instance Transform, Applying Timesampled Velocities to Geometry.
Declaration
vector3f[] velocities
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Vector3fArray
- InvisId(id, time) bool
Ensure that the instance identified by
id
is invisible attime
.This will cause invisibleIds to first be broken down (keyed) at
time
, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one attime
.An invised instance is guaranteed not to render if the renderer honors masking.
- Parameters
id (int) –
time (TimeCode) –
- InvisIds(ids, time) bool
Ensure that the instances identified by
ids
are invisible attime
.This will cause invisibleIds to first be broken down (keyed) at
time
, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one attime
.An invised instance is guaranteed not to render if the renderer honors masking.
- Parameters
ids (Int64Array) –
time (TimeCode) –
- VisAllIds(time) bool
Ensure that all instances are visible at
time
.Operates by authoring an empty array at
time
.This does not guarantee that the instances will be rendered, because each may still be”inactive”due to its id being present in the inactivevIds metadata (see ActivateId() , DeactivateId() )
- Parameters
time (TimeCode) –
- VisId(id, time) bool
Ensure that the instance identified by
id
is visible attime
.This will cause invisibleIds to first be broken down (keyed) at
time
, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one attime
. If the invisibleIds attribute is not authored or is blocked, this operation is a no-op.This does not guarantee that the instance will be rendered, because it may still be”inactive”due to
id
being present in the inactivevIds metadata (see ActivateId() , DeactivateId() )- Parameters
id (int) –
time (TimeCode) –
- VisIds(ids, time) bool
Ensure that the instances identified by
ids
are visible attime
.This will cause invisibleIds to first be broken down (keyed) at
time
, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one attime
. If the invisibleIds attribute is not authored or is blocked, this operation is a no-op.This does not guarantee that the instances will be rendered, because each may still be”inactive”due to
id
being present in the inactivevIds metadata (see ActivateId() , DeactivateId() )- Parameters
ids (Int64Array) –
time (TimeCode) –
- ApplyMask = UsdGeom.PointInstancer.ApplyMask
- ExcludeProtoXform = UsdGeom.PointInstancer.ExcludeProtoXform
- IgnoreMask = UsdGeom.PointInstancer.IgnoreMask
- IncludeProtoXform = UsdGeom.PointInstancer.IncludeProtoXform
- class pxr.UsdGeom.Points
Points are analogous to the RiPoints spec.
Points can be an efficient means of storing and rendering particle effects comprised of thousands or millions of small particles. Points generally receive a single shading sample each, which should take normals into account, if present.
While not technically UsdGeomPrimvars, the widths and normals also have interpolation metadata. It’s common for authored widths and normals to have constant or varying interpolation.
Methods:
classmethod ComputeExtent(points, widths, extent) -> bool
CreateIdsAttr
(defaultValue, writeSparsely)See GetIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateWidthsAttr
(defaultValue, writeSparsely)See GetWidthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Points
classmethod Get(stage, path) -> Points
Ids are optional; if authored, the ids array should be the same length as the points array, specifying (at each timesample if point identities are changing) the id of each point.
GetPointCount
(timeCode)Returns the number of points as defined by the size of the points array at timeCode.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Widths are defined as the diameter of the points, in object space.
Get the interpolation for the widths attribute.
SetWidthsInterpolation
(interpolation)Set the interpolation for the widths attribute.
- static ComputeExtent()
classmethod ComputeExtent(points, widths, extent) -> bool
Compute the extent for the point cloud defined by points and widths.
true upon success, false if widths and points are different sized arrays. On success, extent will contain the axis-aligned bounding box of the point cloud defined by points with the given widths.
This function is to provide easy authoring of extent for usd authoring tools, hence it is static and acts outside a specific prim (as in attribute based methods).
- Parameters
points (Vec3fArray) –
widths (FloatArray) –
extent (Vec3fArray) –
ComputeExtent(points, widths, transform, extent) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix
transform
was first applied.- Parameters
points (Vec3fArray) –
widths (FloatArray) –
transform (Matrix4d) –
extent (Vec3fArray) –
- CreateIdsAttr(defaultValue, writeSparsely) Attribute
See GetIdsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateWidthsAttr(defaultValue, writeSparsely) Attribute
See GetWidthsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Points
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Points
Return a UsdGeomPoints holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomPoints(stage->GetPrimAtPath(path));
- GetIdsAttr() Attribute
Ids are optional; if authored, the ids array should be the same length as the points array, specifying (at each timesample if point identities are changing) the id of each point.
The type is signed intentionally, so that clients can encode some binary state on Id’d points without adding a separate primvar.
Declaration
int64[] ids
C++ Type
VtArray<int64_t>
Usd Type
SdfValueTypeNames->Int64Array
- GetPointCount(timeCode) int
Returns the number of points as defined by the size of the points array at timeCode.
For most code, this check will be performant. When using file formats where the cost of attribute reading is high and the time sampled array will be read into memory later, it may be better to explicitly read the value once and check the size of the array directly.
GetPointsAttr()
- Parameters
timeCode (TimeCode) –
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- GetWidthsAttr() Attribute
Widths are defined as the diameter of the points, in object space.
‘widths’is not a generic Primvar, but the number of elements in this attribute will be determined by its’interpolation’. See SetWidthsInterpolation() . If’widths’and’primvars:widths’are both specified, the latter has precedence.
Declaration
float[] widths
C++ Type
VtArray<float>
Usd Type
SdfValueTypeNames->FloatArray
- GetWidthsInterpolation() str
Get the interpolation for the widths attribute.
Although’widths’is not classified as a generic UsdGeomPrimvar (and will not be included in the results of UsdGeomPrimvarsAPI::GetPrimvars() ) it does require an interpolation specification. The fallback interpolation, if left unspecified, is UsdGeomTokens->vertex, which means a width value is specified for each point.
- SetWidthsInterpolation(interpolation) bool
Set the interpolation for the widths attribute.
true upon success, false if
interpolation
is not a legal value as defined by UsdPrimvar::IsValidInterpolation(), or if there was a problem setting the value. No attempt is made to validate that the widths attr’s value contains the right number of elements to match its interpolation to its prim’s topology.GetWidthsInterpolation()
- Parameters
interpolation (str) –
- class pxr.UsdGeom.Primvar
Schema wrapper for UsdAttribute for authoring and introspecting attributes that are primvars.
UsdGeomPrimvar provides API for authoring and retrieving the additional data required to encode an attribute as a”Primvar”, which is a convenient contraction of RenderMan’s”Primitive Variable”concept, which is represented in Alembic as”arbitrary geometry parameters”(arbGeomParams).
This includes the attribute’s interpolation across the primitive (which RenderMan refers to as its class specifier and Alembic as its “geometry scope” ); it also includes the attribute’s elementSize, which states how many values in the value array must be aggregated for each element on the primitive. An attribute’s TypeName also factors into the encoding of Primvar.
What is the Purpose of a Primvar?
There are three key aspects of Primvar identity:
Primvars define a value that can vary across the primitive on which they are defined, via prescribed interpolation rules
Taken collectively on a prim, its Primvars describe the”per- primitiveoverrides”to the material to which the prim is bound. Different renderers may communicate the variables to the shaders using different mechanisms over which Usd has no control; Primvars simply provide the classification that any renderer should use to locate potential overrides. Do please note that primvars override parameters on UsdShadeShader objects, not Interface Attributes on UsdShadeMaterial prims.
Primvars inherit down scene namespace. Regular USD attributes only apply to the prim on which they are specified, but primvars implicitly also apply to any child prims, unless those child prims have their own opinions about those primvars. This capability necessarily entails added cost to check for inherited values, but the benefit is that it allows concise encoding of certain opinions that broadly affect large amounts of geometry. See UsdGeomImageable::FindInheritedPrimvars().
Creating and Accessing Primvars
The UsdGeomPrimvarsAPI schema provides a complete interface for creating and querying prims for primvars.
The only way to create a new Primvar in scene description is by calling UsdGeomPrimvarsAPI::CreatePrimvar() . One cannot”enhance”or”promote”an already existing attribute into a Primvar, because doing so may require a namespace edit to rename the attribute, which cannot, in general, be done within a single UsdEditContext. Instead, create a new UsdGeomPrimvar of the desired name using UsdGeomPrimvarsAPI::CreatePrimvar() , and then copy the existing attribute onto the new UsdGeomPrimvar.
Primvar names can contain arbitrary sub-namespaces. The behavior of UsdGeomImageable::GetPrimvar(TfToken const & name) is to prepend”primvars:”onto’name’if it is not already a prefix, and return the result, which means we do not have any ambiguity between the primvars”primvars:nsA:foo”and”primvars:nsB:foo”. There are reserved keywords that may not be used as the base names of primvars, and attempting to create Primvars of these names will result in a coding error. The reserved keywords are tokens the Primvar uses internally to encode various features, such as the”indices”keyword used by Indexed Primvars.
If a client wishes to access an already-extant attribute as a Primvar, (which may or may not actually be valid Primvar), they can use the speculative constructor; typically, a primvar is only”interesting”if it additionally provides a value. This might look like:
UsdGeomPrimvar primvar = UsdGeomPrimvar(usdAttr); if (primvar.HasValue()) { VtValue values; primvar.Get(&values, timeCode); TfToken interpolation = primvar.GetInterpolation(); int elementSize = primvar.GetElementSize(); \.\.\. }
or, because Get() returns
true
if and only if it found a value:UsdGeomPrimvar primvar = UsdGeomPrimvar(usdAttr); VtValue values; if (primvar.Get(&values, timeCode)) { TfToken interpolation = primvar.GetInterpolation(); int elementSize = primvar.GetElementSize(); \.\.\. }
As discussed in greater detail in Indexed Primvars, primvars can optionally contain a (possibly time-varying) indexing attribute that establishes a sharing topology for elements of the primvar. Consumers can always chose to ignore the possibility of indexed data by exclusively using the ComputeFlattened() API. If a client wishes to preserve indexing in their processing of a primvar, we suggest a pattern like the following, which accounts for the fact that a stronger layer can block a primvar’s indexing from a weaker layer, via UsdGeomPrimvar::BlockIndices() :
VtValue values; VtIntArray indices; if (primvar.Get(&values, timeCode)){ if (primvar.GetIndices(&indices, timeCode)){ // primvar is indexed: validate/process values and indices together } else { // primvar is not indexed: validate/process values as flat array } }
UsdGeomPrimvar presents a small slice of the UsdAttribute API - enough to extract the data that comprises the”Declaration info”, and get/set of the attribute value. A UsdGeomPrimvar also auto-converts to UsdAttribute, so you can pass a UsdGeomPrimvar to any function that accepts a UsdAttribute or const-ref thereto.
Primvar Allowed Scene Description Types and Plurality
There are no limitations imposed on the allowable scene description types for Primvars; it is the responsibility of each consuming client to perform renderer-specific conversions, if need be (the USD distribution will include reference RenderMan conversion utilities).
A note about type plurality of Primvars: It is legitimate for a Primvar to be of scalar or array type, and again, consuming clients must be prepared to accommodate both. However, while it is not possible, in all cases, for USD to prevent one from changing the type of an attribute in different layers or variants of an asset, it is never a good idea to do so. This is relevant because, except in a few special cases, it is not possible to encode an interpolation of any value greater than constant without providing multiple (i.e. array) data values. Therefore, if there is any possibility that downstream clients might need to change a Primvar’s interpolation, the Primvar-creator should encode it as an array rather than a scalar.
Why allow scalar values at all, then? First, sometimes it brings clarity to (use of) a shader’s API to acknowledge that some parameters are meant to be single-valued over a shaded primitive. Second, many DCC’s provide far richer affordances for editing scalars than they do array values, and we feel it is safer to let the content creator make the decision/tradeoff of which kind of flexibility is more relevant, rather than leaving it to an importer/exporter pair to interpret.
Also, like all attributes, Primvars can be time-sampled, and values can be authored and consumed just as any other attribute. There is currently no validation that the length of value arrays matches to the size required by a gprim’s topology, interpolation, and elementSize.
For consumer convenience, we provide GetDeclarationInfo() , which returns all the type information (other than topology) needed to compute the required array size, which is also all the information required to prepare the Primvar’s value for consumption by a renderer.
Lifetime Management and Primvar Validity
UsdGeomPrimvar has an explicit bool operator that validates that the attribute IsDefined() and thus valid for querying and authoring values and metadata. This is a fairly expensive query that we do not cache, so if client code retains UsdGeomPrimvar objects, it should manage its object validity closely, for performance. An ideal pattern is to listen for UsdNotice::StageContentsChanged notifications, and revalidate/refetch its retained UsdGeomPrimvar s only then, and otherwise use them without validity checking.
Interpolation of Geometric Primitive Variables
In the following explanation of the meaning of the various kinds/levels of Primvar interpolation, each bolded bullet gives the name of the token in UsdGeomTokens that provides the value. So to set a Primvar’s interpolation to”varying”, one would:
primvar.SetInterpolation(UsdGeomTokens->varying);
Reprinted and adapted from the RPS documentation, which contains further details, interpolation describes how the Primvar will be interpolated over the uv parameter space of a surface primitive (or curve or pointcloud). The possible values are:
constant One value remains constant over the entire surface primitive.
uniform One value remains constant for each uv patch segment of the surface primitive (which is a face for meshes).
varying Four values are interpolated over each uv patch segment of the surface. Bilinear interpolation is used for interpolation between the four values.
vertex Values are interpolated between each vertex in the surface primitive. The basis function of the surface is used for interpolation between vertices.
faceVarying For polygons and subdivision surfaces, four values are interpolated over each face of the mesh. Bilinear interpolation is used for interpolation between the four values.
UsdGeomPrimvar As Example of Attribute Schema
Just as UsdSchemaBase and its subclasses provide the pattern for how to layer schema onto the generic UsdPrim object, UsdGeomPrimvar provides an example of how to layer schema onto a generic UsdAttribute object. In both cases, the schema object wraps and contains the UsdObject.
Primvar Namespace Inheritance
Constant interpolation primvar values can be inherited down namespace. That is, a primvar value set on a prim will also apply to any child prims, unless those children have their own opinions about those named primvars. For complete details on how primvars inherit, see usdGeom_PrimvarInheritance.
UsdGeomImageable::FindInheritablePrimvars().
Methods:
Block the indices that were previously set.
classmethod ComputeFlattened(value, time) -> bool
Returns the existing indices attribute if the primvar is indexed or creates a new one.
Get
(value, time)Get the attribute value of the Primvar at
time
.GetAttr
()Explicit UsdAttribute extractor.
UsdAttribute::GetBaseName()
GetDeclarationInfo
(name, typeName, ...)Convenience function for fetching all information required to properly declare this Primvar.
Return the"element size"for this Primvar, which is 1 if unauthored.
GetIndices
(indices, time)Returns the value of the indices array associated with the indexed primvar at
time
.Returns a valid indices attribute if the primvar is indexed.
Return the Primvar's interpolation, which is UsdGeomTokens->constant if unauthored.
GetName
()UsdAttribute::GetName()
UsdAttribute::GetNamespace()
Returns the primvar's name, devoid of the"primvars:"namespace.
GetTimeSamples
(times)Populates a vector with authored sample times for this primvar.
GetTimeSamplesInInterval
(interval, times)Populates a vector with authored sample times in
interval
.UsdAttribute::GetTypeName()
Returns the index that represents unauthored values in the indices array.
Has elementSize been explicitly authored on this Primvar?
Has interpolation been explicitly authored on this Primvar?
Return true if the underlying attribute has an unblocked, authored value.
HasValue
()Return true if the underlying attribute has a value, either from authored scene description or a fallback.
Return true if the underlying UsdAttribute::IsDefined() , and in addition the attribute is identified as a Primvar.
Returns true if the primvar is an Id primvar.
Returns true if the primvar is indexed, i.e., if it has an associated"indices"attribute.
classmethod IsPrimvar(attr) -> bool
classmethod IsValidInterpolation(interpolation) -> bool
classmethod IsValidPrimvarName(name) -> bool
Does this primvar contain any namespaces other than the"primvars:"namespace?
Set
(value, time)Set the attribute value of the Primvar at
time
.SetElementSize
(eltSize)Set the elementSize for this Primvar.
SetIdTarget
(path)This primvar must be of String or StringArray type for this method to succeed.
SetIndices
(indices, time)Sets the indices value of the indexed primvar at
time
.SetInterpolation
(interpolation)Set the Primvar's interpolation.
SetUnauthoredValuesIndex
(unauthoredValuesIndex)Set the index that represents unauthored values in the indices array.
UsdAttribute::SplitName()
classmethod StripPrimvarsName(name) -> str
Return true if it is possible, but not certain, that this primvar's value changes over time, false otherwise.
- BlockIndices() None
Block the indices that were previously set.
This effectively makes an indexed primvar no longer indexed. This is useful when overriding an existing primvar.
- ComputeFlattened()
classmethod ComputeFlattened(value, time) -> bool
Computes the flattened value of the primvar at
time
.If the primvar is not indexed or if the value type of this primvar is a scalar, this returns the authored value, which is the same as Get() . Hence, it’s safe to call ComputeFlattened() on non-indexed primvars.
- Parameters
value (VtArray[ScalarType]) –
time (TimeCode) –
ComputeFlattened(value, time) -> bool
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the flattened value of the primvar at
time
as a VtValue.If the primvar is not indexed or if the value type of this primvar is a scalar, this returns the authored value, which is the same as Get() . Hence, it’s safe to call ComputeFlattened() on non-indexed primvars.
- Parameters
value (VtValue) –
time (TimeCode) –
ComputeFlattened(value, attrVal, indices, errString) -> bool
Computes the flattened value of
attrValue
givenindices
.This method is a static convenience function that performs the main work of ComputeFlattened above without needing an instance of a UsdGeomPrimvar.
Returns
false
if the value contained inattrVal
is not a supported type for flattening. Otherwise returnstrue
. The outputerrString
variable may be populated with an error string if an error is encountered during flattening.- Parameters
value (VtValue) –
attrVal (VtValue) –
indices (IntArray) –
errString (str) –
- CreateIndicesAttr() Attribute
Returns the existing indices attribute if the primvar is indexed or creates a new one.
- Get(value, time) bool
Get the attribute value of the Primvar at
time
.Usd_Handling_Indexed_Primvars for proper handling of indexed primvars
- Parameters
value (T) –
time (TimeCode) –
Get(value, time) -> bool
- Parameters
value (str) –
time (TimeCode) –
Get(value, time) -> bool
- Parameters
value (StringArray) –
time (TimeCode) –
Get(value, time) -> bool
- Parameters
value (VtValue) –
time (TimeCode) –
- GetBaseName() str
UsdAttribute::GetBaseName()
- GetDeclarationInfo(name, typeName, interpolation, elementSize) None
Convenience function for fetching all information required to properly declare this Primvar.
The
name
returned is the”client name”, stripped of the”primvars”namespace, i.e. equivalent to GetPrimvarName()May also be more efficient than querying key individually.
- Parameters
name (str) –
typeName (ValueTypeName) –
interpolation (str) –
elementSize (int) –
- GetElementSize() int
Return the”element size”for this Primvar, which is 1 if unauthored.
If this Primvar’s type is not an array type, (e.g.”Vec3f[]”), then elementSize is irrelevant.
ElementSize does not generally encode the length of an array-type primvar, and rarely needs to be authored. ElementSize can be thought of as a way to create an”aggregate interpolatable type”, by dictating how many consecutive elements in the value array should be taken as an atomic element to be interpolated over a gprim.
For example, spherical harmonics are often represented as a collection of nine floating-point coefficients, and the coefficients need to be sampled across a gprim’s surface: a perfect case for primvars. However, USD has no
float9
datatype. But we can communicate the aggregation of nine floats successfully to renderers by declaring a simple float-array valued primvar, and setting its elementSize to 9. To author a uniform spherical harmonic primvar on a Mesh of 42 faces, the primvar’s array value would contain 9*42 = 378 float elements.
- GetIndices(indices, time) bool
Returns the value of the indices array associated with the indexed primvar at
time
.SetIndices() , Proper Client Handling of”Indexed”Primvars
- GetIndicesAttr() Attribute
Returns a valid indices attribute if the primvar is indexed.
Returns an invalid attribute otherwise.
- GetInterpolation() str
Return the Primvar’s interpolation, which is UsdGeomTokens->constant if unauthored.
Interpolation determines how the Primvar interpolates over a geometric primitive. See Interpolation of Geometric Primitive Variables
- GetName() str
UsdAttribute::GetName()
- GetNamespace() str
UsdAttribute::GetNamespace()
- GetPrimvarName() str
Returns the primvar’s name, devoid of the”primvars:”namespace.
This is the name by which clients should refer to the primvar, if not by its full attribute name - i.e. they should not, in general, use GetBaseName() . In the error condition in which this Primvar object is not backed by a properly namespaced UsdAttribute, return an empty TfToken.
- GetTimeSamples(times) bool
Populates a vector with authored sample times for this primvar.
Returns false on error.
This considers any timeSamples authored on the associated”indices”attribute if the primvar is indexed.
UsdAttribute::GetTimeSamples
- Parameters
times (list[float]) –
- GetTimeSamplesInInterval(interval, times) bool
Populates a vector with authored sample times in
interval
.This considers any timeSamples authored on the associated”indices”attribute if the primvar is indexed.
UsdAttribute::GetTimeSamplesInInterval
- Parameters
interval (Interval) –
times (list[float]) –
- GetTypeName() ValueTypeName
UsdAttribute::GetTypeName()
- GetUnauthoredValuesIndex() int
Returns the index that represents unauthored values in the indices array.
SetUnauthoredValuesIndex()
- HasAuthoredElementSize() bool
Has elementSize been explicitly authored on this Primvar?
GetElementSize()
- HasAuthoredInterpolation() bool
Has interpolation been explicitly authored on this Primvar?
GetInterpolationSize()
- HasAuthoredValue() bool
Return true if the underlying attribute has an unblocked, authored value.
- HasValue() bool
Return true if the underlying attribute has a value, either from authored scene description or a fallback.
- IsDefined() bool
Return true if the underlying UsdAttribute::IsDefined() , and in addition the attribute is identified as a Primvar.
Does not imply that the primvar provides a value
- IsIdTarget() bool
Returns true if the primvar is an Id primvar.
UsdGeomPrimvar_Id_primvars
- IsIndexed() bool
Returns true if the primvar is indexed, i.e., if it has an associated”indices”attribute.
If you are going to query the indices anyways, prefer to simply consult the return-value of GetIndices() , which will be more efficient.
- static IsPrimvar()
classmethod IsPrimvar(attr) -> bool
Test whether a given UsdAttribute represents valid Primvar, which implies that creating a UsdGeomPrimvar from the attribute will succeed.
Success implies that
attr.IsDefined()
is true.- Parameters
attr (Attribute) –
- static IsValidInterpolation()
classmethod IsValidInterpolation(interpolation) -> bool
Validate that the provided
interpolation
is a valid setting for interpolation as defined by Interpolation of Geometric Primitive Variables.- Parameters
interpolation (str) –
- static IsValidPrimvarName()
classmethod IsValidPrimvarName(name) -> bool
Test whether a given
name
represents a valid name of a primvar, which implies that creating a UsdGeomPrimvar with the given name will succeed.- Parameters
name (str) –
- NameContainsNamespaces() bool
Does this primvar contain any namespaces other than the”primvars:”namespace?
Some clients may only wish to consume primvars that have no extra namespaces in their names, for ease of translating to other systems that do not allow namespaces.
- Set(value, time) bool
Set the attribute value of the Primvar at
time
.- Parameters
value (T) –
time (TimeCode) –
- SetElementSize(eltSize) bool
Set the elementSize for this Primvar.
Errors and returns false if
eltSize
less than 1.GetElementSize()
- Parameters
eltSize (int) –
- SetIdTarget(path) bool
This primvar must be of String or StringArray type for this method to succeed.
If not, a coding error is raised.
UsdGeomPrimvar_Id_primvars
- Parameters
path (Path) –
- SetIndices(indices, time) bool
Sets the indices value of the indexed primvar at
time
.The values in the indices array must be valid indices into the authored array returned by Get() . The element numerality of the primvar’s’interpolation’metadata applies to the”indices”array, not the attribute value array (returned by Get() ).
- SetInterpolation(interpolation) bool
Set the Primvar’s interpolation.
Errors and returns false if
interpolation
is out of range as defined by IsValidInterpolation() . No attempt is made to validate that the Primvar’s value contains the right number of elements to match its interpolation to its topology.GetInterpolation() , Interpolation of Geometric Primitive Variables
- Parameters
interpolation (str) –
- SetUnauthoredValuesIndex(unauthoredValuesIndex) bool
Set the index that represents unauthored values in the indices array.
Some apps (like Maya) allow you to author primvars sparsely over a surface. Since most apps can’t handle sparse primvars, Maya needs to provide a value even for the elements it didn’t author. This metadatum provides a way to recover the information in apps that do support sparse authoring / representation of primvars.
The fallback value of unauthoredValuesIndex is -1, which indicates that there are no unauthored values.
GetUnauthoredValuesIndex()
- Parameters
unauthoredValuesIndex (int) –
- SplitName() list[str]
UsdAttribute::SplitName()
- static StripPrimvarsName()
classmethod StripPrimvarsName(name) -> str
Returns the
name
, devoid of the”primvars:”token if present, otherwise returns thename
unchanged.- Parameters
name (str) –
- ValueMightBeTimeVarying() bool
Return true if it is possible, but not certain, that this primvar’s value changes over time, false otherwise.
This considers time-varyingness of the associated”indices”attribute if the primvar is indexed.
UsdAttribute::ValueMightBeTimeVarying
- class pxr.UsdGeom.PrimvarsAPI
UsdGeomPrimvarsAPI encodes geometric”primitive variables”, as UsdGeomPrimvar, which interpolate across a primitive’s topology, can override shader inputs, and inherit down namespace.
Which Method to Use to Retrieve Primvars
While creating primvars is unambiguous ( CreatePrimvar() ), there are quite a few methods available for retrieving primvars, making it potentially confusing knowing which one to use. Here are some guidelines:
If you are populating a GUI with the primvars already available for authoring values on a prim, use GetPrimvars() .
If you want all of the”useful”(e.g. to a renderer) primvars available at a prim, including those inherited from ancestor prims, use FindPrimvarsWithInheritance() . Note that doing so individually for many prims will be inefficient.
To find a particular primvar defined directly on a prim, which may or may not provide a value, use GetPrimvar() .
To find a particular primvar defined on a prim or inherited from ancestors, which may or may not provide a value, use FindPrimvarWithInheritance() .
To efficiently query for primvars using the overloads of FindPrimvarWithInheritance() and FindPrimvarsWithInheritance() , one must first cache the results of FindIncrementallyInheritablePrimvars() for each non-leaf prim on the stage.
Methods:
BlockPrimvar
(name)Remove all time samples on the primvar and its associated indices attr, and author a block
default
value.classmethod CanContainPropertyName(name) -> bool
CreateIndexedPrimvar
(name, typeName, value, ...)Author scene description to create an attribute and authoring a
value
on this prim that will be recognized as an indexed Primvar withindices
appropriately set (i.e.CreateNonIndexedPrimvar
(name, typeName, ...)Author scene description to create an attribute and authoring a
value
on this prim that will be recognized as a Primvar (i.e.CreatePrimvar
(name, typeName, interpolation, ...)Author scene description to create an attribute on this prim that will be recognized as Primvar (i.e.
Compute the primvars that can be inherited from this prim by its child prims, starting from the set of primvars inherited from this prim's ancestors.
Compute the primvars that can be inherited from this prim by its child prims, including the primvars that this prim inherits from ancestor prims.
Like GetPrimvar() , but if the named primvar does not exist or has no authored value on this prim, search for the named, value-producing primvar on ancestor prims.
Find all of the value-producing primvars either defined on this prim, or inherited from ancestor prims.
classmethod Get(stage, path) -> PrimvarsAPI
Like GetPrimvars() , but include only primvars that have some authored scene description (though not necessarily a value).
GetPrimvar
(name)Return the Primvar object named by
name
, which will be valid if a Primvar attribute definition already exists.Return valid UsdGeomPrimvar objects for all defined Primvars on this prim, similarly to UsdPrim::GetAttributes() .
Like GetPrimvars() , but include only primvars that have an authored value.
Like GetPrimvars() , but include only primvars that have some value, whether it comes from authored scene description or a schema fallback.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Is there a Primvar named
name
with an authored value on this prim or any of its ancestors?HasPrimvar
(name)Is there a defined Primvar
name
on this prim?RemovePrimvar
(name)Author scene description to delete an attribute on this prim that was recognized as Primvar (i.e.
- BlockPrimvar(name) None
Remove all time samples on the primvar and its associated indices attr, and author a block
default
value.This will cause authored opinions in weaker layers to be ignored.
UsdAttribute::Block() , UsdGeomPrimvar::BlockIndices
- Parameters
name (str) –
- static CanContainPropertyName()
classmethod CanContainPropertyName(name) -> bool
Test whether a given
name
contains the”primvars:”prefix.- Parameters
name (str) –
- CreateIndexedPrimvar(name, typeName, value, indices, interpolation, elementSize, time) Primvar
Author scene description to create an attribute and authoring a
value
on this prim that will be recognized as an indexed Primvar withindices
appropriately set (i.e.will present as a valid UsdGeomPrimvar).
an invalid UsdGeomPrimvar on error, a valid UsdGeomPrimvar otherwise. It is fine to call this method multiple times, and in different UsdEditTargets, even if there is an existing primvar of the same name, indexed or not.
CreatePrimvar() , CreateNonIndexedPrimvar() , UsdPrim::CreateAttribute() , UsdGeomPrimvar::IsPrimvar()
- Parameters
name (str) –
typeName (ValueTypeName) –
value (T) –
indices (IntArray) –
interpolation (str) –
elementSize (int) –
time (TimeCode) –
- CreateNonIndexedPrimvar(name, typeName, value, interpolation, elementSize, time) Primvar
Author scene description to create an attribute and authoring a
value
on this prim that will be recognized as a Primvar (i.e.will present as a valid UsdGeomPrimvar). Note that unlike CreatePrimvar using this API explicitly authors a block for the indices attr associated with the primvar, thereby blocking any indices set in any weaker layers.
an invalid UsdGeomPrimvar on error, a valid UsdGeomPrimvar otherwise. It is fine to call this method multiple times, and in different UsdEditTargets, even if there is an existing primvar of the same name, indexed or not.
CreatePrimvar() , CreateIndexedPrimvar() , UsdPrim::CreateAttribute() , UsdGeomPrimvar::IsPrimvar()
- Parameters
name (str) –
typeName (ValueTypeName) –
value (T) –
interpolation (str) –
elementSize (int) –
time (TimeCode) –
- CreatePrimvar(name, typeName, interpolation, elementSize) Primvar
Author scene description to create an attribute on this prim that will be recognized as Primvar (i.e.
will present as a valid UsdGeomPrimvar).
The name of the created attribute may or may not be the specified
name
, due to the possible need to apply property namespacing for primvars. See Creating and Accessing Primvars for more information. Creation may fail and return an invalid Primvar ifname
contains a reserved keyword, such as the”indices”suffix we use for indexed primvars.The behavior with respect to the provided
typeName
is the same as for UsdAttributes::Create(), andinterpolation
andelementSize
are as described in UsdGeomPrimvar::GetInterpolation() and UsdGeomPrimvar::GetElementSize() .If
interpolation
and/orelementSize
are left unspecified, we will author no opinions for them, which means any (strongest) opinion already authored in any contributing layer for these fields will become the Primvar’s values, or the fallbacks if no opinions have been authored.an invalid UsdGeomPrimvar if we failed to create a valid attribute, a valid UsdGeomPrimvar otherwise. It is not an error to create over an existing, compatible attribute.
UsdPrim::CreateAttribute() , UsdGeomPrimvar::IsPrimvar()
- Parameters
name (str) –
typeName (ValueTypeName) –
interpolation (str) –
elementSize (int) –
- FindIncrementallyInheritablePrimvars(inheritedFromAncestors) list[Primvar]
Compute the primvars that can be inherited from this prim by its child prims, starting from the set of primvars inherited from this prim’s ancestors.
If this method returns an empty vector, then this prim’s children should inherit the same set of primvars available to this prim, i.e. the input
inheritedFromAncestors
.As opposed to FindInheritablePrimvars() , which always recurses up through all of the prim’s ancestors, this method allows more efficient computation of inheritable primvars by starting with the list of primvars inherited from this prim’s ancestors, and returning a newly allocated vector only when this prim makes a change to the set of inherited primvars. This enables O(n) inherited primvar computation for all prims on a Stage, with potential to share computed results that are identical (i.e. when this method returns an empty vector, its parent’s result can (and must!) be reused for all of the prim’s children.
Which Method to Use to Retrieve Primvars
- Parameters
inheritedFromAncestors (list[Primvar]) –
- FindInheritablePrimvars() list[Primvar]
Compute the primvars that can be inherited from this prim by its child prims, including the primvars that this prim inherits from ancestor prims.
Inherited primvars will be bound to attributes on the corresponding ancestor prims.
Only primvars with authored, non-blocked, constant interpolation values are inheritable; fallback values are not inherited. The order of the returned primvars is undefined.
It is not generally useful to call this method on UsdGeomGprim leaf prims, and furthermore likely to be expensive since most primvars are defined on Gprims.
Which Method to Use to Retrieve Primvars
- FindPrimvarWithInheritance(name) Primvar
Like GetPrimvar() , but if the named primvar does not exist or has no authored value on this prim, search for the named, value-producing primvar on ancestor prims.
The returned primvar will be bound to the attribute on the corresponding ancestor prim on which it was found (if any). If neither this prim nor any ancestor contains a value-producing primvar, then the returned primvar will be the same as that returned by GetPrimvar() .
This is probably the method you want to call when needing to consume a primvar of a particular name.
Which Method to Use to Retrieve Primvars
- Parameters
name (str) –
FindPrimvarWithInheritance(name, inheritedFromAncestors) -> Primvar
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This version of FindPrimvarWithInheritance() takes the pre-computed set of primvars inherited from this prim’s ancestors, as computed by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars() on the prim’s parent.
Which Method to Use to Retrieve Primvars
- Parameters
name (str) –
inheritedFromAncestors (list[Primvar]) –
- FindPrimvarsWithInheritance() list[Primvar]
Find all of the value-producing primvars either defined on this prim, or inherited from ancestor prims.
Which Method to Use to Retrieve Primvars
FindPrimvarsWithInheritance(inheritedFromAncestors) -> list[Primvar]
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This version of FindPrimvarsWithInheritance() takes the pre-computed set of primvars inherited from this prim’s ancestors, as computed by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars() on the prim’s parent.
Which Method to Use to Retrieve Primvars
- Parameters
inheritedFromAncestors (list[Primvar]) –
- static Get()
classmethod Get(stage, path) -> PrimvarsAPI
Return a UsdGeomPrimvarsAPI holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomPrimvarsAPI(stage->GetPrimAtPath(path));
- GetAuthoredPrimvars() list[Primvar]
Like GetPrimvars() , but include only primvars that have some authored scene description (though not necessarily a value).
Which Method to Use to Retrieve Primvars
- GetPrimvar(name) Primvar
Return the Primvar object named by
name
, which will be valid if a Primvar attribute definition already exists.Name lookup will account for Primvar namespacing, which means that this method will succeed in some cases where
UsdGeomPrimvar(prim->GetAttribute(name)) will not, unless ``name`` is properly namespace prefixed.
Just because a Primvar is valid and defined, and even if its underlying UsdAttribute (GetAttr()) answers HasValue() affirmatively, one must still check the return value of Get() , due to the potential of time-varying value blocks (see Attribute Value Blocking).
HasPrimvar() , Which Method to Use to Retrieve Primvars
- Parameters
name (str) –
- GetPrimvars() list[Primvar]
Return valid UsdGeomPrimvar objects for all defined Primvars on this prim, similarly to UsdPrim::GetAttributes() .
The returned primvars may not possess any values, and therefore not be useful to some clients. For the primvars useful for inheritance computations, see GetPrimvarsWithAuthoredValues() , and for primvars useful for direct consumption, see GetPrimvarsWithValues() .
Which Method to Use to Retrieve Primvars
- GetPrimvarsWithAuthoredValues() list[Primvar]
Like GetPrimvars() , but include only primvars that have an authored value.
This is the query used when computing inheritable primvars, and is generally more useful than GetAuthoredPrimvars() .
Which Method to Use to Retrieve Primvars
- GetPrimvarsWithValues() list[Primvar]
Like GetPrimvars() , but include only primvars that have some value, whether it comes from authored scene description or a schema fallback.
For most purposes, this method is more useful than GetPrimvars() .
Which Method to Use to Retrieve Primvars
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- HasPossiblyInheritedPrimvar(name) bool
Is there a Primvar named
name
with an authored value on this prim or any of its ancestors?This is probably the method you want to call when wanting to know whether or not the prim”has”a primvar of a particular name.
FindPrimvarWithInheritance()
- Parameters
name (str) –
- HasPrimvar(name) bool
Is there a defined Primvar
name
on this prim?Name lookup will account for Primvar namespacing.
Like GetPrimvar() , a return value of
true
for HasPrimvar() does not guarantee the primvar will produce a value.- Parameters
name (str) –
- RemovePrimvar(name) bool
Author scene description to delete an attribute on this prim that was recognized as Primvar (i.e.
will present as a valid UsdGeomPrimvar), in the current UsdEditTarget.
Because this method can only remove opinions about the primvar from the current EditTarget, you may generally find it more useful to use BlockPrimvar() which will ensure that all values from the EditTarget and weaker layers for the primvar and its indices will be ignored.
Removal may fail and return false if
name
contains a reserved keyword, such as the”indices”suffix we use for indexed primvars.Note this will also remove the indices attribute associated with an indiced primvar.
true if UsdGeomPrimvar and indices attribute was successfully removed, false otherwise.
UsdPrim::RemoveProperty() )
- Parameters
name (str) –
- class pxr.UsdGeom.Scope
Scope is the simplest grouping primitive, and does not carry the baggage of transformability. Note that transforms should inherit down through a Scope successfully - it is just a guaranteed no-op from a transformability perspective.
Methods:
classmethod Define(stage, path) -> Scope
classmethod Get(stage, path) -> Scope
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- static Define()
classmethod Define(stage, path) -> Scope
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Scope
Return a UsdGeomScope holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomScope(stage->GetPrimAtPath(path));
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Sphere
Defines a primitive sphere centered at the origin.
The fallback values for Cube, Sphere, Cone, and Cylinder are set so that they all pack into the same volume/bounds.
Methods:
CreateExtentAttr
(defaultValue, writeSparsely)See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateRadiusAttr
(defaultValue, writeSparsely)See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod Define(stage, path) -> Sphere
classmethod Get(stage, path) -> Sphere
Extent is re-defined on Sphere only to provide a fallback value.
Indicates the sphere's radius.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
- CreateExtentAttr(defaultValue, writeSparsely) Attribute
See GetExtentAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateRadiusAttr(defaultValue, writeSparsely) Attribute
See GetRadiusAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static Define()
classmethod Define(stage, path) -> Sphere
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Sphere
Return a UsdGeomSphere holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomSphere(stage->GetPrimAtPath(path));
- GetExtentAttr() Attribute
Extent is re-defined on Sphere only to provide a fallback value.
UsdGeomGprim::GetExtentAttr() .
Declaration
float3[] extent = [(-1, -1, -1), (1, 1, 1)]
C++ Type
VtArray<GfVec3f>
Usd Type
SdfValueTypeNames->Float3Array
- GetRadiusAttr() Attribute
Indicates the sphere’s radius.
If you author radius you must also author extent.
GetExtentAttr()
Declaration
double radius = 1
C++ Type
double
Usd Type
SdfValueTypeNames->Double
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- class pxr.UsdGeom.Subset
Encodes a subset of a piece of geometry (i.e. a UsdGeomImageable) as a set of indices. Currently only supports encoding of face-subsets, but could be extended in the future to support subsets representing edges, segments, points etc.
To apply to a geometric prim, a GeomSubset prim must be the prim’s direct child in namespace, and possess a concrete defining specifier (i.e. def). This restriction makes it easy and efficient to discover subsets of a prim. We might want to relax this restriction if it’s common to have multiple families of subsets on a gprim and if it’s useful to be able to organize subsets belonging to a family under a common scope. See’familyName’attribute for more info on defining a family of subsets.
Note that a GeomSubset isn’t an imageable (i.e. doesn’t derive from UsdGeomImageable). So, you can’t author visibility for it or override its purpose.
Materials are bound to GeomSubsets just as they are for regular geometry using API available in UsdShade (UsdShadeMaterial::Bind).
For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value”rightHanded”, use UsdGeomTokens->rightHanded as the value.
Methods:
CreateElementTypeAttr
(defaultValue, ...)See GetElementTypeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
CreateFamilyNameAttr
(defaultValue, writeSparsely)See GetFamilyNameAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod CreateGeomSubset(geom, subsetName, elementType, indices, familyName, familyType) -> Subset
CreateIndicesAttr
(defaultValue, writeSparsely)See GetIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
classmethod CreateUniqueGeomSubset(geom, subsetName, elementType, indices, familyName, familyType) -> Subset
classmethod Define(stage, path) -> Subset
classmethod Get(stage, path) -> Subset
classmethod GetAllGeomSubsetFamilyNames(geom) -> str.Set
classmethod GetAllGeomSubsets(geom) -> list[Subset]
The type of element that the indices target.
The name of the family of subsets that this subset belongs to.
classmethod GetFamilyType(geom, familyName) -> str
classmethod GetGeomSubsets(geom, elementType, familyName) -> list[Subset]
The set of indices included in this subset.
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
classmethod GetUnassignedIndices(subsets, elementCount, time) -> IntArray
classmethod SetFamilyType(geom, familyName, familyType) -> bool
classmethod ValidateFamily(geom, elementType, familyName, reason) -> bool
classmethod ValidateSubsets(subsets, elementCount, familyType, reason) -> bool
- CreateElementTypeAttr(defaultValue, writeSparsely) Attribute
See GetElementTypeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- CreateFamilyNameAttr(defaultValue, writeSparsely) Attribute
See GetFamilyNameAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static CreateGeomSubset()
classmethod CreateGeomSubset(geom, subsetName, elementType, indices, familyName, familyType) -> Subset
Creates a new GeomSubset below the given
geom
with the given name,subsetName
, element type,elementType
andindices
.If a subset named
subsetName
already exists belowgeom
, then this updates its attributes with the values of the provided arguments (indices value at time’default’will be updated) and returns it.The family type is set / updated on
geom
only if a non-empty value is passed in forfamilyType
andfamilyName
.
- CreateIndicesAttr(defaultValue, writeSparsely) Attribute
See GetIndicesAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
If specified, author
defaultValue
as the attribute’s default, sparsely (when it makes sense to do so) ifwriteSparsely
istrue
- the default forwriteSparsely
isfalse
.- Parameters
defaultValue (VtValue) –
writeSparsely (bool) –
- static CreateUniqueGeomSubset()
classmethod CreateUniqueGeomSubset(geom, subsetName, elementType, indices, familyName, familyType) -> Subset
Creates a new GeomSubset below the given imageable,
geom
with the given name,subsetName
, element type,elementType
andindices
.If a subset named
subsetName
already exists belowgeom
, then this creates a new subset by appending a suitable index as suffix tosubsetName
(eg, subsetName_1) to avoid name collisions.The family type is set / updated on
geom
only if a non-empty value is passed in forfamilyType
andfamilyName
.
- static Define()
classmethod Define(stage, path) -> Subset
Attempt to ensure a UsdPrim adhering to this schema at
path
is defined (according to UsdPrim::IsDefined() ) on this stage.If a prim adhering to this schema at
path
is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim atpath
at the current EditTarget. Author SdfPrimSpec s withspecifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
- static Get()
classmethod Get(stage, path) -> Subset
Return a UsdGeomSubset holding the prim adhering to this schema at
path
onstage
.If no prim exists at
path
onstage
, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:UsdGeomSubset(stage->GetPrimAtPath(path));
- static GetAllGeomSubsetFamilyNames()
classmethod GetAllGeomSubsetFamilyNames(geom) -> str.Set
Returns the names of all the families of GeomSubsets defined on the given imageable,
geom
.- Parameters
geom (Imageable) –
- static GetAllGeomSubsets()
classmethod GetAllGeomSubsets(geom) -> list[Subset]
Returns all the GeomSubsets defined on the given imageable,
geom
.- Parameters
geom (Imageable) –
- GetElementTypeAttr() Attribute
The type of element that the indices target.
Currently only allows”face”and defaults to it.
Declaration
uniform token elementType ="face"
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
Allowed Values
face
- GetFamilyNameAttr() Attribute
The name of the family of subsets that this subset belongs to.
This is optional and is primarily useful when there are multiple families of subsets under a geometric prim. In some cases, this could also be used for achieving proper roundtripping of subset data between DCC apps. When multiple subsets belonging to a prim have the same familyName, they are said to belong to the family. A familyType value can be encoded on the owner of a family of subsets as a token using the static method UsdGeomSubset::SetFamilyType() .”familyType”can have one of the following values:
UsdGeomTokens->partition : implies that every element of the whole geometry appears exactly once in only one of the subsets belonging to the family.
UsdGeomTokens->nonOverlapping : an element that appears in one subset may not appear in any other subset belonging to the family.
UsdGeomTokens->unrestricted : implies that there are no restrictions w.r.t. the membership of elements in the subsets. They could be overlapping and the union of all subsets in the family may not represent the whole.
The validity of subset data is not enforced by the authoring APIs, however they can be checked using UsdGeomSubset::ValidateFamily() .
Declaration
uniform token familyName =""
C++ Type
TfToken
Usd Type
SdfValueTypeNames->Token
Variability
SdfVariabilityUniform
- static GetFamilyType()
classmethod GetFamilyType(geom, familyName) -> str
Returns the type of family that the GeomSubsets on the given geometric prim
geom
, with the given family name,familyName
belong to.This only returns the token that’s encoded on
geom
and does not perform any actual validation on the family of GeomSubsets. Please use ValidateFamily() for such validation.When familyType is not set on
geom
, the fallback value UsdTokens->unrestricted is returned.- Parameters
geom (Imageable) –
familyName (str) –
- static GetGeomSubsets()
classmethod GetGeomSubsets(geom, elementType, familyName) -> list[Subset]
Returns all the GeomSubsets of the given
elementType
belonging to the specified family,familyName
on the given imageable,geom
.If
elementType
is empty, then subsets containing all element types are returned. IffamilyName
is left empty, then all subsets of the specifiedelementType
will be returned.- Parameters
geom (Imageable) –
elementType (str) –
familyName (str) –
- GetIndicesAttr() Attribute
The set of indices included in this subset.
The indices need not be sorted, but the same index should not appear more than once.
Declaration
int[] indices = []
C++ Type
VtArray<int>
Usd Type
SdfValueTypeNames->IntArray
- static GetSchemaAttributeNames()
classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
Does not include attributes that may be authored by custom/extended methods of the schemas involved.
- Parameters
includeInherited (bool) –
- static GetUnassignedIndices()
classmethod GetUnassignedIndices(subsets, elementCount, time) -> IntArray
Utility for getting the list of indices that are not assigned to any of the GeomSubsets in
subsets
at the timeCode,time
, given the element count (total number of indices in the array being subdivided),elementCount
.
- static SetFamilyType()
classmethod SetFamilyType(geom, familyName, familyType) -> bool
This method is used to encode the type of family that the GeomSubsets on the given geometric prim
geom
, with the given family name,familyName
belong to.See UsdGeomSubset::GetFamilyNameAttr for the possible values for
familyType
.When a family of GeomSubsets is tagged as a UsdGeomTokens->partition or UsdGeomTokens->nonOverlapping, the validity of the data (i.e. mutual exclusivity and/or wholeness) is not enforced by the authoring APIs. Use ValidateFamily() to validate the data in a family of GeomSubsets.
Returns false upon failure to create or set the appropriate attribute on
geom
.- Parameters
geom (Imageable) –
familyName (str) –
familyType (str) –
- static ValidateFamily()
classmethod ValidateFamily(geom, elementType, familyName, reason) -> bool
Validates whether the family of subsets identified by the given
familyName
andelementType
on the given imageable,geom
contain valid data.If the family is designated as a partition or as non-overlapping using SetFamilyType() , then the validity of the data is checked. If the familyType is”unrestricted”, then this performs only bounds checking of the values in the”indices”arrays.
If
reason
is not None, then it is populated with a string explaining why the family is invalid, if it is invalid.The python version of this method returns a tuple containing a (bool, string), where the bool has the validity of the family and the string contains the reason (if it’s invalid).
- Parameters
geom (Imageable) –
elementType (str) –
familyName (str) –
reason (str) –
- static ValidateSubsets()
classmethod ValidateSubsets(subsets, elementCount, familyType, reason) -> bool
Validates the data in the given set of GeomSubsets,
subsets
, given the total number of elements in the array being subdivided,elementCount
and thefamilyType
that the subsets belong to.For proper validation of indices in
subsets
, all of the GeomSubsets must have the same’elementType’.If one or more subsets contain invalid data, then false is returned and
reason
is populated with a string explaining the reason why it is invalid.The python version of this method returns a tuple containing a (bool, string), where the bool has the validity of the subsets and the string contains the reason (if they’re invalid).
- Parameters
subsets (list[Subset]) –
elementCount (int) –
familyType (str) –
reason (str) –
- class pxr.UsdGeom.Tokens
Attributes: