Various documentation improvements, in particualr in Cholesky and Geometry module.

Added doxygen groups for Matrix typedefs and the Geometry module
2026-04-10 11:34:33 +08:00 · 2008-07-20 15:18:54 +00:00
parent 269f683902
commit ce425d92f1
14 changed files with 179 additions and 89 deletions
--- a/Eigen/src/Geometry/AngleAxis.h
+++ b/Eigen/src/Geometry/AngleAxis.h
@@ -64,10 +64,15 @@ protected:

 public:

+  /** Default constructor without initialization. */
  AngleAxis() {}
+  /** Constructs and initialize the angle-axis rotation from an \a angle in radian
+    * and an \a axis which must be normalized. */
  template<typename Derived>
  inline AngleAxis(Scalar angle, const MatrixBase<Derived>& axis) : m_axis(axis), m_angle(angle) {}
+  /** Constructs and initialize the angle-axis rotation from a quaternion \a q. */
  inline AngleAxis(const QuaternionType& q) { *this = q; }
+  /** Constructs and initialize the angle-axis rotation from a 3x3 rotation matrix. */
  template<typename Derived>
  inline AngleAxis(const MatrixBase<Derived>& m) { *this = m; }

@@ -77,6 +82,8 @@ public:
  const Vector3& axis() const { return m_axis; }
  Vector3& axis() { return m_axis; }

+  /** Automatic conversion to a 3x3 rotation matrix.
+    * \sa toRotationMatrix() */
  operator Matrix3 () const { return toRotationMatrix(); }

  inline QuaternionType operator* (const AngleAxis& other) const
@@ -105,7 +112,11 @@ public:
  Matrix3 toRotationMatrix(void) const;
 };

+/** \ingroup Geometry
+  * single precision angle-axis type */
 typedef AngleAxis<float> AngleAxisf;
+/** \ingroup Geometry
+  * double precision angle-axis type */
 typedef AngleAxis<double> AngleAxisd;

 /** Set \c *this from a quaternion.
--- a/Eigen/src/Geometry/Quaternion.h
+++ b/Eigen/src/Geometry/Quaternion.h
@@ -38,13 +38,12 @@ struct ei_quaternion_assign_impl;
  *
  * \param _Scalar the scalar type, i.e., the type of the coefficients
  *
-  * This class represents a quaternion that is a convenient representation of
-  * orientations and rotations of objects in three dimensions. Compared to other
-  * representations like Euler angles or 3x3 matrices, quatertions offer the
-  * following advantages:
-  * \li \c compact storage (4 scalars)
-  * \li \c efficient to compose (28 flops),
-  * \li \c stable spherical interpolation
+  * This class represents a quaternion \f$ w+xi+yj+zk \f$ that is a convenient representation of
+  * orientations and rotations of objects in three dimensions. Compared to other representations
+  * like Euler angles or 3x3 matrices, quatertions offer the following advantages:
+  * \li \b compact storage (4 scalars)
+  * \li \b efficient to compose (28 flops),
+  * \li \b stable spherical interpolation
  *
  * The following two typedefs are provided for convenience:
  * \li \c Quaternionf for \c float
@@ -63,18 +62,29 @@ public:
  /** the scalar type of the coefficients */
  typedef _Scalar Scalar;

+  /** the type of a 3D vector */
  typedef Matrix<Scalar,3,1> Vector3;
+  /** the equivalent rotation matrix type */
  typedef Matrix<Scalar,3,3> Matrix3;
+  /** the equivalent angle-axis type */
  typedef AngleAxis<Scalar> AngleAxisType;

+  /** \returns the \c x coefficient */
  inline Scalar x() const { return m_coeffs.coeff(0); }
+  /** \returns the \c y coefficient */
  inline Scalar y() const { return m_coeffs.coeff(1); }
+  /** \returns the \c z coefficient */
  inline Scalar z() const { return m_coeffs.coeff(2); }
+  /** \returns the \c w coefficient */
  inline Scalar w() const { return m_coeffs.coeff(3); }

+  /** \returns a reference to the \c x coefficient */
  inline Scalar& x() { return m_coeffs.coeffRef(0); }
+  /** \returns a reference to the \c y coefficient */
  inline Scalar& y() { return m_coeffs.coeffRef(1); }
+  /** \returns a reference to the \c z coefficient */
  inline Scalar& z() { return m_coeffs.coeffRef(2); }
+  /** \returns a reference to the \c w coefficient */
  inline Scalar& w() { return m_coeffs.coeffRef(3); }

  /** \returns a read-only vector expression of the imaginary part (x,y,z) */
@@ -83,25 +93,33 @@ public:
  /** \returns a vector expression of the imaginary part (x,y,z) */
  inline Block<Coefficients,3,1> vec() { return m_coeffs.template start<3>(); }

-  /** \returns a read-only vector expression of the coefficients */
+  /** \returns a read-only vector expression of the coefficients (x,y,z,w) */
  inline const Coefficients& coeffs() const { return m_coeffs; }

-  /** \returns a vector expression of the coefficients */
+  /** \returns a vector expression of the coefficients (x,y,z,w) */
  inline Coefficients& coeffs() { return m_coeffs; }

+  /** Default constructor and initializing an identity quaternion. */
+  inline Quaternion()
+  { m_coeffs << 0, 0, 0, 1; }
+
+  /** Constructs and initializes the quaternion \f$ w+xi+yj+zk \f$ from
+    * its four coefficients \a w, \a x, \a y and \a z.
+    */
  // FIXME what is the prefered order: w x,y,z or x,y,z,w ?
-  inline Quaternion(Scalar w = 1.0, Scalar x = 0.0, Scalar y = 0.0, Scalar z = 0.0)
-  {
-    m_coeffs.coeffRef(0) = x;
-    m_coeffs.coeffRef(1) = y;
-    m_coeffs.coeffRef(2) = z;
-    m_coeffs.coeffRef(3) = w;
-  }
+  inline Quaternion(Scalar w, Scalar x, Scalar y, Scalar z)
+  { m_coeffs << x, y, z, w; }

  /** Copy constructor */
  inline Quaternion(const Quaternion& other) { m_coeffs = other.m_coeffs; }

+  /** Constructs and initializes a quaternion from the angle-axis \a aa */
  explicit inline Quaternion(const AngleAxisType& aa) { *this = aa; }
+  /** Constructs and initializes a quaternion from either:
+    *  - a rotation matrix expression,
+    *  - a 4D vector expression representing quaternion coefficients.
+    * \sa operator=(MatrixBase<Derived>)
+    */
  template<typename Derived>
  explicit inline Quaternion(const MatrixBase<Derived>& other) { *this = other; }

@@ -110,6 +128,7 @@ public:
  template<typename Derived>
  Quaternion& operator=(const MatrixBase<Derived>& m);

+  /** Automatic conversion to a rotation matrix. */
  operator Matrix3 () const { return toRotationMatrix(); }

  /** \returns a quaternion representing an identity rotation
@@ -149,7 +168,11 @@ public:

 };

+/** \ingroup Geometry
+  * single precision quaternion type */
 typedef Quaternion<float> Quaternionf;
+/** \ingroup Geometry
+  * double precision quaternion type */
 typedef Quaternion<double> Quaterniond;

 /** \returns the concatenation of two rotations as a quaternion-quaternion product */
@@ -165,6 +188,7 @@ inline Quaternion<Scalar> Quaternion<Scalar>::operator* (const Quaternion& other
  );
 }

+/** \sa operator*(Quaternion) */
 template <typename Scalar>
 inline Quaternion<Scalar>& Quaternion<Scalar>::operator*= (const Quaternion& other)
 {
@@ -200,8 +224,7 @@ inline Quaternion<Scalar>& Quaternion<Scalar>::operator=(const Quaternion& other
  return *this;
 }

-/** Set \c *this from an angle-axis \a aa
-  * and returns a reference to \c *this
+/** Set \c *this from an angle-axis \a aa and returns a reference to \c *this
  */
 template<typename Scalar>
 inline Quaternion<Scalar>& Quaternion<Scalar>::operator=(const AngleAxisType& aa)
--- a/Eigen/src/Geometry/Rotation.h
+++ b/Eigen/src/Geometry/Rotation.h
@@ -28,7 +28,7 @@
 // this file aims to contains the various representations of rotation/orientation
 // in 2D and 3D space excepted Matrix and Quaternion.

-/** \geometry_module
+/** \internal
  *
  * \class ToRotationMatrix
  *
@@ -103,7 +103,7 @@ struct ToRotationMatrix<Scalar, Dim, MatrixBase<OtherDerived> >
  }
 };

-/** \geometry_module
+/** \geometry_module \ingroup Geometry
  *
  * \class Rotation2D
  *
@@ -111,10 +111,10 @@ struct ToRotationMatrix<Scalar, Dim, MatrixBase<OtherDerived> >
  *
  * \param _Scalar the scalar type, i.e., the type of the coefficients
  *
-  * This class is equivalent to a single scalar representing the rotation angle
-  * in radian with some additional features such as the conversion from/to
-  * rotation matrix. Moreover this class aims to provide a similar interface
-  * to Quaternion in order to facilitate the writing of generic algorithm
+  * 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
  * dealing with rotations.
  *
  * \sa class Quaternion, class Transform
@@ -134,16 +134,22 @@ protected:

 public:

+  /** Construct a 2D counter clock wise rotation from the angle \a a in radian. */
  inline Rotation2D(Scalar a) : m_angle(a) {}
  inline operator Scalar& () { return m_angle; }
  inline operator Scalar () const { return m_angle; }

+  /** Automatic convertion to a 2D rotation matrix.
+    * \sa toRotationMatrix()
+    */
+  inline operator Matrix2() const { return toRotationMatrix(); }
+
  template<typename Derived>
  Rotation2D& fromRotationMatrix(const MatrixBase<Derived>& m);
  Matrix2 toRotationMatrix(void) const;

  /** \returns the spherical interpolation between \c *this and \a other using
-    * parameter \a t. It is equivalent to a linear interpolation.
+    * parameter \a t. It is in fact equivalent to a linear interpolation.
    */
  inline Rotation2D slerp(Scalar t, const Rotation2D& other) const
  { return m_angle * (1-t) + t * other; }
--- a/Eigen/src/Geometry/Transform.h
+++ b/Eigen/src/Geometry/Transform.h
@@ -50,20 +50,29 @@ struct ei_transform_product_impl;
  * Conversion methods from/to Qt's QMatrix are available if the preprocessor token
  * EIGEN_QT_SUPPORT is defined.
  *
+  * \sa class Matrix, class Quaternion
  */
 template<typename _Scalar, int _Dim>
 class Transform
 {
 public:

-  enum { Dim = _Dim, HDim = _Dim+1 };
+  enum {
+    Dim = _Dim,     ///< space dimension in which the transformation holds
+    HDim = _Dim+1   ///< size of a respective homogeneous vector
+  };
  /** the scalar type of the coefficients */
  typedef _Scalar Scalar;
+  /** type of the matrix used to represent the transformation */
  typedef Matrix<Scalar,HDim,HDim> MatrixType;
+  /** type of the matrix used to represent the affine part of the transformation */
  typedef Matrix<Scalar,Dim,Dim> AffineMatrixType;
-  typedef Block<MatrixType,Dim,Dim> AffineMatrixRef;
+  /** type of read/write reference to the affine part of the transformation */
+  typedef Block<MatrixType,Dim,Dim> AffinePart;
+  /** type of a vector */
  typedef Matrix<Scalar,Dim,1> VectorType;
-  typedef Block<MatrixType,Dim,1> VectorRef;
+  /** type of a read/write reference to the translation part of the rotation */
+  typedef Block<MatrixType,Dim,1> TranslationPart;

 protected:

@@ -80,10 +89,12 @@ public:
  inline Transform& operator=(const Transform& other)
  { m_matrix = other.m_matrix; return *this; }

+  /** Constructs and initializes a transformation from a (Dim+1)^2 matrix. */
  template<typename OtherDerived>
  inline explicit Transform(const MatrixBase<OtherDerived>& other)
  { m_matrix = other; }

+  /** Set \c *this from a (Dim+1)^2 matrix. */
  template<typename OtherDerived>
  inline Transform& operator=(const MatrixBase<OtherDerived>& other)
  { m_matrix = other; return *this; }
@@ -100,14 +111,14 @@ public:
  inline MatrixType& matrix() { return m_matrix; }

  /** \returns a read-only expression of the affine (linear) part of the transformation */
-  inline const AffineMatrixRef affine() const { return m_matrix.template block<Dim,Dim>(0,0); }
+  inline const AffinePart affine() const { return m_matrix.template block<Dim,Dim>(0,0); }
  /** \returns a writable expression of the affine (linear) part of the transformation */
-  inline AffineMatrixRef affine() { return m_matrix.template block<Dim,Dim>(0,0); }
+  inline AffinePart affine() { return m_matrix.template block<Dim,Dim>(0,0); }

  /** \returns a read-only expression of the translation vector of the transformation */
-  inline const VectorRef translation() const { return m_matrix.template block<Dim,1>(0,Dim); }
+  inline const TranslationPart translation() const { return m_matrix.template block<Dim,1>(0,Dim); }
  /** \returns a writable expression of the translation vector of the transformation */
-  inline VectorRef translation() { return m_matrix.template block<Dim,1>(0,Dim); }
+  inline TranslationPart translation() { return m_matrix.template block<Dim,1>(0,Dim); }

  template<typename OtherDerived>
  const typename ei_transform_product_impl<OtherDerived,_Dim,_Dim+1>::ResultType
@@ -118,6 +129,7 @@ public:
  operator * (const Transform& other) const
  { return m_matrix * other.matrix(); }

+  /** \sa MatrixBase::setIdentity() */
  void setIdentity() { m_matrix.setIdentity(); }

  template<typename OtherDerived>
@@ -138,10 +150,7 @@ public:
  template<typename RotationType>
  Transform& prerotate(const RotationType& rotation);

-  template<typename OtherDerived>
  Transform& shear(Scalar sx, Scalar sy);
-
-  template<typename OtherDerived>
  Transform& preshear(Scalar sx, Scalar sy);

  AffineMatrixType extractRotation() const;
@@ -151,6 +160,7 @@ public:
  Transform& fromPositionOrientationScale(const MatrixBase<PositionDerived> &position,
    const OrientationType& orientation, const MatrixBase<ScaleDerived> &scale);

+  /** \sa MatrixBase::inverse() */
  const Inverse<MatrixType, false> inverse() const
  { return m_matrix.inverse(); }

@@ -158,8 +168,19 @@ protected:

 };

+/** \ingroup Geometry */
+typedef Transform<float,2> Transform2f;
+/** \ingroup Geometry */
+typedef Transform<float,3> Transform3f;
+/** \ingroup Geometry */
+typedef Transform<double,2> Transform2d;
+/** \ingroup Geometry */
+typedef Transform<double,3> Transform3d;
+
 #ifdef EIGEN_QT_SUPPORT
 /** Initialises \c *this from a QMatrix assuming the dimension is 2.
+  *
+  * This function is available only if the token EIGEN_QT_SUPPORT is defined.
  */
 template<typename Scalar, int Dim>
 Transform<Scalar,Dim>::Transform(const QMatrix& other)
@@ -168,6 +189,8 @@ Transform<Scalar,Dim>::Transform(const QMatrix& other)
 }

 /** Set \c *this from a QMatrix assuming the dimension is 2.
+  *
+  * This function is available only if the token EIGEN_QT_SUPPORT is defined.
  */
 template<typename Scalar, int Dim>
 Transform<Scalar,Dim>& Transform<Scalar,Dim>::operator=(const QMatrix& other)
@@ -180,21 +203,25 @@ Transform<Scalar,Dim>& Transform<Scalar,Dim>::operator=(const QMatrix& other)
 }

 /** \returns a QMatrix from \c *this assuming the dimension is 2.
+  *
+  * This function is available only if the token EIGEN_QT_SUPPORT is defined.
  */
 template<typename Scalar, int Dim>
 QMatrix Transform<Scalar,Dim>::toQMatrix(void) const
 {
  EIGEN_STATIC_ASSERT(Dim==2, you_did_a_programming_error);
-  return QMatrix( other.coeffRef(0,0), other.coeffRef(1,0),
-                  other.coeffRef(0,1), other.coeffRef(1,1),
-                  other.coeffRef(0,2), other.coeffRef(1,2),
+  return QMatrix(other.coeffRef(0,0), other.coeffRef(1,0),
+                 other.coeffRef(0,1), other.coeffRef(1,1),
+                 other.coeffRef(0,2), other.coeffRef(1,2));
 }
 #endif

 /** \returns an expression of the product between the transform \c *this and a matrix expression \a other
  *
-  * The right hand side \a other might be a vector of size Dim, an homogeneous vector of size Dim+1
-  * or a transformation matrix of size Dim+1 x Dim+1.
+  * The right hand side \a other might be either:
+  * \li a vector of size Dim,
+  * \li an homogeneous vector of size Dim+1,
+  * \li a transformation matrix of size Dim+1 x Dim+1.
  */
 template<typename Scalar, int Dim>
 template<typename OtherDerived>
@@ -213,8 +240,7 @@ template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::scale(const MatrixBase<OtherDerived> &other)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim), you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(OtherDerived,Dim);
  affine() = (affine() * other.asDiagonal()).lazy();
  return *this;
 }
@@ -228,8 +254,7 @@ template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::prescale(const MatrixBase<OtherDerived> &other)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim), you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(OtherDerived,Dim);
  m_matrix.template block<Dim,HDim>(0,0) = (other.asDiagonal() * m_matrix.template block<Dim,HDim>(0,0)).lazy();
  return *this;
 }
@@ -243,8 +268,7 @@ template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::translate(const MatrixBase<OtherDerived> &other)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim), you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(OtherDerived,Dim);
  translation() += affine() * other;
  return *this;
 }
@@ -258,8 +282,7 @@ template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::pretranslate(const MatrixBase<OtherDerived> &other)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim), you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(OtherDerived,Dim);
  translation() += other;
  return *this;
 }
@@ -273,8 +296,8 @@ Transform<Scalar,Dim>::pretranslate(const MatrixBase<OtherDerived> &other)
  * Natively supported types includes:
  *   - any scalar (2D),
  *   - a Dim x Dim matrix expression,
-  *   - Quaternion (3D),
-  *   - AngleAxis (3D)
+  *   - a Quaternion (3D),
+  *   - a AngleAxis (3D)
  *
  * This mechanism is easily extendable to support user types such as Euler angles,
  * or a pair of Quaternion for 4D rotations.
@@ -293,9 +316,9 @@ Transform<Scalar,Dim>::rotate(const RotationType& rotation)
 /** Applies on the left the rotation represented by the rotation \a rotation
  * to \c *this and returns a reference to \c *this.
  *
-  * See rotate(RotationType) for further details.
+  * See rotate() for further details.
  *
-  * \sa rotate(RotationType), rotate(Scalar)
+  * \sa rotate()
  */
 template<typename Scalar, int Dim>
 template<typename RotationType>
@@ -303,7 +326,7 @@ Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::prerotate(const RotationType& rotation)
 {
  m_matrix.template block<Dim,HDim>(0,0) = ToRotationMatrix<Scalar,Dim,RotationType>::convert(rotation)
-                                      * m_matrix.template block<Dim,HDim>(0,0);
+                                         * m_matrix.template block<Dim,HDim>(0,0);
  return *this;
 }

@@ -313,12 +336,10 @@ Transform<Scalar,Dim>::prerotate(const RotationType& rotation)
  * \sa preshear()
  */
 template<typename Scalar, int Dim>
-template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::shear(Scalar sx, Scalar sy)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim) && int(Dim)==2, you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT(int(Dim)==2, you_did_a_programming_error);
  VectorType tmp = affine().col(0)*sy + affine().col(1);
  affine() << affine().col(0) + affine().col(1)*sx, tmp;
  return *this;
@@ -330,18 +351,16 @@ Transform<Scalar,Dim>::shear(Scalar sx, Scalar sy)
  * \sa shear()
  */
 template<typename Scalar, int Dim>
-template<typename OtherDerived>
 Transform<Scalar,Dim>&
 Transform<Scalar,Dim>::preshear(Scalar sx, Scalar sy)
 {
-  EIGEN_STATIC_ASSERT(int(OtherDerived::IsVectorAtCompileTime)
-    && int(OtherDerived::SizeAtCompileTime)==int(Dim), you_did_a_programming_error);
+  EIGEN_STATIC_ASSERT(int(Dim)==2, you_did_a_programming_error);
  m_matrix.template block<Dim,HDim>(0,0) = AffineMatrixType(1, sx, sy, 1) * m_matrix.template block<Dim,HDim>(0,0);
  return *this;
 }

 /** \returns the rotation part of the transformation using a QR decomposition.
-  * \sa extractRotationNoShear()
+  * \sa extractRotationNoShear(), class QR
  */
 template<typename Scalar, int Dim>
 typename Transform<Scalar,Dim>::AffineMatrixType
@@ -408,15 +427,15 @@ struct ei_transform_product_impl<Other,Dim,HDim, Dim,1>
 {
  typedef typename Other::Scalar Scalar;
  typedef Transform<Scalar,Dim> TransformType;
-  typedef typename TransformType::AffineMatrixRef MatrixType;
+  typedef typename TransformType::AffinePart MatrixType;
  typedef const CwiseUnaryOp<
      ei_scalar_multiple_op<Scalar>,
      NestByValue<CwiseBinaryOp<
        ei_scalar_sum_op<Scalar>,
        NestByValue<typename ProductReturnType<NestByValue<MatrixType>,Other>::Type >,
-        NestByValue<typename TransformType::VectorRef> > >
+        NestByValue<typename TransformType::TranslationPart> > >
      > ResultType;
-  // FIXME shall we offer an optimized version when the last row is known to be 0,0...,0,1 ?
+  // FIXME should we offer an optimized version when the last row is known to be 0,0...,0,1 ?
  static ResultType run(const TransformType& tr, const Other& other)
  { return ((tr.affine().nestByValue() * other).nestByValue() + tr.translation().nestByValue()).nestByValue()
          * (Scalar(1) / ( (tr.matrix().template block<1,Dim>(Dim,0) * other).coeff(0) + tr.matrix().coeff(Dim,Dim))); }