All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdGeomXformCommonAPI Class Reference

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

+ Inheritance diagram for UsdGeomXformCommonAPI:

Public Types

enum  RotationOrder {
  RotationOrderXYZ, RotationOrderXZY, RotationOrderYXZ, RotationOrderYZX,
  RotationOrderZXY, RotationOrderZYX
}
 Enumerates the rotation order of the 3-angle Euler rotation. More...
 

Public Member Functions

 UsdGeomXformCommonAPI (const UsdPrim &prim=UsdPrim())
 
 UsdGeomXformCommonAPI (const UsdGeomXformable &xformable)
 
virtual USDGEOM_API ~UsdGeomXformCommonAPI ()
 Destructor. More...
 
USDGEOM_API bool SetXformVectors (const GfVec3d &translation, const GfVec3f &rotation, const GfVec3f &scale, const GfVec3f &pivot, RotationOrder rotOrder, const UsdTimeCode time)
 Set values for the various component xformOps at a given time. More...
 
USDGEOM_API bool GetXformVectors (GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, RotationOrder *rotOrder, const UsdTimeCode time)
 Retrieve values of the various component xformOps at a given time. More...
 
USDGEOM_API bool GetXformVectorsByAccumulation (GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, UsdGeomXformCommonAPI::RotationOrder *rotOrder, const UsdTimeCode time)
 Retrieve values of the various component xformOps at a given time. More...
 
USDGEOM_API bool GetResetXformStack () const
 Returns whether the xformable resets the transform stack. More...
 
API for setting individual ops independently.

USDGEOM_API bool SetTranslate (const GfVec3d &translation, const UsdTimeCode time=UsdTimeCode::Default())
 Set translation at time to translation. More...
 
USDGEOM_API bool SetPivot (const GfVec3f &pivot, const UsdTimeCode time=UsdTimeCode::Default())
 Set pivot position at time to pivot. More...
 
USDGEOM_API bool SetRotate (const GfVec3f &rotation, UsdGeomXformCommonAPI::RotationOrder rotOrder=RotationOrderXYZ, const UsdTimeCode time=UsdTimeCode::Default())
 Set rotation at time to rotation. More...
 
USDGEOM_API bool SetScale (const GfVec3f &scale, const UsdTimeCode time=UsdTimeCode::Default())
 Set scale at time to scale. More...
 
USDGEOM_API bool SetResetXformStack (bool resetXformStack) const
 Set whether the xformable resets the transform stack. More...
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description. More...
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped. More...
 
bool IsAPISchema () const
 Returns whether this is an API schema or not. More...
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not. More...
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not. More...
 
UsdSchemaType GetSchemaType () const
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim. More...
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema. More...
 
virtual USD_API ~UsdSchemaBase ()
 Destructor. More...
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise. More...
 
UsdPrim GetPrim () const
 Return this schema object's held prim. More...
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath(). More...
 
USD_API SdfPrimSpecHandle GetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null. More...
 

Static Public Member Functions

static USDGEOM_API
UsdGeomXformCommonAPI 
Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomXformCommonAPI holding the xformable adhering to this API at path on stage. More...
 
Computing transforms
static USDGEOM_API GfMatrix4d GetRotationTransform (const GfVec3f &rotation, const UsdGeomXformCommonAPI::RotationOrder rotationOrder)
 Return the 4x4 matrix that applies the rotation encoded by rotation vector rotation using the rotation order rotationOrder. More...
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Protected Member Functions

USDGEOM_API bool _IsCompatible () const override
 Returns whether the underlying xformable is compatible with the API. More...
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaType _GetSchemaType () const
 Returns the type of schema this class is. More...
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Additional Inherited Members

- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaType schemaType = UsdSchemaType::AbstractBase
 Compile time constant representing what kind of schema this class is. More...
 

Detailed Description

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

See Also
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.

See Also
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.

Note
Manipulating the xformOpOrder attribute manually or using the API provided in UsdGeomXformable to add or remove xformOps causes the UsdGeomXformCommonAPI object to contain invalid or stale information. A new UsdGeomXformCommonAPI object must be created with the xformable after invoking any operation on the underlying xformable that would cause the xformOpOrder to change.

Definition at line 88 of file xformCommonAPI.h.

Member Enumeration Documentation

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

Definition at line 143 of file xformCommonAPI.h.

Constructor & Destructor Documentation

virtual USDGEOM_API ~UsdGeomXformCommonAPI ( )
virtual

Destructor.

Member Function Documentation

USDGEOM_API bool _IsCompatible ( ) const
overrideprotectedvirtual

Returns whether the underlying xformable is compatible with the API.

Reimplemented from UsdSchemaBase.

static USDGEOM_API UsdGeomXformCommonAPI Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdGeomXformCommonAPI holding the xformable adhering to this API at path on stage.

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

* UsdGeomXformCommonAPI(UsdGeomXformable(stage->GetPrimAtPath(path)));
*
USDGEOM_API bool GetResetXformStack ( ) const

Returns whether the xformable resets the transform stack.

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

static USDGEOM_API GfMatrix4d GetRotationTransform ( const GfVec3f rotation,
const UsdGeomXformCommonAPI::RotationOrder  rotationOrder 
)
static

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

USDGEOM_API bool GetXformVectors ( GfVec3d translation,
GfVec3f rotation,
GfVec3f scale,
GfVec3f pivot,
RotationOrder rotOrder,
const UsdTimeCode  time 
)

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.

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

USDGEOM_API bool GetXformVectorsByAccumulation ( GfVec3d translation,
GfVec3f rotation,
GfVec3f scale,
GfVec3f pivot,
UsdGeomXformCommonAPI::RotationOrder rotOrder,
const UsdTimeCode  time 
)

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.

Note
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.
USDGEOM_API bool SetPivot ( const GfVec3f pivot,
const UsdTimeCode  time = UsdTimeCode::Default() 
)

Set pivot position at time to pivot.

USDGEOM_API bool SetResetXformStack ( bool  resetXformStack) const

Set whether the xformable resets the transform stack.

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

USDGEOM_API bool SetRotate ( const GfVec3f rotation,
UsdGeomXformCommonAPI::RotationOrder  rotOrder = RotationOrderXYZ,
const UsdTimeCode  time = UsdTimeCode::Default() 
)

Set rotation at time to rotation.

USDGEOM_API bool SetScale ( const GfVec3f scale,
const UsdTimeCode  time = UsdTimeCode::Default() 
)

Set scale at time to scale.

USDGEOM_API bool SetTranslate ( const GfVec3d translation,
const UsdTimeCode  time = UsdTimeCode::Default() 
)

Set translation at time to translation.

USDGEOM_API bool SetXformVectors ( const GfVec3d translation,
const GfVec3f rotation,
const GfVec3f scale,
const GfVec3f pivot,
RotationOrder  rotOrder,
const UsdTimeCode  time 
)

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.

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

The documentation for this class was generated from the following file: