Euler

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 <Imath/ImathMatrixAlgo.h>
#include <cassert>

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

No initialization by default.

constexpr Euler(const Euler&)

Copy constructor.

constexpr Euler(Order p)

Construct from given Order.

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

Construct from vector, order, layout.

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

Construct from explicit axes, order, layout.

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

Copy constructor with new Order.

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

Construct from Matrix33.

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

Construct from Matrix44.

~Euler()

Destructor.

Query

constexpr Order order() const

Return the order.

constexpr bool frameStatic() const

Return frameStatic.

constexpr bool initialRepeated() const

Return intialRepeated.

constexpr bool parityEven() const

Return partityEven.

constexpr Axis initialAxis() const

Return initialAxis.

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

Unpack angles from ijk form.

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

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

static constexpr bool legal(Order)

Return whether the given value is a legal Order.

Set Value

void setOrder(Order)

Set the order.

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

void setXYZVector(const Vec3<T>&)

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)

Set the value.

Assignments and Conversions

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

Assignment.

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

Assignment.

void extract(const Matrix33<T>&)

Assign from Matrix33, assumed to be affine.

void extract(const Matrix44<T>&)

Assign from Matrix44, assumed to be affine.

void extract(const Quat<T>&)

Assign from Quaternion.

Matrix33<T> toMatrix33() const

Convert to Matrix33.

Matrix44<T> toMatrix44() const

Convert to Matrix44.

Quat<T> toQuat() const

Convert to Quat.

Vec3<T> toXYZVector() const

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)

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)

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

static void simpleXYZRotation(Vec3<T> &xyzRot, const Vec3<T> &targetXyzRot)

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)

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:

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 = XYZ | XZY | YZX | YXZ | ZXY | ZYX | XZX | XYX | YXY | YZY | ZYZ | ZXZ | XYZr | XZYr | YZXr | YXZr | ZXYr | ZYXr | XZXr | XYXr | YXYr | YZYr | ZYZr | ZXZr
Min = 0x0000
Max = 0x2111
Default = XYZ
enum Axis

Axes.

Values:

X = 0
Y = 1
Z = 2
enum InputLayout

Layout.

Values:

XYZLayout
IJKLayout

Warning

doxygenfunction: Unable to resolve multiple matches for function “operator<<” with arguments (std::ostream& o, const Euler<T>& euler) in doxygen xml output for project “Imath” from directory: /build/ilmbase-TFRjEc/ilmbase-3.1.11/obj-x86_64-linux-gnu/website/doxygen/xml. Potential matches:

- std::ostream &operator<<(std::ostream&, Imath::half)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Color4<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Euler<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Interval<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Line3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix22<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix33<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix44<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Plane3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Quat<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Shear6<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec2<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec4<T>&)