EulerAngles.h

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
// Copyright (C) 2023 Juraj Oršulić, University of Zagreb <juraj.orsulic@fer.hr>
//
// This Source Code Form is subject to the terms of the Mozilla
// Public License v. 2.0. If a copy of the MPL was not distributed
// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0
 
#ifndef EIGEN_EULERANGLES_H
#define EIGEN_EULERANGLES_H
 
// IWYU pragma: private
#include "./InternalHeaderCheck.h"
 
namespace Eigen {

template <typename Derived>
EIGEN_DEVICE_FUNC inline Matrix<typename MatrixBase<Derived>::Scalar, 3, 1> MatrixBase<Derived>::canonicalEulerAngles(
    Index a0, Index a1, Index a2) const {
  /* Implemented from Graphics Gems IV */
  EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(Derived, 3, 3)
 
  Matrix<Scalar, 3, 1> res;
 
  const Index odd = ((a0 + 1) % 3 == a1) ? 0 : 1;
  const Index i = a0;
  const Index j = (a0 + 1 + odd) % 3;
  const Index k = (a0 + 2 - odd) % 3;
 
  if (a0 == a2) {
    // Proper Euler angles (same first and last axis).
    // The i, j, k indices enable addressing the input matrix as the XYX archetype matrix (see Graphics Gems IV),
    // where e.g. coeff(k, i) means third column, first row in the XYX archetype matrix:
    //  c2      s2s1              s2c1
    //  s2s3   -c2s1s3 + c1c3    -c2c1s3 - s1c3
    // -s2c3    c2s1c3 + c1s3     c2c1c3 - s1s3
 
    // Note: s2 is always positive.
    Scalar s2 = numext::hypot(coeff(j, i), coeff(k, i));
    if (odd) {
      res[0] = numext::atan2(coeff(j, i), coeff(k, i));
      // s2 is always positive, so res[1] will be within the canonical [0, pi] range
      res[1] = numext::atan2(s2, coeff(i, i));
    } else {
      // In the !odd case, signs of all three angles are flipped at the very end. To keep the solution within the
      // canonical range, we flip the solution and make res[1] always negative here (since s2 is always positive,
      // -atan2(s2, c2) will always be negative). The final flip at the end due to !odd will thus make res[1] positive
      // and canonical. NB: in the general case, there are two correct solutions, but only one is canonical. For proper
      // Euler angles, flipping from one solution to the other involves flipping the sign of the second angle res[1] and
      // adding/subtracting pi to the first and third angles. The addition/subtraction of pi to the first angle res[0]
      // is handled here by flipping the signs of arguments to atan2, while the calculation of the third angle does not
      // need special adjustment since it uses the adjusted res[0] as the input and produces a correct result.
      res[0] = numext::atan2(-coeff(j, i), -coeff(k, i));
      res[1] = -numext::atan2(s2, coeff(i, i));
    }
 
    // With a=(0,1,0), we have i=0; j=1; k=2, and after computing the first two angles,
    // we can compute their respective rotation, and apply its inverse to M. Since the result must
    // be a rotation around x, we have:
    //
    //  c2  s1.s2 c1.s2                   1  0   0
    //  0   c1    -s1       *    M    =   0  c3  s3
    //  -s2 s1.c2 c1.c2                   0 -s3  c3
    //
    //  Thus:  m11.c1 - m21.s1 = c3  &   m12.c1 - m22.s1 = s3
 
    // Recover sin(res[0]) and cos(res[0]) from the atan2 arguments directly,
    // avoiding a redundant sin+cos evaluation. s2 = hypot(coeff(j,i), coeff(k,i))
    // is the norm of the atan2 arguments (with sign adjustment for !odd).
    Scalar s1, c1;
    if (s2 > NumTraits<Scalar>::epsilon()) {
      Scalar inv_s2 = Scalar(1) / s2;
      if (odd) {
        // res[0] = atan2(coeff(j,i), coeff(k,i))
        s1 = coeff(j, i) * inv_s2;
        c1 = coeff(k, i) * inv_s2;
      } else {
        // res[0] = atan2(-coeff(j,i), -coeff(k,i))
        s1 = -coeff(j, i) * inv_s2;
        c1 = -coeff(k, i) * inv_s2;
      }
    } else {
      // Gimbal lock (s2 ≈ 0): recover sin/cos from the computed angle.
      s1 = numext::sin(res[0]);
      c1 = numext::cos(res[0]);
    }
    res[2] = numext::atan2(c1 * coeff(j, k) - s1 * coeff(k, k), c1 * coeff(j, j) - s1 * coeff(k, j));
  } else {
    // Tait-Bryan angles (all three axes are different; typically used for yaw-pitch-roll calculations).
    // The i, j, k indices enable addressing the input matrix as the XYZ archetype matrix (see Graphics Gems IV),
    // where e.g. coeff(k, i) means third column, first row in the XYZ archetype matrix:
    //  c2c3    s2s1c3 - c1s3     s2c1c3 + s1s3
    //  c2s3    s2s1s3 + c1c3     s2c1s3 - s1c3
    // -s2      c2s1              c2c1
 
    // Recover sin(res[0]) and cos(res[0]) from the atan2 arguments directly:
    //   res[0] = atan2(coeff(j,k), coeff(k,k))
    //   sin(res[0]) = coeff(j,k) / hypot(coeff(j,k), coeff(k,k))
    //   cos(res[0]) = coeff(k,k) / hypot(coeff(j,k), coeff(k,k))
    Scalar n1 = numext::hypot(coeff(j, k), coeff(k, k));
    res[0] = numext::atan2(coeff(j, k), coeff(k, k));
 
    Scalar c2 = numext::hypot(coeff(i, i), coeff(i, j));
    // c2 is always positive, so the following atan2 will always return a result in the correct canonical middle angle
    // range [-pi/2, pi/2]
    res[1] = numext::atan2(-coeff(i, k), c2);
 
    Scalar s1, c1;
    if (n1 > NumTraits<Scalar>::epsilon()) {
      Scalar inv_n1 = Scalar(1) / n1;
      s1 = coeff(j, k) * inv_n1;
      c1 = coeff(k, k) * inv_n1;
    } else {
      // Gimbal lock: coeff(j,k) and coeff(k,k) are both near zero.
      // Fall back to sin/cos of the computed angle.
      s1 = numext::sin(res[0]);
      c1 = numext::cos(res[0]);
    }
    res[2] = numext::atan2(s1 * coeff(k, i) - c1 * coeff(j, i), c1 * coeff(j, j) - s1 * coeff(k, j));
  }
  if (!odd) {
    res = -res;
  }
 
  return res;
}

template <typename Derived>
EIGEN_DEVICE_FUNC inline Matrix<typename MatrixBase<Derived>::Scalar, 3, 1> MatrixBase<Derived>::eulerAngles(
    Index a0, Index a1, Index a2) const {
  /* Implemented from Graphics Gems IV */
  EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(Derived, 3, 3)
 
  Matrix<Scalar, 3, 1> res;
 
  const Index odd = ((a0 + 1) % 3 == a1) ? 0 : 1;
  const Index i = a0;
  const Index j = (a0 + 1 + odd) % 3;
  const Index k = (a0 + 2 - odd) % 3;
 
  if (a0 == a2) {
    res[0] = numext::atan2(coeff(j, i), coeff(k, i));
    if ((odd && res[0] < Scalar(0)) || ((!odd) && res[0] > Scalar(0))) {
      if (res[0] > Scalar(0)) {
        res[0] -= Scalar(EIGEN_PI);
      } else {
        res[0] += Scalar(EIGEN_PI);
      }
 
      Scalar s2 = numext::hypot(coeff(j, i), coeff(k, i));
      res[1] = -numext::atan2(s2, coeff(i, i));
    } else {
      Scalar s2 = numext::hypot(coeff(j, i), coeff(k, i));
      res[1] = numext::atan2(s2, coeff(i, i));
    }
 
    // With a=(0,1,0), we have i=0; j=1; k=2, and after computing the first two angles,
    // we can compute their respective rotation, and apply its inverse to M. Since the result must
    // be a rotation around x, we have:
    //
    //  c2  s1.s2 c1.s2                   1  0   0
    //  0   c1    -s1       *    M    =   0  c3  s3
    //  -s2 s1.c2 c1.c2                   0 -s3  c3
    //
    //  Thus:  m11.c1 - m21.s1 = c3  &   m12.c1 - m22.s1 = s3
 
    Scalar s1 = numext::sin(res[0]);
    Scalar c1 = numext::cos(res[0]);
    res[2] = numext::atan2(c1 * coeff(j, k) - s1 * coeff(k, k), c1 * coeff(j, j) - s1 * coeff(k, j));
  } else {
    res[0] = numext::atan2(coeff(j, k), coeff(k, k));
    Scalar c2 = numext::hypot(coeff(i, i), coeff(i, j));
    if ((odd && res[0] < Scalar(0)) || ((!odd) && res[0] > Scalar(0))) {
      if (res[0] > Scalar(0)) {
        res[0] -= Scalar(EIGEN_PI);
      } else {
        res[0] += Scalar(EIGEN_PI);
      }
      res[1] = numext::atan2(-coeff(i, k), -c2);
    } else {
      res[1] = numext::atan2(-coeff(i, k), c2);
    }
    Scalar s1 = numext::sin(res[0]);
    Scalar c1 = numext::cos(res[0]);
    res[2] = numext::atan2(s1 * coeff(k, i) - c1 * coeff(j, i), c1 * coeff(j, j) - s1 * coeff(k, j));
  }
  if (!odd) {
    res = -res;
  }
 
  return res;
}
 
}  // end namespace Eigen
 
#endif  // EIGEN_EULERANGLES_H