Imath
<navlinks>
<page>

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

</page>