blob: 7ea0cd789b7f35400caf0d2a2a919d8087d3e5bf [file] [log] [blame]
 namespace Eigen { /** \eigenManualPage TutorialMatrixClass The Matrix class \eigenAutoToc In Eigen, all matrices and vectors are objects of the Matrix template class. Vectors are just a special case of matrices, with either 1 row or 1 column. \section TutorialMatrixFirst3Params The first three template parameters of Matrix The Matrix class takes six template parameters, but for now it's enough to learn about the first three first parameters. The three remaining parameters have default values, which for now we will leave untouched, and which we \ref TutorialMatrixOptTemplParams "discuss below". The three mandatory template parameters of Matrix are: \code Matrix \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. See \ref TopicScalarTypes "Scalar types" for a list of all supported 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 (see \ref TutorialMatrixDynamic "below" for what to do if the number is not 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 Matrix4f; \endcode We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs. \section TutorialMatrixVectors Vectors 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 a (column) vector of 3 floats. It is defined as follows by Eigen: \code typedef Matrix Vector3f; \endcode We also offer convenience typedefs for row-vectors, for example: \code typedef Matrix RowVector2i; \endcode \section TutorialMatrixDynamic The special value Dynamic Of course, Eigen is not limited to matrices whose dimensions are known at compile time. The \c RowsAtCompileTime and \c ColsAtCompileTime template parameters 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 MatrixXd; \endcode And similarly, we define a self-explanatory typedef \c VectorXi as follows: \code typedef Matrix VectorXi; \endcode You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in: \code Matrix \endcode \section TutorialMatrixConstructors Constructors A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do: \code Matrix3f a; MatrixXf b; \endcode Here, \li \c a is a 3-by-3 matrix, with a plain float[9] array of uninitialized coefficients, \li \c b is a dynamic-size matrix whose size is currently 0-by-0, 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 \section TutorialMatrixCoeffAccessors Coefficient accessors 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:
Example:Output:
\include tut_matrix_coefficient_accessors.cpp \verbinclude tut_matrix_coefficient_accessors.out
Note that the syntax m(index) 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 column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders". 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] ! \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:
Example:Output:
\include Tutorial_commainit_01.cpp \verbinclude Tutorial_commainit_01.out