UsdGeomXformable#

Fully qualified name: usdrt::UsdGeomXformable

class UsdGeomXformable : public usdrt::UsdGeomImageable #

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

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.

Data Encoding and Op Ordering

See also

Using the Authoring API

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

Note

You may find it useful to review UsdGeom_LinAlgBasics while reading this class description.

Note

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.

Subclassed by usdrt::UsdGeomBoundable, usdrt::UsdGeomCamera, usdrt::UsdGeomXform, usdrt::UsdLuxLight, usdrt::UsdLuxLightFilter, usdrt::UsdLuxLightPortal, usdrt::UsdLuxNonboundableLightBase, usdrt::UsdLuxPluginLight, usdrt::UsdMediaSpatialAudio, usdrt::UsdVolFieldBase

Public Functions

inline explicit UsdGeomXformable(const UsdPrim &prim = UsdPrim())#: Construct a UsdGeomXformable on UsdPrim prim. Equivalent to UsdGeomXformable::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdGeomXformable(const UsdSchemaBase &schemaObj)#: Construct a UsdGeomXformable on the prim held by schemaObj . Should be preferred over UsdGeomXformable(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdGeomXformable()#: Destructor.

inline UsdAttribute GetXformOpOrderAttr() const#

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

inline UsdAttribute CreateXformOpOrderAttr() const#: 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.

inline UsdAttribute GetVisibilityAttr() const#

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

inline UsdAttribute CreateVisibilityAttr() const#: 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.

inline UsdAttribute GetPurposeAttr() const#

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 UsdGeom_ImageablePurpose 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

inline UsdAttribute CreatePurposeAttr() const#: 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.

inline UsdRelationship GetProxyPrimRel() const#

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.

Note

It is only valid to author the proxyPrim relationship on prims whose purpose is “render”.

inline UsdRelationship CreateProxyPrimRel() const#: See GetProxyPrimRel(), and also Create vs Get Property Methods for when to use Get vs Create.

UsdPrim GetPrim() const#: Return this schema object’s held prim.

SdfPath GetPath() const#: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const#

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.