Euler

#include <Imath/ImathEuler.h>

The Euler class template represents an euler angle rotation/orientation, with predefined typedefs of type float and double.

The Euler class is derived from Imath::Vec3 and thus has fields named x, y, and z, which correspond to the first, second, and third rotation angles in a specified order, which, depending on the order, may not correspond directly to x, y, or z rotations.

Example:

#include <Imath/ImathEuler.h>
#include <ImathMatrixAlgo.h>

void
euler_example()
{
    int i, j, k;
    
    Imath::Eulerf xyz (Imath::Eulerf::XYZ);
    xyz.angleOrder (i, j, k);
    assert (i == 0 && j == 1 && k == 2);

    Imath::Eulerf xzy (Imath::Eulerf::XZY);
    xzy.angleOrder (i, j, k);
    assert (i == 0 && j == 2 && k == 1);

    Imath::Eulerf e1 (0.0f, 0.0f, 0.1f + 2 * M_PI);
    Imath::Eulerf e2 (0.0f, 0.0f, 0.1f);

    e1.makeNear (e2);
    Imath::V3f v = e2.toXYZVector();
    assert (v.equalWithAbsError (Imath::V3f (0.0f, 0.0f, 0.1f), 0.00001f));
}
  
typedef Euler<float> Imath::Eulerf

Euler of type float.

typedef Euler<double> Imath::Eulerd

Euler of type double.

template<class T>
class Imath::Euler : public Imath::Vec3<T>

Template class Euler<T>

The Euler 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.

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 Euler() noexcept

No initialization by default.

constexpr Euler(const Euler&) noexcept

Copy constructor.

constexpr Euler(Order p) noexcept

Construct from given Order.

constexpr Euler(const Vec3<T> &v, Order o = Default, InputLayout l = IJKLayout) noexcept

Construct from vector, order, layout.

constexpr Euler(T i, T j, T k, Order o = Default, InputLayout l = IJKLayout) noexcept

Construct from explicit axes, order, layout.

constexpr Euler(const Euler<T> &euler, Order newp) noexcept

Copy constructor with new Order.

constexpr Euler(const Matrix33<T>&, Order o = Default) noexcept

Construct from Matrix33.

constexpr Euler(const Matrix44<T>&, Order o = Default) noexcept

Construct from Matrix44.

~Euler() = default

Destructor.

Query

constexpr Order order() const noexcept

Return the order.

inline constexpr bool frameStatic() const

Return frameStatic.

inline constexpr bool initialRepeated() const

Return intialRepeated.

inline constexpr bool parityEven() const

Return partityEven.

inline constexpr Axis initialAxis() const

Return initialAxis.

void angleOrder(int &i, int &j, int &k) const noexcept

Unpack angles from ijk form.

void angleMapping(int &i, int &j, int &k) const noexcept

Determine mapping from xyz to ijk (reshuffle the xyz to match the order)

static constexpr bool legal(Order) noexcept

Return whether the given value is a legal Order.

Set Value

void setOrder(Order) noexcept

Set the order.

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

void 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].

void set(Axis initial, bool relative, bool parityEven, bool firstRepeats) noexcept

Set the value.

Assignments and Conversions

constexpr const Euler<T> &operator=(const Euler<T>&) noexcept

Assignment.

constexpr const Euler<T> &operator=(const Vec3<T>&) noexcept

Assignment.

void extract(const Matrix33<T>&) noexcept

Assign from Matrix33, assumed to be affine.

void extract(const Matrix44<T>&) noexcept

Assign from Matrix44, assumed to be affine.

void extract(const Quat<T>&) noexcept

Assign from Quaternion.

Matrix33<T> toMatrix33() const noexcept

Convert to Matrix33.

Matrix44<T> toMatrix44() const noexcept

Convert to Matrix44.

Quat<T> toQuat() const noexcept

Convert to Quat.

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

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

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

static constexpr float angleMod(T angle) noexcept

Convert an angle to its equivalent in [-PI, PI].

static 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 void nearestRotation(Vec3<T> &xyzRot, const Vec3<T> &targetXyzRot, Order order = XYZ) noexcept

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.

Public Types

enum Order

All 24 possible orderings.

Values:

enumerator XYZ
enumerator XZY
enumerator YZX
enumerator YXZ
enumerator ZXY
enumerator ZYX
enumerator XZX
enumerator XYX
enumerator YXY
enumerator YZY
enumerator ZYZ
enumerator ZXZ
enumerator XYZr
enumerator XZYr
enumerator YZXr
enumerator YXZr
enumerator ZXYr
enumerator ZYXr
enumerator XZXr
enumerator XYXr
enumerator YXYr
enumerator YZYr
enumerator ZYZr
enumerator ZXZr
enumerator Legal
enumerator Min
enumerator Max
enumerator Default
enum Axis

Axes.

Values:

enumerator X
enumerator Y
enumerator Z
enum InputLayout

Layout.

Values:

enumerator XYZLayout
enumerator IJKLayout
template<class T>
std::ostream &Imath::operator<<(std::ostream &o, const Euler<T> &euler)

Stream ouput, as “(x y z i j k)”.