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:

Classes

struct  Ops
 Return type for CreateXformOps(). More...
 

Public Types

enum  RotationOrder {
  RotationOrderXYZ, RotationOrderXZY, RotationOrderYXZ, RotationOrderYZX,
  RotationOrderZXY, RotationOrderZYX
}
 Enumerates the rotation order of the 3-angle Euler rotation. More...
 
enum  OpFlags {
  OpNone = 0, OpTranslate = 1, OpPivot = 2, OpRotate = 4,
  OpScale = 8
}
 Enumerates the categories of ops that can be handled by XformCommonAPI. More...
 

Public Member Functions

 UsdGeomXformCommonAPI (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomXformCommonAPI on UsdPrim prim . More...
 
 UsdGeomXformCommonAPI (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomXformCommonAPI on the prim held by schemaObj . More...
 
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) const
 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) const
 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) const
 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()) const
 Set translation at time to translation. More...
 
USDGEOM_API bool SetPivot (const GfVec3f &pivot, const UsdTimeCode time=UsdTimeCode::Default()) const
 Set pivot position at time to pivot. More...
 
USDGEOM_API bool SetRotate (const GfVec3f &rotation, UsdGeomXformCommonAPI::RotationOrder rotOrder=RotationOrderXYZ, const UsdTimeCode time=UsdTimeCode::Default()) const
 Set rotation at time to rotation. More...
 
USDGEOM_API bool SetScale (const GfVec3f &scale, const UsdTimeCode time=UsdTimeCode::Default()) const
 Set scale at time to scale. More...
 
USDGEOM_API bool SetResetXformStack (bool resetXformStack) const
 Set whether the xformable resets the transform stack. More...
 
USDGEOM_API Ops CreateXformOps (RotationOrder rotOrder, OpFlags op1=OpNone, OpFlags op2=OpNone, OpFlags op3=OpNone, OpFlags op4=OpNone) const
 Creates the specified XformCommonAPI-compatible xform ops, or returns the existing ops if they already exist. More...
 
USDGEOM_API Ops CreateXformOps (OpFlags op1=OpNone, OpFlags op2=OpNone, OpFlags op3=OpNone, OpFlags op4=OpNone) const
 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. More...
 
- Public Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
 Construct a UsdAPISchemaBase on UsdPrim prim . More...
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
 Construct a UsdAPISchemaBase on the prim held by schemaObj . More...
 
virtual USD_API ~UsdAPISchemaBase ()=0
 Destructor. 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 const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null. More...
 

Static Public Member Functions

static USDGEOM_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes. More...
 
static USDGEOM_API
UsdGeomXformCommonAPI 
Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomXformCommonAPI holding the prim adhering to this schema at path on stage. More...
 
static USDGEOM_API
UsdGeomXformOp::Type 
ConvertRotationOrderToOpType (RotationOrder rotOrder)
 Converts the given rotOrder to the corresponding value in the UsdGeomXformOp::Type enum. More...
 
static USDGEOM_API RotationOrder ConvertOpTypeToRotationOrder (UsdGeomXformOp::Type opType)
 Converts the given opType to the corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum. More...
 
static USDGEOM_API bool CanConvertOpTypeToRotationOrder (UsdGeomXformOp::Type opType)
 Whether the given opType has a corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum (i.e., whether it is a three-axis rotation). 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 UsdAPISchemaBase
static USD_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes. More...
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

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

Protected Member Functions

USDGEOM_API UsdSchemaType _GetSchemaType () const override
 Returns the type of schema this class belongs to. More...
 
USDGEOM_API bool _IsCompatible () const override
 Returns whether the underlying xformable is compatible with the API. More...
 
- Protected Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on UsdPrim prim with the specified instanceName. More...
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on the prim held by schemaObj with the given instanceName. More...
 
const TfToken_GetInstanceName () const
 Returns the instance name of the API schema object belonging to a multiple-apply API schema. More...
 
- Protected Member Functions inherited from UsdSchemaBase
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Additional Inherited Members

- Static Protected Member Functions inherited from UsdAPISchemaBase
template<typename APISchemaType >
static APISchemaType _ApplyAPISchema (const UsdPrim &prim, const TfToken &apiSchemaName)
 Helper method to apply a single-apply API schema with the given schema name apiSchemaName' and C++ type 'APISchemaType'. More...
 
template<typename APISchemaType >
static APISchemaType _MultipleApplyAPISchema (const UsdPrim &prim, const TfToken &apiSchemaName, const TfToken &instanceName)
 Helper method to apply a multiple-apply API schema with the given schema name apiSchemaName', C++ type 'APISchemaType' and instance name instanceName. 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.

Definition at line 89 of file xformCommonAPI.h.


Class Documentation

struct UsdGeomXformCommonAPI::Ops

Return type for CreateXformOps().

Stores the op of each type that is present on the prim. The order of members in this struct corresponds to the expected op order for XformCommonAPI.

Definition at line 194 of file xformCommonAPI.h.

Class Members
UsdGeomXformOp inversePivotOp
UsdGeomXformOp pivotOp
UsdGeomXformOp rotateOp
UsdGeomXformOp scaleOp
UsdGeomXformOp translateOp

Member Enumeration Documentation

enum OpFlags

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

For use with CreateXformOps().

Definition at line 182 of file xformCommonAPI.h.

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

Definition at line 171 of file xformCommonAPI.h.

Constructor & Destructor Documentation

UsdGeomXformCommonAPI ( const UsdPrim prim = UsdPrim())
inlineexplicit

Construct a UsdGeomXformCommonAPI on UsdPrim prim .

Equivalent to UsdGeomXformCommonAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 101 of file xformCommonAPI.h.

UsdGeomXformCommonAPI ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdGeomXformCommonAPI on the prim held by schemaObj .

Should be preferred over UsdGeomXformCommonAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 109 of file xformCommonAPI.h.

virtual USDGEOM_API ~UsdGeomXformCommonAPI ( )
virtual

Destructor.

Member Function Documentation

USDGEOM_API UsdSchemaType _GetSchemaType ( ) const
overrideprotectedvirtual

Returns the type of schema this class belongs to.

See Also
UsdSchemaType

Reimplemented from UsdAPISchemaBase.

USDGEOM_API bool _IsCompatible ( ) const
overrideprotectedvirtual

Returns whether the underlying xformable is compatible with the API.

Reimplemented from UsdAPISchemaBase.

static USDGEOM_API bool CanConvertOpTypeToRotationOrder ( UsdGeomXformOp::Type  opType)
static

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

static USDGEOM_API RotationOrder ConvertOpTypeToRotationOrder ( UsdGeomXformOp::Type  opType)
static

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.

static USDGEOM_API UsdGeomXformOp::Type ConvertRotationOrderToOpType ( RotationOrder  rotOrder)
static

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.

USDGEOM_API Ops CreateXformOps ( RotationOrder  rotOrder,
OpFlags  op1 = OpNone,
OpFlags  op2 = OpNone,
OpFlags  op3 = OpNone,
OpFlags  op4 = OpNone 
) const

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

USDGEOM_API Ops CreateXformOps ( OpFlags  op1 = OpNone,
OpFlags  op2 = OpNone,
OpFlags  op3 = OpNone,
OpFlags  op4 = OpNone 
) const

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

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

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

Deprecated:
Please use the result of ConvertRotationOrderToOpType() along with UsdGeomXformOp::GetOpTransform() instead.
static USDGEOM_API const TfTokenVector& GetSchemaAttributeNames ( bool  includeInherited = true)
static

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.

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

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

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

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

Set rotation at time to rotation.

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

Set scale at time to scale.

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

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

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.

Member Data Documentation

const UsdSchemaType schemaType = UsdSchemaType::NonAppliedAPI
static

Compile time constant representing what kind of schema this class is.

See Also
UsdSchemaType

Definition at line 95 of file xformCommonAPI.h.


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