namespace Eigen { /** \page TutorialCore Tutorial 1/3 - Core features \ingroup Tutorial
\ref index "Overview" | \b Core \b features | \ref TutorialGeometry "Geometry" | \ref TutorialAdvancedLinearAlgebra "Advanced linear algebra"
\b Table \b of \b contents - \ref TutorialCoreSimpleExampleFixedSize - \ref TutorialCoreSimpleExampleDynamicSize - \ref TutorialCoreMatrixTypes - \ref TutorialCoreMatrixInitialization - \ref TutorialCoreBasicLinearAlgebra - \ref TutorialCoreReductions - \ref TutorialCoreSubMatrix - \ref TutorialCoreMatrixTransformations - \ref TutorialCoreTriangularMatrix - \ref TutorialCorePerformance \n
\section TutorialCoreSimpleExampleFixedSize Simple example with fixed-size matrices and vectors By fixed-size, we mean that the number of rows and columns are known at compile-time. In this case, Eigen avoids dynamic memory allocation and unroll loops. This is useful for very small sizes (typically up to 4x4).
\include Tutorial_simple_example_fixed_size.cpp output: \include Tutorial_simple_example_fixed_size.out
top\section TutorialCoreSimpleExampleDynamicSize Simple example with dynamic-size matrices and vectors Dynamic-size means that the number of rows and columns are not known at compile-time. In this case, they are stored as runtime variables and the arrays are dynamically allocated.
\include Tutorial_simple_example_dynamic_size.cpp output: \include Tutorial_simple_example_dynamic_size.out
top\section TutorialCoreMatrixTypes Matrix and vector types In Eigen, all kinds of dense matrices and vectors are represented by the template class Matrix. In most cases you can simply use one of the \ref matrixtypedefs "several convenient typedefs". The template class Matrix takes a number of template parameters, but for now it is enough to understand the 3 first ones (and the others can then be left unspecified): \code Matrix \endcode \li \c Scalar is the scalar type, i.e. the type of the coefficients. That is, if you want a vector of floats, choose \c float here. \li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows and columns of the matrix as known at compile-time. For example, \c Vector3d is a typedef for \code Matrix \endcode What if the matrix has dynamic-size i.e. the number of rows or cols isn't known at compile-time? Then use the special value Eigen::Dynamic. For example, \c VectorXd is a typedef for \code Matrix \endcode top\section TutorialCoreMatrixInitialization Matrix and vector creation and initialization \subsection TutorialPredefMat PredefinedMatrix Eigen offers several methods to create or set matrices with coefficients equals to either a constant value, the identity matrix or even random values:
Fixed-size matrix or vector Dynamic-size matrix Dynamic-size vector
\code Matrix3f x; x = Matrix3f::Zero(); x = Matrix3f::Ones(); x = Matrix3f::Constant(value); x = Matrix3f::Identity(); x = Matrix3f::Random(); x.setZero(); x.setOnes(); x.setIdentity(); x.setConstant(value); x.setRandom(); \endcode \code MatrixXf x; x = MatrixXf::Zero(rows, cols); x = MatrixXf::Ones(rows, cols); x = MatrixXf::Constant(rows, cols, value); x = MatrixXf::Identity(rows, cols); x = MatrixXf::Random(rows, cols); x.setZero(rows, cols); x.setOnes(rows, cols); x.setConstant(rows, cols, value); x.setIdentity(rows, cols); x.setRandom(rows, cols); \endcode \code VectorXf x; x = VectorXf::Zero(size); x = VectorXf::Ones(size); x = VectorXf::Constant(size, value); x = VectorXf::Identity(size); x = VectorXf::Random(size); x.setZero(size); x.setOnes(size); x.setConstant(size, value); x.setIdentity(size); x.setRandom(size); \endcode
Basis vectors \link MatrixBase::Unit [details]\endlink
\code Vector3f::UnixX() // 1 0 0 Vector3f::UnixY() // 0 1 0 Vector3f::UnixZ() // 0 0 1 \endcode\code VectorXf::Unit(size,i) VectorXf::Unit(4,1) == Vector4f(0,1,0,0) == Vector4f::UnitY() \endcode
Here is an usage example:
\code cout << MatrixXf::Constant(2, 3, sqrt(2)) << endl; RowVector3i v; v.setConstant(6); cout << "v = " << v << endl; \endcode output: \code 1.41 1.41 1.41 1.41 1.41 1.41 v = 6 6 6 \endcode
\subsection TutorialMap Map Any memory buffer can be mapped as an Eigen's expression:
\code std::vector stlarray(10); Map(&stlarray[0], stlarray.size()).setOnes(); int data[4] = 1, 2, 3, 4; Matrix2i mat2x2(data); MatrixXi mat2x2 = Map(data); MatrixXi mat2x2 = Map(data,2,2); \endcode
\subsection TutorialCommaInit Comma initializer Eigen also offer a \link MatrixBase::operator<<(const Scalar &) comma initializer syntax \endlink which allows you to set all the coefficients of a matrix to specific values:
\include Tutorial_commainit_01.cpp output: \verbinclude Tutorial_commainit_01.out
Feel the above example boring ? Look at the following example where the matrix is set per block:
\include Tutorial_commainit_02.cpp output: \verbinclude Tutorial_commainit_02.out
\b Side \b note: here \link CommaInitializer::finished() .finished() \endlink is used to get the actual matrix object once the comma initialization of our temporary submatrix is done. Note that despite the appearant complexity of such an expression Eigen's comma initializer usually yields to very optimized code without any overhead. top\section TutorialCoreBasicLinearAlgebra Basic Linear Algebra In short all mathematically well defined operators can be used right away as in the following example: \code mat4 -= mat1*1.5 + mat2 * mat3/4; \endcode which includes two matrix scalar products ("mat1*1.5" and "mat3/4"), a matrix-matrix product ("mat2 * mat3/4"), a matrix addition ("+") and substraction with assignment ("-=").
matrix/vector product\code col2 = mat1 * col1; row2 = row1 * mat1; row1 *= mat1; mat3 = mat1 * mat2; mat3 *= mat1; \endcode
add/subtract\code mat3 = mat1 + mat2; mat3 += mat1; mat3 = mat1 - mat2; mat3 -= mat1;\endcode
scalar product\code mat3 = mat1 * s1; mat3 = s1 * mat1; mat3 *= s1; mat3 = mat1 / s1; mat3 /= s1;\endcode
\link MatrixBase::dot() dot product \endlink (inner product)\code scalar = vec1.dot(vec2);\endcode
outer product\code mat = vec1 * vec2.transpose();\endcode
\link MatrixBase::cross() cross product \endlink\code #include vec3 = vec1.cross(vec2);\endcode
In Eigen only mathematically well defined operators can be used right away, but don't worry, thanks to the \link Cwise .cwise() \endlink operator prefix, Eigen's matrices also provide a very powerful numerical container supporting most common coefficient wise operators:
Coefficient wise \link Cwise::operator*() product \endlink \code mat3 = mat1.cwise() * mat2; \endcode
Add a scalar to all coefficients\code mat3 = mat1.cwise() + scalar; mat3.cwise() += scalar; mat3.cwise() -= scalar; \endcode
Coefficient wise \link Cwise::operator/() division \endlink\code mat3 = mat1.cwise() / mat2; \endcode
Coefficient wise \link Cwise::inverse() reciprocal \endlink\code mat3 = mat1.cwise().inverse(); \endcode
Coefficient wise comparisons \n (support all operators)\code mat3 = mat1.cwise() < mat2; mat3 = mat1.cwise() <= mat2; mat3 = mat1.cwise() > mat2; etc. \endcode
\b Trigo: \n \link Cwise::sin sin \endlink, \link Cwise::cos cos \endlink, \link Cwise::tan tan \endlink\code mat3 = mat1.cwise().sin(); etc. \endcode
\b Power: \n \link Cwise::pow() pow \endlink, \link Cwise::square square \endlink, \link Cwise::cube cube \endlink, \n \link Cwise::sqrt sqrt \endlink, \link Cwise::exp exp \endlink, \link Cwise::log log \endlink \code mat3 = mat1.cwise().square(); mat3 = mat1.cwise().pow(5); mat3 = mat1.cwise().log(); etc. \endcode
\link Cwise::min min \endlink, \link Cwise::max max \endlink, \n absolute value (\link Cwise::abs() abs \endlink, \link Cwise::abs2() abs2 \endlink \code mat3 = mat1.cwise().min(mat2); mat3 = mat1.cwise().max(mat2); mat3 = mat1.cwise().abs(mat2); mat3 = mat1.cwise().abs2(mat2); \endcode
\b Side \b note: If you feel the \c .cwise() syntax is too verbose for your taste and don't bother to have non mathematical operator directly available feel free to extend MatrixBase as described \ref ExtendingMatrixBase "here". top\section TutorialCoreReductions Reductions Eigen provides several several reduction methods such as: \link MatrixBase::minCoeff() minCoeff() \endlink, \link MatrixBase::maxCoeff() maxCoeff() \endlink, \link MatrixBase::sum() sum() \endlink, \link MatrixBase::trace() trace() \endlink, \link MatrixBase::norm() norm() \endlink, \link MatrixBase::norm2() norm2() \endlink, \link MatrixBase::all() all() \endlink,and \link MatrixBase::any() any() \endlink. All reduction operations can be done matrix-wise, \link MatrixBase::colwise() column-wise \endlink or \link MatrixBase::rowwise() row-wise \endlink. Usage example:
\code 5 3 1 mat = 2 7 8 9 4 6 \endcode \code mat.minCoeff(); \endcode\code 1 \endcode
\code mat.colwise().minCoeff(); \endcode\code 2 3 1 \endcode
\code mat.rowwise().minCoeff(); \endcode\code 1 2 4 \endcode
\b Side \b note: The all() and any() functions are especially useful in combinaison with coeff-wise comparison operators (\ref CwiseAll "example"). top\section TutorialCoreSubMatrix Sub matrices Read-write access to a \link MatrixBase::col(int) column \endlink or a \link MatrixBase::row(int) row \endlink of a matrix: \code mat1.row(i) = mat2.col(j); mat1.col(j1).swap(mat1.col(j2)); \endcode Read-write access to sub-vectors:
Default versions Optimized versions when the size is known at compile time
\code vec1.start(n)\endcode\code vec1.start()\endcodethe first \c n coeffs
\code vec1.end(n)\endcode\code vec1.end()\endcodethe last \c n coeffs
\code vec1.block(pos,n)\endcode\code vec1.block(pos)\endcode the \c size coeffs in the range [\c pos : \c pos + \c n [
Read-write access to sub-matrices:
Default versions Optimized versions when the size is known at compile time
\code mat1.block(i,j,rows,cols)\endcode \link MatrixBase::block(int,int,int,int) (more) \endlink \code mat1.block(i,j)\endcode \link MatrixBase::block(int,int) (more) \endlink the \c rows x \c cols sub-matrix starting from position (\c i,\c j)
\code mat1.corner(TopLeft,rows,cols) mat1.corner(TopRight,rows,cols) mat1.corner(BottomLeft,rows,cols) mat1.corner(BottomRight,rows,cols)\endcode \link MatrixBase::corner(CornerType,int,int) (more) \endlink \code mat1.corner(TopLeft) mat1.corner(TopRight) mat1.corner(BottomLeft) mat1.corner(BottomRight)\endcode \link MatrixBase::corner(CornerType) (more) \endlink the \c rows x \c cols sub-matrix \n taken in one of the four corners
\code vec1 = mat1.diagonal(); mat1.diagonal() = vec1; \endcode \link MatrixBase::diagonal() (more) \endlink
top\section TutorialCoreMatrixTransformations Matrix transformations
\link MatrixBase::transpose() transposition \endlink (read-write)\code mat3 = mat1.transpose() * mat2; mat3.transpose() = mat1 * mat2.transpose(); \endcode
\link MatrixBase::adjoint() adjoint \endlink (read only)\n\code mat3 = mat1.adjoint() * mat2; mat3 = mat1.conjugate().transpose() * mat2; \endcode
returns a \link MatrixBase::normalized() normalized \endlink vector \n \link MatrixBase::normalize() normalize \endlink a vector \code vec3 = vec1.normalized(); vec1.normalize();\endcode
\link MatrixBase::asDiagonal() make a diagonal matrix \endlink from a vector \n \b Note: this product is automatically optimized !\code mat3 = mat1 * vec2.asDiagonal();\endcode
\link MatrixBase::minor() minor \endlink (read-write)\code mat4x4.minor(i,j) = mat3x3; mat3x3 = mat4x4.minor(i,j);\endcode
top\section TutorialCoreTriangularMatrix Dealing with triangular matrices todo top\section TutorialCorePerformance Notes on performances
\code m4 = m4 * m4;\endcode auto-evaluates so no aliasing problem (performance penalty is low)
\code Matrix4f other = (m4 * m4).lazy();\endcode forces lazy evaluation
\code m4 = m4 + m4;\endcode here Eigen goes for lazy evaluation, as with most expressions
\code m4 = -m4 + m4 + 5 * m4;\endcode same here, Eigen chooses lazy evaluation for all that.
\code m4 = m4 * (m4 + m4);\endcode here Eigen chooses to first evaluate m4 + m4 into a temporary. indeed, here it is an optimization to cache this intermediate result.
\code m3 = m3 * m4.block<3,3>(1,1);\endcode here Eigen chooses \b not to evaluate block() into a temporary because accessing coefficients of that block expression is not more costly than accessing coefficients of a plain matrix.
\code m4 = m4 * m4.transpose();\endcode same here, lazy evaluation of the transpose.
\code m4 = m4 * m4.transpose().eval();\endcode forces immediate evaluation of the transpose
*/ /** \page TutorialGeometry Tutorial 2/3 - Geometry \ingroup Tutorial
\ref index "Overview" | \ref TutorialCore "Core features" | \b Geometry | \ref TutorialAdvancedLinearAlgebra "Advanced linear algebra"
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 top\section TutorialGeoRotations 2D and 3D Rotations \subsection TutorialGeoRotationTypes Rotation types
Rotation typeTypical initialization codeRecommended usage
2D rotation from an angle\code Rotation2D rot2(angle_in_radian);\endcode
2D rotation matrix\code Matrix2f rotmat2 = Rotation2Df(angle_in_radian);\endcode
3D rotation as an angle + axis\code AngleAxis aa(angle_in_radian, Vector3f(ax,ay,az));\endcode
3D rotation as a quaternion\code Quaternion q = AngleAxis(angle_in_radian, axis);\endcode
3D rotation matrix\code Matrix3f rotmat3 = AngleAxis(angle_in_radian, axis);\endcode
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 across 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:
Convertion from and to any types (of same space dimension)\code RotType2 a = RotType1();\endcode
Concatenation of two rotations\code rot3 = rot1 * rot2;\endcode
Apply the rotation to a vector\code vec2 = rot1 * vec1;\endcode
Get the inverse rotation \n (not always the most effient choice)\code rot2 = rot1.inverse();\endcode
Spherical interpolation \n (Rotation2D and Quaternion only)\code rot3 = rot1.slerp(alpha,rot2);\endcode
\subsection TutorialGeoEulerAngles Euler angles
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.\code Matrix3f m; m = AngleAxisf(angle1, Vector3f::UnitZ()) * AngleAxisf(angle2, Vector3f::UnitY()) * AngleAxisf(angle3, Vector3f::UnitZ()); \endcode
top\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.
\b 3D \b 2D
Creation \n rot2D can also be an angle in radian\code Transform3f t; t.fromPositionOrientationScale( pos,any_3D_rotation,Vector3f(sx,sy,sz)); \endcode\code Transform2f t; t.fromPositionOrientationScale( pos,any_2D_rotation,Vector2f(sx,sy)); \endcode
Apply the transformation to a \b point \code Vector3f p1, p2; p2 = t * p1;\endcode\code Vector2f p1, p2; p2 = t * p1;\endcode
Apply the transformation to a \b vector \code Vector3f v1, v2; v2 = t.linear() * v1;\endcode\code Vector2f v1, v2; v2 = t.linear() * v1;\endcode
Concatenate two transformations\code t3 = t1 * t2;\endcode\code t3 = t1 * t2;\endcode
OpenGL compatibility\code glLoadMatrixf(t.data());\endcode\code Transform3f aux(Transform3f::Identity); aux.linear().corner<2,2>(TopLeft) = t.linear(); aux.translation().start<2>() = t.translation(); glLoadMatrixf(aux.data());\endcode
\b Component \b accessors
translation part\code t.translation() = vec3; vec3 = t.translation(); \endcode\code t.translation() = vec2; vec2 = t.translation(); \endcode
linear part\code t.linear() = mat3x3; mat3x3 = t.linear(); \endcode\code t.linear() = mat2x2; mat2x2 = t.linear(); \endcode
\b Editing \b shortcuts
Applies a translation\code t.translate(Vector3f(tx, ty, tz)); t.pretranslate(Vector3f(tx, ty, tz)); \endcode\code t.translate(Vector2f(tx, ty)); t.pretranslate(Vector2f(tx, ty)); \endcode
Applies a rotation \n rot2D can also be an angle in radian\code t.rotate(rot3D); t.prerotate(rot3D); \endcode\code t.rotate(rot2D); t.prerotate(rot2D); \endcode
Applies a scaling\code t.scale(Vector3f(sx, sy, sz)); t.scale(Vector3f::Constant(s)); t.prescale(Vector3f(sx, sy, sz)); \endcode\code t.scale(Vector2f(tx, ty)); t.scale(Vector2f::Constant(s)); t.prescale(Vector2f(tx, ty)); \endcode
Applies a shear transformation \n(2D only)\code t.shear(sx,sy); t.preshear(sx,sy); \endcode
*/ /** \page TutorialAdvancedLinearAlgebra Tutorial 3/3 - Advanced linear algebra \ingroup Tutorial
\ref index "Overview" | \ref TutorialCore "Core features" | \ref TutorialGeometry "Geometry" | \b Advanced \b linear \b algebra
\b Table \b of \b contents - \ref TutorialAdvLinearSolvers - \ref TutorialAdvLU - \ref TutorialAdvCholesky - \ref TutorialAdvQR - \ref TutorialAdvEigenProblems \section TutorialAdvLinearSolvers Solving linear problems todo top\section TutorialAdvLU LU todo top\section TutorialAdvCholesky Cholesky todo top\section TutorialAdvQR QR todo top\section TutorialAdvEigenProblems Eigen value problems todo */ }