Euler< T > Class Template Reference

#include <ImathEuler.h>

Inheritance diagram for Euler< T >:

Public Types
enum	Order {   XYZ = 0x0101 , XZY = 0x0001 , YZX = 0x1101 , YXZ = 0x1001 ,   ZXY = 0x2101 , ZYX = 0x2001 , XZX = 0x0011 , XYX = 0x0111 ,   YXY = 0x1011 , YZY = 0x1111 , ZYZ = 0x2011 , ZXZ = 0x2111 ,   XYZr = 0x2000 , XZYr = 0x2100 , YZXr = 0x1000 , YXZr = 0x1100 ,   ZXYr = 0x0000 , ZYXr = 0x0100 , XZXr = 0x2110 , XYXr = 0x2010 ,   YXYr = 0x1110 , YZYr = 0x1010 , ZYZr = 0x0110 , ZXZr = 0x0010 ,   Legal , Min = 0x0000 , Max = 0x2111 , Default = XYZ }
enum	Axis { X = 0 , Y = 1 , Z = 2 }
enum	InputLayout { XYZLayout , IJKLayout }
Public Types inherited from Vec3< T >
typedef T	BaseType

Public Member Functions
Constructors
All default to ZYX non-relative (ala Softimage 3D/Maya), where there is no argument to specify it. The Euler-from-matrix constructors assume that the matrix does not include shear or non-uniform scaling, but the constructors do not examine the matrix to verify this assumption. If necessary, you can adjust the matrix by calling the removeScalingAndShear() function, defined in ImathMatrixAlgo.h.
constexpr ATOMSMATH_HOSTDEVICE	Euler () noexcept
	No initialization by default.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (const Euler &) noexcept
	Copy constructor.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (Order p) noexcept
	Construct from given Order.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (const Vec3< T > &v, Order o=Default, InputLayout l=IJKLayout) noexcept
	Construct from vector, order, layout.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (T i, T j, T k, Order o=Default, InputLayout l=IJKLayout) noexcept
	Construct from explicit axes, order, layout.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (const Euler< T > &euler, Order newp) noexcept
	Copy constructor with new Order.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (const Matrix33< T > &, Order o=Default) noexcept
	Construct from Matrix33.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14	Euler (const Matrix44< T > &, Order o=Default) noexcept
	Construct from Matrix44.
	~Euler ()=default
	Destructor.
Set Value
ATOMSMATH_HOSTDEVICE void	setOrder (Order) noexcept
ATOMSMATH_HOSTDEVICE void	setXYZVector (const Vec3< T > &) noexcept
ATOMSMATH_HOSTDEVICE void	set (Axis initial, bool relative, bool parityEven, bool firstRepeats) noexcept
	Set the value.
Assignments and Conversions
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Euler< T > &	operator= (const Euler< T > &) noexcept
	Assignment.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Euler< T > &	operator= (const Vec3< T > &) noexcept
	Assignment.
ATOMSMATH_HOSTDEVICE void	extract (const Matrix33< T > &) noexcept
	Assign from Matrix33, assumed to be affine.
ATOMSMATH_HOSTDEVICE void	extract (const Matrix44< T > &) noexcept
	Assign from Matrix44, assumed to be affine.
ATOMSMATH_HOSTDEVICE void	extract (const Quat< T > &) noexcept
	Assign from Quaternion.
ATOMSMATH_HOSTDEVICE Matrix33< T >	toMatrix33 () const noexcept
	Convert to Matrix33.
ATOMSMATH_HOSTDEVICE Matrix44< T >	toMatrix44 () const noexcept
	Convert to Matrix44.
ATOMSMATH_HOSTDEVICE Quat< T >	toQuat () const noexcept
	Convert to Quat.
ATOMSMATH_HOSTDEVICE Vec3< T >	toXYZVector () const noexcept
Public Member Functions inherited from Vec3< T >
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 T &	operator[] (int i) noexcept
	Element access by index.
constexpr ATOMSMATH_HOSTDEVICE const T &	operator[] (int i) const noexcept
	Element access by index.
short	length () const noexcept=delete
const Vec3< short > &	normalize () noexcept=delete
const Vec3< short > &	normalizeExc ()=delete
const Vec3< short > &	normalizeNonNull () noexcept=delete
Vec3< short >	normalized () const noexcept=delete
Vec3< short >	normalizedExc () const=delete
Vec3< short >	normalizedNonNull () const noexcept=delete
int	length () const noexcept=delete
const Vec3< int > &	normalize () noexcept=delete
const Vec3< int > &	normalizeExc ()=delete
const Vec3< int > &	normalizeNonNull () noexcept=delete
Vec3< int >	normalized () const noexcept=delete
Vec3< int >	normalizedExc () const=delete
Vec3< int >	normalizedNonNull () const noexcept=delete
template<class S >
constexpr	Vec3 (const Vec3< S > &v) noexcept
template<class S >
constexpr	Vec3 (const Vec4< S > &v) noexcept
template<class S >
void	setValue (S a, S b, S c) noexcept
template<class S >
void	setValue (const Vec3< S > &v) noexcept
template<class S >
void	getValue (S &a, S &b, S &c) const noexcept
template<class S >
void	getValue (Vec3< S > &v) const noexcept
template<class S >
constexpr bool	operator== (const Vec3< S > &v) const noexcept
template<class S >
constexpr bool	operator!= (const Vec3< S > &v) const noexcept
ATOMSMATH_HOSTDEVICE	Vec3 () noexcept
	Uninitialized by default.
constexpr ATOMSMATH_HOSTDEVICE	Vec3 (T a) noexcept
	Initialize to a scalar (a,a,a)
constexpr ATOMSMATH_HOSTDEVICE	Vec3 (T a, T b, T c) noexcept
	Initialize to given elements (a,b,c)
constexpr ATOMSMATH_HOSTDEVICE	Vec3 (const Vec3 &v) noexcept
	Copy constructor.
template<class S >
constexpr ATOMSMATH_HOSTDEVICE	Vec3 (const Vec3< S > &v) noexcept
	Construct from Vec3 of another base type.
template<class S >
constexpr ATOMSMATH_HOSTDEVICE	Vec3 (const Vec4< S > &v) noexcept
template<class S >
ATOMSMATH_CONSTEXPR14	Vec3 (const Vec4< S > &v, InfException)
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator= (const Vec3 &v) noexcept
	Assignment.
	~Vec3 () noexcept=default
	Destructor.
template<class S >
ATOMSMATH_HOSTDEVICE void	setValue (S a, S b, S c) noexcept
	Set the value.
template<class S >
ATOMSMATH_HOSTDEVICE void	setValue (const Vec3< S > &v) noexcept
	Set the value.
template<class S >
ATOMSMATH_HOSTDEVICE void	getValue (S &a, S &b, S &c) const noexcept
	Return the value in a, b, and c
template<class S >
ATOMSMATH_HOSTDEVICE void	getValue (Vec3< S > &v) const noexcept
	Return the value in v
ATOMSMATH_HOSTDEVICE T *	getValue () noexcept
	Return a raw pointer to the array of values.
ATOMSMATH_HOSTDEVICE const T *	getValue () const noexcept
	Return a raw pointer to the array of values.
template<class S >
constexpr ATOMSMATH_HOSTDEVICE bool	operator== (const Vec3< S > &v) const noexcept
	Equality.
template<class S >
constexpr ATOMSMATH_HOSTDEVICE bool	operator!= (const Vec3< S > &v) const noexcept
	Inequality.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 bool	equalWithAbsError (const Vec3< T > &v, T e) const noexcept
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 bool	equalWithRelError (const Vec3< T > &v, T e) const noexcept
constexpr ATOMSMATH_HOSTDEVICE T	dot (const Vec3 &v) const noexcept
	Dot product.
constexpr ATOMSMATH_HOSTDEVICE T	operator^ (const Vec3 &v) const noexcept
	Dot product.
constexpr ATOMSMATH_HOSTDEVICE Vec3	cross (const Vec3 &v) const noexcept
	Right-handed cross product.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator%= (const Vec3 &v) noexcept
	Right-handed cross product.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator% (const Vec3 &v) const noexcept
	Right-handed cross product.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator+= (const Vec3 &v) noexcept
	Component-wise addition.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator+ (const Vec3 &v) const noexcept
	Component-wise addition.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator-= (const Vec3 &v) noexcept
	Component-wise subtraction.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator- (const Vec3 &v) const noexcept
	Component-wise subtraction.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator- () const noexcept
	Component-wise multiplication by -1.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	negate () noexcept
	Component-wise multiplication by -1.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator*= (const Vec3 &v) noexcept
	Component-wise multiplication.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator*= (T a) noexcept
	Component-wise multiplication.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator* (const Vec3 &v) const noexcept
	Component-wise multiplication.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator* (T a) const noexcept
	Component-wise multiplication.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator/= (const Vec3 &v) noexcept
	Component-wise division.
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 const Vec3 &	operator/= (T a) noexcept
	Component-wise division.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator/ (const Vec3 &v) const noexcept
	Component-wise division.
constexpr ATOMSMATH_HOSTDEVICE Vec3	operator/ (T a) const noexcept
	Component-wise division.
ATOMSMATH_HOSTDEVICE T	length () const noexcept
	Return the Euclidean norm.
constexpr ATOMSMATH_HOSTDEVICE T	length2 () const noexcept
ATOMSMATH_HOSTDEVICE const Vec3 &	normalize () noexcept
	Normalize in place. If length()==0, return a null vector.
const Vec3 &	normalizeExc ()
	Normalize in place. If length()==0, throw an exception.
ATOMSMATH_HOSTDEVICE const Vec3 &	normalizeNonNull () noexcept
ATOMSMATH_HOSTDEVICE Vec3< T >	normalized () const noexcept
	Return a normalized vector. Does not modify *this.
Vec3< T >	normalizedExc () const
ATOMSMATH_HOSTDEVICE Vec3< T >	normalizedNonNull () const noexcept

Protected Attributes
bool	_frameStatic: 1
	relative or static rotations
bool	_initialRepeated: 1
	init axis repeated as last
bool	_parityEven: 1
	"parity of axis permutation"
Axis	_initialAxis: 2
	First axis of rotation.

Query
ATOMSMATH_HOSTDEVICE ATOMSMATH_CONSTEXPR14 Order	order () const noexcept
	Return the order.
constexpr ATOMSMATH_HOSTDEVICE bool	frameStatic () const
	Return frameStatic.
constexpr ATOMSMATH_HOSTDEVICE bool	initialRepeated () const
	Return intialRepeated.
constexpr ATOMSMATH_HOSTDEVICE bool	parityEven () const
	Return partityEven.
constexpr ATOMSMATH_HOSTDEVICE Axis	initialAxis () const
	Return initialAxis.
ATOMSMATH_HOSTDEVICE void	angleOrder (int &i, int &j, int &k) const noexcept
	Unpack angles from ijk form.
ATOMSMATH_HOSTDEVICE void	angleMapping (int &i, int &j, int &k) const noexcept
	Determine mapping from xyz to ijk (reshuffle the xyz to match the order)
constexpr static ATOMSMATH_HOSTDEVICE bool	legal (Order) noexcept
	Return whether the given value is a legal Order.

Utility Methods
Utility methods for getting continuous rotations. None of these methods change the orientation given by its inputs (or at least that is the intent).
ATOMSMATH_HOSTDEVICE void	makeNear (const Euler< T > &target) noexcept
ATOMSMATH_HOSTDEVICE static ATOMSMATH_CONSTEXPR14 float	angleMod (T angle) noexcept
	Convert an angle to its equivalent in [-PI, PI].
static ATOMSMATH_HOSTDEVICE void	simpleXYZRotation (Vec3< T > &xyzRot, const Vec3< T > &targetXyzRot) noexcept
	Adjust xyzRot so that its components differ from targetXyzRot by no more than +/-PI.
static ATOMSMATH_HOSTDEVICE void	nearestRotation (Vec3< T > &xyzRot, const Vec3< T > &targetXyzRot, Order order=XYZ) noexcept

Additional Inherited Members
Static Public Member Functions inherited from Vec3< T >
constexpr static ATOMSMATH_HOSTDEVICE unsigned int	dimensions () noexcept
	Return the number of dimensions, i.e. 3.
constexpr static ATOMSMATH_HOSTDEVICE T	baseTypeLowest () noexcept
	Largest possible negative value.
constexpr static ATOMSMATH_HOSTDEVICE T	baseTypeMax () noexcept
	Largest possible positive value.
constexpr static ATOMSMATH_HOSTDEVICE T	baseTypeSmallest () noexcept
	Smallest possible positive value.
constexpr static ATOMSMATH_HOSTDEVICE T	baseTypeEpsilon () noexcept
	Smallest possible e for which 1+e != 1.
Public Attributes inherited from Vec3< T >
T	x
T	y
T	z

Detailed Description

template<class T>
class Euler< T >

Template class Euler<T>

This class represents euler angle orientations. The class inherits from Vec3 to it can be freely cast. The additional information is the euler priorities rep. This class is essentially a rip off of Ken Shoemake's GemsIV code. It has been modified minimally to make it more understandable, but hardly enough to make it easy to grok completely.

There are 24 possible combonations of Euler angle representations of which 12 are common in CG and you will probably only use 6 of these which in this scheme are the non-relative-non-repeating types.

The representations can be partitioned according to two criteria:

1) Are the angles measured relative to a set of fixed axis or relative to each other (the latter being what happens when rotation matrices are multiplied together and is almost ubiquitous in the cg community)

2) Is one of the rotations repeated (ala XYX rotation)

When you construct a given representation from scratch you must order the angles according to their priorities. So, the easiest is a softimage or aerospace (yaw/pitch/roll) ordering of ZYX.

float x_rot = 1;
float y_rot = 2;
float z_rot = 3;

Eulerf angles(z_rot, y_rot, x_rot, Eulerf::ZYX);

or:

Eulerf angles( V3f(z_rot,y_rot,z_rot), Eulerf::ZYX );

If instead, the order was YXZ for instance you would have to do this:

float x_rot = 1;
float y_rot = 2;
float z_rot = 3;

Eulerf angles(y_rot, x_rot, z_rot, Eulerf::YXZ);

or:

Eulerf angles( V3f(y_rot,x_rot,z_rot), Eulerf::YXZ );

Notice how the order you put the angles into the three slots should correspond to the enum (YXZ) ordering. The input angle vector is called the "ijk" vector – not an "xyz" vector. The ijk vector order is the same as the enum. If you treat the Euler as a Vec3 (which it inherts from) you will find the angles are ordered in the same way, i.e.:

V3f v = angles;
v.x == y_rot, v.y == x_rot, v.z == z_rot

If you just want the x, y, and z angles stored in a vector in that order, you can do this:

V3f v = angles.toXYZVector()
v.x == x_rot, v.y == y_rot, v.z == z_rot

If you want to set the Euler with an XYZVector use the optional layout argument:

Eulerf angles(x_rot, y_rot, z_rot, Eulerf::YXZ, Eulerf::XYZLayout);

This is the same as:

Eulerf angles(y_rot, x_rot, z_rot, Eulerf::YXZ);

Note that this won't do anything intelligent if you have a repeated axis in the euler angles (e.g. XYX)

If you need to use the "relative" versions of these, you will need to use the "r" enums.

The units of the rotation angles are assumed to be radians.

Member Enumeration Documentation

Axis

template<class T >

enum Euler::Axis

Axes

InputLayout

template<class T >

enum Euler::InputLayout

Layout

Order

template<class T >

enum Euler::Order

All 24 possible orderings

Member Function Documentation

makeNear()

template<class T >

ATOMSMATH_HOSTDEVICE void Euler< T >::makeNear ( const Euler< T > &  target )

noexcept

Adjusts "this" Euler so that its components differ from target by as little as possible. This method might not make sense for Eulers with different order and it probably doesn't work for repeated axis and relative orderings (TODO).

nearestRotation()

template<class T >

static ATOMSMATH_HOSTDEVICE void Euler< T >::nearestRotation ( Vec3< T > &  xyzRot, const Vec3< T > &  targetXyzRot, Order  order = XYZ  )

staticnoexcept

Adjust xyzRot so that its components differ from targetXyzRot by as little as possible. Note that xyz here really means ijk, because the order must be provided.

setOrder()

template<class T >

ATOMSMATH_HOSTDEVICE void Euler< T >::setOrder ( Order  )

noexcept

Set the order. This does NOT convert the angles, but it does reorder the input vector.

setXYZVector()

template<class T >

ATOMSMATH_HOSTDEVICE void Euler< T >::setXYZVector ( const Vec3< T > &  )

noexcept

Set the euler value: set the first angle to v[0], the second to v[1], the third to v[2].

toXYZVector()

template<class T >

ATOMSMATH_HOSTDEVICE Vec3<T> Euler< T >::toXYZVector ( ) const

noexcept

Reorder the angles so that the X rotation comes first, followed by the Y and Z in cases like XYX ordering, the repeated angle will be in the "z" component

---

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

• C:/projects/AtomsVFX/Atoms/Public/AtomsMath/ImathEuler.h