More docs, and minor code fixes

5 files changed, 180 insertions, 48 deletions

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