* remove debug code commited by mistake in Assign

* keep going on the doc: added a short geometry tutorial

CMakeLists.txt

@@ -5,7 +5,6 @@ CMAKE_MINIMUM_REQUIRED(VERSION 2.4)
 set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
 
 OPTION(BUILD_TESTS "Build tests" OFF)
-OPTION(BUILD_DOC "Build documentation and examples" OFF)
 OPTION(BUILD_DEMOS "Build demos" OFF)
 OPTION(BUILD_LIB "Build the binary shared library" OFF)
 OPTION(BUILD_BTL "Build benchmark suite" OFF)

Eigen/Core

@@ -9,8 +9,9 @@
 namespace Eigen {
 
 /** \defgroup Core_Module Core module
-  * This is the main module of Eigen providing dense matrix and vector support with
+  * This is the main module of Eigen providing dense matrix and vector support
-  * features equivalent to a BLAS library and much more...
+  * (both fixed and dynamic size) with all the features corresponding to a BLAS library
+  * and much more...
   *
   * \code
   * #include <Eigen/Core>

Eigen/Geometry

@@ -9,7 +9,7 @@
 
 namespace Eigen {
 
-/** \defgroup Geometry Geometry module
+/** \defgroup GeometryModule Geometry module
   * This module provides support for:
   *  - fixed-size homogeneous transformations
   *  - 2D and 3D rotations

Eigen/src/Core/Assign.h

@@ -299,58 +299,28 @@ struct ei_assign_impl<Derived1, Derived2, InnerVectorization, InnerUnrolling>
 *** Linear vectorization ***
 ***************************/
 
-// template<typename Derived1, typename Derived2>
-// struct ei_assign_impl<Derived1, Derived2, LinearVectorization, NoUnrolling>
-// {
-//   static void run(Derived1 &dst, const Derived2 &src)
-//   {
-//     const int size = dst.size();
-//     const int packetSize = ei_packet_traits<typename Derived1::Scalar>::size;
-//     const int alignedStart = ei_assign_traits<Derived1,Derived2>::DstIsAligned ? 0
-//                            : ei_alignmentOffset(&dst.coeffRef(0), size);
-//     const int alignedEnd = alignedStart + ((size-alignedStart)/packetSize)*packetSize;
-// 
-//     for(int index = 0; index < alignedStart; index++)
-//       dst.copyCoeff(index, src);
-// 
-//     for(int index = alignedStart; index < alignedEnd; index += packetSize)
-//     {
-//       dst.template copyPacket<Derived2, Aligned, ei_assign_traits<Derived1,Derived2>::SrcAlignment>(index, src);
-//     }
-// 
-//     for(int index = alignedEnd; index < size; index++)
-//       dst.copyCoeff(index, src);
-//   }
-// };
 template<typename Derived1, typename Derived2>
 struct ei_assign_impl<Derived1, Derived2, LinearVectorization, NoUnrolling>
 {
- static void run(Derived1 &dst, const Derived2 &src)
+  static void run(Derived1 &dst, const Derived2 &src)
- {
+  {
-   asm("#begin");
+    const int size = dst.size();
-   const int size = dst.size();
+    const int packetSize = ei_packet_traits<typename Derived1::Scalar>::size;
-   const int packetSize = ei_packet_traits<typename Derived1::Scalar>::size;
+    const int alignedStart = ei_assign_traits<Derived1,Derived2>::DstIsAligned ? 0
-   const int alignedStart = ei_assign_traits<Derived1,Derived2>::DstIsAligned ? 0
+                           : ei_alignmentOffset(&dst.coeffRef(0), size);
-                          : ei_alignmentOffset(&dst.coeffRef(0), size);
+    const int alignedEnd = alignedStart + ((size-alignedStart)/packetSize)*packetSize;
-   const int alignedEnd = alignedStart + ((size-alignedStart)/packetSize)*packetSize;
 
-   asm("#unaligned start");
+    for(int index = 0; index < alignedStart; index++)
+      dst.copyCoeff(index, src);
 
-   for(int index = 0; index < alignedStart; index++)
+    for(int index = alignedStart; index < alignedEnd; index += packetSize)
-     dst.copyCoeff(index, src);
+    {
-   asm("#aligned middle");
+      dst.template copyPacket<Derived2, Aligned, ei_assign_traits<Derived1,Derived2>::SrcAlignment>(index, src);
+    }
 
-   for(int index = alignedStart; index < alignedEnd; index += packetSize)
+    for(int index = alignedEnd; index < size; index++)
-   {
+      dst.copyCoeff(index, src);
-     dst.template copyPacket<Derived2, Aligned, ei_assign_traits<Derived1,Derived2>::SrcAlignment>(index, src);
+  }
-   }
-
-   asm("#unaligned end");
-
-   for(int index = alignedEnd; index < size; index++)
-     dst.copyCoeff(index, src);
-   asm("#end");
- }
 };
 
 template<typename Derived1, typename Derived2>

Eigen/src/Geometry/AngleAxis.h

@@ -25,7 +25,7 @@
 #ifndef EIGEN_ANGLEAXIS_H
 #define EIGEN_ANGLEAXIS_H
 
-/** \geometry_module \ingroup Geometry
+/** \geometry_module \ingroup GeometryModule
   *
   * \class AngleAxis
   *
@@ -122,10 +122,10 @@ public:
   Matrix3 toRotationMatrix(void) const;
 };
 
-/** \ingroup Geometry
+/** \ingroup GeometryModule
   * single precision angle-axis type */
 typedef AngleAxis<float> AngleAxisf;
-/** \ingroup Geometry
+/** \ingroup GeometryModule
   * double precision angle-axis type */
 typedef AngleAxis<double> AngleAxisd;
 

Eigen/src/Geometry/Quaternion.h

@@ -30,7 +30,7 @@ template<typename Other,
          int OtherCols=Other::ColsAtCompileTime>
 struct ei_quaternion_assign_impl;
 
-/** \geometry_module \ingroup Geometry
+/** \geometry_module \ingroup GeometryModule
   *
   * \class Quaternion
   *
@@ -169,10 +169,10 @@ public:
 
 };
 
-/** \ingroup Geometry
+/** \ingroup GeometryModule
   * single precision quaternion type */
 typedef Quaternion<float> Quaternionf;
-/** \ingroup Geometry
+/** \ingroup GeometryModule
   * double precision quaternion type */
 typedef Quaternion<double> Quaterniond;
 

Eigen/src/Geometry/Rotation.h

@@ -103,7 +103,7 @@ struct ToRotationMatrix<Scalar, Dim, MatrixBase<OtherDerived> >
   }
 };
 
-/** \geometry_module \ingroup Geometry
+/** \geometry_module \ingroup GeometryModule
   *
   * \class Rotation2D
   *
@@ -114,7 +114,7 @@ struct ToRotationMatrix<Scalar, Dim, MatrixBase<OtherDerived> >
   * This class is equivalent to a single scalar representing a counter clock wise rotation
   * as a single angle in radian. It provides some additional features such as the automatic
   * conversion from/to a 2x2 rotation matrix. Moreover this class aims to provide a similar
-  * interface to Quaternion in order to facilitate the writing of generic algorithm
+  * interface to Quaternion in order to facilitate the writing of generic algorithms
   * dealing with rotations.
   *
   * \sa class Quaternion, class Transform

Eigen/src/Geometry/Transform.h

@@ -35,7 +35,7 @@ template< typename Other,
           int OtherCols=Other::ColsAtCompileTime>
 struct ei_transform_product_impl;
 
-/** \geometry_module \ingroup Geometry
+/** \geometry_module \ingroup GeometryModule
   *
   * \class Transform
   *
@@ -202,13 +202,13 @@ protected:
 
 };
 
-/** \ingroup Geometry */
+/** \ingroup GeometryModule */
 typedef Transform<float,2> Transform2f;
-/** \ingroup Geometry */
+/** \ingroup GeometryModule */
 typedef Transform<float,3> Transform3f;
-/** \ingroup Geometry */
+/** \ingroup GeometryModule */
 typedef Transform<double,2> Transform2d;
-/** \ingroup Geometry */
+/** \ingroup GeometryModule */
 typedef Transform<double,3> Transform3d;
 
 #ifdef EIGEN_QT_SUPPORT

Mainpage.dox

@@ -7,8 +7,8 @@ In order to generate the documentation of Eigen, please follow these steps:
   <li>make sure you have the required software installed: cmake, doxygen, and a C++ compiler.
   <li>create a new directory, which we will call the "build directory", outside of the Eigen source directory.</li>
   <li>enter the build directory</li>
-  <li>configure the project: <pre>cmake -DBUILD_DOC=ON /path/to/source/directory</pre></li>
+  <li>configure the project: <pre>cmake /path/to/source/directory</pre></li>
-  <li>now generate the documentaion: <pre>make</pre> or, if you have two CPUs, <pre>make -j2</pre> Note that this will compile the examples, run them, and integrate their output into the documentation, which can take some time.</li>
+  <li>now generate the documentaion: <pre>make doc</pre> or, if you have two CPUs, <pre>make doc -j2</pre> Note that this will compile the examples, run them, and integrate their output into the documentation, which can take some time.</li>
 </ul>
 
 After doing that, you will find the HTML documentation in the doc/html/ subdirectory of the build directory.

doc/CMakeLists.txt

@@ -1,4 +1,5 @@
-IF(BUILD_DOC)
+
+SET_DIRECTORY_PROPERTIES(PROPERTIES EXCLUDE_FROM_ALL TRUE)
 
 IF(CMAKE_COMPILER_IS_GNUCXX)
   IF(CMAKE_SYSTEM_NAME MATCHES Linux)
@@ -28,7 +29,7 @@ ADD_SUBDIRECTORY(examples)
 ADD_SUBDIRECTORY(snippets)
 
 ADD_CUSTOM_TARGET(
-  run_doxygen
+  doc
   ALL
   COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/eigendoxy_tabs.css
                                    ${CMAKE_CURRENT_BINARY_DIR}/html/
@@ -39,6 +40,4 @@ ADD_CUSTOM_TARGET(
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 )
 
-ADD_DEPENDENCIES(run_doxygen all_snippets all_examples)
+ADD_DEPENDENCIES(doc all_snippets all_examples)
-
-ENDIF(BUILD_DOC)

doc/QuickStartGuide.dox

@@ -492,17 +492,88 @@ forces immediate evaluation of the transpose</td></tr>
   | \ref TutorialAdvancedLinearAlgebra "Advanced linear algebra"
 </div>
 
+In this tutorial chapter we will shortly introduce the many possibilities offered by the \ref GeometryModule "geometry module",
+namely 2D and 3D rotations and affine transformations.
+
 \b Table \b of \b contents
   - \ref TutorialGeoRotations
   - \ref TutorialGeoTransformation
 
 <a href="#" class="top">top</a>\section TutorialGeoRotations 2D and 3D Rotations
 
-todo
+\subsection TutorialGeoRotationTypes Rotation types
 
-<a href="#" class="top">top</a>\section TutorialGeoTransformation 2D and 3D Transformations
 
-todo
+<table class="tutorial_code">
+<tr><td>Rotation type</td><td>Typical initialization code</td><td>Recommended usage</td></tr>
+<tr><td>2D rotation from an angle</td><td>\code
+Rotation2D<float> rot2(angle_in_radian);\endcode</td><td></td></tr>
+<tr><td>2D rotation matrix</td><td>\code
+Matrix2f rotmat2 = Rotation2Df(angle_in_radian);\endcode</td><td></td></tr>
+<tr><td>3D rotation as an angle + axis</td><td>\code
+AngleAxis<float> aa(angle_in_radian, Vector3f(ax,ay,az));\endcode</td><td></td></tr>
+<tr><td>3D rotation as a quaternion</td><td>\code
+Quaternion<float> q = AngleAxis<float>(angle_in_radian, axis);\endcode</td><td></td></tr>
+<tr><td>3D rotation matrix</td><td>\code
+Matrix3f rotmat3 = AngleAxis<float>(angle_in_radian, axis);\endcode</td><td></td></tr>
+</table>
+
+To transform more than a single vector the prefered representations are rotation matrices,
+for other usage Rotation2D and Quaternion are the representations of choice as they are
+more compact, fast and stable. AngleAxis are only useful to create other rotation objects.
+
+\subsection TutorialGeoCommonRotationAPI Common API of rotation types
+
+To some extent, Eigen's \ref Geometry_Module "geometry module" allows you to write
+generic algorithms working on both 2D and 3D rotations of any of the five above types.
+The following operation are supported:
+<table class="tutorial_code">
+<tr><td>Convertion from and to any types (of same space dimension)</td><td>\code
+RotType2 a = RotType1();\endcode</td></tr>
+<tr><td>Concatenation of two rotations</td><td>\code
+rot3 = rot1 * rot2;\endcode</td></tr>
+<tr><td>Apply the rotation to a vector</td><td>\code
+vec2 = rot1 * vec1;\endcode</td></tr>
+<tr><td>Get the inverse rotation \n (not always the most effient choice)</td><td>\code
+rot2 = rot1.inverse();\endcode</td></tr>
+<tr><td>Spherical interpolation \n (Rotation2D and Quaternion only)</td><td>\code
+rot3 = rot1.slerp(alpha,rot2);\endcode</td></tr>
+</table>
+
+\subsection TutorialGeoEulerAngles Euler angles
+<table class="tutorial_code">
+<tr><td style="max-width:30em;">
+Euler angles might be convenient to create rotation object.
+Since there exist 24 differents convensions, they are one
+the ahand pretty confusing to use. This example shows how
+to create a rotation matrix according to the 2-1-2 convention.</td><td>\code
+Matrix3f m;
+m = AngleAxisf(angle1, Vector3f::UnitZ())
+  * AngleAxisf(angle2, Vector3f::UnitY())
+  * AngleAxisf(angle3, Vector3f::UnitZ());
+\endcode</td></tr>
+</table>
+
+<a href="#" class="top">top</a>\section TutorialGeoTransformation Affine transformations
+In Eigen we have chosen to not distinghish between points and vectors such that all points are
+actually represented by displacement vector from the origine (pt \~ pt-0). With that in mind,
+real points and vector distinguish when the rotation is applied.
+<table class="tutorial_code">
+<tr><td>Creation</td><td>\code
+Transform3f t;
+t.setFrom \endcode</td></tr>
+<tr><td>Apply the transformation to a \b point </td><td>\code
+Vector3f p1, p2;
+p2 = t * p1;\endcode</td></tr>
+<tr><td>Apply the transformation to a \b vector </td><td>\code
+Vector3f v1, v2;
+v2 = t.linear() * v1;\endcode</td></tr>
+<tr><td>Concatenate two transformations</td><td>\code
+t3 = t1 * t2;\endcode</td></tr>
+<tr><td>OpenGL compatibility</td><td>\code
+glLoadMatrixf(t.data());\endcode</td></tr>
+</table>
+
 
 */
 
@@ -519,6 +590,8 @@ todo
   | \b Advanced \b linear \b algebra
 </div>
 
+
+
 \b Table \b of \b contents
   - \ref TutorialAdvLinearSolvers
   - \ref TutorialAdvLU