UsdGeom module

Summary: The UsdGeom module defines 3D graphics-related prim and property schemas that form a basis for geometry interchange.

Classes:

`BBoxCache`	Caches bounds by recursively computing and aggregating bounds of children in world space and aggregating the result back into local space.
`BasisCurves`	BasisCurves are a batched curve representation analogous to the classic RIB definition via Basis and Curves statements.
`Boundable`	Boundable introduces the ability for a prim to persistently cache a rectilinear, local-space, extent.
`Camera`	Transformable camera.
`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.
`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.
`ConstraintTarget`	Schema wrapper for UsdAttribute for authoring and introspecting attributes that are constraint targets.
`Cube`	Defines a primitive rectilinear cube centered at the origin.
`Curves`	Base class for UsdGeomBasisCurves, UsdGeomNurbsCurves, and UsdGeomHermiteCurves.
`Cylinder`	Defines a primitive cylinder with closed ends, centered at the origin, whose spine is along the specified axis.
`Gprim`	Base class for all geometric primitives.
`HermiteCurves`	This schema specifies a cubic hermite interpolated curve batch as sometimes used for defining guides for animation.
`Imageable`	Base class for all prims that may require rendering or visualization of some sort.
`LinearUnits`
`Mesh`	Encodes a mesh with optional subdivision properties and features.
`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.
`MotionAPI`	UsdGeomMotionAPI encodes data that can live on any prim that may affect computations involving:
`NurbsCurves`	This schema is analagous to NURBS Curves in packages like Maya and Houdini, often used for interchange of rigging and modeling curves.
`NurbsPatch`	Encodes a rational or polynomial non-uniform B-spline surface, with optional trim curves.
`Plane`	Defines a primitive plane, centered at the origin, and is defined by a cardinal axis, width, and length.
`PointBased`	Base class for all UsdGeomGprims that possess points, providing common attributes such as normals and velocities.
`PointInstancer`	Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters), which can be arbitrary prims/subtrees on a UsdStage.
`Points`	Points are analogous to the RiPoints spec.
`Primvar`	Schema wrapper for UsdAttribute for authoring and introspecting attributes that are primvars.
`PrimvarsAPI`	UsdGeomPrimvarsAPI encodes geometric"primitive variables", as UsdGeomPrimvar, which interpolate across a primitive's topology, can override shader inputs, and inherit down namespace.
`Scope`	Scope is the simplest grouping primitive, and does not carry the baggage of transformability.
`Sphere`	Defines a primitive sphere centered at the origin.
`Subset`	Encodes a subset of a piece of geometry (i.e.
`Tokens`
`VisibilityAPI`	UsdGeomVisibilityAPI introduces properties that can be used to author visibility opinions.
`Xform`	Concrete prim schema for a transform, which implements Xformable
`XformCache`	A caching mechanism for transform matrices.
`XformCommonAPI`	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.
`XformOp`	Schema wrapper for UsdAttribute for authoring and computing transformation operations, as consumed by UsdGeomXformable schema.
`XformOpTypes`
`Xformable`	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.
`ClearBaseTime`()	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` .
`ComputePointInstanceRelativeBounds`(...)	Compute the bounds of the given point instances in the space of an ancestor prim `relativeToAncestorPrim` .
`ComputePointInstanceUntransformedBound`(...)	Computes the bound of the given point instances, but does not include the instancer's transform.
`ComputePointInstanceUntransformedBounds`(...)	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.
`ComputeUntransformedBound`(prim)	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` .
`GetBaseTime`()	Return the base time if set, otherwise GetTime() .
`GetIncludedPurposes`()	Get the current set of included purposes.
`GetTime`()	Get the current time from which this cache is reading values.
`GetUseExtentsHint`()	Returns whether authored extent hints are used to compute bounding boxes.
`HasBaseTime`()	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.

Clear() → None: Clears all pre-cached values.

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 to numIds 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 if relativeToAncestorPrim is not an ancestor of prim .

The result pointer must point to numIds 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 to numIds 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 to numIds 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 if relativeToAncestorPrim is not an ancestor of prim .

Parameters

prim (Prim) –
relativeToAncestorPrim (Prim) –

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 the ctmOverrides 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.

Parameters

prim (Prim) –
pathsToSkip (SdfPathSet) –
ctmOverrides (TfHashMap[Path, Matrix4d, Path.Hash]) –

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. If prim is invalid, this method will abort the program; therefore it is the client’s responsibility to ensure prim 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 and ctmOverrides 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.

Parameters

prim (Prim) –
pathsToSkip (SdfPathSet) –
primOverride (Matrix4d) –
ctmOverrides (TfHashMap[Path, Matrix4d, Path.Hash]) –

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.

GetTime() → TimeCode: Get the current time from which this cache is reading values.

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]) –

SetTime(time) → None

Use the new time when computing values and may clear any existing values cached for the previous time.

Setting time to the current time is a no-op.

Parameters: time (TimeCode) –

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]

periodic

linear

N/A

[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.
`Define`	classmethod Define(stage, path) -> BasisCurves
`Get`	classmethod Get(stage, path) -> BasisCurves
`GetBasisAttr`()	The basis specifies the vstep and matrix used for cubic interpolation.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetTypeAttr`()	Linear curves interpolate linearly between two vertices.
`GetWrapAttr`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> BasisCurves

Return a UsdGeomBasisCurves holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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:

`ComputeExtent`	classmethod ComputeExtent(radius, extent) -> bool
`ComputeExtentFromPlugins`	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.
`Get`	classmethod Get(stage, path) -> Boundable
`GetExtentAttr`()	Extent is a three dimensional range measuring the geometric extent of the authored gprim in its own local space (i.e.
`GetSchemaAttributeNames`	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 time time .

If successful, populates extent with the result and returns true , otherwise returns false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> Boundable

Return a UsdGeomBoundable holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`CreateHorizontalApertureOffsetAttr`(...)	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.
`CreateVerticalApertureOffsetAttr`(...)	See GetVerticalApertureOffsetAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Define`	classmethod Define(stage, path) -> Camera
`Get`	classmethod Get(stage, path) -> Camera
`GetCamera`(time)	Creates a GfCamera object from the attribute values at `time` .
`GetClippingPlanesAttr`()	Additional, arbitrarily oriented clipping planes.
`GetClippingRangeAttr`()	Near and far clipping distances in scene units; see Units of Measure for Camera Properties.
`GetExposureAttr`()	Exposure adjustment, as a log base-2 value.
`GetFStopAttr`()	Lens aperture.
`GetFocalLengthAttr`()	Perspective focal length in tenths of a scene unit; see Units of Measure for Camera Properties.
`GetFocusDistanceAttr`()	Distance from the camera to the focus plane in scene units; see Units of Measure for Camera Properties.
`GetHorizontalApertureAttr`()	Horizontal aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
`GetHorizontalApertureOffsetAttr`()	Horizontal aperture offset in the same units as horizontalAperture.
`GetProjectionAttr`()	Declaration
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetShutterCloseAttr`()	Frame relative shutter close time, analogous comments from shutter:open apply.
`GetShutterOpenAttr`()	Frame relative shutter open time in UsdTimeCode units (negative value indicates that the shutter opens before the current frame time).
`GetStereoRoleAttr`()	If different from mono, the camera is intended to be the left or right camera of a stereo setup.
`GetVerticalApertureAttr`()	Vertical aperture in tenths of a scene unit; see Units of Measure for Camera Properties.
`GetVerticalApertureOffsetAttr`()	Vertical aperture offset in the same units as verticalAperture.
`SetFromCamera`(camera, time)	Write attribute values from `camera` for `time` .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Camera

Return a UsdGeomCamera holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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 for time .

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.

Parameters

camera (Camera) –
time (TimeCode) –

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.
`Define`	classmethod Define(stage, path) -> Capsule
`Get`	classmethod Get(stage, path) -> Capsule
`GetAxisAttr`()	The axis along which the spine of the capsule is aligned.
`GetExtentAttr`()	Extent is re-defined on Capsule only to provide a fallback value.
`GetHeightAttr`()	The size of the capsule's spine along the specified axis excluding the size of the two half spheres, i.e.
`GetRadiusAttr`()	The radius of the capsule.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Capsule

Return a UsdGeomCapsule holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`Define`	classmethod Define(stage, path) -> Cone
`Get`	classmethod Get(stage, path) -> Cone
`GetAxisAttr`()	The axis along which the spine of the cone is aligned.
`GetExtentAttr`()	Extent is re-defined on Cone only to provide a fallback value.
`GetHeightAttr`()	The size of the cone's spine along the specified axis.
`GetRadiusAttr`()	The radius of the cone.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Cone

Return a UsdGeomCone holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`GetConstraintAttrName`	classmethod GetConstraintAttrName(constraintName) -> str
`GetIdentifier`()	Get the stored identifier unique to the enclosing model's namespace for this constraint target.
`IsDefined`()	Return true if the wrapped UsdAttribute::IsDefined() , and in addition the attribute is identified as a ConstraintTarget.
`IsValid`	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 .

Parameters

value (Matrix4d) –
time (TimeCode) –

GetAttr() → Attribute: Explicit UsdAttribute extractor.

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 .

Parameters

value (Matrix4d) –
time (TimeCode) –

SetIdentifier(identifier) → None

Explicitly sets the stored identifier to the given string.

Clients are responsible for ensuring the uniqueness of this identifier within the enclosing model’s namespace.

Parameters: identifier (str) –

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.
`Define`	classmethod Define(stage, path) -> Cube
`Get`	classmethod Get(stage, path) -> Cube
`GetExtentAttr`()	Extent is re-defined on Cube only to provide a fallback value.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetSizeAttr`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Cube

Return a UsdGeomCube holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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) –

GetSizeAttr() → Attribute

Indicates the length of each edge of the cube.

If you author size you must also author extent.

GetExtentAttr()

Declaration

double size = 2

C++ Type

double

Usd Type

SdfValueTypeNames->Double

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:

`ComputeExtent`	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.
`Get`	classmethod Get(stage, path) -> Curves
`GetCurveCount`(timeCode)	Returns the number of curves as defined by the size of the curveVertexCounts array at timeCode.
`GetCurveVertexCountsAttr`()	Curves-derived primitives can represent multiple distinct, potentially disconnected curves.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetWidthsAttr`()	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.
`GetWidthsInterpolation`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> Curves

Return a UsdGeomCurves holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`Define`	classmethod Define(stage, path) -> Cylinder
`Get`	classmethod Get(stage, path) -> Cylinder
`GetAxisAttr`()	The axis along which the spine of the cylinder is aligned.
`GetExtentAttr`()	Extent is re-defined on Cylinder only to provide a fallback value.
`GetHeightAttr`()	The size of the cylinder's spine along the specified axis.
`GetRadiusAttr`()	The radius of the cylinder.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Cylinder

Return a UsdGeomCylinder holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`Get`	classmethod Get(stage, path) -> Gprim
`GetDisplayColorAttr`()	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.
`GetDisplayColorPrimvar`()	Convenience function to get the displayColor Attribute as a Primvar.
`GetDisplayOpacityAttr`()	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.
`GetDisplayOpacityPrimvar`()	Convenience function to get the displayOpacity Attribute as a Primvar.
`GetDoubleSidedAttr`()	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.
`GetOrientationAttr`()	Orientation specifies whether the gprim's surface normal should be computed using the right hand rule, or the left hand rule.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> Gprim

Return a UsdGeomGprim holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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:

PointAndTangentArrays

Methods:

`CreateTangentsAttr`(defaultValue, writeSparsely)	See GetTangentsAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Define`	classmethod Define(stage, path) -> HermiteCurves
`Get`	classmethod Get(stage, path) -> HermiteCurves
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetTangentsAttr`()	Defines the outgoing trajectory tangent for each point.

class PointAndTangentArrays

Methods:

`GetPoints`
`GetTangents`
`Interleave`
`IsEmpty`
`Separate`

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> HermiteCurves

Return a UsdGeomHermiteCurves holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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) –

GetTangentsAttr() → Attribute

Defines the outgoing trajectory tangent for each point.

Tangents should be the same size as the points attribute.

Declaration

vector3f[] tangents = []

C++ Type

VtArray<GfVec3f>

Usd Type

SdfValueTypeNames->Vector3fArray

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:

PurposeInfo

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.
`ComputeLocalToWorldTransform`(time)	Compute the transformation matrix for this prim at the given time, including the transform authored on the Prim itself, if present.
`ComputeParentToWorldTransform`(time)	Compute the transformation matrix for this prim at the given time, NOT including the transform authored on the prim itself.
`ComputeProxyPrim`	Returns None if neither this prim nor any of its ancestors has a valid renderProxy prim.
`ComputePurpose`()	Calculate the effective purpose information about this prim.
`ComputePurposeInfo`()	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.
`CreateProxyPrimRel`()	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.
`Get`	classmethod Get(stage, path) -> Imageable
`GetOrderedPurposeTokens`	classmethod GetOrderedPurposeTokens() -> list[str]
`GetProxyPrimRel`()	The proxyPrim relationship allows us to link a prim whose purpose is"render"to its (single target) purpose="proxy"prim.
`GetPurposeAttr`()	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` .
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetVisibilityAttr`()	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:

GetInheritablePurpose

Attributes:

`isInheritable`
`purpose`

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> Imageable

Return a UsdGeomImageable holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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`
`feet`
`inches`
`kilometers`
`lightYears`
`meters`
`micrometers`
`miles`
`millimeters`
`nanometers`
`yards`

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.
`CreateFaceVaryingLinearInterpolationAttr`(...)	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.
`CreateTriangleSubdivisionRuleAttr`(...)	See GetTriangleSubdivisionRuleAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Define`	classmethod Define(stage, path) -> Mesh
`Get`	classmethod Get(stage, path) -> Mesh
`GetCornerIndicesAttr`()	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).
`GetCornerSharpnessesAttr`()	The sharpness values associated with a corresponding set of points specified in cornerIndices (so the size of this array must match that of cornerIndices).
`GetCreaseIndicesAttr`()	The indices of points grouped into sets of successive pairs that identify edges to be creased.
`GetCreaseLengthsAttr`()	The length of this array specifies the number of creases (sets of adjacent sharpened edges) on the mesh.
`GetCreaseSharpnessesAttr`()	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.
`GetFaceVaryingLinearInterpolationAttr`()	Specifies how elements of a primvar of interpolation type"faceVarying"are interpolated for subdivision surfaces.
`GetFaceVertexCountsAttr`()	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.
`GetFaceVertexIndicesAttr`()	Flat list of the index (into the points attribute) of each vertex of each face in the mesh.
`GetHoleIndicesAttr`()	The indices of all faces that should be treated as holes, i.e.
`GetInterpolateBoundaryAttr`()	Specifies how subdivision is applied for faces adjacent to boundary edges and boundary points.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetSubdivisionSchemeAttr`()	The subdivision scheme to be applied to the surface.
`GetTriangleSubdivisionRuleAttr`()	Specifies an option to the subdivision rules for the Catmull-Clark scheme to try and improve undesirable artifacts when subdividing triangles.
`ValidateTopology`	classmethod ValidateTopology(faceVertexIndices, faceVertexCounts, numPoints, reason) -> bool

Attributes:

SHARPNESS_INFINITE

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Mesh

Return a UsdGeomMesh holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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 the faceVertexIndices array, and that all face vertex indices in the faceVertexIndices array are in the range [0, numPoints). Returns true if the topology is valid, or false otherwise. If the topology is invalid and reason is non-null, an error message describing the validation error will be set.

Parameters

faceVertexIndices (IntArray) –
faceVertexCounts (IntArray) –
numPoints (int) –
reason (str) –

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:

`Apply`	classmethod Apply(prim) -> ModelAPI
`CanApply`	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.
`Get`	classmethod Get(stage, path) -> ModelAPI
`GetConstraintTarget`(constraintName)	Get the constraint target with the given name, `constraintName` .
`GetConstraintTargets`()	Returns all the constraint targets belonging to the model.
`GetExtentsHint`(extents, time)	Retrieve the authored value (if any) of this model's"extentsHint".
`GetExtentsHintAttr`()	Returns the custom'extentsHint'attribute if it exits.
`GetModelApplyDrawModeAttr`()	If true, and the resolved value of model:drawMode is non-default, apply an alternate imaging mode to this prim.
`GetModelCardGeometryAttr`()	The geometry to generate for imaging prims inserted for cards imaging mode.
`GetModelCardTextureXNegAttr`()	In cards imaging mode, the texture applied to the X- quad.
`GetModelCardTextureXPosAttr`()	In cards imaging mode, the texture applied to the X+ quad.
`GetModelCardTextureYNegAttr`()	In cards imaging mode, the texture applied to the Y- quad.
`GetModelCardTextureYPosAttr`()	In cards imaging mode, the texture applied to the Y+ quad.
`GetModelCardTextureZNegAttr`()	In cards imaging mode, the texture applied to the Z- quad.
`GetModelCardTextureZPosAttr`()	In cards imaging mode, the texture applied to the Z+ quad.
`GetModelDrawModeAttr`()	Alternate imaging mode; applied to this prim or child prims where model:applyDrawMode is true, or where the prim has kind component.
`GetModelDrawModeColorAttr`()	The base color of imaging prims inserted for alternate imaging modes.
`GetSchemaAttributeNames`	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, the bboxCache 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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> ModelAPI

Return a UsdGeomModelAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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) –

GetExtentsHintAttr() → Attribute: Returns the custom’extentsHint’attribute if it exits.

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:

`Apply`	classmethod Apply(prim) -> MotionAPI
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`ComputeMotionBlurScale`(time)	Compute the inherited value of motion:blurScale at `time` , i.e.
`ComputeNonlinearSampleCount`(time)	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.
`Get`	classmethod Get(stage, path) -> MotionAPI
`GetMotionBlurScaleAttr`()	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.
`GetNonlinearSampleCountAttr`()	Determines the number of position or transformation samples created when motion is described by attributes contributing non-linear terms.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetVelocityScaleAttr`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> MotionAPI

Return a UsdGeomMotionAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`Define`	classmethod Define(stage, path) -> NurbsCurves
`Get`	classmethod Get(stage, path) -> NurbsCurves
`GetFormAttr`()	Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous curve.
`GetKnotsAttr`()	Knot vector providing curve parameterization.
`GetOrderAttr`()	Order of the curve.
`GetPointWeightsAttr`()	Optionally provides"w"components for each control point, thus must be the same length as the points attribute.
`GetRangesAttr`()	Provides the minimum and maximum parametric values (as defined by knots) over which the curve is actually defined.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> NurbsCurves

Return a UsdGeomNurbsCurves holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`CreateTrimCurveVertexCountsAttr`(...)	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.
`Define`	classmethod Define(stage, path) -> NurbsPatch
`Get`	classmethod Get(stage, path) -> NurbsPatch
`GetPointWeightsAttr`()	Optionally provides"w"components for each control point, thus must be the same length as the points attribute.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetTrimCurveCountsAttr`()	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.
`GetTrimCurveKnotsAttr`()	Flat list of parametric values for each of the nCurves curves.
`GetTrimCurveOrdersAttr`()	Flat list of orders for each of the nCurves curves.
`GetTrimCurvePointsAttr`()	Flat list of homogeneous 2D points (u, v, w) that comprise the nCurves curves.
`GetTrimCurveRangesAttr`()	Flat list of minimum and maximum parametric values (as defined by knots) for each of the nCurves curves.
`GetTrimCurveVertexCountsAttr`()	Flat list of number of vertices for each of the nCurves curves.
`GetUFormAttr`()	Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the U dimension.
`GetUKnotsAttr`()	Knot vector for U direction providing U parameterization.
`GetUOrderAttr`()	Order in the U direction.
`GetURangeAttr`()	Provides the minimum and maximum parametric values (as defined by uKnots) over which the surface is actually defined.
`GetUVertexCountAttr`()	Number of vertices in the U direction.
`GetVFormAttr`()	Interpret the control grid and knot vectors as representing an open, geometrically closed, or geometrically closed and C2 continuous surface along the V dimension.
`GetVKnotsAttr`()	Knot vector for V direction providing U parameterization.
`GetVOrderAttr`()	Order in the V direction.
`GetVRangeAttr`()	Provides the minimum and maximum parametric values (as defined by vKnots) over which the surface is actually defined.
`GetVVertexCountAttr`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> NurbsPatch

Return a UsdGeomNurbsPatch holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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

GetVVertexCountAttr() → Attribute

Number of vertices in the V direction.

Should be at least as large as vOrder.

Declaration

int vVertexCount

C++ Type

int

Usd Type

SdfValueTypeNames->Int

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.
`Define`	classmethod Define(stage, path) -> Plane
`Get`	classmethod Get(stage, path) -> Plane
`GetAxisAttr`()	The axis along which the surface of the plane is aligned.
`GetDoubleSidedAttr`()	Planes are double-sided by default.
`GetExtentAttr`()	Extent is re-defined on Plane only to provide a fallback value.
`GetLengthAttr`()	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'.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetWidthAttr`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Plane

Return a UsdGeomPlane holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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) –

GetWidthAttr() → Attribute

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

If you author width you must also author extent.

UsdGeomGprim::GetExtentAttr()

Declaration

double width = 2

C++ Type

double

Usd Type

SdfValueTypeNames->Double

class pxr.UsdGeom.PointBased

Base class for all UsdGeomGprims that possess points, providing common attributes such as normals and velocities.

Methods:

`ComputeExtent`	classmethod ComputeExtent(points, extent) -> bool
`ComputePointsAtTime`	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.
`Get`	classmethod Get(stage, path) -> PointBased
`GetAccelerationsAttr`()	If provided,'accelerations'should be used with velocities to compute positions between samples for the'points'attribute rather than interpolating between neighboring'points'samples.
`GetNormalsAttr`()	Provide an object-space orientation for individual points, which, depending on subclass, may define a surface, curve, or free points.
`GetNormalsInterpolation`()	Get the interpolation for the normals attribute.
`GetPointsAttr`()	The primary geometry attribute for all PointBased primitives, describes points in (local) space.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetVelocitiesAttr`()	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 leave points untouched if:

points is None

one of time and baseTime 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 and points 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 for baseTime that it does for time . When baseTime is less than or equal to time , we will choose the lower bracketing timeSample.

Parameters

points (VtArray[Vec3f]) –
time (TimeCode) –
baseTime (TimeCode) –

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.

Parameters

pointsArray (list[VtArray[Vec3f]]) –
times (list[TimeCode]) –
baseTime (TimeCode) –

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> PointBased

Return a UsdGeomPointBased holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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,

def PointInstancer "Crowd_Mid"
{
   rel prototypes = [ </Crowd_Mid/Prototypes/MaleThin_Business>, </Crowd_Mid/Prototypes/MaleThin_Casual> ]
04
   over "Prototypes"
   {
        def "MaleThin_Business" (
            references = [@MaleGroupA/usd/MaleGroupA.usd@</MaleGroupA>]
            variants = {
                string modelingVariant = "Thin"
                string costumeVariant = "BusinessAttire"
            }
        )
        { \.\.\. }
15
        def "MaleThin_Casual"
        \.\.\.
   }
}

Classes:

`MaskApplication`	Encodes whether to evaluate and apply the PointInstancer's mask to computed results.
`ProtoXformInclusion`	Encodes whether to include each prototype's root prim's transformation as the most-local component of computed instance transforms.

Methods:

`ActivateAllIds`()	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` .
`ComputeInstanceTransformsAtTime`	classmethod ComputeInstanceTransformsAtTime(xforms, time, baseTime, doProtoXforms, applyMask) -> bool
`ComputeInstanceTransformsAtTimes`(...)	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.
`CreatePrototypesRel`()	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.
`Define`	classmethod Define(stage, path) -> PointInstancer
`Get`	classmethod Get(stage, path) -> PointInstancer
`GetAccelerationsAttr`()	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.
`GetAngularVelocitiesAttr`()	If authored, per-instance angular velocity vector to be used for interoplating orientations.
`GetIdsAttr`()	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.
`GetInvisibleIdsAttr`()	A list of id's to make invisible at the evaluation time.
`GetOrientationsAttr`()	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.
`GetPositionsAttr`()	Required property.
`GetProtoIndicesAttr`()	Required property.
`GetPrototypesRel`()	Required property.
`GetScalesAttr`()	If authored, per-instance scale to be applied to each instance, before any rotation is applied.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetVelocitiesAttr`()	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 at `time`
`InvisIds`(ids, time)	Ensure that the instances identified by `ids` are invisible at `time` .
`VisAllIds`(time)	Ensure that all instances are visible at `time` .
`VisId`(id, time)	Ensure that the instance identified by `id` is visible at `time` .
`VisIds`(ids, time)	Ensure that the instances identified by `ids` are visible at `time` .

Attributes:

`ApplyMask`
`ExcludeProtoXform`
`IgnoreMask`
`IncludeProtoXform`

class MaskApplication

Encodes whether to evaluate and apply the PointInstancer’s mask to computed results.

ComputeMaskAtTime()

Methods:

GetValueFromName

Attributes:

allValues

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:

GetValueFromName

Attributes:

allValues

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 and extent will be the tightest bounds we can compute efficiently. If an error occurs, false will be returned and extent 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 for baseTime that it does for time . When baseTime is less than or equal to time , 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 in times .

As in ComputeExtentAtTime, if there is no error, we return true and extents will be the tightest bounds we can compute efficiently. If an error occurs computing the extent at any time, false will be returned and extents 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 leave xforms untouched if:

xforms is None

one of time and baseTime 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 is IncludeProtoXform but an index value in protoIndices is outside the range [0, prototypes.size())

applyMask is ApplyMask 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 and xforms 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 for baseTime that it does for time . When baseTime is less than or equal to time , 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 at time . 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 a true 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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> PointInstancer

Return a UsdGeomPointInstancer holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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 at time .

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 at time .

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 at time .

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 at time .

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 at time .

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 at time . 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 at time .

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 at time . 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:

`ComputeExtent`	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.
`Define`	classmethod Define(stage, path) -> Points
`Get`	classmethod Get(stage, path) -> Points
`GetIdsAttr`()	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.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetWidthsAttr`()	Widths are defined as the diameter of the points, in object space.
`GetWidthsInterpolation`()	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Points

Return a UsdGeomPoints holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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:

`BlockIndices`()	Block the indices that were previously set.
`ComputeFlattened`	classmethod ComputeFlattened(value, time) -> bool
`CreateIndicesAttr`()	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.
`GetBaseName`()	UsdAttribute::GetBaseName()
`GetDeclarationInfo`(name, typeName, ...)	Convenience function for fetching all information required to properly declare this Primvar.
`GetElementSize`()	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` .
`GetIndicesAttr`()	Returns a valid indices attribute if the primvar is indexed.
`GetInterpolation`()	Return the Primvar's interpolation, which is UsdGeomTokens->constant if unauthored.
`GetName`()	UsdAttribute::GetName()
`GetNamespace`()	UsdAttribute::GetNamespace()
`GetPrimvarName`()	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` .
`GetTypeName`()	UsdAttribute::GetTypeName()
`GetUnauthoredValuesIndex`()	Returns the index that represents unauthored values in the indices array.
`HasAuthoredElementSize`()	Has elementSize been explicitly authored on this Primvar?
`HasAuthoredInterpolation`()	Has interpolation been explicitly authored on this Primvar?
`HasAuthoredValue`()	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.
`IsDefined`()	Return true if the underlying UsdAttribute::IsDefined() , and in addition the attribute is identified as a Primvar.
`IsIdTarget`()	Returns true if the primvar is an Id primvar.
`IsIndexed`()	Returns true if the primvar is indexed, i.e., if it has an associated"indices"attribute.
`IsPrimvar`	classmethod IsPrimvar(attr) -> bool
`IsValidInterpolation`	classmethod IsValidInterpolation(interpolation) -> bool
`IsValidPrimvarName`	classmethod IsValidPrimvarName(name) -> bool
`NameContainsNamespaces`()	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.
`SplitName`()	UsdAttribute::SplitName()
`StripPrimvarsName`	classmethod StripPrimvarsName(name) -> str
`ValueMightBeTimeVarying`()	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 given indices .

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 in attrVal is not a supported type for flattening. Otherwise returns true . The output errString 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) –

GetAttr() → Attribute: Explicit UsdAttribute extractor.

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

Parameters

indices (IntArray) –
time (TimeCode) –

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

Parameters

indices (IntArray) –
time (TimeCode) –

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 the name 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.
`CanContainPropertyName`	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 with `indices` 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.
`FindIncrementallyInheritablePrimvars`(...)	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.
`FindInheritablePrimvars`()	Compute the primvars that can be inherited from this prim by its child prims, including the primvars that this prim inherits from ancestor prims.
`FindPrimvarWithInheritance`(name)	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.
`FindPrimvarsWithInheritance`()	Find all of the value-producing primvars either defined on this prim, or inherited from ancestor prims.
`Get`	classmethod Get(stage, path) -> PrimvarsAPI
`GetAuthoredPrimvars`()	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.
`GetPrimvars`()	Return valid UsdGeomPrimvar objects for all defined Primvars on this prim, similarly to UsdPrim::GetAttributes() .
`GetPrimvarsWithAuthoredValues`()	Like GetPrimvars() , but include only primvars that have an authored value.
`GetPrimvarsWithValues`()	Like GetPrimvars() , but include only primvars that have some value, whether it comes from authored scene description or a schema fallback.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`HasPossiblyInheritedPrimvar`(name)	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 with indices 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 if name 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(), and interpolation and elementSize are as described in UsdGeomPrimvar::GetInterpolation() and UsdGeomPrimvar::GetElementSize() .

If interpolation and/or elementSize 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 on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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:

`Define`	classmethod Define(stage, path) -> Scope
`Get`	classmethod Get(stage, path) -> Scope
`GetSchemaAttributeNames`	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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Scope

Return a UsdGeomScope holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`Define`	classmethod Define(stage, path) -> Sphere
`Get`	classmethod Get(stage, path) -> Sphere
`GetExtentAttr`()	Extent is re-defined on Sphere only to provide a fallback value.
`GetRadiusAttr`()	Indicates the sphere's radius.
`GetSchemaAttributeNames`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Sphere

Return a UsdGeomSphere holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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.
`CreateGeomSubset`	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.
`CreateUniqueGeomSubset`	classmethod CreateUniqueGeomSubset(geom, subsetName, elementType, indices, familyName, familyType) -> Subset
`Define`	classmethod Define(stage, path) -> Subset
`Get`	classmethod Get(stage, path) -> Subset
`GetAllGeomSubsetFamilyNames`	classmethod GetAllGeomSubsetFamilyNames(geom) -> str.Set
`GetAllGeomSubsets`	classmethod GetAllGeomSubsets(geom) -> list[Subset]
`GetElementTypeAttr`()	The type of element that the indices target.
`GetFamilyNameAttr`()	The name of the family of subsets that this subset belongs to.
`GetFamilyType`	classmethod GetFamilyType(geom, familyName) -> str
`GetGeomSubsets`	classmethod GetGeomSubsets(geom, elementType, familyName) -> list[Subset]
`GetIndicesAttr`()	The set of indices included in this subset.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetUnassignedIndices`	classmethod GetUnassignedIndices(subsets, elementCount, time) -> IntArray
`SetFamilyType`	classmethod SetFamilyType(geom, familyName, familyType) -> bool
`ValidateFamily`	classmethod ValidateFamily(geom, elementType, familyName, reason) -> bool
`ValidateSubsets`	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) if writeSparsely is true - the default for writeSparsely is false .

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) if writeSparsely is true - the default for writeSparsely is false .

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 and indices .

If a subset named subsetName already exists below geom , 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 for familyType and familyName .

Parameters

geom (Imageable) –
subsetName (str) –
elementType (str) –
indices (IntArray) –
familyName (str) –
familyType (str) –

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) if writeSparsely is true - the default for writeSparsely is false .

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 and indices .

If a subset named subsetName already exists below geom , then this creates a new subset by appending a suitable index as suffix to subsetName (eg, subsetName_1) to avoid name collisions.

The family type is set / updated on geom only if a non-empty value is passed in for familyType and familyName .

Parameters

geom (Imageable) –
subsetName (str) –
elementType (str) –
indices (IntArray) –
familyName (str) –
familyType (str) –

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Subset

Return a UsdGeomSubset holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , 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));

Parameters

stage (Stage) –
path (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. If familyName is left empty, then all subsets of the specified elementType 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 .

Parameters

subsets (list[Subset]) –
elementCount (int) –
time (TimeCode) –

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 and elementType 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 the familyType 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:

`accelerations`
`all`
`angularVelocities`
`axis`
`basis`
`bezier`
`bilinear`
`boundaries`
`bounds`
`box`
`bspline`
`cards`
`catmullClark`
`catmullRom`
`clippingPlanes`
`clippingRange`
`closed`
`constant`
`cornerIndices`
`cornerSharpnesses`
`cornersOnly`
`cornersPlus1`
`cornersPlus2`
`creaseIndices`
`creaseLengths`
`creaseSharpnesses`
`cross`
`cubic`
`curveVertexCounts`
`default_`
`doubleSided`
`edgeAndCorner`
`edgeOnly`
`elementSize`
`elementType`
`exposure`
`extent`
`extentsHint`
`fStop`
`face`
`faceVarying`
`faceVaryingLinearInterpolation`
`faceVertexCounts`
`faceVertexIndices`
`familyName`
`focalLength`
`focusDistance`
`form`
`fromTexture`
`guide`
`guideVisibility`
`height`
`hermite`
`holeIndices`
`horizontalAperture`
`horizontalApertureOffset`
`ids`
`inactiveIds`
`indices`
`inherited`
`interpolateBoundary`
`interpolation`
`invisible`
`invisibleIds`
`knots`
`left`
`leftHanded`
`length`
`linear`
`loop`
`metersPerUnit`
`modelApplyDrawMode`
`modelCardGeometry`
`modelCardTextureXNeg`
`modelCardTextureXPos`
`modelCardTextureYNeg`
`modelCardTextureYPos`
`modelCardTextureZNeg`
`modelCardTextureZPos`
`modelDrawMode`
`modelDrawModeColor`
`mono`
`motionBlurScale`
`motionNonlinearSampleCount`
`motionVelocityScale`
`nonOverlapping`
`none`
`nonperiodic`
`normals`
`open`
`order`
`orientation`
`orientations`
`origin`
`orthographic`
`partition`
`periodic`
`perspective`
`pinned`
`pivot`
`pointWeights`
`points`
`positions`
`power`
`primvarsDisplayColor`
`primvarsDisplayOpacity`
`projection`
`protoIndices`
`prototypes`
`proxy`
`proxyPrim`
`proxyVisibility`
`purpose`
`radius`
`ranges`
`render`
`renderVisibility`
`right`
`rightHanded`
`scales`
`shutterClose`
`shutterOpen`
`size`
`smooth`
`stereoRole`
`subdivisionScheme`
`tangents`
`triangleSubdivisionRule`
`trimCurveCounts`
`trimCurveKnots`
`trimCurveOrders`
`trimCurvePoints`
`trimCurveRanges`
`trimCurveVertexCounts`
`type`
`uForm`
`uKnots`
`uOrder`
`uRange`
`uVertexCount`
`unauthoredValuesIndex`
`uniform`
`unrestricted`
`upAxis`
`vForm`
`vKnots`
`vOrder`
`vRange`
`vVertexCount`
`varying`
`velocities`
`vertex`
`verticalAperture`
`verticalApertureOffset`
`visibility`
`visible`
`width`
`widths`
`wrap`
`x`
`xformOpOrder`
`y`
`z`

accelerations = 'accelerations'

all = 'all'

angularVelocities = 'angularVelocities'

axis = 'axis'

basis = 'basis'

bezier = 'bezier'

bilinear = 'bilinear'

boundaries = 'boundaries'

bounds = 'bounds'

box = 'box'

bspline = 'bspline'

cards = 'cards'

catmullClark = 'catmullClark'

catmullRom = 'catmullRom'

clippingPlanes = 'clippingPlanes'

clippingRange = 'clippingRange'

closed = 'closed'

constant = 'constant'

cornerIndices = 'cornerIndices'

cornerSharpnesses = 'cornerSharpnesses'

cornersOnly = 'cornersOnly'

cornersPlus1 = 'cornersPlus1'

cornersPlus2 = 'cornersPlus2'

creaseIndices = 'creaseIndices'

creaseLengths = 'creaseLengths'

creaseSharpnesses = 'creaseSharpnesses'

cross = 'cross'

cubic = 'cubic'

curveVertexCounts = 'curveVertexCounts'

default_ = 'default'

doubleSided = 'doubleSided'

edgeAndCorner = 'edgeAndCorner'

edgeOnly = 'edgeOnly'

elementSize = 'elementSize'

elementType = 'elementType'

exposure = 'exposure'

extent = 'extent'

extentsHint = 'extentsHint'

fStop = 'fStop'

face = 'face'

faceVarying = 'faceVarying'

faceVaryingLinearInterpolation = 'faceVaryingLinearInterpolation'

faceVertexCounts = 'faceVertexCounts'

faceVertexIndices = 'faceVertexIndices'

familyName = 'familyName'

focalLength = 'focalLength'

focusDistance = 'focusDistance'

form = 'form'

fromTexture = 'fromTexture'

guide = 'guide'

guideVisibility = 'guideVisibility'

height = 'height'

hermite = 'hermite'

holeIndices = 'holeIndices'

horizontalAperture = 'horizontalAperture'

horizontalApertureOffset = 'horizontalApertureOffset'

ids = 'ids'

inactiveIds = 'inactiveIds'

indices = 'indices'

inherited = 'inherited'

interpolateBoundary = 'interpolateBoundary'

interpolation = 'interpolation'

invisible = 'invisible'

invisibleIds = 'invisibleIds'

knots = 'knots'

left = 'left'

leftHanded = 'leftHanded'

length = 'length'

linear = 'linear'

loop = 'loop'

metersPerUnit = 'metersPerUnit'

modelApplyDrawMode = 'model:applyDrawMode'

modelCardGeometry = 'model:cardGeometry'

modelCardTextureXNeg = 'model:cardTextureXNeg'

modelCardTextureXPos = 'model:cardTextureXPos'

modelCardTextureYNeg = 'model:cardTextureYNeg'

modelCardTextureYPos = 'model:cardTextureYPos'

modelCardTextureZNeg = 'model:cardTextureZNeg'

modelCardTextureZPos = 'model:cardTextureZPos'

modelDrawMode = 'model:drawMode'

modelDrawModeColor = 'model:drawModeColor'

mono = 'mono'

motionBlurScale = 'motion:blurScale'

motionNonlinearSampleCount = 'motion:nonlinearSampleCount'

motionVelocityScale = 'motion:velocityScale'

nonOverlapping = 'nonOverlapping'

none = 'none'

nonperiodic = 'nonperiodic'

normals = 'normals'

open = 'open'

order = 'order'

orientation = 'orientation'

orientations = 'orientations'

origin = 'origin'

orthographic = 'orthographic'

partition = 'partition'

periodic = 'periodic'

perspective = 'perspective'

pinned = 'pinned'

pivot = 'pivot'

pointWeights = 'pointWeights'

points = 'points'

positions = 'positions'

power = 'power'

primvarsDisplayColor = 'primvars:displayColor'

primvarsDisplayOpacity = 'primvars:displayOpacity'

projection = 'projection'

protoIndices = 'protoIndices'

prototypes = 'prototypes'

proxy = 'proxy'

proxyPrim = 'proxyPrim'

proxyVisibility = 'proxyVisibility'

purpose = 'purpose'

radius = 'radius'

ranges = 'ranges'

render = 'render'

renderVisibility = 'renderVisibility'

right = 'right'

rightHanded = 'rightHanded'

scales = 'scales'

shutterClose = 'shutter:close'

shutterOpen = 'shutter:open'

size = 'size'

smooth = 'smooth'

stereoRole = 'stereoRole'

subdivisionScheme = 'subdivisionScheme'

tangents = 'tangents'

triangleSubdivisionRule = 'triangleSubdivisionRule'

trimCurveCounts = 'trimCurve:counts'

trimCurveKnots = 'trimCurve:knots'

trimCurveOrders = 'trimCurve:orders'

trimCurvePoints = 'trimCurve:points'

trimCurveRanges = 'trimCurve:ranges'

trimCurveVertexCounts = 'trimCurve:vertexCounts'

type = 'type'

uForm = 'uForm'

uKnots = 'uKnots'

uOrder = 'uOrder'

uRange = 'uRange'

uVertexCount = 'uVertexCount'

unauthoredValuesIndex = 'unauthoredValuesIndex'

uniform = 'uniform'

unrestricted = 'unrestricted'

upAxis = 'upAxis'

vForm = 'vForm'

vKnots = 'vKnots'

vOrder = 'vOrder'

vRange = 'vRange'

vVertexCount = 'vVertexCount'

varying = 'varying'

velocities = 'velocities'

vertex = 'vertex'

verticalAperture = 'verticalAperture'

verticalApertureOffset = 'verticalApertureOffset'

visibility = 'visibility'

visible = 'visible'

width = 'width'

widths = 'widths'

wrap = 'wrap'

x = 'X'

xformOpOrder = 'xformOpOrder'

y = 'Y'

z = 'Z'

class pxr.UsdGeom.VisibilityAPI

UsdGeomVisibilityAPI introduces properties that can be used to author visibility opinions.

Currently, this schema only introduces the attributes that are used to control purpose visibility. Later, this schema will define all visibility-related properties and UsdGeomImageable will no longer define those properties. The purpose visibility attributes added by this schema, guideVisibility, proxyVisibility, and renderVisibility can each be used to control visibility for geometry of the corresponding purpose values, with the overall visibility attribute acting as an override. I.e., if visibility evaluates to”invisible”, purpose visibility is invisible; otherwise, purpose visibility is determined by the corresponding purpose visibility attribute.

Note that the behavior of guideVisibility is subtly different from the proxyVisibility and renderVisibility attributes, in that”guide”purpose visibility always evaluates to either”invisible”or”visible”, whereas the other attributes may yield computed values of”inherited”if there is no authored opinion on the attribute or inherited from an ancestor. This is motivated by the fact that, in Pixar”s user workflows, we have never found a need to have all guides visible in a scene by default, whereas we do find that flexibility useful for”proxy”and”render”geometry.

This schema can only be applied to UsdGeomImageable prims. The UseGeomImageable schema provides API for computing the purpose visibility values that result from the attributes introduced by this schema.

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:

`Apply`	classmethod Apply(prim) -> VisibilityAPI
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`CreateGuideVisibilityAttr`(defaultValue, ...)	See GetGuideVisibilityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateProxyVisibilityAttr`(defaultValue, ...)	See GetProxyVisibilityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateRenderVisibilityAttr`(defaultValue, ...)	See GetRenderVisibilityAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Get`	classmethod Get(stage, path) -> VisibilityAPI
`GetGuideVisibilityAttr`()	This attribute controls visibility for geometry with purpose"guide".
`GetProxyVisibilityAttr`()	This attribute controls visibility for geometry with purpose"proxy".
`GetPurposeVisibilityAttr`(purpose)	Return the attribute that is used for expressing visibility opinions for the given `purpose` .
`GetRenderVisibilityAttr`()	This attribute controls visibility for geometry with purpose"render".
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

static Apply()

classmethod Apply(prim) -> VisibilityAPI

Applies this single-apply API schema to the given prim .

This information is stored by adding”VisibilityAPI”to the token- valued, listOp metadata apiSchemas on the prim.

A valid UsdGeomVisibilityAPI object is returned upon success. An invalid (or empty) UsdGeomVisibilityAPI 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) –

CreateGuideVisibilityAttr(defaultValue, writeSparsely) → Attribute

See GetGuideVisibilityAttr() , 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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateProxyVisibilityAttr(defaultValue, writeSparsely) → Attribute

See GetProxyVisibilityAttr() , 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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateRenderVisibilityAttr(defaultValue, writeSparsely) → Attribute

See GetRenderVisibilityAttr() , 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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> VisibilityAPI

Return a UsdGeomVisibilityAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomVisibilityAPI(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetGuideVisibilityAttr() → Attribute

This attribute controls visibility for geometry with purpose”guide”.

Unlike overall visibility, guideVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, guideVisibility is tri-state, in that a descendant with an opinion of”visible”overrides an ancestor opinion of”invisible”.

The guideVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose”guide”is determined by the inherited values it receives for the visibility and guideVisibility attributes. If visibility evaluates to”invisible”, the prim is invisible. If visibility evaluates to”inherited”and guideVisibility evaluates to”visible”, then the prim is visible. Otherwise, it is invisible.

Declaration

uniform token guideVisibility ="invisible"

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

Allowed Values

inherited, invisible, visible

GetProxyVisibilityAttr() → Attribute

This attribute controls visibility for geometry with purpose”proxy”.

Unlike overall visibility, proxyVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, proxyVisibility is tri-state, in that a descendant with an opinion of”visible”overrides an ancestor opinion of”invisible”.

The proxyVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose”proxy”is determined by the inherited values it receives for the visibility and proxyVisibility attributes. If visibility evaluates to”invisible”, the prim is invisible. If visibility evaluates to”inherited”then: If proxyVisibility evaluates to”visible”, then the prim is visible; if proxyVisibility evaluates to”invisible”, then the prim is invisible; if proxyVisibility evaluates to”inherited”, then the prim may either be visible or invisible, depending on a fallback value determined by the calling context.

Declaration

uniform token proxyVisibility ="inherited"

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

Allowed Values

inherited, invisible, visible

GetPurposeVisibilityAttr(purpose) → Attribute

Return the attribute that is used for expressing visibility opinions for the given purpose .

The valid purpose tokens are”guide”,”proxy”, and”render”which return the attributes guideVisibility, proxyVisibility, and renderVisibility respectively.

Note that while”default”is a valid purpose token for UsdGeomImageable::GetPurposeVisibilityAttr, it is not a valid purpose for this function, as UsdGeomVisibilityAPI itself does not have a default visibility attribute. Calling this function with “default will result in a coding error.

Parameters: purpose (str) –

GetRenderVisibilityAttr() → Attribute

This attribute controls visibility for geometry with purpose”render”.

Unlike overall visibility, renderVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, renderVisibility is tri-state, in that a descendant with an opinion of”visible”overrides an ancestor opinion of”invisible”.

The renderVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose”render”is determined by the inherited values it receives for the visibility and renderVisibility attributes. If visibility evaluates to”invisible”, the prim is invisible. If visibility evaluates to”inherited”then: If renderVisibility evaluates to”visible”, then the prim is visible; if renderVisibility evaluates to”invisible”, then the prim is invisible; if renderVisibility evaluates to”inherited”, then the prim may either be visible or invisible, depending on a fallback value determined by the calling context.

Declaration

uniform token renderVisibility ="inherited"

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

Allowed Values

inherited, invisible, visible

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.Xform

Concrete prim schema for a transform, which implements Xformable

Methods:

`Define`	classmethod Define(stage, path) -> Xform
`Get`	classmethod Get(stage, path) -> Xform
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

static Define()

classmethod Define(stage, path) -> Xform

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 at path at the current EditTarget. Author SdfPrimSpec s with specifier == 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.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Xform

Return a UsdGeomXform holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomXform(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (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.XformCache

A caching mechanism for transform matrices. For best performance, this object should be reused for multiple CTM queries.

Instances of this type can be copied, though using Swap() may result in better performance.

It is valid to cache prims from multiple stages in a single XformCache.

WARNING: this class does not automatically invalidate cached values based on changes to the stage from which values were cached. Additionally, a separate instance of this class should be used per- thread, calling the Get* methods from multiple threads is not safe, as they mutate internal state.

Methods:

`Clear`()	Clears all pre-cached values.
`ComputeRelativeTransform`(prim, ancestor, ...)	Returns the result of concatenating all transforms beneath `ancestor` that affect `prim` .
`GetLocalToWorldTransform`(prim)	Compute the transformation matrix for the given `prim` , including the transform authored on the Prim itself, if present.
`GetLocalTransformation`(prim, resetsXformStack)	Returns the local transformation of the prim.
`GetParentToWorldTransform`(prim)	Compute the transformation matrix for the given `prim` , but do NOT include the transform authored on the prim itself.
`GetTime`()	Get the current time from which this cache is reading values.
`SetTime`(time)	Use the new `time` when computing values and may clear any existing values cached for the previous time.
`Swap`(other)	Swap the contents of this XformCache with `other` .

Clear() → None: Clears all pre-cached values.

ComputeRelativeTransform(prim, ancestor, resetXformStack) → Matrix4d

Returns the result of concatenating all transforms beneath ancestor that affect prim .

This includes the local transform of prim itself, but not the local transform of ancestor . If ancestor is not an ancestor of prim , the resulting transform is the local-to-world transformation of prim . The resetXformTsack pointer must be valid. If any intermediate prims reset the transform stack, resetXformStack will be set to true. Intermediate transforms are cached, but the result of this call itself is not cached.

Parameters

prim (Prim) –
ancestor (Prim) –
resetXformStack (bool) –

GetLocalToWorldTransform(prim) → Matrix4d

Compute the transformation matrix for the given prim , including the transform authored on the Prim itself, if present.

This method may mutate internal cache state and is not thread safe.

Parameters: prim (Prim) –

GetLocalTransformation(prim, resetsXformStack) → Matrix4d

Returns the local transformation of the prim.

Uses the cached XformQuery to compute the result quickly. The resetsXformStack pointer must be valid. It will be set to true if prim resets the transform stack. The result of this call is cached.

Parameters

prim (Prim) –
resetsXformStack (bool) –

GetParentToWorldTransform(prim) → Matrix4d

Compute the transformation matrix for the given prim , but do NOT include the transform authored on the prim itself.

This method may mutate internal cache state and is not thread safe.

Parameters: prim (Prim) –

GetTime() → TimeCode: Get the current time from which this cache is reading values.

SetTime(time) → None

Use the new time when computing values and may clear any existing values cached for the previous time.

Setting time to the current time is a no-op.

Parameters: time (TimeCode) –

Swap(other) → None

Swap the contents of this XformCache with other .

Parameters: other (XformCache) –

class pxr.UsdGeom.XformCommonAPI

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. The goal of the API is to enhance component-wise interchange. It achieves this by limiting the set of allowed basic ops and by specifying the order in which they are applied. In addition to the basic set of ops, the’resetXformStack’bit can also be set to indicate whether the underlying xformable resets the parent transformation (i.e. does not inherit it’s parent’s transformation).

UsdGeomXformCommonAPI::GetResetXformStack()

UsdGeomXformCommonAPI::SetResetXformStack() The operator-bool for the class will inform you whether an existing xformable is compatible with this API.

The scale-rotate pivot is represented by a pair of (translate, inverse-translate) xformOps around the scale and rotate operations. The rotation operation can be any of the six allowed Euler angle sets.

UsdGeomXformOp::Type. The xformOpOrder of an xformable that has all of the supported basic ops is as follows: [“xformOp:translate”,”xformOp:translate:pivot”,”xformOp:rotateXYZ”,”xformOp:scale”,”!invert!xformOp:translate:pivot”].

It is worth noting that all of the ops are optional. For example, an xformable may have only a translate or a rotate. It would still be considered as compatible with this API. Individual SetTranslate() , SetRotate() , SetScale() and SetPivot() methods are provided by this API to allow such sparse authoring.

Classes:

`OpFlags`	Enumerates the categories of ops that can be handled by XformCommonAPI.
`RotationOrder`	Enumerates the rotation order of the 3-angle Euler rotation.

Methods:

`CanConvertOpTypeToRotationOrder`	classmethod CanConvertOpTypeToRotationOrder(opType) -> bool
`ConvertOpTypeToRotationOrder`	classmethod ConvertOpTypeToRotationOrder(opType) -> RotationOrder
`ConvertRotationOrderToOpType`	classmethod ConvertRotationOrderToOpType(rotOrder) -> XformOp.Type
`CreateXformOps`(rotOrder, op1, op2, op3, op4)	Creates the specified XformCommonAPI-compatible xform ops, or returns the existing ops if they already exist.
`Get`	classmethod Get(stage, path) -> XformCommonAPI
`GetResetXformStack`()	Returns whether the xformable resets the transform stack.
`GetRotationTransform`	classmethod GetRotationTransform(rotation, rotationOrder) -> Matrix4d
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetXformVectors`(translation, rotation, ...)	Retrieve values of the various component xformOps at a given `time`
`GetXformVectorsByAccumulation`(translation, ...)	Retrieve values of the various component xformOps at a given `time`
`SetPivot`(pivot, time)	Set pivot position at `time` to `pivot` .
`SetResetXformStack`(resetXformStack)	Set whether the xformable resets the transform stack.
`SetRotate`(rotation, rotOrder, time)	Set rotation at `time` to `rotation` .
`SetScale`(scale, time)	Set scale at `time` to `scale` .
`SetTranslate`(translation, time)	Set translation at `time` to `translation` .
`SetXformVectors`(translation, rotation, ...)	Set values for the various component xformOps at a given `time` .

Attributes:

`OpPivot`
`OpRotate`
`OpScale`
`OpTranslate`
`RotationOrderXYZ`
`RotationOrderXZY`
`RotationOrderYXZ`
`RotationOrderYZX`
`RotationOrderZXY`
`RotationOrderZYX`

class OpFlags

Enumerates the categories of ops that can be handled by XformCommonAPI.

For use with CreateXformOps() .

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()

allValues = (UsdGeom.XformCommonAPI.OpTranslate, UsdGeom.XformCommonAPI.OpRotate, UsdGeom.XformCommonAPI.OpScale, UsdGeom.XformCommonAPI.OpPivot)

class RotationOrder

Enumerates the rotation order of the 3-angle Euler rotation.

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()

allValues = (UsdGeom.XformCommonAPI.RotationOrderXYZ, UsdGeom.XformCommonAPI.RotationOrderXZY, UsdGeom.XformCommonAPI.RotationOrderYXZ, UsdGeom.XformCommonAPI.RotationOrderYZX, UsdGeom.XformCommonAPI.RotationOrderZXY, UsdGeom.XformCommonAPI.RotationOrderZYX)

static CanConvertOpTypeToRotationOrder()

classmethod CanConvertOpTypeToRotationOrder(opType) -> bool

Whether the given opType has a corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum (i.e., whether it is a three-axis rotation).

Parameters: opType (XformOp.Type) –

static ConvertOpTypeToRotationOrder()

classmethod ConvertOpTypeToRotationOrder(opType) -> RotationOrder

Converts the given opType to the corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum.

For example, TypeRotateYZX corresponds to RotationOrderYZX. Raises a coding error if opType is not convertible to RotationOrder (i.e., if it isn’t a three-axis rotation) and returns the default RotationOrderXYZ instead.

Parameters: opType (XformOp.Type) –

static ConvertRotationOrderToOpType()

classmethod ConvertRotationOrderToOpType(rotOrder) -> XformOp.Type

Converts the given rotOrder to the corresponding value in the UsdGeomXformOp::Type enum.

For example, RotationOrderYZX corresponds to TypeRotateYZX. Raises a coding error if rotOrder is not one of the named enumerators of RotationOrder.

Parameters: rotOrder (RotationOrder) –

CreateXformOps(rotOrder, op1, op2, op3, op4) → Ops

Creates the specified XformCommonAPI-compatible xform ops, or returns the existing ops if they already exist.

If successful, returns an Ops object with all the ops on this prim, identified by type. If the requested xform ops couldn’t be created or the prim is not XformCommonAPI-compatible, returns an Ops object with all invalid ops.

The rotOrder is only used if OpRotate is specified. Otherwise, it is ignored. (If you don’t need to create a rotate op, you might find it helpful to use the other overload that takes no rotation order.)

Parameters

rotOrder (RotationOrder) –
op1 (OpFlags) –
op2 (OpFlags) –
op3 (OpFlags) –
op4 (OpFlags) –

CreateXformOps(op1, op2, op3, op4) -> Ops

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload does not take a rotation order.

If you specify OpRotate, then this overload assumes RotationOrderXYZ or the previously-authored rotation order. (If you do need to create a rotate op, you might find it helpful to use the other overload that explicitly takes a rotation order.)

Parameters

op1 (OpFlags) –
op2 (OpFlags) –
op3 (OpFlags) –
op4 (OpFlags) –

static Get()

classmethod Get(stage, path) -> XformCommonAPI

Return a UsdGeomXformCommonAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomXformCommonAPI(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetResetXformStack() → bool

Returns whether the xformable resets the transform stack.

i.e., does not inherit the parent transformation.

static GetRotationTransform()

classmethod GetRotationTransform(rotation, rotationOrder) -> Matrix4d

Return the 4x4 matrix that applies the rotation encoded by rotation vector rotation using the rotation order rotationOrder .

Deprecated

Please use the result of ConvertRotationOrderToOpType() along with UsdGeomXformOp::GetOpTransform() instead.

Parameters

rotation (Vec3f) –
rotationOrder (XformCommonAPI.RotationOrder) –

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

GetXformVectors(translation, rotation, scale, pivot, rotOrder, time) → bool

Retrieve values of the various component xformOps at a given time .

Identity values are filled in for the component xformOps that don’t exist or don’t have an authored value.

This method works even on prims with an incompatible xform schema, i.e. when the bool operator returns false. When the underlying xformable has an incompatible xform schema, it performs a full-on matrix decomposition to XYZ rotation order.

Parameters

translation (Vec3d) –
rotation (Vec3f) –
scale (Vec3f) –
pivot (Vec3f) –
rotOrder (RotationOrder) –
time (TimeCode) –

GetXformVectorsByAccumulation(translation, rotation, scale, pivot, rotOrder, time) → bool

Retrieve values of the various component xformOps at a given time .

Identity values are filled in for the component xformOps that don’t exist or don’t have an authored value.

This method allows some additional flexibility for xform schemas that do not strictly adhere to the xformCommonAPI. For incompatible schemas, this method will attempt to reduce the schema into one from which component vectors can be extracted by accumulating xformOp transforms of the common types.

When the underlying xformable has a compatible xform schema, the usual component value extraction method is used instead. When the xform schema is incompatible and it cannot be reduced by accumulating transforms, it performs a full-on matrix decomposition to XYZ rotation order.

Parameters

translation (Vec3d) –
rotation (Vec3f) –
scale (Vec3f) –
pivot (Vec3f) –
rotOrder (XformCommonAPI.RotationOrder) –
time (TimeCode) –

SetPivot(pivot, time) → bool

Set pivot position at time to pivot .

Parameters

pivot (Vec3f) –
time (TimeCode) –

SetResetXformStack(resetXformStack) → bool

Set whether the xformable resets the transform stack.

i.e., does not inherit the parent transformation.

Parameters: resetXformStack (bool) –

SetRotate(rotation, rotOrder, time) → bool

Set rotation at time to rotation .

Parameters

rotation (Vec3f) –
rotOrder (XformCommonAPI.RotationOrder) –
time (TimeCode) –

SetScale(scale, time) → bool

Set scale at time to scale .

Parameters

scale (Vec3f) –
time (TimeCode) –

SetTranslate(translation, time) → bool

Set translation at time to translation .

Parameters

translation (Vec3d) –
time (TimeCode) –

SetXformVectors(translation, rotation, scale, pivot, rotOrder, time) → bool

Set values for the various component xformOps at a given time .

Calling this method will call all of the supported ops to be created, even if they only contain default (identity) values.

To author individual operations selectively, use the Set[OpType]() API.

Once the rotation order has been established for a given xformable (either because of an already defined (and compatible) rotate op or from calling SetXformVectors() or SetRotate() ), it cannot be changed.

Parameters

translation (Vec3d) –
rotation (Vec3f) –
scale (Vec3f) –
pivot (Vec3f) –
rotOrder (RotationOrder) –
time (TimeCode) –

OpPivot = UsdGeom.XformCommonAPI.OpPivot

OpRotate = UsdGeom.XformCommonAPI.OpRotate

OpScale = UsdGeom.XformCommonAPI.OpScale

OpTranslate = UsdGeom.XformCommonAPI.OpTranslate

RotationOrderXYZ = UsdGeom.XformCommonAPI.RotationOrderXYZ

RotationOrderXZY = UsdGeom.XformCommonAPI.RotationOrderXZY

RotationOrderYXZ = UsdGeom.XformCommonAPI.RotationOrderYXZ

RotationOrderYZX = UsdGeom.XformCommonAPI.RotationOrderYZX

RotationOrderZXY = UsdGeom.XformCommonAPI.RotationOrderZXY

RotationOrderZYX = UsdGeom.XformCommonAPI.RotationOrderZYX

class pxr.UsdGeom.XformOp

Schema wrapper for UsdAttribute for authoring and computing transformation operations, as consumed by UsdGeomXformable schema.

The semantics of an op are determined primarily by its name, which allows us to decode an op very efficiently. All ops are independent attributes, which must live in the”xformOp”property namespace. The op’s primary name within the namespace must be one of UsdGeomXformOpTypes, which determines the type of transformation operation, and its secondary name (or suffix) within the namespace (which is not required to exist), can be any name that distinguishes it from other ops of the same type. Suffixes are generally imposed by higer level xform API schemas.

On packing order of rotateABC triples The order in which the axis rotations are recorded in a Vec3* for the six rotateABC Euler triples is always the same: vec[0] = X, vec[1] = Y, vec[2] = Z. The A, B, C in the op name dictate the order in which their corresponding elements are consumed by the rotation, not how they are laid out.

Classes:

`Precision`	Precision with which the value of the tranformation operation is encoded.
`Type`	Enumerates the set of all transformation operation types.

Methods:

`Get`(value, time)	Get the attribute value of the XformOp at `time` .
`GetAttr`()	Explicit UsdAttribute extractor.
`GetBaseName`()	UsdAttribute::GetBaseName()
`GetName`()	UsdAttribute::GetName()
`GetNamespace`()	UsdAttribute::GetNamespace()
`GetNumTimeSamples`()	Returns the number of time samples authored for this xformOp.
`GetOpName`	classmethod GetOpName(opType, opSuffix, inverse) -> str
`GetOpTransform`	classmethod GetOpTransform(time) -> Matrix4d
`GetOpType`()	Return the operation type of this op, one of UsdGeomXformOp::Type.
`GetOpTypeEnum`	classmethod GetOpTypeEnum(opTypeToken) -> Type
`GetOpTypeToken`	classmethod GetOpTypeToken(opType) -> str
`GetPrecision`()	Returns the precision level of the xform op.
`GetTimeSamples`(times)	Populates the list of time samples at which the associated attribute is authored.
`GetTimeSamplesInInterval`(interval, times)	Populates the list of time samples within the given `interval` , at which the associated attribute is authored.
`GetTypeName`()	UsdAttribute::GetTypeName()
`IsDefined`()	Return true if the wrapped UsdAttribute::IsDefined() , and in addition the attribute is identified as a XformOp.
`IsInverseOp`()	Returns whether the xformOp represents an inverse operation.
`MightBeTimeVarying`()	Determine whether there is any possibility that this op's value may vary over time.
`Set`(value, time)	Set the attribute value of the XformOp at `time` .
`SplitName`()	UsdAttribute::SplitName()

Attributes:

`PrecisionDouble`
`PrecisionFloat`
`PrecisionHalf`
`TypeInvalid`
`TypeOrient`
`TypeRotateX`
`TypeRotateXYZ`
`TypeRotateXZY`
`TypeRotateY`
`TypeRotateYXZ`
`TypeRotateYZX`
`TypeRotateZ`
`TypeRotateZXY`
`TypeRotateZYX`
`TypeScale`
`TypeTransform`
`TypeTranslate`

class Precision

Precision with which the value of the tranformation operation is encoded.

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()

allValues = (UsdGeom.XformOp.PrecisionDouble, UsdGeom.XformOp.PrecisionFloat, UsdGeom.XformOp.PrecisionHalf)

class Type

Enumerates the set of all transformation operation types.

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()

allValues = (UsdGeom.XformOp.TypeInvalid, UsdGeom.XformOp.TypeTranslate, UsdGeom.XformOp.TypeScale, UsdGeom.XformOp.TypeRotateX, UsdGeom.XformOp.TypeRotateY, UsdGeom.XformOp.TypeRotateZ, UsdGeom.XformOp.TypeRotateXYZ, UsdGeom.XformOp.TypeRotateXZY, UsdGeom.XformOp.TypeRotateYXZ, UsdGeom.XformOp.TypeRotateYZX, UsdGeom.XformOp.TypeRotateZXY, UsdGeom.XformOp.TypeRotateZYX, UsdGeom.XformOp.TypeOrient, UsdGeom.XformOp.TypeTransform)

Get(value, time) → bool

Get the attribute value of the XformOp at time .

For inverted ops, this returns the raw, uninverted value.

Parameters

value (T) –
time (TimeCode) –

GetAttr() → Attribute: Explicit UsdAttribute extractor.

GetBaseName() → str: UsdAttribute::GetBaseName()

GetName() → str: UsdAttribute::GetName()

GetNamespace() → str: UsdAttribute::GetNamespace()

GetNumTimeSamples() → int: Returns the number of time samples authored for this xformOp.

GetOpName()

classmethod GetOpName(opType, opSuffix, inverse) -> str

Returns the xformOp’s name as it appears in xformOpOrder, given the opType, the (optional) suffix and whether it is an inverse operation.

Parameters

opType (Type) –
opSuffix (str) –
inverse (bool) –

GetOpName() -> str

Returns the opName as it appears in the xformOpOrder attribute.

This will begin with”!invert!:xformOp:”if it is an inverse xform operation. If it is not an inverse xformOp, it will begin with’xformOp:’.

This will be empty for an invalid xformOp.

GetOpTransform()

classmethod GetOpTransform(time) -> Matrix4d

Return the 4x4 matrix that applies the transformation encoded in this op at time .

Returns the identity matrix and issues a coding error if the op is invalid.

If the op is valid, but has no authored value, the identity matrix is returned and no error is issued.

Parameters: time (TimeCode) –

GetOpTransform(opType, opVal, isInverseOp) -> Matrix4d

Return the 4x4 matrix that applies the transformation encoded by op opType and data value opVal .

If isInverseOp is true, then the inverse of the tranformation represented by the op/value pair is returned.

An error will be issued if opType is not one of the values in the enum UsdGeomXformOp::Type or if opVal cannot be converted to a suitable input to opType

Parameters

opType (Type) –
opVal (VtValue) –
isInverseOp (bool) –

GetOpType() → Type: Return the operation type of this op, one of UsdGeomXformOp::Type.

static GetOpTypeEnum()

classmethod GetOpTypeEnum(opTypeToken) -> Type

Returns the Type enum associated with the given opTypeToken .

Parameters: opTypeToken (str) –

static GetOpTypeToken()

classmethod GetOpTypeToken(opType) -> str

Returns the TfToken used to encode the given opType .

Note that an empty TfToken is used to represent TypeInvalid

Parameters: opType (Type) –

GetPrecision() → Precision: Returns the precision level of the xform op.

GetTimeSamples(times) → bool

Populates the list of time samples at which the associated attribute is authored.

Parameters: times (list[float]) –

GetTimeSamplesInInterval(interval, times) → bool

Populates the list of time samples within the given interval , at which the associated attribute is authored.

Parameters

interval (Interval) –
times (list[float]) –

GetTypeName() → ValueTypeName: UsdAttribute::GetTypeName()

IsDefined() → bool: Return true if the wrapped UsdAttribute::IsDefined() , and in addition the attribute is identified as a XformOp.

IsInverseOp() → bool: Returns whether the xformOp represents an inverse operation.

MightBeTimeVarying() → bool

Determine whether there is any possibility that this op’s value may vary over time.

The determination is based on a snapshot of the authored state of the op, and may become invalid in the face of further authoring.

Set(value, time) → bool

Set the attribute value of the XformOp at time .

This only works on non-inverse operations. If invoked on an inverse xform operation, a coding error is issued and no value is authored.

Parameters

value (T) –
time (TimeCode) –

SplitName() → list[str]: UsdAttribute::SplitName()

PrecisionDouble = UsdGeom.XformOp.PrecisionDouble

PrecisionFloat = UsdGeom.XformOp.PrecisionFloat

PrecisionHalf = UsdGeom.XformOp.PrecisionHalf

TypeInvalid = UsdGeom.XformOp.TypeInvalid

TypeOrient = UsdGeom.XformOp.TypeOrient

TypeRotateX = UsdGeom.XformOp.TypeRotateX

TypeRotateXYZ = UsdGeom.XformOp.TypeRotateXYZ

TypeRotateXZY = UsdGeom.XformOp.TypeRotateXZY

TypeRotateY = UsdGeom.XformOp.TypeRotateY

TypeRotateYXZ = UsdGeom.XformOp.TypeRotateYXZ

TypeRotateYZX = UsdGeom.XformOp.TypeRotateYZX

TypeRotateZ = UsdGeom.XformOp.TypeRotateZ

TypeRotateZXY = UsdGeom.XformOp.TypeRotateZXY

TypeRotateZYX = UsdGeom.XformOp.TypeRotateZYX

TypeScale = UsdGeom.XformOp.TypeScale

TypeTransform = UsdGeom.XformOp.TypeTransform

TypeTranslate = UsdGeom.XformOp.TypeTranslate

class pxr.UsdGeom.XformOpTypes

Attributes:

`orient`
`resetXformStack`
`rotateX`
`rotateXYZ`
`rotateXZY`
`rotateY`
`rotateYXZ`
`rotateYZX`
`rotateZ`
`rotateZXY`
`rotateZYX`
`scale`
`transform`
`translate`

orient = 'orient'

resetXformStack = '!resetXformStack!'

rotateX = 'rotateX'

rotateXYZ = 'rotateXYZ'

rotateXZY = 'rotateXZY'

rotateY = 'rotateY'

rotateYXZ = 'rotateYXZ'

rotateYZX = 'rotateYZX'

rotateZ = 'rotateZ'

rotateZXY = 'rotateZXY'

rotateZYX = 'rotateZYX'

scale = 'scale'

transform = 'transform'

translate = 'translate'

class pxr.UsdGeom.Xformable

Base class for all transformable prims, which allows arbitrary sequences of component affine transformations to be encoded.

You may find it useful to review Linear Algebra in UsdGeom while reading this class description. Supported Component Transformation Operations

UsdGeomXformable currently supports arbitrary sequences of the following operations, each of which can be encoded in an attribute of the proper shape in any supported precision:

translate - 3D

scale - 3D

rotateX - 1D angle in degrees

rotateY - 1D angle in degrees

rotateZ - 1D angle in degrees

rotateABC - 3D where ABC can be any combination of the six principle Euler Angle sets: XYZ, XZY, YXZ, YZX, ZXY, ZYX. See note on rotation packing order

orient - 4D (quaternion)

transform - 4x4D Creating a Component Transformation

To add components to a UsdGeomXformable prim, simply call AddXformOp() with the desired op type, as enumerated in UsdGeomXformOp::Type, and the desired precision, which is one of UsdGeomXformOp::Precision. Optionally, you can also provide an”op suffix”for the operator that disambiguates it from other components of the same type on the same prim. Application-specific transform schemas can use the suffixes to fill a role similar to that played by AbcGeom::XformOp’s”Hint”enums for their own round-tripping logic.

We also provide specific”Add”API for each type, for clarity and conciseness, e.g. AddTranslateOp() , AddRotateXYZOp() etc.

AddXformOp() will return a UsdGeomXformOp object, which is a schema on a newly created UsdAttribute that provides convenience API for authoring and computing the component transformations. The UsdGeomXformOp can then be used to author any number of timesamples and default for the op.

Each successive call to AddXformOp() adds an operator that will be applied”more locally”than the preceding operator, just as if we were pushing transforms onto a transformation stack - which is precisely what should happen when the operators are consumed by a reader.

If you can, please try to use the UsdGeomXformCommonAPI, which wraps the UsdGeomXformable with an interface in which Op creation is taken care of for you, and there is a much higher chance that the data you author will be importable without flattening into other DCC’s, as it conforms to a fixed set of Scale-Rotate-Translate Ops.

Using the Authoring API Data Encoding and Op Ordering

Because there is no”fixed schema”of operations, all of the attributes that encode transform operations are dynamic, and are scoped in the namespace”xformOp”. The second component of an attribute’s name provides the type of operation, as listed above. An”xformOp”attribute can have additional namespace components derived from the opSuffix argument to the AddXformOp() suite of methods, which provides a preferred way of naming the ops such that we can have multiple”translate”ops with unique attribute names. For example, in the attribute named”xformOp:translate:maya:pivot”,”translate”is the type of operation and”maya:pivot”is the suffix.

The following ordered list of attribute declarations in usda define a basic Scale-Rotate-Translate with XYZ Euler angles, wherein the translation is double-precision, and the remainder of the ops are single, in which we will:

Scale by 2.0 in each dimension

Rotate about the X, Y, and Z axes by 30, 60, and 90 degrees, respectively

Translate by 100 units in the Y direction

float3 xformOp:rotateXYZ = (30, 60, 90)
float3 xformOp:scale = (2, 2, 2)
double3 xformOp:translate = (0, 100, 0)
uniform token[] xformOpOrder = [ "xformOp:translate", "xformOp:rotateXYZ", "xformOp:scale" ]

The attributes appear in the dictionary order in which USD, by default, sorts them. To ensure the ops are recovered and evaluated in the correct order, the schema introduces the xformOpOrder attribute, which contains the names of the op attributes, in the precise sequence in which they should be pushed onto a transform stack. Note that the order is opposite to what you might expect, given the matrix algebra described in Linear Algebra in UsdGeom. This also dictates order of op creation, since each call to AddXformOp() adds a new op to the end of the xformOpOrder array, as a new”most- local”operation. See Example 2 below for C++ code that could have produced this USD.

If it were important for the prim’s rotations to be independently overridable, we could equivalently (at some performance cost) encode the transformation also like so:

float xformOp:rotateX = 30
float xformOp:rotateY = 60
float xformOp:rotateZ = 90
float3 xformOp:scale = (2, 2, 2)
double3 xformOp:translate = (0, 100, 0)
uniform token[] xformOpOrder = [ "xformOp:translate", "xformOp:rotateZ", "xformOp:rotateY", "xformOp:rotateX", "xformOp:scale" ]

Again, note that although we are encoding an XYZ rotation, the three rotations appear in the xformOpOrder in the opposite order, with Z, followed, by Y, followed by X.

Were we to add a Maya-style scalePivot to the above example, it might look like the following:

float3 xformOp:rotateXYZ = (30, 60, 90)
float3 xformOp:scale = (2, 2, 2)
double3 xformOp:translate = (0, 100, 0)
double3 xformOp:translate:scalePivot
uniform token[] xformOpOrder = [ "xformOp:translate", "xformOp:rotateXYZ", "xformOp:translate:scalePivot", "xformOp:scale" ]

Paired”Inverted”Ops

We have been claiming that the ordered list of ops serves as a set of instructions to a transform stack, but you may have noticed in the last example that there is a missing operation - the pivot for the scale op needs to be applied in its inverse-form as a final (most local) op! In the AbcGeom::Xform schema, we would have encoded an actual”final”translation op whose value was authored by the exporter as the negation of the pivot’s value. However, doing so would be brittle in USD, given that each op can be independently overridden, and the constraint that one attribute must be maintained as the negation of the other in order for successful re-importation of the schema cannot be expressed in USD.

Our solution leverages the xformOpOrder member of the schema, which, in addition to ordering the ops, may also contain one of two special tokens that address the paired op and”stack resetting”behavior.

The”paired op”behavior is encoded as an”!invert!”prefix in xformOpOrder, as the result of an AddXformOp(isInverseOp=True) call. The xformOpOrder for the last example would look like:

uniform token[] xformOpOrder = [ "xformOp:translate", "xformOp:rotateXYZ", "xformOp:translate:scalePivot", "xformOp:scale", "!invert!xformOp:translate:scalePivot" ]

When asked for its value via UsdGeomXformOp::GetOpTransform() , an”inverted”Op (i.e. the”inverted”half of a set of paired Ops) will fetch the value of its paired attribute and return its negation. This works for all op types - an error will be issued if a”transform”type op is singular and cannot be inverted. When getting the authored value of an inverted op via UsdGeomXformOp::Get() , the raw, uninverted value of the associated attribute is returned.

For the sake of robustness, setting a value on an inverted op is disallowed. Attempting to set a value on an inverted op will result in a coding error and no value being set.

Resetting the Transform Stack

The other special op/token that can appear in xformOpOrder is “!resetXformStack!”, which, appearing as the first element of xformOpOrder, indicates this prim should not inherit the transformation of its namespace parent. See SetResetXformStack()

Expected Behavior for”Missing”Ops

If an importer expects Scale-Rotate-Translate operations, but a prim has only translate and rotate ops authored, the importer should assume an identity scale. This allows us to optimize the data a bit, if only a few components of a very rich schema (like Maya’s) are authored in the app.

Using the C++ API

#1. Creating a simple transform matrix encoding

#2. Creating the simple SRT from the example above

#3. Creating a parameterized SRT with pivot using

UsdGeomXformCommonAPI

#4. Creating a rotate-only pivot transform with animated rotation and

translation

Methods:

`AddOrientOp`(precision, opSuffix, isInverseOp)	Add a orient op (arbitrary axis/angle rotation) to the local stack represented by this xformable.
`AddRotateXOp`(precision, opSuffix, isInverseOp)	Add a rotation about the X-axis to the local stack represented by this xformable.
`AddRotateXYZOp`(precision, opSuffix, isInverseOp)	Add a rotation op with XYZ rotation order to the local stack represented by this xformable.
`AddRotateXZYOp`(precision, opSuffix, isInverseOp)	Add a rotation op with XZY rotation order to the local stack represented by this xformable.
`AddRotateYOp`(precision, opSuffix, isInverseOp)	Add a rotation about the YX-axis to the local stack represented by this xformable.
`AddRotateYXZOp`(precision, opSuffix, isInverseOp)	Add a rotation op with YXZ rotation order to the local stack represented by this xformable.
`AddRotateYZXOp`(precision, opSuffix, isInverseOp)	Add a rotation op with YZX rotation order to the local stack represented by this xformable.
`AddRotateZOp`(precision, opSuffix, isInverseOp)	Add a rotation about the Z-axis to the local stack represented by this xformable.
`AddRotateZXYOp`(precision, opSuffix, isInverseOp)	Add a rotation op with ZXY rotation order to the local stack represented by this xformable.
`AddRotateZYXOp`(precision, opSuffix, isInverseOp)	Add a rotation op with ZYX rotation order to the local stack represented by this xformable.
`AddScaleOp`(precision, opSuffix, isInverseOp)	Add a scale operation to the local stack represented by this xformable.
`AddTransformOp`(precision, opSuffix, isInverseOp)	Add a tranform op (4x4 matrix transformation) to the local stack represented by this xformable.
`AddTranslateOp`(precision, opSuffix, isInverseOp)	Add a translate operation to the local stack represented by this xformable.
`AddXformOp`(opType, precision, opSuffix, ...)	Add an affine transformation to the local stack represented by this Xformable.
`ClearXformOpOrder`()	Clears the local transform stack.
`CreateXformOpOrderAttr`(defaultValue, ...)	See GetXformOpOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Get`	classmethod Get(stage, path) -> Xformable
`GetLocalTransformation`	Compute the fully-combined, local-to-parent transformation for this prim.
`GetOrderedXformOps`	Return the ordered list of transform operations to be applied to this prim, in least-to-most-local order.
`GetResetXformStack`()	Does this prim reset its parent's inherited transformation?
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetTimeSamples`	classmethod GetTimeSamples(times) -> bool
`GetTimeSamplesInInterval`	classmethod GetTimeSamplesInInterval(interval, times) -> bool
`GetXformOpOrderAttr`()	Encodes the sequence of transformation operations in the order in which they should be pushed onto a transform stack while visiting a UsdStage 's prims in a graph traversal that will effect the desired positioning for this prim and its descendant prims.
`IsTransformationAffectedByAttrNamed`	classmethod IsTransformationAffectedByAttrNamed(attrName) -> bool
`MakeMatrixXform`()	Clears the existing local transform stack and creates a new xform op of type'transform'.
`SetResetXformStack`(resetXform)	Specify whether this prim's transform should reset the transformation stack inherited from its parent prim.
`SetXformOpOrder`(orderedXformOps, resetXformStack)	Reorder the already-existing transform ops on this prim.
`TransformMightBeTimeVarying`()	Determine whether there is any possibility that this prim's local transformation may vary over time.

AddOrientOp(precision, opSuffix, isInverseOp) → XformOp

Add a orient op (arbitrary axis/angle rotation) to the local stack represented by this xformable.

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateXOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation about the X-axis to the local stack represented by this xformable.

Set the angle value of the resulting UsdGeomXformOp in degrees

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateXYZOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with XYZ rotation order to the local stack represented by this xformable.

Set the angle value of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateXZYOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with XZY rotation order to the local stack represented by this xformable.

Set the angle values of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateYOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation about the YX-axis to the local stack represented by this xformable.

Set the angle value of the resulting UsdGeomXformOp in degrees

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateYXZOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with YXZ rotation order to the local stack represented by this xformable.

Set the angle values of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateYZXOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with YZX rotation order to the local stack represented by this xformable.

Set the angle values of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateZOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation about the Z-axis to the local stack represented by this xformable.

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateZXYOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with ZXY rotation order to the local stack represented by this xformable.

Set the angle values of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddRotateZYXOp(precision, opSuffix, isInverseOp) → XformOp

Add a rotation op with ZYX rotation order to the local stack represented by this xformable.

Set the angle values of the resulting UsdGeomXformOp in degrees

AddXformOp() , note on angle packing order

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddScaleOp(precision, opSuffix, isInverseOp) → XformOp

Add a scale operation to the local stack represented by this xformable.

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddTransformOp(precision, opSuffix, isInverseOp) → XformOp

Add a tranform op (4x4 matrix transformation) to the local stack represented by this xformable.

AddXformOp() Note: This method takes a precision argument only to be consistent with the other types of xformOps. The only valid precision here is double since matrix values cannot be encoded in floating-pt precision in Sdf.

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddTranslateOp(precision, opSuffix, isInverseOp) → XformOp

Add a translate operation to the local stack represented by this xformable.

AddXformOp()

Parameters

precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

AddXformOp(opType, precision, opSuffix, isInverseOp) → XformOp

Add an affine transformation to the local stack represented by this Xformable.

This will fail if there is already a transform operation of the same name in the ordered ops on this prim (i.e. as returned by GetOrderedXformOps() ), or if an op of the same name exists at all on the prim with a different precision than that specified.

The newly created operation will become the most-locally applied transformation on the prim, and will appear last in the list returned by GetOrderedXformOps() . It is OK to begin authoring values to the returned UsdGeomXformOp immediately, interspersed with subsequent calls to AddXformOp() - just note the order of application, which can be changed at any time (and in stronger layers) via SetXformOpOrder() .

opType

is the type of transform operation, one of UsdGeomXformOp::Type. precision

allows you to specify the precision with which you desire to encode the data. This should be one of the values in the enum UsdGeomXformOp::Precision. opSuffix

allows you to specify the purpose/meaning of the op in the stack. When opSuffix is specified, the associated attribute’s name is set to”xformOp:<opType>:<opSuffix>”. isInverseOp

is used to indicate an inverse transformation operation.

a UsdGeomXformOp that can be used to author to the operation. An error is issued and the returned object will be invalid (evaluate to false) if the op being added already exists in xformOpOrder or if the arguments supplied are invalid.

If the attribute associated with the op already exists, but isn’t of the requested precision, a coding error is issued, but a valid xformOp is returned with the existing attribute.

Parameters

opType (XformOp.Type) –
precision (XformOp.Precision) –
opSuffix (str) –
isInverseOp (bool) –

ClearXformOpOrder() → bool: Clears the local transform stack.

CreateXformOpOrderAttr(defaultValue, writeSparsely) → Attribute

See GetXformOpOrderAttr() , 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) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> Xformable

Return a UsdGeomXformable holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomXformable(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetLocalTransformation()

Compute the fully-combined, local-to-parent transformation for this prim. If a client does not need to manipulate the individual ops themselves, and requires only the combined transform on this prim, this method will take care of all the data marshalling and linear algebra needed to combine the ops into a 4x4 affine transformation matrix, in double-precision, regardless of the precision of the op inputs. The python version of this function only returns the computed local-to-parent transformation. Clients must independently call GetResetXformStack() to be able to construct the local-to-world transformation.

Compute the fully-combined, local-to-parent transformation for this prim as efficiently as possible, using pre-fetched list of ordered xform ops supplied by the client. The python version of this function only returns the computed local-to-parent transformation. Clients must independently call GetResetXformStack() to be able to construct the local-to-world transformation.

GetOrderedXformOps()

Return the ordered list of transform operations to be applied to this prim, in least-to-most-local order. This is determined by the intersection of authored op-attributes and the explicit ordering of those attributes encoded in the “xformOpOrder” attribute on this prim.

Any entries in “xformOpOrder” that do not correspond to valid attributes on the xformable prim are skipped and a warning is issued.

A UsdGeomTransformable that has not had any ops added via AddXformOp() will return an empty vector.

The python version of this function only returns the ordered list of xformOps. Clients must independently call GetResetXformStack() if they need the info.

GetResetXformStack() → bool

Does this prim reset its parent’s inherited transformation?

Returns true if”!resetXformStack!”appears anywhere in xformOpOrder. When this returns true, all ops upto the last”!resetXformStack!”in xformOpOrder are ignored when computing the local transformation.

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

GetTimeSamples()

classmethod GetTimeSamples(times) -> bool

Sets times to the union of all the timesamples at which xformOps that are included in the xformOpOrder attribute are authored.

This clears the times vector before accumulating sample times from all the xformOps.

UsdAttribute::GetTimeSamples

Parameters: times (list[float]) –

GetTimeSamples(orderedXformOps, times) -> bool

Returns the union of all the timesamples at which the attributes belonging to the given orderedXformOps are authored.

This clears the times vector before accumulating sample times from orderedXformOps .

UsdGeomXformable::GetTimeSamples

Parameters

orderedXformOps (list[XformOp]) –
times (list[float]) –

GetTimeSamplesInInterval()

classmethod GetTimeSamplesInInterval(interval, times) -> bool

Sets times to the union of all the timesamples in the interval, interval , at which xformOps that are included in the xformOpOrder attribute are authored.

This clears the times vector before accumulating sample times from all the xformOps.

UsdAttribute::GetTimeSamples

Parameters

interval (Interval) –
times (list[float]) –

GetTimeSamplesInInterval(orderedXformOps, interval, times) -> bool

Returns the union of all the timesamples in the interval at which the attributes belonging to the given orderedXformOps are authored.

This clears the times vector before accumulating sample times from orderedXformOps .

UsdGeomXformable::GetTimeSamplesInInterval

Parameters

orderedXformOps (list[XformOp]) –
interval (Interval) –
times (list[float]) –

GetXformOpOrderAttr() → Attribute

Encodes the sequence of transformation operations in the order in which they should be pushed onto a transform stack while visiting a UsdStage ‘s prims in a graph traversal that will effect the desired positioning for this prim and its descendant prims.

You should rarely, if ever, need to manipulate this attribute directly. It is managed by the AddXformOp() , SetResetXformStack() , and SetXformOpOrder() , and consulted by GetOrderedXformOps() and GetLocalTransformation() .

Declaration

uniform token[] xformOpOrder

C++ Type

VtArray<TfToken>

Usd Type

SdfValueTypeNames->TokenArray

Variability

SdfVariabilityUniform

static IsTransformationAffectedByAttrNamed()

classmethod IsTransformationAffectedByAttrNamed(attrName) -> bool

Returns true if the attribute named attrName could affect the local transformation of an xformable prim.

Parameters: attrName (str) –

MakeMatrixXform() → XformOp

Clears the existing local transform stack and creates a new xform op of type’transform’.

This API is provided for convenience since this is the most common xform authoring operation.

ClearXformOpOrder()

AddTransformOp()

SetResetXformStack(resetXform) → bool

Specify whether this prim’s transform should reset the transformation stack inherited from its parent prim.

By default, parent transforms are inherited. SetResetXformStack() can be called at any time during authoring, but will always add a’!resetXformStack!’op as the first op in the ordered list, if one does not exist already. If one already exists, and resetXform is false, it will remove all ops upto and including the last”!resetXformStack!”op.

Parameters: resetXform (bool) –

SetXformOpOrder(orderedXformOps, resetXformStack) → bool

Reorder the already-existing transform ops on this prim.

All elements in orderedXformOps must be valid and represent attributes on this prim. Note that it is not required that all the existing operations be present in orderedXformOps , so this method can be used to completely change the transformation structure applied to the prim.

If resetXformStack is set to true, then “!resetXformOp! will be set as the first op in xformOpOrder, to indicate that the prim does not inherit its parent’s transformation.

If you wish to re-specify a prim’s transformation completely in a stronger layer, you should first call this method with an empty orderedXformOps vector. From there you can call AddXformOp() just as if you were authoring to the prim from scratch.

false if any of the elements of orderedXformOps are not extant on this prim, or if an error occurred while authoring the ordering metadata. Under either condition, no scene description is authored.

GetOrderedXformOps()

Parameters

orderedXformOps (list[XformOp]) –
resetXformStack (bool) –

TransformMightBeTimeVarying() → bool

Determine whether there is any possibility that this prim’s local transformation may vary over time.

The determination is based on a snapshot of the authored state of the op attributes on the prim, and may become invalid in the face of further authoring.

TransformMightBeTimeVarying(ops) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Determine whether there is any possibility that this prim’s local transformation may vary over time, using a pre-fetched (cached) list of ordered xform ops supplied by the client.

The determination is based on a snapshot of the authored state of the op attributes on the prim, and may become invalid in the face of further authoring.

Parameters: ops (list[XformOp]) –