[136] | 1 | namespace Eigen {
|
---|
| 2 |
|
---|
| 3 | /** \eigenManualPage TutorialMatrixClass The Matrix class
|
---|
| 4 |
|
---|
| 5 | \eigenAutoToc
|
---|
| 6 |
|
---|
| 7 | In Eigen, all matrices and vectors are objects of the Matrix template class.
|
---|
| 8 | Vectors are just a special case of matrices, with either 1 row or 1 column.
|
---|
| 9 |
|
---|
| 10 | \section TutorialMatrixFirst3Params The first three template parameters of Matrix
|
---|
| 11 |
|
---|
| 12 | The Matrix class takes six template parameters, but for now it's enough to
|
---|
| 13 | learn about the first three first parameters. The three remaining parameters have default
|
---|
| 14 | values, which for now we will leave untouched, and which we
|
---|
| 15 | \ref TutorialMatrixOptTemplParams "discuss below".
|
---|
| 16 |
|
---|
| 17 | The three mandatory template parameters of Matrix are:
|
---|
| 18 | \code
|
---|
| 19 | Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
|
---|
| 20 | \endcode
|
---|
| 21 | \li \c Scalar is the scalar type, i.e. the type of the coefficients.
|
---|
| 22 | That is, if you want a matrix of floats, choose \c float here.
|
---|
| 23 | See \ref TopicScalarTypes "Scalar types" for a list of all supported
|
---|
| 24 | scalar types and for how to extend support to new types.
|
---|
| 25 | \li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows
|
---|
| 26 | and columns of the matrix as known at compile time (see
|
---|
| 27 | \ref TutorialMatrixDynamic "below" for what to do if the number is not
|
---|
| 28 | known at compile time).
|
---|
| 29 |
|
---|
| 30 | We offer a lot of convenience typedefs to cover the usual cases. For example, \c Matrix4f is
|
---|
| 31 | a 4x4 matrix of floats. Here is how it is defined by Eigen:
|
---|
| 32 | \code
|
---|
| 33 | typedef Matrix<float, 4, 4> Matrix4f;
|
---|
| 34 | \endcode
|
---|
| 35 | We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs.
|
---|
| 36 |
|
---|
| 37 | \section TutorialMatrixVectors Vectors
|
---|
| 38 |
|
---|
| 39 | As mentioned above, in Eigen, vectors are just a special case of
|
---|
| 40 | matrices, with either 1 row or 1 column. The case where they have 1 column is the most common;
|
---|
| 41 | such vectors are called column-vectors, often abbreviated as just vectors. In the other case
|
---|
| 42 | where they have 1 row, they are called row-vectors.
|
---|
| 43 |
|
---|
| 44 | For example, the convenience typedef \c Vector3f is a (column) vector of 3 floats. It is defined as follows by Eigen:
|
---|
| 45 | \code
|
---|
| 46 | typedef Matrix<float, 3, 1> Vector3f;
|
---|
| 47 | \endcode
|
---|
| 48 | We also offer convenience typedefs for row-vectors, for example:
|
---|
| 49 | \code
|
---|
| 50 | typedef Matrix<int, 1, 2> RowVector2i;
|
---|
| 51 | \endcode
|
---|
| 52 |
|
---|
| 53 | \section TutorialMatrixDynamic The special value Dynamic
|
---|
| 54 |
|
---|
| 55 | Of course, Eigen is not limited to matrices whose dimensions are known at compile time.
|
---|
| 56 | The \c RowsAtCompileTime and \c ColsAtCompileTime template parameters can take the special
|
---|
| 57 | value \c Dynamic which indicates that the size is unknown at compile time, so must
|
---|
| 58 | be handled as a run-time variable. In Eigen terminology, such a size is referred to as a
|
---|
| 59 | \em dynamic \em size; while a size that is known at compile time is called a
|
---|
| 60 | \em fixed \em size. For example, the convenience typedef \c MatrixXd, meaning
|
---|
| 61 | a matrix of doubles with dynamic size, is defined as follows:
|
---|
| 62 | \code
|
---|
| 63 | typedef Matrix<double, Dynamic, Dynamic> MatrixXd;
|
---|
| 64 | \endcode
|
---|
| 65 | And similarly, we define a self-explanatory typedef \c VectorXi as follows:
|
---|
| 66 | \code
|
---|
| 67 | typedef Matrix<int, Dynamic, 1> VectorXi;
|
---|
| 68 | \endcode
|
---|
| 69 | You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in:
|
---|
| 70 | \code
|
---|
| 71 | Matrix<float, 3, Dynamic>
|
---|
| 72 | \endcode
|
---|
| 73 |
|
---|
| 74 | \section TutorialMatrixConstructors Constructors
|
---|
| 75 |
|
---|
| 76 | A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do:
|
---|
| 77 | \code
|
---|
| 78 | Matrix3f a;
|
---|
| 79 | MatrixXf b;
|
---|
| 80 | \endcode
|
---|
| 81 | Here,
|
---|
| 82 | \li \c a is a 3-by-3 matrix, with a plain float[9] array of uninitialized coefficients,
|
---|
| 83 | \li \c b is a dynamic-size matrix whose size is currently 0-by-0, and whose array of
|
---|
| 84 | coefficients hasn't yet been allocated at all.
|
---|
| 85 |
|
---|
| 86 | Constructors taking sizes are also available. For matrices, the number of rows is always passed first.
|
---|
| 87 | For vectors, just pass the vector size. They allocate the array of coefficients
|
---|
| 88 | with the given size, but don't initialize the coefficients themselves:
|
---|
| 89 | \code
|
---|
| 90 | MatrixXf a(10,15);
|
---|
| 91 | VectorXf b(30);
|
---|
| 92 | \endcode
|
---|
| 93 | Here,
|
---|
| 94 | \li \c a is a 10x15 dynamic-size matrix, with allocated but currently uninitialized coefficients.
|
---|
| 95 | \li \c b is a dynamic-size vector of size 30, with allocated but currently uninitialized coefficients.
|
---|
| 96 |
|
---|
| 97 | In order to offer a uniform API across fixed-size and dynamic-size matrices, it is legal to use these
|
---|
| 98 | constructors on fixed-size matrices, even if passing the sizes is useless in this case. So this is legal:
|
---|
| 99 | \code
|
---|
| 100 | Matrix3f a(3,3);
|
---|
| 101 | \endcode
|
---|
| 102 | and is a no-operation.
|
---|
| 103 |
|
---|
| 104 | Finally, we also offer some constructors to initialize the coefficients of small fixed-size vectors up to size 4:
|
---|
| 105 | \code
|
---|
| 106 | Vector2d a(5.0, 6.0);
|
---|
| 107 | Vector3d b(5.0, 6.0, 7.0);
|
---|
| 108 | Vector4d c(5.0, 6.0, 7.0, 8.0);
|
---|
| 109 | \endcode
|
---|
| 110 |
|
---|
| 111 | \section TutorialMatrixCoeffAccessors Coefficient accessors
|
---|
| 112 |
|
---|
| 113 | The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators.
|
---|
| 114 | For matrices, the row index is always passed first. For vectors, just pass one index.
|
---|
| 115 | The numbering starts at 0. This example is self-explanatory:
|
---|
| 116 |
|
---|
| 117 | <table class="example">
|
---|
| 118 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 119 | <tr><td>
|
---|
| 120 | \include tut_matrix_coefficient_accessors.cpp
|
---|
| 121 | </td>
|
---|
| 122 | <td>
|
---|
| 123 | \verbinclude tut_matrix_coefficient_accessors.out
|
---|
| 124 | </td></tr></table>
|
---|
| 125 |
|
---|
| 126 | Note that the syntax <tt> m(index) </tt>
|
---|
| 127 | is not restricted to vectors, it is also available for general matrices, meaning index-based access
|
---|
| 128 | in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to
|
---|
| 129 | column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders".
|
---|
| 130 |
|
---|
| 131 | The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to
|
---|
| 132 | take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language
|
---|
| 133 | would make matrix[i,j] compile to the same thing as matrix[j] !
|
---|
| 134 |
|
---|
| 135 | \section TutorialMatrixCommaInitializer Comma-initialization
|
---|
| 136 |
|
---|
| 137 | %Matrix and vector coefficients can be conveniently set using the so-called \em comma-initializer syntax.
|
---|
| 138 | For now, it is enough to know this example:
|
---|
| 139 |
|
---|
| 140 | <table class="example">
|
---|
| 141 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 142 | <tr>
|
---|
| 143 | <td>\include Tutorial_commainit_01.cpp </td>
|
---|
| 144 | <td>\verbinclude Tutorial_commainit_01.out </td>
|
---|
| 145 | </tr></table>
|
---|
| 146 |
|
---|
| 147 |
|
---|
| 148 | The right-hand side can also contain matrix expressions as discussed in \ref TutorialAdvancedInitialization "this page".
|
---|
| 149 |
|
---|
| 150 | \section TutorialMatrixSizesResizing Resizing
|
---|
| 151 |
|
---|
| 152 | The current size of a matrix can be retrieved by \link EigenBase::rows() rows()\endlink, \link EigenBase::cols() cols() \endlink and \link EigenBase::size() size()\endlink. These methods return the number of rows, the number of columns and the number of coefficients, respectively. Resizing a dynamic-size matrix is done by the \link PlainObjectBase::resize(Index,Index) resize() \endlink method.
|
---|
| 153 |
|
---|
| 154 | <table class="example">
|
---|
| 155 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 156 | <tr>
|
---|
| 157 | <td>\include tut_matrix_resize.cpp </td>
|
---|
| 158 | <td>\verbinclude tut_matrix_resize.out </td>
|
---|
| 159 | </tr></table>
|
---|
| 160 |
|
---|
| 161 | The resize() method is a no-operation if the actual matrix size doesn't change; otherwise it is destructive: the values of the coefficients may change.
|
---|
| 162 | If you want a conservative variant of resize() which does not change the coefficients, use \link PlainObjectBase::conservativeResize() conservativeResize()\endlink, see \ref TopicResizing "this page" for more details.
|
---|
| 163 |
|
---|
| 164 | All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually
|
---|
| 165 | resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure;
|
---|
| 166 | but the following code is legal:
|
---|
| 167 |
|
---|
| 168 | <table class="example">
|
---|
| 169 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 170 | <tr>
|
---|
| 171 | <td>\include tut_matrix_resize_fixed_size.cpp </td>
|
---|
| 172 | <td>\verbinclude tut_matrix_resize_fixed_size.out </td>
|
---|
| 173 | </tr></table>
|
---|
| 174 |
|
---|
| 175 |
|
---|
| 176 | \section TutorialMatrixAssignment Assignment and resizing
|
---|
| 177 |
|
---|
| 178 | Assignment is the action of copying a matrix into another, using \c operator=. Eigen resizes the matrix on the left-hand side automatically so that it matches the size of the matrix on the right-hand size. For example:
|
---|
| 179 |
|
---|
| 180 | <table class="example">
|
---|
| 181 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 182 | <tr>
|
---|
| 183 | <td>\include tut_matrix_assignment_resizing.cpp </td>
|
---|
| 184 | <td>\verbinclude tut_matrix_assignment_resizing.out </td>
|
---|
| 185 | </tr></table>
|
---|
| 186 |
|
---|
| 187 | Of course, if the left-hand side is of fixed size, resizing it is not allowed.
|
---|
| 188 |
|
---|
| 189 | If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see
|
---|
| 190 | \ref TopicResizing "this page".
|
---|
| 191 |
|
---|
| 192 |
|
---|
| 193 | \section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size
|
---|
| 194 |
|
---|
| 195 | When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)?
|
---|
| 196 | The simple answer is: use fixed
|
---|
| 197 | sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes,
|
---|
| 198 | especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial
|
---|
| 199 | to performance, as it allows Eigen to avoid dynamic memory allocation and to unroll
|
---|
| 200 | loops. Internally, a fixed-size Eigen matrix is just a plain array, i.e. doing
|
---|
| 201 | \code Matrix4f mymatrix; \endcode
|
---|
| 202 | really amounts to just doing
|
---|
| 203 | \code float mymatrix[16]; \endcode
|
---|
| 204 | so this really has zero runtime cost. By contrast, the array of a dynamic-size matrix
|
---|
| 205 | is always allocated on the heap, so doing
|
---|
| 206 | \code MatrixXf mymatrix(rows,columns); \endcode
|
---|
| 207 | amounts to doing
|
---|
| 208 | \code float *mymatrix = new float[rows*columns]; \endcode
|
---|
| 209 | and in addition to that, the MatrixXf object stores its number of rows and columns as
|
---|
| 210 | member variables.
|
---|
| 211 |
|
---|
| 212 | The limitation of using fixed sizes, of course, is that this is only possible
|
---|
| 213 | when you know the sizes at compile time. Also, for large enough sizes, say for sizes
|
---|
| 214 | greater than (roughly) 32, the performance benefit of using fixed sizes becomes negligible.
|
---|
| 215 | Worse, trying to create a very large matrix using fixed sizes inside a function could result in a
|
---|
| 216 | stack overflow, since Eigen will try to allocate the array automatically as a local variable, and
|
---|
| 217 | this is normally done on the stack.
|
---|
| 218 | Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize
|
---|
| 219 | (use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization".
|
---|
| 220 |
|
---|
| 221 | \section TutorialMatrixOptTemplParams Optional template parameters
|
---|
| 222 |
|
---|
| 223 | We mentioned at the beginning of this page that the Matrix class takes six template parameters,
|
---|
| 224 | but so far we only discussed the first three. The remaining three parameters are optional. Here is
|
---|
| 225 | the complete list of template parameters:
|
---|
| 226 | \code
|
---|
| 227 | Matrix<typename Scalar,
|
---|
| 228 | int RowsAtCompileTime,
|
---|
| 229 | int ColsAtCompileTime,
|
---|
| 230 | int Options = 0,
|
---|
| 231 | int MaxRowsAtCompileTime = RowsAtCompileTime,
|
---|
| 232 | int MaxColsAtCompileTime = ColsAtCompileTime>
|
---|
| 233 | \endcode
|
---|
| 234 | \li \c Options is a bit field. Here, we discuss only one bit: \c RowMajor. It specifies that the matrices
|
---|
| 235 | of this type use row-major storage order; by default, the storage order is column-major. See the page on
|
---|
| 236 | \ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices:
|
---|
| 237 | \code
|
---|
| 238 | Matrix<float, 3, 3, RowMajor>
|
---|
| 239 | \endcode
|
---|
| 240 | \li \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime are useful when you want to specify that, even though
|
---|
| 241 | the exact sizes of your matrices are not known at compile time, a fixed upper bound is known at
|
---|
| 242 | compile time. The biggest reason why you might want to do that is to avoid dynamic memory allocation.
|
---|
| 243 | For example the following matrix type uses a plain array of 12 floats, without dynamic memory allocation:
|
---|
| 244 | \code
|
---|
| 245 | Matrix<float, Dynamic, Dynamic, 0, 3, 4>
|
---|
| 246 | \endcode
|
---|
| 247 |
|
---|
| 248 | \section TutorialMatrixTypedefs Convenience typedefs
|
---|
| 249 |
|
---|
| 250 | Eigen defines the following Matrix typedefs:
|
---|
| 251 | \li MatrixNt for Matrix<type, N, N>. For example, MatrixXi for Matrix<int, Dynamic, Dynamic>.
|
---|
| 252 | \li VectorNt for Matrix<type, N, 1>. For example, Vector2f for Matrix<float, 2, 1>.
|
---|
| 253 | \li RowVectorNt for Matrix<type, 1, N>. For example, RowVector3d for Matrix<double, 1, 3>.
|
---|
| 254 |
|
---|
| 255 | Where:
|
---|
| 256 | \li N can be any one of \c 2, \c 3, \c 4, or \c X (meaning \c Dynamic).
|
---|
| 257 | \li t can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double),
|
---|
| 258 | \c cf (meaning complex<float>), or \c cd (meaning complex<double>). The fact that typedefs are only
|
---|
| 259 | defined for these five types doesn't mean that they are the only supported scalar types. For example,
|
---|
| 260 | all standard integer types are supported, see \ref TopicScalarTypes "Scalar types".
|
---|
| 261 |
|
---|
| 262 |
|
---|
| 263 | */
|
---|
| 264 |
|
---|
| 265 | }
|
---|