From 5e0a178df2b70829e990e84602fd70f92131484f Mon Sep 17 00:00:00 2001 From: Tal Hadad Date: Sun, 27 Sep 2015 16:51:24 +0300 Subject: Initial fork of unsupported module EulerAngles. --- unsupported/Eigen/src/EulerAngles/CMakeLists.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 unsupported/Eigen/src/EulerAngles/CMakeLists.txt (limited to 'unsupported/Eigen/src/EulerAngles/CMakeLists.txt') diff --git a/unsupported/Eigen/src/EulerAngles/CMakeLists.txt b/unsupported/Eigen/src/EulerAngles/CMakeLists.txt new file mode 100644 index 000000000..7986afc5e --- /dev/null +++ b/unsupported/Eigen/src/EulerAngles/CMakeLists.txt @@ -0,0 +1,6 @@ +FILE(GLOB Eigen_IterativeSolvers_SRCS "*.h") + +INSTALL(FILES + ${Eigen_IterativeSolvers_SRCS} + DESTINATION ${INCLUDE_INSTALL_DIR}/unsupported/Eigen/src/IterativeSolvers COMPONENT Devel + ) -- cgit v1.2.3 From 06206482d9964835b201c682884360dd0d1e73a5 Mon Sep 17 00:00:00 2001 From: Tal Hadad Date: Sun, 12 Jun 2016 23:40:17 +0300 Subject: More docs, and minor code fixes --- unsupported/Eigen/CMakeLists.txt | 3 +- unsupported/Eigen/EulerAngles | 4 + unsupported/Eigen/src/EulerAngles/CMakeLists.txt | 6 +- unsupported/Eigen/src/EulerAngles/EulerAngles.h | 120 ++++++++++++++++------- unsupported/Eigen/src/EulerAngles/EulerSystem.h | 95 ++++++++++++++++-- 5 files changed, 180 insertions(+), 48 deletions(-) (limited to 'unsupported/Eigen/src/EulerAngles/CMakeLists.txt') diff --git a/unsupported/Eigen/CMakeLists.txt b/unsupported/Eigen/CMakeLists.txt index 6d0cf4f9d..2fc8db412 100644 --- a/unsupported/Eigen/CMakeLists.txt +++ b/unsupported/Eigen/CMakeLists.txt @@ -4,6 +4,7 @@ set(Eigen_HEADERS ArpackSupport AutoDiff BVH + EulerAngles FFT IterativeSolvers KroneckerProduct @@ -26,4 +27,4 @@ install(FILES ) add_subdirectory(src) -add_subdirectory(CXX11) \ No newline at end of file +add_subdirectory(CXX11) diff --git a/unsupported/Eigen/EulerAngles b/unsupported/Eigen/EulerAngles index 5e1d2ccba..a595b5f2c 100644 --- a/unsupported/Eigen/EulerAngles +++ b/unsupported/Eigen/EulerAngles @@ -22,6 +22,10 @@ namespace Eigen { * \defgroup EulerAngles_Module EulerAngles module * \brief This module provides generic euler angles rotation. * + * Euler angles are a way to represent 3D rotation. + * + * !TODO! More about the purpose of this module and examples. + * * See EulerAngles for more information. * * \code diff --git a/unsupported/Eigen/src/EulerAngles/CMakeLists.txt b/unsupported/Eigen/src/EulerAngles/CMakeLists.txt index 7986afc5e..40af550e8 100644 --- a/unsupported/Eigen/src/EulerAngles/CMakeLists.txt +++ b/unsupported/Eigen/src/EulerAngles/CMakeLists.txt @@ -1,6 +1,6 @@ -FILE(GLOB Eigen_IterativeSolvers_SRCS "*.h") +FILE(GLOB Eigen_EulerAngles_SRCS "*.h") INSTALL(FILES - ${Eigen_IterativeSolvers_SRCS} - DESTINATION ${INCLUDE_INSTALL_DIR}/unsupported/Eigen/src/IterativeSolvers COMPONENT Devel + ${Eigen_EulerAngles_SRCS} + DESTINATION ${INCLUDE_INSTALL_DIR}/unsupported/Eigen/src/EulerAngles COMPONENT Devel ) diff --git a/unsupported/Eigen/src/EulerAngles/EulerAngles.h b/unsupported/Eigen/src/EulerAngles/EulerAngles.h index 4082eb6c4..9d1762ace 100644 --- a/unsupported/Eigen/src/EulerAngles/EulerAngles.h +++ b/unsupported/Eigen/src/EulerAngles/EulerAngles.h @@ -19,11 +19,60 @@ namespace Eigen /** \class EulerAngles * - * \brief Represents a rotation in a 3 dimensional space as three Euler angles + * \brief Represents a rotation in a 3 dimensional space as three Euler angles. * - * \sa _Scalar the scalar type, i.e., the type of the angles. + * Euler rotation is a set of three rotation of three angles over three fixed axes, defined by the EulerSystem given as a template parameter. + * + * Here is how intrinsic Euler angles works: + * - first, rotate the axes system over the alpha axis in angle alpha + * - then, rotate the axes system over the beta axis(which was rotated in the first stage) in angle beta + * - then, rotate the axes system over the gamma axis(which was rotated in the two stages above) in angle gamma * - * \sa _System the EulerSystem to use, which represents the axes of rotation. + * \note This class support only intrinsic Euler angles for simplicity, + * see EulerSystem how to easily overcome it for extrinsic systems. + * + * ### Rotation representation and conversions ### + * + * It has been proved(see Wikipedia link below) that every rotation can be represented + * by Euler angles, but there is no singular representation (e.g. unlike rotation matrices). + * Therefore, you can convert from Eigen rotation and to them + * (including rotation matrices, which is not called "rotations" by Eigen design). + * + * Euler angles usually used for: + * - convenient human representation of rotation, especially in interactive GUI. + * - gimbal systems and robotics + * - efficient encoding(i.e. 3 floats only) of rotation for network protocols. + * + * However, Euler angles are slow comparing to quaternion or matrices, + * because their unnatural math definition, although it's simple for human. + * To overcome this, this class provide easy movement from the math friendly representation + * to the human friendly representation, and vise-versa. + * + * All the user need to do is a safe simple C++ type conversion, + * and this class take care for the math. + * Additionally, some axes related computation is done in compile time. + * + * ### Convenient user typedefs ### + * + * Convenient typedefs for EulerAngles exist for float and double scalar, + * in a form of EulerAngles{A}{B}{C}{scalar}, + * e.g. EulerAnglesXYZd, EulerAnglesZYZf. + * + * !TODO! Add examples + * + * Only for positive axes{+x,+y,+z} euler systems are have convenient typedef. + * If you need negative axes{-x,-y,-z}, it is recommended to create you own typedef with + * a word that represent what you need, e.g. EulerAnglesUTM (!TODO! make it more clear with example code). + * + * ### Additional reading ### + * + * If you're want to get more idea about how Euler system work in Eigen see EulerSystem. + * + * More information about Euler angles: https://en.wikipedia.org/wiki/Euler_angles + * + * \tparam _Scalar the scalar type, i.e., the type of the angles. + * + * \tparam _System the EulerSystem to use, which represents the axes of rotation. */ template class EulerAngles : public RotationBase, 3> @@ -62,17 +111,18 @@ namespace Eigen public: /** Default constructor without initialization. */ EulerAngles() {} - /** Constructs and initialize euler angles(\p alpha, \p beta, \p gamma). */ - EulerAngles(Scalar alpha, Scalar beta, Scalar gamma) : m_angles(alpha, beta, gamma) {} + /** Constructs and initialize Euler angles(\p alpha, \p beta, \p gamma). */ + EulerAngles(const Scalar& alpha, const Scalar& beta, const Scalar& gamma) : + m_angles(alpha, beta, gamma) {} - /** Constructs and initialize euler angles from a 3x3 rotation matrix \p m. + /** Constructs and initialize Euler angles from a 3x3 rotation matrix \p m. * * \note All angles will be in the range [-PI, PI]. */ template EulerAngles(const MatrixBase& m) { *this = m; } - /** Constructs and initialize euler angles from a 3x3 rotation matrix \p m, + /** Constructs and initialize Euler angles from a 3x3 rotation matrix \p m, * with options to choose for each angle the requested range. * * If possitive range is true, then the specified angle will be in the range [0, +2*PI]. @@ -93,14 +143,16 @@ namespace Eigen System::CalcEulerAngles(*this, m, positiveRangeAlpha, positiveRangeBeta, positiveRangeGamma); } - /** Constructs and initialize euler angles from a rotation \p rot. + /** Constructs and initialize Euler angles from a rotation \p rot. * - * \note All angles will be in the range [-PI, PI]. + * \note All angles will be in the range [-PI, PI], unless \p rot is an EulerAngles. + * If rot is an EulerAngles, expected EulerAngles range is undefined. + * (Use other functions here for enforcing range if this effect is desired) */ template EulerAngles(const RotationBase& rot) { *this = rot; } - /** Constructs and initialize euler angles from a rotation \p rot, + /** Constructs and initialize Euler angles from a rotation \p rot, * with options to choose for each angle the requested range. * * If possitive range is true, then the specified angle will be in the range [0, +2*PI]. @@ -141,7 +193,7 @@ namespace Eigen /** \returns A read-write reference to the angle of the third angle. */ Scalar& gamma() { return m_angles[2]; } - /** \returns The euler angles rotation inverse (which is as same as the negative), + /** \returns The Euler angles rotation inverse (which is as same as the negative), * (-alpha, -beta, -gamma). */ EulerAngles inverse() const @@ -151,7 +203,7 @@ namespace Eigen return res; } - /** \returns The euler angles rotation negative (which is as same as the inverse), + /** \returns The Euler angles rotation negative (which is as same as the inverse), * (-alpha, -beta, -gamma). */ EulerAngles operator -() const @@ -159,7 +211,7 @@ namespace Eigen return inverse(); } - /** Constructs and initialize euler angles from a 3x3 rotation matrix \p m, + /** Constructs and initialize Euler angles from a 3x3 rotation matrix \p m, * with options to choose for each angle the requested range (__only in compile time__). * * If possitive range is true, then the specified angle will be in the range [0, +2*PI]. @@ -182,7 +234,7 @@ namespace Eigen return e; } - /** Constructs and initialize euler angles from a rotation \p rot, + /** Constructs and initialize Euler angles from a rotation \p rot, * with options to choose for each angle the requested range (__only in compile time__). * * If possitive range is true, then the specified angle will be in the range [0, +2*PI]. @@ -241,40 +293,34 @@ namespace Eigen return static_cast(*this).toRotationMatrix(); } - /** \returns an equivalent quaternion */ - QuaternionType toQuaternion() const + /** Convert the Euler angles to quaternion. */ + operator QuaternionType() const { return AngleAxisType(alpha(), AlphaAxisVector()) * - AngleAxisType(beta(), BetaAxisVector()) * + AngleAxisType(beta(), BetaAxisVector()) * AngleAxisType(gamma(), GammaAxisVector()); } - - /** Convert the euler angles to quaternion. */ - operator QuaternionType() const - { - return toQuaternion(); - } }; -#define EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(SYSTEM, SCALAR_TYPE, SCALAR_POSTFIX) \ - typedef EulerAngles SYSTEM##SCALAR_POSTFIX; +#define EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(AXES, SCALAR_TYPE, SCALAR_POSTFIX) \ + typedef EulerAngles EulerSystem##AXES##SCALAR_POSTFIX; #define EIGEN_EULER_ANGLES_TYPEDEFS(SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemXYZ, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemXYX, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemXZY, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemXZX, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(XYZ, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(XYX, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(XZY, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(XZX, SCALAR_TYPE, SCALAR_POSTFIX) \ \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemYZX, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemYZY, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemYXZ, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemYXY, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(YZX, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(YZY, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(YXZ, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(YXY, SCALAR_TYPE, SCALAR_POSTFIX) \ \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemZXY, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemZXZ, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemZYX, SCALAR_TYPE, SCALAR_POSTFIX) \ - EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(EulerSystemZYZ, SCALAR_TYPE, SCALAR_POSTFIX) + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(ZXY, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(ZXZ, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(ZYX, SCALAR_TYPE, SCALAR_POSTFIX) \ + EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(ZYZ, SCALAR_TYPE, SCALAR_POSTFIX) EIGEN_EULER_ANGLES_TYPEDEFS(float, f) EIGEN_EULER_ANGLES_TYPEDEFS(double, d) diff --git a/unsupported/Eigen/src/EulerAngles/EulerSystem.h b/unsupported/Eigen/src/EulerAngles/EulerSystem.h index a5ef56a5e..ac73b48a0 100644 --- a/unsupported/Eigen/src/EulerAngles/EulerSystem.h +++ b/unsupported/Eigen/src/EulerAngles/EulerSystem.h @@ -38,27 +38,107 @@ namespace Eigen }; } + /** \brief Representation of a fixed signed rotation axis for EulerAngles. + * + * Values here represent: + * - The axis of the rotation: X, Y or Z. + * - The sign (i.e. direction of the rotation along the axis): possitive(+) or negative(-) + * + * Therefore, this could express all the axes {+X,+Y,+Z,-X,-Y,-Z} + * + * For positive axis, use +EULER_{axis}, and for negative axis use -EULER_{axis}. + * + * !TODO! Add examples + */ enum EulerAxis { - EULER_X = 1, - EULER_Y = 2, - EULER_Z = 3 + EULER_X = 1, /*!< the X axis */ + EULER_Y = 2, /*!< the Y axis */ + EULER_Z = 3 /*!< the Z axis */ }; - + + /** \class EulerSystem + * + * \brief Represents a fixed Euler rotation system. + * + * This meta-class goal is to represent the Euler system in compilation time, for EulerAngles. + * + * You can use this class to get two things: + * - Build an Euler system, and then pass it as a template parameter to EulerAngles. + * - Query some compile time data about an Euler system. (e.g. Whether it's tait bryan) + * + * Euler rotation is a set of three rotation on fixed axes. (see EulerAngles) + * This meta-class store constantly those signed axes. (see EulerAxis) + * + * ### Types of Euler systems ### + * + * All and only valid 3 dimension Euler rotation over standard + * signed axes{+X,+Y,+Z,-X,-Y,-Z} are supported: + * - all axes X, Y, Z in each valid order (see below what order is valid) + * - rotation over the axis is supported both over the positive and negative directions. + * - both tait bryan and classic Euler angles (i.e. the opposite). + * + * Since EulerSystem support both positive and negative directions, + * you may call this rotation distinction in other names: + * - right handed or left handed + * - counterclockwise or clockwise + * + * Notice all axed combination are valid, and would trigger an assertion !TODO!. + * Same unsigned axes can't be neighbors, e.g. {X,X,Y} is invalid. + * This yield two and only two classes: + * - tait bryan - all unsigned axes are distinct, e.g. {X,Y,Z} + * - proper/classic Euler angles - The first and the third unsigned axes is equal, + * and the second is different, e.g. {X,Y,X} + * + * !TODO! Add some example code. + * + * ### Intrinsic vs extrinsic Euler systems ### + * + * Only intrinsic Euler systems are supported for simplicity. + * If you want to use extrinsic Euler systems, + * just use the equal intrinsic opposite order for axes and angles. + * I.E axes (A,B,C) becomes (C,B,A), and angles (a,b,c) becomes (c,b,a). + * !TODO! Make it more clear and add some example code. + * + * ### Convenient user typedefs ### + * + * Convenient typedefs for EulerSystem exist (only for positive axes Euler systems), + * in a form of EulerSystem{A}{B}{C}, e.g. EulerSystemXYZd. + * !TODO! Make it more clear + * + * ### Additional reading ### + * + * More information about Euler angles: https://en.wikipedia.org/wiki/Euler_angles + * + * \tparam _AlphaAxis the first fixed EulerAxis + * + * \tparam _AlphaAxis the second fixed EulerAxis + * + * \tparam _AlphaAxis the third fixed EulerAxis + */ template class EulerSystem { public: // It's defined this way and not as enum, because I think // that enum is not guerantee to support negative numbers + + /** The first rotation axis */ static const int AlphaAxis = _AlphaAxis; + + /** The second rotation axis */ static const int BetaAxis = _BetaAxis; + + /** The third rotation axis */ static const int GammaAxis = _GammaAxis; enum { + /** The first rotation axis unsigned */ AlphaAxisAbs = internal::Abs::value, + /** The second rotation axis unsigned */ BetaAxisAbs = internal::Abs::value, + /** The third rotation axis unsigned */ GammaAxisAbs = internal::Abs::value, IsAlphaOpposite = (AlphaAxis < 0) ? 1 : 0, @@ -81,7 +161,7 @@ namespace Eigen enum { - // I, J, K are the pivot indexes permutation for the rotation matrix, that match this euler system. + // I, J, K are the pivot indexes permutation for the rotation matrix, that match this Euler system. // They are used in this class converters. // They are always different from each other, and their possible values are: 0, 1, or 2. I = AlphaAxisAbs - 1, @@ -150,8 +230,6 @@ namespace Eigen Scalar c1 = cos(res[0]); res[2] = atan2(c1*mat(J,K)-s1*mat(K,K), c1*mat(J,J) - s1 * mat(K,J)); } - - public: template static void CalcEulerAngles( @@ -204,6 +282,9 @@ namespace Eigen if (PositiveRangeGamma && (res.gamma() < 0)) res.gamma() += Scalar(2 * EIGEN_PI); } + + template + friend class Eigen::EulerAngles; }; #define EIGEN_EULER_SYSTEM_TYPEDEF(A, B, C) \ -- cgit v1.2.3