Update documentation of FeaturePose + fix doxygen warnings.

doc/Doxyfile.extra.in

@@ -4,8 +4,6 @@ IMAGE_PATH             = @CMAKE_SOURCE_DIR@/doc/pictures
 
 FILE_PATTERNS          = *.cc *.cpp *.h *.hh *.hxx
 
-TAGFILES               = \
-"@JRL_MAL_DOXYGENDOCDIR@/jrl-mal.doxytag = @JRL_MAL_DOXYGENDOCDIR@" \
-"@DYNAMIC_GRAPH_DOXYGENDOCDIR@/dynamic-graph.doxytag = @DYNAMIC_GRAPH_DOXYGENDOCDIR@"
-
 COLLABORATION_GRAPH    = NO
+
+CITE_BIB_FILES         = @CMAKE_SOURCE_DIR@/doc/references.bib

doc/additionalDoc/a-features.h

 /**
-   \defgroup Filters
+   \defgroup Filters Filters
  */

doc/additionalDoc/codeorg.h

@@ -16,7 +16,7 @@ See \ref sot_core_base for a list of what's in this code base.
 
 This library implements
 \li A solver for the control law using tasks and features: the stack of tasks
-\li The framework of Tasks and Features, as defined in \ref Mansard2007, that
+\li The framework of Tasks and Features, as defined in \cite Mansard2007, that
 \li Base classes for working with tasks and features, such as special matrices
 (rotation, twist) and vectors (quaternions, etc.)
 \li A basic C++ "machinery", the \ref factory, that "makes things work"

doc/additionalDoc/e-operators.h

@@ -7,14 +7,14 @@
 
 This entity output a vector remapping an input vector 
 \f${\bf v}_{in}=[v_0,v_1,\cdots,v_n]\f$.
-It is realized by specifying bounds such as \f(${[i,j],[k,l]}f$),
+It is realized by specifying bounds such as \f$({[i,j],[k,l]})\f$,
 then the output vector will be the contanetion of the
 intervals extracted from the input vector:
 \f${\bf v}_{out}=[v_i,v_{i+1},\cdots,v_{j-1},v_{j},v_{k},
 v_{k+1},\cdots,v_{l-1},v_l]\f$
 For instance if we have an input vector
 such that: 
-\code[bash]
+\code
 1
 2
 3
@@ -27,7 +27,7 @@ such that:
 \endcode
 then specifying the bounds \f$(3,5)\f$ and \f$( 7,10\f$) will gives
 the following output vector
-\code[bash]
+\code
 3
 4
 7

doc/additionalDoc/package.h

@@ -2,7 +2,7 @@
 \section sec_intro Introduction
 
 This library implements a modular architecture to test and experiment
-controllers in the Stack of Tasks Framework as defined in \ref Mansard2007.
+controllers in the Stack of Tasks Framework as defined in \cite Mansard2007.
 It is specifically targeted to retain real-time performance while
 having high level software capabilities, like plugins and python scripting.
 
@@ -21,8 +21,6 @@ either with the hardware or with a simulator </li>
 
 \subpage page_featuredoc 
 
-\subpage page_references
-    
 \subpage page_sot
 
 \subsection tasks Tasks
@@ -33,7 +31,7 @@ and so on ... a task is mainly defined by the feature it is
 handling and its gain.
 
 After being defined, tasks are pushed in the Stack of Tasks which then
-calculates a control law as explained in \ref Mansard2007.
+calculates a control law as explained in \cite Mansard2007.
 
 See documentation of class dynamicgraph::sot::TaskAbstract for more information.
 
@@ -51,7 +49,7 @@ library, the following classes are present:
 
 \subsection subsec_sot Stack of Task solvers
 A hierarchical inequality solver, sot::SolverHierarchicalInequalities, is
-present. For the maths, see \ref Mansard2007.
+present. For the maths, see \cite Mansard2007.
 
 \subsection subsec_exceptions Exceptions
 The library defines the following classes of exceptions that derive from std::exception:

doc/additionalDoc/references-doc.h

-/** \page page_references References
-
-\anchor Mansard2007
-<b>"Task sequencing for sensor-based control"</b>,
-<em>N. Mansard, F. Chaumette,</em>
-IEEE Trans. on Robotics, 23(1):60-72, February 2007
-
-*/

doc/additionalDoc/sot-doc.h

@@ -34,7 +34,7 @@
 
     where:
     \li \f$\frac{\partial{\bf e}}{\partial{\bf q}}^{\dagger}\f$ is the
-        pseudo-inverse of \frac{\partial{\bf e}}{\partial{\bf q}},
+        pseudo-inverse of \f$\frac{\partial{\bf e}}{\partial{\bf q}}\f$,
     \li \f$\dot{\bf q} \in \mathbb{R}^n\f$,
     \li \f$K \in \mathcal{M}_{n,m}(\mathbb{R})\f$ is a base of the kernel of
         \f$\frac{\partial{\bf e}}{\partial{\bf q}}\f$, of dimension \f$m\f$,

doc/references.bib

+@ARTICLE { Mansard2007,
+    AUTHOR = { Mansard, N. and Chaumette, F. },
+    TITLE = { Task sequencing for sensor-based control },
+    JOURNAL = { IEEE Transaction on Robotics },
+    VOLUME = { 23 },
+    NUMBER = { 1 },
+    PAGES = { 60 - 72 },
+    MONTH = { February },
+    YEAR = { 2007 },
+    PDF = { 2007-mansard-itro.pdf },
+}

include/sot/core/feature-abstract.hh

@@ -40,7 +40,7 @@ namespace dynamicgraph {
       \ingroup features
       \brief This class gives the abstract definition of a feature.
 
-      \paragraph par_features_definition Definition
+      \par par_features_definition Definition
       In short, a feature is a data evolving according to time.  It is defined
       by a vector \f${\bf s}({\bf q}) \in \mathbb{R}^n \f$ where \f$ {\bf q} \f$ is a robot
       configuration, which depends on the time \f$ t \f$.

include/sot/core/feature-pose.hh

@@ -25,6 +25,7 @@
 namespace dynamicgraph { namespace sot {
 namespace dg = dynamicgraph;
 
+/// Enum used to specify what difference operation is used in FeaturePose.
 enum Representation_t {
   SE3Representation,
   R3xSO3Representation
@@ -34,18 +35,31 @@ enum Representation_t {
   \brief Feature that controls the relative (or absolute) pose between
   two frames A (or world) and B.
 
+  @tparam representation specify the difference operation to use. This changes
+          - the descent direction,
+          - the meaning of the mask.
+          With R3xSO3Representation, the mask is relative to <em>Frame A</em>.
+          If this feature is alone in a SOT, the relative motion of <em>Frame B</em>
+          wrt <em>Frame A</em> will be a line.
+          This is what most people want.
+
   Notations:
-  \li The frames are refered to with \c fa and \c fb.
-  \li Each frame is attached to a joint, which are refered to with \c ja and \c jb.
-  \li the difference operator is defined as \f[
-  \begin{array}{ccccc}
-  \ominus & : & SE(3)^2 & \to & \mathfrak{se}(3) \\
-          &   & a, b    & \mapsto & b \ominus a = \log(a^{-1} b) \\
-   \end{array}
-  \f]
-  \todo express error in R3xS03 so that the mask isn't surprising for user.
+  - The frames are refered to with \c fa and \c fb.
+  - Each frame is attached to a joint, which are refered to with \c ja and \c jb.
+  - the difference operator is defined differently depending on the representation:
+    - R3xSO3Representation:
+        \f[ \begin{array}{ccccc}
+        \ominus & : & (R^3\times SO(3))^2                 & \to & R^3 \times \mathfrak{so}(3) \\
+                &   & (a = (t_a,R_a),b = (t_b,R_b))       & \mapsto & b \ominus a = (t_b - t_a, \log(R_a^{-1} R_b) \\
+        \end{array} \f]
+    - SE3Representation:
+        \f[ \begin{array}{ccccc}
+        \ominus & : & SE(3)^2 & \to & \mathfrak{se}(3) \\
+                &   & a, b    & \mapsto & b \ominus a = \log(a^{-1} b) \\
+        \end{array} \f]
+
 */
-template <Representation_t representation>
+template <Representation_t representation = R3xSO3Representation>
 class SOT_CORE_DLLAPI FeaturePose
   : public FeatureAbstract
 {
@@ -80,22 +94,20 @@ class SOT_CORE_DLLAPI FeaturePose
   /*! \name Output signals
     @{
   */
-  /// Pose of <em>Frame B</em> wrt to <em>world frame</em>.
+  /// Pose of <em>Frame B</em> wrt to <em>Frame A</em>.
   SignalTimeDependent< MatrixHomogeneous, int > faMfb;
 
-  /// Pose of <em>Frame B</em> wrt to <em>world frame</em>.
+  /// Pose of <em>Frame B</em> wrt to <em>Frame A</em>.
   /// It is expressed as a translation followed by a quaternion.
   SignalTimeDependent< Vector7, int > q_faMfb;
 
-  /// Pose of <em>Frame B*</em> wrt to <em>world frame</em>.
+  /// Desired pose of <em>Frame B</em> wrt to <em>Frame A</em>.
   /// It is expressed as a translation followed by a quaternion.
   SignalTimeDependent< Vector7, int > q_faMfbDes;
   /*! @} */
 
   using FeatureAbstract::selectionSIN;
-  // TODO Rename into dError_dq or Jerror
   using FeatureAbstract::jacobianSOUT;
-  // TODO Rename into error
   using FeatureAbstract::errorSOUT;
 
   /*! \name Dealing with the reference value to be reach with this feature.
@@ -109,11 +121,17 @@ class SOT_CORE_DLLAPI FeaturePose
 
   virtual unsigned int& getDimension( unsigned int & dim, int time );
 
-  /// Computes \f$ {}^oM_{fb} \ominus {}^oM_{fa} {}^{fa}M^*_{fb} \f$
+  /// Computes \f$ {}^oM^{-1}_{fa} {}^oM_{fb} \ominus {}^{fa}M^*_{fb} \f$
   virtual dg::Vector& computeError( dg::Vector& res,int time );
-  /// Computes \f$ \frac{\partial\ominus}{\partial b} {{}^{fb^*}X_{fa}} {}^{fa}\nu^*_{fafb} \f$
+  /// Computes \f$ \frac{\partial\ominus}{\partial b} X {}^{fa}\nu^*_{fafb} \f$.
+  /// There are two different cases, depending on the representation:
+  /// - R3xSO3Representation: \f$ X = \left( \begin{array}{cc} I_3 & [ {}^{fa}t_{fb} ] \\ 0_3 & {{}^{fa}R^*_{fb}}^T \end{array} \right) \f$
+  /// - SE3Representation: \f$ X = {{}^{fa}X^*_{fb}}^{-1} \f$ (see pinocchio::SE3Base<Scalar,Options>::toActionMatrix)
   virtual dg::Vector& computeErrorDot( dg::Vector& res,int time );
-  /// Computes \f$ \frac{\partial\ominus}{\partial b} {{}^{fb}X_{jb}} {}^{jb}J_{jb} + \frac{\partial\ominus}{\partial a} {{}^{fb^*}X_{ja}} {}^{ja}J_{ja} \f$
+  /// Computes \f$ \frac{\partial\ominus}{\partial b} Y \left( {{}^{fb}X_{jb}} {}^{jb}J_{jb} - {{}^{fb}X_{ja}} {}^{ja}J_{ja} \right) \f$.
+  /// There are two different cases, depending on the representation:
+  /// - R3xSO3Representation: \f$ Y = \left( \begin{array}{cc} {{}^{fa}R_{fb}} & 0_3 \\ 0_3 & I_3 \end{array} \right) \f$
+  /// - SE3Representation: \f$ Y = I_6 \f$
   virtual dg::Matrix& computeJacobian( dg::Matrix& res,int time );
 
   /** Static Feature selection. */

include/sot/core/robot-utils.hh

@@ -250,7 +250,7 @@ namespace dynamicgraph {
 
       /** \name Logger related methods */
       /** \{*/
-      /// \brief Send messages \param msg with level t. Add string file and line to message.
+      /// \brief Send messages \c msg with level \c t. Add string \c file and \c line to message.
       void sendMsg(const std::string &msg,
 		   MsgType t=MSG_TYPE_INFO,
 		   const char *file="",