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#

usdex::core::RotationOrder

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

Functions#

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.

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

Enumerations#

enum class usdex::core::RotationOrder#

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

Values:

enumerator eXyz#
enumerator eXzy#
enumerator eYxz#
enumerator eYzx#
enumerator eZxy#
enumerator eZyx#

Functions#

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.

Parameters:

  • prim – The prim to get local transform from.

  • time – Time at which to query the value.

Returns:

Transform value as a transform.

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.

Parameters:

  • prim – The prim to get local transform from.

  • translation – Translation result.

  • pivot – Pivot position result.

  • rotation – Rotation result in degrees.

  • rotationOrder – Rotation order the rotation result.

  • scale – Scale result.

  • time – Time at which to query the value.

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.

Parameters:

  • prim – The prim to get local transform from.

  • time – Time at which to query the value.

Returns:

Transform value as a 4x4 matrix.

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.

Parameters:

  • prim – The prim to set local transform on.

  • matrix – The matrix value to set.

  • time – Time at which to write the value.

Returns:

A bool indicating if the local transform was set.

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.

Parameters:

  • prim – The prim to set local transform on.

  • translation – The translation value to set.

  • pivot – The pivot position value to set.

  • rotation – The rotation value to set in degrees.

  • rotationOrder – The rotation order of the rotation value.

  • scale – The scale value to set.

  • time – Time at which to write the values.

Returns:

True if the transform was set successfully.

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

Set the local transform of a prim.

Parameters:

  • prim – The prim to set local transform on.

  • transform – The transform value to set.

  • time – Time at which to write the value.

Returns:

A bool indicating if the local transform was set.

On this page