3D Transformations#

Utility functions to manipulate 3D transformation data on UsdGeomXformable Prims.

The UsdGeomXformable schema supports a rich set of transform operations from which a resulting matrix can be computed.

The flexibility of this system adds complexity to the code required for authoring and retrieving transform information. This module provides functions for authoring and retrieving transformation using a standard suite of transform formats.

The goal of these functions is to decouple the caller’s preferred transform format from the format in which the transform is stored on the UsdPrim. This is accomplished by internally converting between formats as needed, and modifing the storage format when required.

Getting Transforms#

The getLocalTransform functions will retrieve the local transform of a UsdPrim in the format requested.

  • If the existing UsdGeomXformOps can be mapped to the requested format, then the components will be populated with the values authored.

  • If there is no clear mapping, then a local transformation matrix will be computed, and the components extracted from that.

Setting Transforms#

The setLocalTransform functions will set the values of existing UsdGeomXformOps on a UsdPrim to achieve the transform supplied.

  • If the given format can be mapped to the existing UsdGeomXformOps, or have mappable values extracted, then the values of those will be set.

  • If the given format (or the value it holds) cannot be mapped to the existing UsdGeomXformOps, then new operations will be authored that can.

  • If no UsdGeomXformOps exist, then new ones matching the format will be authored.

When a value is set at a given time, all existing time samples will be maintained, even in cases where the operations were changed.

Enumerations Summary#

usdex::core::RotationOrder

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

Functions Summary#

pxr::GfTransform usdex::core::getLocalTransform(const pxr::UsdGeomXformable &xformable, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of an xformable at a given time.

pxr::GfTransform usdex::core::getLocalTransform(const pxr::UsdPrim &prim, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time.

void usdex::core::getLocalTransformComponents(const pxr::UsdPrim &prim, pxr::GfVec3d &translation, pxr::GfVec3d &pivot, pxr::GfVec3f &rotation, RotationOrder &rotationOrder, pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time in the form of common transform components.

void usdex::core::getLocalTransformComponents(const pxr::UsdGeomXformable &xformable, pxr::GfVec3d &translation, pxr::GfVec3d &pivot, pxr::GfVec3f &rotation, RotationOrder &rotationOrder, pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of an xformable at a given time in the form of common transform components.

void usdex::core::getLocalTransformComponentsQuat(const pxr::UsdGeomXformable &xformable, pxr::GfVec3d &translation, pxr::GfVec3d &pivot, pxr::GfQuatf &orientation, pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of an xformable at a given time in the form of common transform components with quaternion orientation.

void usdex::core::getLocalTransformComponentsQuat(const pxr::UsdPrim &prim, pxr::GfVec3d &translation, pxr::GfVec3d &pivot, pxr::GfQuatf &orientation, pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time in the form of common transform components with quaternion orientation.

pxr::GfMatrix4d usdex::core::getLocalTransformMatrix(const pxr::UsdGeomXformable &xformable, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of an xformable at a given time in the form of a 4x4 matrix.

pxr::GfMatrix4d usdex::core::getLocalTransformMatrix(const pxr::UsdPrim &prim, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time in the form of a 4x4 matrix.

bool usdex::core::setLocalTransform(const pxr::UsdGeomXformable &xformable, const pxr::GfVec3d &translation, const pxr::GfVec3d &pivot, const pxr::GfVec3f &rotation, const RotationOrder rotationOrder, const pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of an xformable from common transform components.

bool usdex::core::setLocalTransform(pxr::UsdPrim prim, const pxr::GfMatrix4d &matrix, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim from a 4x4 matrix.

bool usdex::core::setLocalTransform(pxr::UsdPrim prim, const pxr::GfVec3d &translation, const pxr::GfVec3d &pivot, const pxr::GfVec3f &rotation, const RotationOrder rotationOrder, const pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim from common transform components.

bool usdex::core::setLocalTransform(pxr::UsdPrim prim, const pxr::GfTransform &transform, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim.

bool usdex::core::setLocalTransform(const pxr::UsdGeomXformable &xformable, const pxr::GfMatrix4d &matrix, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of an xformable from a 4x4 matrix.

bool usdex::core::setLocalTransform(const pxr::UsdGeomXformable &xformable, const pxr::GfTransform &transform, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of an xformable.

bool usdex::core::setLocalTransform(const pxr::UsdGeomXformable &xformable, const pxr::GfVec3d &translation, const pxr::GfQuatf &orientation, const pxr::GfVec3f &scale=pxr::GfVec3f(1.0f, 1.0f, 1.0f), pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of an xformable from common transform components using a quaternion for orientation.

bool usdex::core::setLocalTransform(pxr::UsdPrim prim, const pxr::GfVec3d &translation, const pxr::GfQuatf &orientation, const pxr::GfVec3f &scale=pxr::GfVec3f(1.0f, 1.0f, 1.0f), pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim from common transform components using a quaternion for orientation.