Eigen::EulerAngles< _Scalar, _System > Class Template Reference

Detailed Description

template<typename _Scalar, class _System>
class Eigen::EulerAngles< _Scalar, _System >

Represents a rotation in a 3 dimensional space as three Euler 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
Note:
This class support only intrinsic Euler angles for simplicity, see EulerSystem how to easily overcome this 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.

#### Euler angles ranges in conversions ####

When converting some rotation to Euler angles, there are some ways you can guarantee the Euler angles ranges.

#### implicit ranges #### When using implicit ranges, all angles are guarantee to be in the range [-PI, +PI], unless you convert from some other Euler angles. In this case, the range is __undefined__ (might be even less than -PI or greater than +2*PI).

See also:
EulerAngles(const MatrixBase<Derived>&)
EulerAngles(const RotationBase<Derived, 3>&)

#### explicit ranges #### When using explicit ranges, all angles are guarantee to be in the range you choose. In the range Boolean parameter, you're been ask whether you prefer the positive range or not:

  • _true_ - force the range between [0, +2*PI]
  • _false_ - force the range between [-PI, +PI]

##### compile time ranges ##### This is when you have compile time ranges and you prefer to use template parameter. (e.g. for performance)

See also:
FromRotation()

##### run-time time ranges ##### Run-time ranges are also supported.

See also:
EulerAngles(const MatrixBase<Derived>&, bool, bool, bool)
EulerAngles(const RotationBase<Derived, 3>&, bool, bool, bool)

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

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.

### Example ###

#include <unsupported/Eigen/EulerAngles>
#include <iostream>

using namespace Eigen;

int main()
{
  // A common Euler system by many armies around the world,
  //  where the first one is the azimuth(the angle from the north -
  //   the same angle that is show in compass)
  //  and the second one is elevation(the angle from the horizon)
  //  and the third one is roll(the angle between the horizontal body
  //   direction and the plane ground surface)
  // Keep remembering we're using radian angles here!
  typedef EulerSystem<-EULER_Z, EULER_Y, EULER_X> MyArmySystem;
  typedef EulerAngles<double, MyArmySystem> MyArmyAngles;
  
  MyArmyAngles vehicleAngles(
    3.14/*PI*/ / 2, /* heading to east, notice that this angle is counter-clockwise */
    -0.3, /* going down from a mountain */
    0.1); /* slightly rolled to the right */
  
  // Some Euler angles representation that our plane use.
  EulerAnglesZYZd planeAngles(0.78474, 0.5271, -0.513794);
  
  MyArmyAngles planeAnglesInMyArmyAngles = MyArmyAngles::FromRotation<true, false, false>(planeAngles);
  
  std::cout << "vehicle angles(MyArmy):     " << vehicleAngles << std::endl;
  std::cout << "plane angles(ZYZ):        " << planeAngles << std::endl;
  std::cout << "plane angles(MyArmy):     " << planeAnglesInMyArmyAngles << std::endl;
  
  // Now lets rotate the plane a little bit
  std::cout << "==========================================================\n";
  std::cout << "rotating plane now!\n";
  std::cout << "==========================================================\n";
  
  Quaterniond planeRotated = AngleAxisd(-0.342, Vector3d::UnitY()) * planeAngles;
  
  planeAngles = planeRotated;
  planeAnglesInMyArmyAngles = MyArmyAngles::FromRotation<true, false, false>(planeRotated);
  
  std::cout << "new plane angles(ZYZ):     " << planeAngles << std::endl;
  std::cout << "new plane angles(MyArmy): " << planeAnglesInMyArmyAngles << std::endl;
  
  return 0;
}

Output:

vehicle angles(MyArmy):     1.57 -0.3  0.1
plane angles(ZYZ):          0.78474    0.5271 -0.513794
plane angles(MyArmy):       6.07691  0.453463 -0.278617
==========================================================
rotating plane now!
==========================================================
new plane angles(ZYZ):      1.44358 0.366507 -1.23637
new plane angles(MyArmy):   6.09671  0.117896 -0.347841

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

Template Parameters:
_Scalarthe scalar type, i.e., the type of the angles.
_Systemthe EulerSystem to use, which represents the axes of rotation.

Inherits RotationBase< EulerAngles< _Scalar, _System >, 3 >.

List of all members.

Public Types

typedef AngleAxis< ScalarAngleAxisType
typedef Matrix< Scalar, 3, 3 > Matrix3
typedef Quaternion< ScalarQuaternionType
typedef _Scalar Scalar
typedef _System System
typedef Matrix< Scalar, 3, 1 > Vector3

Public Member Functions

Scalar alpha () const
Scalaralpha ()
const Vector3angles () const
Vector3angles ()
Scalar beta () const
Scalarbeta ()
 EulerAngles ()
 EulerAngles (const Scalar &alpha, const Scalar &beta, const Scalar &gamma)
template<typename Derived >
 EulerAngles (const MatrixBase< Derived > &m)
template<typename Derived >
 EulerAngles (const MatrixBase< Derived > &m, bool positiveRangeAlpha, bool positiveRangeBeta, bool positiveRangeGamma)
template<typename Derived >
 EulerAngles (const RotationBase< Derived, 3 > &rot)
template<typename Derived >
 EulerAngles (const RotationBase< Derived, 3 > &rot, bool positiveRangeAlpha, bool positiveRangeBeta, bool positiveRangeGamma)
Scalar gamma () const
Scalargamma ()
EulerAngles inverse () const
 operator QuaternionType () const
EulerAngles operator- () const
template<typename Derived >
EulerAnglesoperator= (const MatrixBase< Derived > &m)
template<typename Derived >
EulerAnglesoperator= (const RotationBase< Derived, 3 > &rot)
Matrix3 toRotationMatrix () const

Static Public Member Functions

static Vector3 AlphaAxisVector ()
static Vector3 BetaAxisVector ()
template<bool PositiveRangeAlpha, bool PositiveRangeBeta, bool PositiveRangeGamma, typename Derived >
static EulerAngles FromRotation (const MatrixBase< Derived > &m)
template<bool PositiveRangeAlpha, bool PositiveRangeBeta, bool PositiveRangeGamma, typename Derived >
static EulerAngles FromRotation (const RotationBase< Derived, 3 > &rot)
static Vector3 GammaAxisVector ()

Member Typedef Documentation

template<typename _Scalar , class _System >
typedef AngleAxis<Scalar> Eigen::EulerAngles< _Scalar, _System >::AngleAxisType

the equivalent angle-axis type

template<typename _Scalar , class _System >
typedef Matrix<Scalar,3,3> Eigen::EulerAngles< _Scalar, _System >::Matrix3

the equivalent rotation matrix type

template<typename _Scalar , class _System >
typedef Quaternion<Scalar> Eigen::EulerAngles< _Scalar, _System >::QuaternionType

the equivalent quaternion type

template<typename _Scalar , class _System >
typedef _Scalar Eigen::EulerAngles< _Scalar, _System >::Scalar

the scalar type of the angles

template<typename _Scalar , class _System >
typedef _System Eigen::EulerAngles< _Scalar, _System >::System

the EulerSystem to use, which represents the axes of rotation.

template<typename _Scalar , class _System >
typedef Matrix<Scalar,3,1> Eigen::EulerAngles< _Scalar, _System >::Vector3

the equivalent 3 dimension vector type


Constructor & Destructor Documentation

template<typename _Scalar , class _System >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( ) [inline]

Default constructor without initialization.

template<typename _Scalar , class _System >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( const Scalar alpha,
const Scalar beta,
const Scalar gamma 
) [inline]

Constructs and initialize Euler angles(alpha, beta, gamma).

template<typename _Scalar , class _System >
template<typename Derived >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( const MatrixBase< Derived > &  m) [inline]

Constructs and initialize Euler angles from a 3x3 rotation matrix m.

Note:
All angles will be in the range [-PI, PI].
template<typename _Scalar , class _System >
template<typename Derived >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( const MatrixBase< Derived > &  m,
bool  positiveRangeAlpha,
bool  positiveRangeBeta,
bool  positiveRangeGamma 
) [inline]

Constructs and initialize Euler angles from a 3x3 rotation matrix m, with options to choose for each angle the requested range.

If positive range is true, then the specified angle will be in the range [0, +2*PI]. Otherwise, the specified angle will be in the range [-PI, +PI].

Parameters:
mThe 3x3 rotation matrix to convert
positiveRangeAlphaIf true, alpha will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeBetaIf true, beta will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeGammaIf true, gamma will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
template<typename _Scalar , class _System >
template<typename Derived >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( const RotationBase< Derived, 3 > &  rot) [inline]

Constructs and initialize Euler angles from a rotation rot.

Note:
All angles will be in the range [-PI, PI], unless 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 _Scalar , class _System >
template<typename Derived >
Eigen::EulerAngles< _Scalar, _System >::EulerAngles ( const RotationBase< Derived, 3 > &  rot,
bool  positiveRangeAlpha,
bool  positiveRangeBeta,
bool  positiveRangeGamma 
) [inline]

Constructs and initialize Euler angles from a rotation rot, with options to choose for each angle the requested range.

If positive range is true, then the specified angle will be in the range [0, +2*PI]. Otherwise, the specified angle will be in the range [-PI, +PI].

Parameters:
rotThe 3x3 rotation matrix to convert
positiveRangeAlphaIf true, alpha will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeBetaIf true, beta will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeGammaIf true, gamma will be in [0, 2*PI]. Otherwise, in [-PI, +PI].

Member Function Documentation

template<typename _Scalar , class _System >
Scalar Eigen::EulerAngles< _Scalar, _System >::alpha ( ) const [inline]
Returns:
The value of the first angle.
template<typename _Scalar , class _System >
Scalar& Eigen::EulerAngles< _Scalar, _System >::alpha ( ) [inline]
Returns:
A read-write reference to the angle of the first angle.
template<typename _Scalar , class _System >
static Vector3 Eigen::EulerAngles< _Scalar, _System >::AlphaAxisVector ( ) [inline, static]
Returns:
the axis vector of the first (alpha) rotation
template<typename _Scalar , class _System >
const Vector3& Eigen::EulerAngles< _Scalar, _System >::angles ( ) const [inline]
Returns:
The angle values stored in a vector (alpha, beta, gamma).
template<typename _Scalar , class _System >
Vector3& Eigen::EulerAngles< _Scalar, _System >::angles ( ) [inline]
Returns:
A read-write reference to the angle values stored in a vector (alpha, beta, gamma).
template<typename _Scalar , class _System >
Scalar Eigen::EulerAngles< _Scalar, _System >::beta ( ) const [inline]
Returns:
The value of the second angle.
template<typename _Scalar , class _System >
Scalar& Eigen::EulerAngles< _Scalar, _System >::beta ( ) [inline]
Returns:
A read-write reference to the angle of the second angle.
template<typename _Scalar , class _System >
static Vector3 Eigen::EulerAngles< _Scalar, _System >::BetaAxisVector ( ) [inline, static]
Returns:
the axis vector of the second (beta) rotation
template<typename _Scalar , class _System >
template<bool PositiveRangeAlpha, bool PositiveRangeBeta, bool PositiveRangeGamma, typename Derived >
static EulerAngles Eigen::EulerAngles< _Scalar, _System >::FromRotation ( const MatrixBase< Derived > &  m) [inline, static]

Constructs and initialize Euler angles from a 3x3 rotation matrix m, with options to choose for each angle the requested range (__only in compile time__).

If positive range is true, then the specified angle will be in the range [0, +2*PI]. Otherwise, the specified angle will be in the range [-PI, +PI].

Parameters:
mThe 3x3 rotation matrix to convert
Template Parameters:
positiveRangeAlphaIf true, alpha will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeBetaIf true, beta will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeGammaIf true, gamma will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
template<typename _Scalar , class _System >
template<bool PositiveRangeAlpha, bool PositiveRangeBeta, bool PositiveRangeGamma, typename Derived >
static EulerAngles Eigen::EulerAngles< _Scalar, _System >::FromRotation ( const RotationBase< Derived, 3 > &  rot) [inline, static]

Constructs and initialize Euler angles from a rotation rot, with options to choose for each angle the requested range (__only in compile time__).

If positive range is true, then the specified angle will be in the range [0, +2*PI]. Otherwise, the specified angle will be in the range [-PI, +PI].

Parameters:
rotThe 3x3 rotation matrix to convert
Template Parameters:
positiveRangeAlphaIf true, alpha will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeBetaIf true, beta will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
positiveRangeGammaIf true, gamma will be in [0, 2*PI]. Otherwise, in [-PI, +PI].
template<typename _Scalar , class _System >
Scalar Eigen::EulerAngles< _Scalar, _System >::gamma ( ) const [inline]
Returns:
The value of the third angle.
template<typename _Scalar , class _System >
Scalar& Eigen::EulerAngles< _Scalar, _System >::gamma ( ) [inline]
Returns:
A read-write reference to the angle of the third angle.
template<typename _Scalar , class _System >
static Vector3 Eigen::EulerAngles< _Scalar, _System >::GammaAxisVector ( ) [inline, static]
Returns:
the axis vector of the third (gamma) rotation
template<typename _Scalar , class _System >
EulerAngles Eigen::EulerAngles< _Scalar, _System >::inverse ( ) const [inline]
Returns:
The Euler angles rotation inverse (which is as same as the negative), (-alpha, -beta, -gamma).
template<typename _Scalar , class _System >
Eigen::EulerAngles< _Scalar, _System >::operator QuaternionType ( ) const [inline]

Convert the Euler angles to quaternion.

template<typename _Scalar , class _System >
EulerAngles Eigen::EulerAngles< _Scalar, _System >::operator- ( ) const [inline]
Returns:
The Euler angles rotation negative (which is as same as the inverse), (-alpha, -beta, -gamma).
template<typename _Scalar , class _System >
template<typename Derived >
EulerAngles& Eigen::EulerAngles< _Scalar, _System >::operator= ( const MatrixBase< Derived > &  m) [inline]

Set *this from a rotation matrix(i.e. pure orthogonal matrix with determinant of +1).

template<typename _Scalar , class _System >
template<typename Derived >
EulerAngles& Eigen::EulerAngles< _Scalar, _System >::operator= ( const RotationBase< Derived, 3 > &  rot) [inline]

Set *this from a rotation.

template<typename _Scalar , class _System >
Matrix3 Eigen::EulerAngles< _Scalar, _System >::toRotationMatrix ( ) const [inline]
Returns:
an equivalent 3x3 rotation matrix.

The documentation for this class was generated from the following file:
 All Classes Functions Variables Typedefs Enumerator