UT_TransformUtil.h File Reference

#include "UT_API.h"
#include "UT_Array.h"
#include "UT_Assert.h"
#include "UT_Matrix3.h"
#include "UT_Matrix4.h"
#include "UT_Quaternion.h"
#include "UT_SmallArray.h"
#include "UT_Vector3.h"
#include "UT_Vector4.h"
#include <SYS/SYS_Math.h>

Include dependency graph for UT_TransformUtil.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	UT_SlerpCache< PREC >
struct	UT_Detail::QuatSlerp< T, NORMALIZE_WEIGHTS >
struct	UT_Detail::QuatSlerp< T, false >
struct	UT_Detail::QuatSlerp< T, true >

Namespaces
	UT_Detail
	detail

Macros
#define	UT_TRANSFORM_COMBINE(M, A)
#define	IF_UT_TRANSFORM_COMBINE(M, A)

Enumerations
enum	UT_ScaleInheritanceMode {   UT_ScaleInheritanceMode::DEFAULT = 0, UT_ScaleInheritanceMode::OFFSET_ONLY, UT_ScaleInheritanceMode::OFFSET_AND_SCALE, UT_ScaleInheritanceMode::SCALE_ONLY,   UT_ScaleInheritanceMode::IGNORE_PARENT_LOCAL }
	Scale inheritance modes. More...
enum	UT_ParameterTransformMode { UT_ParameterTransformMode::MODE_PRE = 0, UT_ParameterTransformMode::MODE_POST, UT_ParameterTransformMode::MODE_OVERRIDE }
enum	UT_SLERP_METHOD { UT_SLERP_METHOD::NLERP, UT_SLERP_METHOD::ACCURATE }
	Method of slerp for blending. More...
enum	UT_SLERP_FLIP_METHOD { UT_SLERP_FLIP_METHOD::FIRST, UT_SLERP_FLIP_METHOD::SUCCESSIVE }
	Flip method for slerp to ensure consistency during blending. More...

Functions
template<typename PREC >
SYS_FORCE_INLINE UT_Matrix4T < PREC >	UTtransformCombineLocal (const UT_Matrix4T< PREC > &L, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pL, UT_ScaleInheritanceMode mode=UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *effective_local=nullptr, UT_Matrix3T< PREC > *pLS_ptr=nullptr, UT_Matrix3T< PREC > *pLS_inv_ptr=nullptr, bool *pLS_init_ptr=nullptr)
template<typename PREC , UT_ScaleInheritanceMode MODE, bool HAS_PLS>
SYS_FORCE_INLINE UT_Matrix4T < PREC >	UTtransformCombineLocalT (const UT_Matrix4T< PREC > &L, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pL, UT_Matrix4T< PREC > *effective_local=nullptr, UT_Matrix3T< PREC > *pLS_ptr=nullptr, UT_Matrix3T< PREC > *pLS_inv_ptr=nullptr, bool *pLS_init_ptr=nullptr)
template<typename PREC >
UT_Matrix4T< PREC >	UTtransformExtractLocal (const UT_Matrix4T< PREC > &W, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pL, UT_ScaleInheritanceMode mode=UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *effective_local=nullptr)
	Extract relative transform with scale inheritance. More...
template<typename PREC >
void	UTtransformExtractLocal (UT_Matrix4T< PREC > &L, const UT_Matrix4T< PREC > &W, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pW_inv, const UT_Matrix4T< PREC > &pL, UT_ScaleInheritanceMode mode, UT_Matrix4T< PREC > *effective_local)
	Extract relative transform with scale inheritance. More...
template<typename PREC , UT_ScaleInheritanceMode MODE = UT_ScaleInheritanceMode::DEFAULT, bool HAS_EFFECTIVE_LOCAL = false>
SYS_FORCE_INLINE void	UTtransformExtractLocalT (UT_Matrix4T< PREC > &L, const UT_Matrix4T< PREC > &W, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pW_inv, const UT_Matrix4T< PREC > &pL, UT_Matrix4T< PREC > *effective_local)
	Extract relative transform with scale inheritance. More...
template<typename PREC >
SYS_FORCE_INLINE UT_Matrix4T < PREC >	UTcombineParametersWithLocalTransform (const UT_Matrix4T< PREC > &local, const UT_XformOrder &parm_ord, UT_Vector3T< PREC > parm_t, UT_Vector3T< PREC > parm_r, UT_Vector3T< PREC > parm_s, UT_Vector3T< PREC > parm_sh, const typename UT_Matrix4T< PREC >::PivotSpace &pivot_space=typename UT_Matrix4T< PREC >::PivotSpace{}, const UT_ParameterTransformMode mode=UT_ParameterTransformMode::MODE_PRE)
template<typename PREC >
SYS_FORCE_INLINE std::tuple < UT_Vector3T< PREC > , UT_Vector3T< PREC > , UT_Vector3T< PREC > , UT_Vector3T< PREC > >	UTextractParametersFromLocalTransform (const UT_Matrix4T< PREC > &local, const UT_Matrix4T< PREC > &relative_local, const UT_XformOrder &parm_ord, const typename UT_Matrix4T< PREC >::PivotSpace &pivot_space=typename UT_Matrix4T< PREC >::PivotSpace{}, const UT_ParameterTransformMode mode=UT_ParameterTransformMode::MODE_PRE, const UT_Vector3T< PREC > &reflection_hint=UT_Vector3T< PREC >(1., 1., 1.))
	Extracts the local space transformation components from the local matrix with respect to the relativelocal matrix. More...
template<typename PREC , bool NORMALIZE_WEIGHTS = true, UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>
UT_Matrix4T< PREC >	UTslerp (const UT_Array< UT_Matrix4T< PREC >> &xforms, const UT_Array< PREC > &input_weights)
	Spherically blend transforms by decomposing into separate quaternions. More...
template<typename PREC , UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>
SYS_FORCE_INLINE UT_Matrix4T < PREC >	UTslerp (const UT_Matrix4T< PREC > &xform0, const UT_Matrix4T< PREC > &xform1, const PREC input_weight)
	Spherically blend 2 transforms by decomposing into separate quaternions. More...
template<typename PREC , bool NORMALIZE_WEIGHTS = true>
UT_QuaternionT< PREC >	UTslerp (const UT_Array< UT_QuaternionT< PREC >> &quats, const UT_Array< PREC > &weights)
	Spherically blend multiple quaternions, provided for interface consistency. More...
template<typename PREC , UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>
UT_Matrix4T< PREC >	UTslerp (const UT_Matrix4T< PREC > &xform0, const UT_Matrix4T< PREC > &xform1, const PREC input_weight, UT_SlerpCache< PREC > *makerotcache)
template<typename PREC >
UT_Matrix4T< PREC >	UTtransformCombineLocal (const UT_Matrix4T< PREC > &L, const UT_Matrix4T< PREC > &pW, const UT_Matrix4T< PREC > &pL, UT_ScaleInheritanceMode mode, UT_Matrix4T< PREC > *effective_local, UT_Matrix3T< PREC > *pLS_ptr, UT_Matrix3T< PREC > *pLS_inv_ptr, bool *pLS_init_ptr)
template<typename PREC >
void	UTcombineParameterTransform (UT_Matrix4T< PREC > &local, const UT_Vector3T< PREC > &parent_local_s, const UT_XformOrder &adjust_ord, const UT_Vector3T< PREC > &parm_t, const UT_Vector3T< PREC > &parm_r, const UT_Vector3T< PREC > &parm_s, const UT_Vector3T< PREC > &parm_p, const UT_Vector3T< PREC > &parm_pr, const UT_ScaleInheritanceMode scalecomp, const UT_ParameterTransformMode mode)
template<typename PREC >
void	UTextractParameterTransform (const UT_Matrix4T< PREC > &local, const UT_Matrix4T< PREC > &inputlocal, const UT_XformOrder &parmorder, const UT_ScaleInheritanceMode scalecomp, const UT_ParameterTransformMode mode, const UT_Vector3T< PREC > &parent_local_s, UT_Vector3T< PREC > &parm_t, UT_Vector3T< PREC > &parm_r, UT_Vector3T< PREC > &parm_s)
template<typename PREC >
SYS_FORCE_INLINE void	detail::UTexplodeWithReflectionHint (const UT_Matrix4T< PREC > &xform, const UT_Vector3T< PREC > &reflect_hint, UT_Vector3T< PREC > &xform_r, UT_Vector3T< PREC > &xform_s, UT_Vector3T< PREC > &xform_t, const typename UT_Matrix4T< PREC >::PivotSpace &pivot_space, UT_Vector3T< PREC > *xform_sh)

Detailed Description

Additional utilities for dealing with transforms

Definition in file UT_TransformUtil.h.

Macro Definition Documentation

#define IF_UT_TRANSFORM_COMBINE	(		M,
			A
	)

Value:

if (mode == M) \
        UT_TRANSFORM_COMBINE(M, A) \

#define UT_TRANSFORM_COMBINE	(		M,
			A
	)

Value:

return UTtransformCombineLocalT<PREC, M, A>( \
            L, pW, pL, effective_local, pLS_ptr, pLS_inv_ptr, pLS_init_ptr); \

Enumeration Type Documentation

enum UT_ParameterTransformMode

strong

Enumerator
MODE_PRE
MODE_POST
MODE_OVERRIDE

Definition at line 53 of file UT_TransformUtil.h.

enum UT_ScaleInheritanceMode

strong

Scale inheritance modes.

Enumerator
DEFAULT	simple inheritance: W = L * pW
OFFSET_ONLY	child doesn't scale with the parent local scales, but local translation is scaled: W = SR * pLS^-1 * T * pW (Maya segment scale compensation)
OFFSET_AND_SCALE	local translation is scaled as before but parent local scaling is also reapplied by the child in local space: W = pLS * SR * pLS^-1 * T * pW (Softimage hierarchical scaling)
SCALE_ONLY	local translation is not scaled, but parent local scaling is reapplied by the child in local space: W = pLS * SRT * pLS^-1 * pW
IGNORE_PARENT_LOCAL	child completely ignores any parent local scaling: W = SRT * pLS^-1 * pW

Definition at line 29 of file UT_TransformUtil.h.

enum UT_SLERP_FLIP_METHOD

strong

Flip method for slerp to ensure consistency during blending.

Enumerator
FIRST
SUCCESSIVE	use hemisphere of first quaternion

Definition at line 241 of file UT_TransformUtil.h.

enum UT_SLERP_METHOD

strong

Method of slerp for blending.

Enumerator
NLERP
ACCURATE	normalized lerp of quaternion

Definition at line 234 of file UT_TransformUtil.h.

Function Documentation

template<typename PREC >

SYS_FORCE_INLINE UT_Matrix4T< PREC > UTcombineParametersWithLocalTransform	(	const UT_Matrix4T< PREC > &	local,
		const UT_XformOrder &	parm_ord,
		UT_Vector3T< PREC >	parm_t,
		UT_Vector3T< PREC >	parm_r,
		UT_Vector3T< PREC >	parm_s,
		UT_Vector3T< PREC >	parm_sh,
		const typename UT_Matrix4T< PREC >::PivotSpace &	pivot_space = typename UT_Matrix4T<PREC>::PivotSpace{},
		const UT_ParameterTransformMode	mode = UT_ParameterTransformMode::MODE_PRE
	)

Combines the local space transform components with a local space matrix.

The matrix composition takes the follow forms: UT_ParameterTransformMode::MODE_PRE: M = S_parm * S_local * (Sh_parm + Sh_local)

• R_parm * T_parm * R_local * T_local

UT_ParameterTransformMode::MODE_POST: M = S_local * S_parm * (Sh_local + Sh_parm)

• R_local * R_parm * T_local * T_parm

UT_ParameterTransformMode::MODE_OVERRIDE: M = S_parm * Sh_parm * R_parm * T_parm

MODE_PRE behaves similarly to a traditional parent-child transformation (with the component parameters representing the child and the local matrix representing the parent); however, the parent's scaling and shearing are applied in the child's local space. This behavior is desirable when the parent matrix represents a local space rest transform. For example, a prop's rest scale can be manipulated without affecting its animated position. Simultaneously, this behavior avoids unintentional shearing when the prop rotates while non-uniformly scaled.

MODE_POST first applies the local transformation (eg. a local space rest transform). Then, the rotation and translation parameters are applied using the local transform's position as its pivot point (essentially layering the rotation translation on top of local transformation). The scale and shear parameters are combined with the local transform's scale and shear in the same manner as MODE_PRE. Mathematically, this can be understood as adding the following pivot: R_local * T_local * pivot^1 * R_parm * pivot * T_parm = R_local * T_local * (T_local)^1 * R_parm * (T_local) * T_parm = R_local * R_parm * T_local * T_parm

MODE_OVERRIDE forms a transformation from the parameter components and ignores the local matrix.

Template Parameters

PREC	Precision of the matrix and vector types

Parameters

local	A local space matrix
parm_ord	Transform and rotation order of transform components
parm_t	Translation
parm_r	Rotation (Euler angles in degrees). Respects parm_ord.
parm_s	Scale
parm_sh	Shear
pivot_space	Pivot space for the components
mode	Controls how the components are combined with the local matrix

Returns

The combined local space transformation matrix

Definition at line 1413 of file UT_TransformUtil.h.

template<typename PREC >

void UTcombineParameterTransform ( UT_Matrix4T< PREC > &  local, const UT_Vector3T< PREC > &  parent_local_s, const UT_XformOrder &  adjust_ord, const UT_Vector3T< PREC > &  parm_t, const UT_Vector3T< PREC > &  parm_r, const UT_Vector3T< PREC > &  parm_s, const UT_Vector3T< PREC > &  parm_p, const UT_Vector3T< PREC > &  parm_pr, const UT_ScaleInheritanceMode  scalecomp, const UT_ParameterTransformMode  mode  )

inline

Definition at line 1154 of file UT_TransformUtil.h.

template<typename PREC >

SYS_FORCE_INLINE std::tuple< UT_Vector3T< PREC >, UT_Vector3T< PREC >, UT_Vector3T< PREC >, UT_Vector3T< PREC > > UTextractParametersFromLocalTransform	(	const UT_Matrix4T< PREC > &	local,
		const UT_Matrix4T< PREC > &	relative_local,
		const UT_XformOrder &	parm_ord,
		const typename UT_Matrix4T< PREC >::PivotSpace &	pivot_space = typename UT_Matrix4T<PREC>::PivotSpace{},
		const UT_ParameterTransformMode	mode = UT_ParameterTransformMode::MODE_PRE,
		const UT_Vector3T< PREC > &	reflection_hint = UT_Vector3T<PREC>(1., 1., 1.)
	)

Extracts the local space transformation components from the local matrix with respect to the relativelocal matrix.

This function behaves as the inverse of UTcombineParametersWithLocalTransform(). In particular, if the returned parameters are re-combined with the relative_local matrix using UTcombineParametersWithLocalTransform(), then the local matrix will be reformed. As such, this function is useful for rig inversion workflows in which the end goal is to produce the animated components which would re-construct the local matrix. The relative_local matrix could represent a rest matrix or some other input pose upon which to transfer animation.

Template Parameters

PREC	Precision of the matrix and vector types

Parameters

local	A local space matrix from which to extract the transform components
relative_local	The extraction of the transform components is performed relative to this matrix
parm_ord	Transform and rotation order
pivot_space	Pivot space for the extracted components
mode	Controls how the extraction of the parameter components happens in relation to the relative_local matrix
reflection_hint	A vector which provides a hint as to which axes should have negative scales. The sign of each vector component is used.

Returns

Tuple representing the extracted translation, rotation (Euler angles in degrees), scale, and shear components (in that order)

Definition at line 1522 of file UT_TransformUtil.h.

template<typename PREC >

void UTextractParameterTransform ( const UT_Matrix4T< PREC > &  local, const UT_Matrix4T< PREC > &  inputlocal, const UT_XformOrder &  parmorder, const UT_ScaleInheritanceMode  scalecomp, const UT_ParameterTransformMode  mode, const UT_Vector3T< PREC > &  parent_local_s, UT_Vector3T< PREC > &  parm_t, UT_Vector3T< PREC > &  parm_r, UT_Vector3T< PREC > &  parm_s  )

inline

Definition at line 1259 of file UT_TransformUtil.h.

template<typename PREC , bool NORMALIZE_WEIGHTS = true, UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>

UT_Matrix4T< PREC > UTslerp ( const UT_Array< UT_Matrix4T< PREC >> &  xforms, const UT_Array< PREC > &  input_weights  )

inline

Spherically blend transforms by decomposing into separate quaternions.

Definition at line 750 of file UT_TransformUtil.h.

template<typename PREC , UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>

SYS_FORCE_INLINE UT_Matrix4T< PREC > UTslerp	(	const UT_Matrix4T< PREC > &	xform0,
		const UT_Matrix4T< PREC > &	xform1,
		const PREC	input_weight
	)

Spherically blend 2 transforms by decomposing into separate quaternions.

Definition at line 869 of file UT_TransformUtil.h.

template<typename PREC , bool NORMALIZE_WEIGHTS = true>

UT_QuaternionT< PREC > UTslerp	(	const UT_Array< UT_QuaternionT< PREC >> &	quats,
		const UT_Array< PREC > &	weights
	)

Spherically blend multiple quaternions, provided for interface consistency.

Definition at line 1145 of file UT_TransformUtil.h.

template<typename PREC , UT_SLERP_METHOD METHOD = UT_SLERP_METHOD::ACCURATE, UT_SLERP_FLIP_METHOD FLIP_METHOD = UT_SLERP_FLIP_METHOD::SUCCESSIVE>

UT_Matrix4T< PREC > UTslerp ( const UT_Matrix4T< PREC > &  xform0, const UT_Matrix4T< PREC > &  xform1, const PREC  input_weight, UT_SlerpCache< PREC > *  makerotcache  )

inline

Spherically blend 2 transforms by decomposing into separate quaternions Also makes use of a cache to avoid calling makeRotationMatrix if the input matrices didn't change. 2 cache entries are used per invocation.

Definition at line 976 of file UT_TransformUtil.h.

template<typename PREC >

SYS_FORCE_INLINE UT_Matrix4T<PREC> UTtransformCombineLocal ( const UT_Matrix4T< PREC > &  L, const UT_Matrix4T< PREC > &  pW, const UT_Matrix4T< PREC > &  pL, UT_ScaleInheritanceMode  mode = UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *  effective_local = nullptr, UT_Matrix3T< PREC > *  pLS_ptr = nullptr, UT_Matrix3T< PREC > *  pLS_inv_ptr = nullptr, bool *  pLS_init_ptr = nullptr  )

inline

Combine a local transform on top of another with scale inheritance options L is modified to contain the effective local transform on return for t.

Parameters

pW	local transform
pL	parent world transform
mode	parent local transform
pLS_inv_ptr	parent local transform stretch
pLS_init_ptr	parent local transform stretch_inv

Definition at line 423 of file UT_TransformUtil.h.

template<typename PREC >

UT_Matrix4T<PREC> UTtransformCombineLocal ( const UT_Matrix4T< PREC > &  L, const UT_Matrix4T< PREC > &  pW, const UT_Matrix4T< PREC > &  pL, UT_ScaleInheritanceMode  mode = UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *  effective_local = nullptr, UT_Matrix3T< PREC > *  pLS_ptr = nullptr, UT_Matrix3T< PREC > *  pLS_inv_ptr = nullptr, bool *  pLS_init_ptr = nullptr  )

inline

Combine a local transform on top of another with scale inheritance options L is modified to contain the effective local transform on return for t.

Parameters

pW	local transform
pL	parent world transform
mode	parent local transform
pLS_inv_ptr	parent local transform stretch
pLS_init_ptr	parent local transform stretch_inv

Definition at line 423 of file UT_TransformUtil.h.

template<typename PREC , UT_ScaleInheritanceMode MODE, bool HAS_PLS>

SYS_FORCE_INLINE UT_Matrix4T< PREC > UTtransformCombineLocalT	(	const UT_Matrix4T< PREC > &	L,
		const UT_Matrix4T< PREC > &	pW,
		const UT_Matrix4T< PREC > &	pL,
		UT_Matrix4T< PREC > *	effective_local = nullptr,
		UT_Matrix3T< PREC > *	pLS_ptr = nullptr,
		UT_Matrix3T< PREC > *	pLS_inv_ptr = nullptr,
		bool *	pLS_init_ptr = nullptr
	)

Combine a local transform on top of another with scale inheritance options L is modified to contain the effective local transform on return for t. Same as UTtransformCombineLocal, but with mode passed as a template argument and an optimization with HAS_EFFECTIVE_LOCAL.

Parameters

pW	local transform
pL	parent world transform
effective_local	parent local transform
pLS_inv_ptr	parent local transform stretch
pLS_init_ptr	parent local transform stretch_inv

Definition at line 310 of file UT_TransformUtil.h.

template<typename PREC >

UT_Matrix4T< PREC > UTtransformExtractLocal ( const UT_Matrix4T< PREC > &  W, const UT_Matrix4T< PREC > &  pW, const UT_Matrix4T< PREC > &  pL, UT_ScaleInheritanceMode  mode = UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *  effective_local = nullptr  )

inline

Extract relative transform with scale inheritance.

Parameters

pW	source world transform
pL	target parent world
mode	target parent local

Definition at line 728 of file UT_TransformUtil.h.

template<typename PREC >

void UTtransformExtractLocal ( UT_Matrix4T< PREC > &  L, const UT_Matrix4T< PREC > &  W, const UT_Matrix4T< PREC > &  pW, const UT_Matrix4T< PREC > &  pW_inv, const UT_Matrix4T< PREC > &  pL, UT_ScaleInheritanceMode  mode = UT_ScaleInheritanceMode::DEFAULT, UT_Matrix4T< PREC > *  effective_local = nullptr  )

inline

Extract relative transform with scale inheritance.

Parameters

pW	source world transform
pW_inv	target parent world
pL	target parent world
mode	target parent local

Definition at line 469 of file UT_TransformUtil.h.

template<typename PREC , UT_ScaleInheritanceMode MODE = UT_ScaleInheritanceMode::DEFAULT, bool HAS_EFFECTIVE_LOCAL = false>

SYS_FORCE_INLINE void UTtransformExtractLocalT	(	UT_Matrix4T< PREC > &	L,
		const UT_Matrix4T< PREC > &	W,
		const UT_Matrix4T< PREC > &	pW,
		const UT_Matrix4T< PREC > &	pW_inv,
		const UT_Matrix4T< PREC > &	pL,
		UT_Matrix4T< PREC > *	effective_local = nullptr
	)

Extract relative transform with scale inheritance.

Parameters

pW	source world transform
pW_inv	target parent world
pL	target parent world
effective_local	target parent local

Definition at line 599 of file UT_TransformUtil.h.