GitHub-Proxy/eigen
1
0
Fork 0
mirror of https://gitlab.com/libeigen/eigen.git synced 2025-04-29 07:14:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

More docs, and minor code fixes

Browse Source
This commit is contained in:
Tal Hadad 2016-06-12 23:40:17 +03:00
parent e30133e439
commit 06206482d9
5 changed files with 180 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
unsupported/Eigen/CMakeLists.txt
View File

@ -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)
add_subdirectory(CXX11)

4
unsupported/Eigen/EulerAngles
View File

@ -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

6
unsupported/Eigen/src/EulerAngles/CMakeLists.txt
View File

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

120
unsupported/Eigen/src/EulerAngles/EulerAngles.h
View File

@ -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 <typename _Scalar, class _System>
class EulerAngles : public RotationBase<EulerAngles<_Scalar, _System>, 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<typename Derived>
EulerAngles(const MatrixBase<Derived>& 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<typename Derived>
EulerAngles(const RotationBase<Derived, 3>& 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<QuaternionType>(*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<SCALAR_TYPE, SYSTEM> SYSTEM##SCALAR_POSTFIX;
#define EIGEN_EULER_ANGLES_SINGLE_TYPEDEF(AXES, SCALAR_TYPE, SCALAR_POSTFIX) \
typedef EulerAngles<SCALAR_TYPE, EulerSystem##AXES> 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)

95
unsupported/Eigen/src/EulerAngles/EulerSystem.h
View File

@ -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 <int _AlphaAxis, int _BetaAxis, int _GammaAxis>
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<AlphaAxis>::value,
/** The second rotation axis unsigned */
BetaAxisAbs = internal::Abs<BetaAxis>::value,
/** The third rotation axis unsigned */
GammaAxisAbs = internal::Abs<GammaAxis>::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<typename Scalar>
static void CalcEulerAngles(
@ -204,6 +282,9 @@ namespace Eigen
if (PositiveRangeGamma && (res.gamma() < 0))
res.gamma() += Scalar(2 * EIGEN_PI);
}
template <typename _Scalar, class _System>
friend class Eigen::EulerAngles;
};
#define EIGEN_EULER_SYSTEM_TYPEDEF(A, B, C) \