2010-06-25 22:04:35 +08:00
|
|
|
namespace Eigen {
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
/** \page TutorialMatrixClass Tutorial page 1 - the %Matrix class
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
\ingroup Tutorial
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\li \b Previous: \ref GettingStarted
|
|
|
|
\li \b Next: \ref TutorialMatrixArithmetic
|
|
|
|
|
2010-06-28 02:21:12 +08:00
|
|
|
We assume that you have already read the quick \link GettingStarted "getting started" \endlink tutorial.
|
2010-06-25 22:04:35 +08:00
|
|
|
This page is the first one in a much longer multi-page tutorial.
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\b Table \b of \b contents
|
|
|
|
- \ref TutorialMatrixFirst3Params
|
|
|
|
- \ref TutorialMatrixVectors
|
|
|
|
- \ref TutorialMatrixDynamic
|
|
|
|
- \ref TutorialMatrixConstructors
|
|
|
|
- \ref TutorialMatrixCoeffAccessors
|
2010-06-28 06:22:47 +08:00
|
|
|
- \ref TutorialMatrixCommaInitializer
|
2010-06-27 02:00:00 +08:00
|
|
|
- \ref TutorialMatrixSizesResizing
|
|
|
|
- \ref TutorialMatrixAssignment
|
|
|
|
- \ref TutorialMatrixFixedVsDynamic
|
|
|
|
- \ref TutorialMatrixOptTemplParams
|
|
|
|
- \ref TutorialMatrixTypedefs
|
|
|
|
|
2010-06-25 22:04:35 +08:00
|
|
|
In Eigen, all matrices and vectors are object of the Matrix class.
|
|
|
|
Vectors are just a special case of matrices, with either 1 row or 1 column.
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixFirst3Params The first 3 template parameters of Matrix
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
The Matrix class takes 6 template parameters, but for now it's enough to
|
|
|
|
learn about the 3 first parameters. The 3 remaining parameters have default
|
|
|
|
values, which for now we will leave untouched, and which we
|
2010-06-27 02:00:00 +08:00
|
|
|
\ref TutorialMatrixOptTemplParams "discuss below".
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
The 3 mandatory template parameters of Matrix are:
|
|
|
|
\code
|
|
|
|
Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
|
|
|
|
\endcode
|
|
|
|
\li \c Scalar is the scalar type, i.e. the type of the coefficients.
|
|
|
|
That is, if you want a matrix of floats, choose \c float here.
|
2010-06-27 02:00:00 +08:00
|
|
|
See \ref TopicScalarTypes "Scalar types" for a list of all supported
|
2010-06-25 22:04:35 +08:00
|
|
|
scalar types and for how to extend support to new types.
|
|
|
|
\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows
|
|
|
|
and columns of the matrix as known at compile-time.
|
|
|
|
|
|
|
|
We offer a lot of convenience typedefs to cover the usual cases. For example, \c Matrix4f is
|
|
|
|
a 4x4 matrix of floats. Here is how it is defined by Eigen:
|
|
|
|
\code
|
|
|
|
typedef Matrix<float,4,4> Matrix4f;
|
|
|
|
\endcode
|
2010-06-27 02:00:00 +08:00
|
|
|
We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs.
|
2010-06-25 22:04:35 +08:00
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixVectors Vectors
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
As mentioned above, in Eigen, vectors are just a special case of
|
|
|
|
matrices, with either 1 row or 1 column. The case where they have 1 column is the most common;
|
|
|
|
such vectors are called column-vectors, often abbreviated as just vectors. In the other case
|
|
|
|
where they have 1 row, they are called row-vectors.
|
|
|
|
|
|
|
|
For example, the convenience typedef \c Vector3f is defined as follows by Eigen:
|
|
|
|
\code
|
|
|
|
typedef Matrix<float, 3, 1> Vector3f;
|
|
|
|
\endcode
|
|
|
|
and we also offer convenience typedefs for row-vectors, for example:
|
|
|
|
\code
|
|
|
|
typedef Matrix<int, 1, 2> RowVector2i;
|
|
|
|
\endcode
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixDynamic The special value Dynamic
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
Of course, Eigen is not limited to matrices whose dimensions are known at compile time.
|
|
|
|
The above-discussed \c RowsAtCompileTime and \c ColsAtCompileTime can take the special
|
|
|
|
value \c Dynamic which indicates that the size is unknown at compile time, so must
|
|
|
|
be handled as a run time variable. In Eigen terminology, such a size is referred to as a
|
|
|
|
\em dynamic \em size; while a size that is known at compile time is called a
|
|
|
|
\em fixed \em size. For example, the convenience typedef \c MatrixXd, meaning
|
|
|
|
a matrix of doubles with dynamic size, is defined as follows:
|
|
|
|
\code
|
|
|
|
typedef Matrix<double,Dynamic,Dynamic> MatrixXd;
|
|
|
|
\endcode
|
|
|
|
And similarly, we define a self-explanatory typedef \c VectorXi as follows:
|
|
|
|
\code
|
|
|
|
typedef Matrix<int,Dynamic,1> VectorXi;
|
|
|
|
\endcode
|
|
|
|
You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in:
|
|
|
|
\code
|
|
|
|
Matrix<float, 3, Dynamic>
|
|
|
|
\endcode
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixConstructors Constructors
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
A default constructor is always available, and always has zero runtime cost. You can do:
|
|
|
|
\code
|
|
|
|
Matrix3f a;
|
|
|
|
MatrixXf b;
|
|
|
|
\endcode
|
|
|
|
Here,
|
|
|
|
\li \c a is a 3x3 matrix, with a static float[9] array of uninitialized coefficients,
|
|
|
|
\li \c b is a dynamic-size matrix whose size is currently 0x0, and whose array of
|
|
|
|
coefficients hasn't yet been allocated at all.
|
|
|
|
|
|
|
|
Constructors taking sizes are also available. For matrices, the number of rows is always passed first.
|
|
|
|
For vectors, just pass the vector size. They allocate the array of coefficients
|
|
|
|
with the given size, but don't initialize the coefficients themselves:
|
|
|
|
\code
|
|
|
|
MatrixXf a(10,15);
|
|
|
|
VectorXf b(30);
|
|
|
|
\endcode
|
|
|
|
Here,
|
|
|
|
\li \c a is a 10x15 dynamic-size matrix, with allocated but currently uninitialized coefficients.
|
|
|
|
\li \c b is a dynamic-size vector of size 30, with allocated but currently uninitialized coefficients.
|
|
|
|
|
|
|
|
In order to offer a uniform API across fixed-size and dynamic-size matrices, it is legal to use these
|
|
|
|
constructors on fixed-size matrices, even if passing the sizes is useless in this case. So this is legal:
|
|
|
|
\code
|
|
|
|
Matrix3f a(3,3);
|
|
|
|
\endcode
|
|
|
|
and is a no-operation.
|
|
|
|
|
|
|
|
Finally, we also offer some constructors to initialize the coefficients of small fixed-size vectors up to size 4:
|
|
|
|
\code
|
|
|
|
Vector2d a(5.0, 6.0);
|
|
|
|
Vector3d b(5.0, 6.0, 7.0);
|
|
|
|
Vector4d c(5.0, 6.0, 7.0, 8.0);
|
|
|
|
\endcode
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixCoeffAccessors Coefficient accessors
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators.
|
|
|
|
For matrices, the row index is always passed first. For vectors, just pass one index.
|
|
|
|
The numbering starts at 0. This example is self-explanatory:
|
|
|
|
\include tut_matrix_coefficient_accessors.cpp
|
|
|
|
Output: \verbinclude tut_matrix_coefficient_accessors.out
|
|
|
|
|
|
|
|
Note that the syntax
|
|
|
|
\code
|
|
|
|
m(index)
|
|
|
|
\endcode
|
|
|
|
is not restricted to vectors, it is also available for general matrices, meaning index-based access
|
|
|
|
in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to
|
2010-06-27 02:00:00 +08:00
|
|
|
column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders".
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to
|
|
|
|
take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language
|
|
|
|
would make matrix[i,j] compile to the same thing as matrix[j] !
|
|
|
|
|
2010-06-28 06:22:47 +08:00
|
|
|
\section TutorialMatrixCommaInitializer Comma-initialization
|
|
|
|
|
|
|
|
Matrix and vector coefficients can be conveniently set using the so-called \em comma-initializer syntax.
|
|
|
|
For now, it is enough to know this example:
|
|
|
|
\include Tutorial_commainit_01.cpp
|
|
|
|
Output: \verbinclude Tutorial_commainit_01.out
|
|
|
|
The right hand side can also contains matrix expressions as discussed in \ref TutorialAdvancedInitialization "this page".
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixSizesResizing Resizing
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
The current sizes can be retrieved by rows(), cols() and size(). Resizing a dynamic-size matrix is done by the resize() method.
|
|
|
|
For example: \include tut_matrix_resize.cpp
|
|
|
|
Output: \verbinclude tut_matrix_resize.out
|
|
|
|
|
|
|
|
The resize() method is a no-operation if the actual array size doesn't change; otherwise it is destructive.
|
2010-06-27 02:00:00 +08:00
|
|
|
If you want a conservative variant of resize(), use conservativeResize(), see \ref TopicResizing "this page" for more details.
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually
|
|
|
|
resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure;
|
|
|
|
but the following code is legal:
|
|
|
|
\include tut_matrix_resize_fixed_size.cpp
|
|
|
|
Output: \verbinclude tut_matrix_resize_fixed_size.out
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixAssignment Assignment and resizing
|
|
|
|
|
|
|
|
Assignment is the action of copying a matrix into another, using \c operator=. The only non-obvious thing to know here, is that
|
|
|
|
Eigen does automatic resizing of the left hand side to match the right hand side's size. For example:
|
|
|
|
\include tut_matrix_assignment_resizing.cpp
|
|
|
|
Output: \verbinclude tut_matrix_assignment_resizing.out
|
|
|
|
|
|
|
|
Of course, if the left hand side is of fixed size, resizing it is not allowed.
|
2010-06-25 22:04:35 +08:00
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see
|
|
|
|
\ref TopicResizing "this page".
|
|
|
|
|
|
|
|
|
|
|
|
\section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size
|
|
|
|
|
|
|
|
When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)?
|
2010-06-25 22:04:35 +08:00
|
|
|
The simple answer is: use fixed
|
|
|
|
sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes,
|
|
|
|
especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial
|
|
|
|
to performance, as it allows Eigen to avoid dynamic memory allocation and to unroll
|
|
|
|
loops. Internally, a fixed-size Eigen matrix is just a plain static array, i.e. doing
|
|
|
|
\code Matrix4f mymatrix; \endcode
|
|
|
|
really amounts to just doing
|
|
|
|
\code float mymatrix[16]; \endcode
|
|
|
|
so this really has zero runtime cost. By constrast, the array of a dynamic-size matrix
|
|
|
|
is always allocated on the heap, so doing
|
|
|
|
\code MatrixXf mymatrix(rows,columns); \endcode
|
|
|
|
amounts to doing
|
|
|
|
\code float *mymatrix = new float[rows*columns]; \endcode
|
|
|
|
and in addition to that, the MatrixXf object stores its number of rows and columns as
|
|
|
|
member variables.
|
|
|
|
|
|
|
|
The limitation of using fixed sizes, of course, is that this is only possible
|
|
|
|
when you know the sizes at compile time. Also, for large enough sizes, say for sizes
|
|
|
|
greater than (roughly) 32, the performance benefit of using fixed sizes becomes negligible.
|
|
|
|
Worse, trying to create a very large matrix using fixed sizes could result in a stack overflow,
|
|
|
|
since Eigen will try to allocate the array as a static array, which by default goes on the stack.
|
|
|
|
Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize
|
2010-06-27 02:00:00 +08:00
|
|
|
(use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization".
|
2010-06-25 22:04:35 +08:00
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixOptTemplParams Optional template parameters
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
We mentioned at the beginning of this page that the Matrix class takes 6 template parameters,
|
|
|
|
but so far we only discussed the first 3. The remaining 3 parameters are optional. Here is
|
|
|
|
the complete list of template parameters:
|
|
|
|
\code
|
|
|
|
Matrix<typename Scalar,
|
|
|
|
int RowsAtCompileTime,
|
|
|
|
int ColsAtCompileTime,
|
|
|
|
int Options = 0,
|
|
|
|
int MaxRowsAtCompileTime = RowsAtCompileTime,
|
|
|
|
int MaxColsAtCompileTime = ColsAtCompileTime>
|
|
|
|
\endcode
|
|
|
|
\li \c Options is a bit field; let us only mention here one bit: \c RowMajor. It specifies that the matrices
|
|
|
|
of this type use row-major storage order; the default is column-major. See the page on
|
2010-06-27 02:00:00 +08:00
|
|
|
\ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices:
|
2010-06-25 22:04:35 +08:00
|
|
|
\code
|
|
|
|
Matrix<float,3,3,RowMajor>
|
|
|
|
\endcode
|
|
|
|
\li \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime are useful when you want to specify that, even though
|
|
|
|
the exact sizes of your matrices are unknown at compile time, a fixed upper bound is known at
|
|
|
|
compile time. The biggest reason why you might want to do that is to avoid dynamic memory allocation.
|
|
|
|
For example the following matrix type uses a static array of 12 floats, without dynamic memory allocation:
|
|
|
|
\code
|
|
|
|
Matrix<float,Dynamic,Dynamic,0,3,4>
|
|
|
|
\endcode
|
|
|
|
|
2010-06-27 02:00:00 +08:00
|
|
|
\section TutorialMatrixTypedefs Convenience typedefs
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
Eigen defines the following Matrix typedefs:
|
|
|
|
\li MatrixNT for Matrix<T, N, N>. For example, MatrixXi for Matrix<int, Dynamic, Dynamic>.
|
|
|
|
\li VectorNT for Matrix<T, N, 1>. For example, Vector2f for Matrix<float, 2, 1>.
|
|
|
|
\li MatrixNT for Matrix<T, 1, N>. For example, RowVector3d for Matrix<double, 1, 3>.
|
|
|
|
|
|
|
|
Where:
|
|
|
|
\li N can be any one of \c 2,\c 3,\c 4, or \c Dynamic.
|
|
|
|
\li T can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double),
|
|
|
|
\c cf (meaning complex<float>), or \c cd (meaning complex<double>). The fact that typedefs are only
|
|
|
|
defined for these 5 types doesn't mean that they are the only supported scalar types. For example,
|
2010-06-27 02:00:00 +08:00
|
|
|
all standard integer types are supported, see \ref TopicScalarTypes "Scalar types".
|
|
|
|
|
|
|
|
\li \b Next: \ref TutorialMatrixArithmetic
|
2010-06-25 22:04:35 +08:00
|
|
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
}
|