TutorialReshape.dox (2981B)
1 namespace Eigen { 2 3 /** \eigenManualPage TutorialReshape Reshape 4 5 Since the version 3.4, %Eigen exposes convenient methods to reshape a matrix to another matrix of different sizes or vector. 6 All cases are handled via the DenseBase::reshaped(NRowsType,NColsType) and DenseBase::reshaped() functions. 7 Those functions do not perform in-place reshaping, but instead return a <i> view </i> on the input expression. 8 9 \eigenAutoToc 10 11 \section TutorialReshapeMat2Mat Reshaped 2D views 12 13 The more general reshaping transformation is handled via: `reshaped(nrows,ncols)`. 14 Here is an example reshaping a 4x4 matrix to a 2x8 one: 15 16 <table class="example"> 17 <tr><th>Example:</th><th>Output:</th></tr> 18 <tr><td> 19 \include MatrixBase_reshaped_int_int.cpp 20 </td> 21 <td> 22 \verbinclude MatrixBase_reshaped_int_int.out 23 </td></tr></table> 24 25 By default, the input coefficients are always interpreted in column-major order regardless of the storage order of the input expression. 26 For more control on ordering, compile-time sizes, and automatic size deduction, please see de documentation of DenseBase::reshaped(NRowsType,NColsType) that contains all the details with many examples. 27 28 29 \section TutorialReshapeMat2Vec 1D linear views 30 31 A very common usage of reshaping is to create a 1D linear view over a given 2D matrix or expression. 32 In this case, sizes can be deduced and thus omitted as in the following example: 33 34 <table class="example"> 35 <tr><th>Example:</th></tr> 36 <tr><td> 37 \include MatrixBase_reshaped_to_vector.cpp 38 </td></tr> 39 <tr><th>Output:</th></tr> 40 <tr><td> 41 \verbinclude MatrixBase_reshaped_to_vector.out 42 </td></tr></table> 43 44 This shortcut always returns a column vector and by default input coefficients are always interpreted in column-major order. 45 Again, see the documentation of DenseBase::reshaped() for more control on the ordering. 46 47 \section TutorialReshapeInPlace 48 49 The above examples create reshaped views, but what about reshaping inplace a given matrix? 50 Of course this task in only conceivable for matrix and arrays having runtime dimensions. 51 In many cases, this can be accomplished via PlainObjectBase::resize(Index,Index): 52 53 <table class="example"> 54 <tr><th>Example:</th></tr> 55 <tr><td> 56 \include Tutorial_reshaped_vs_resize_1.cpp 57 </td></tr> 58 <tr><th>Output:</th></tr> 59 <tr><td> 60 \verbinclude Tutorial_reshaped_vs_resize_1.out 61 </td></tr></table> 62 63 However beware that unlike \c reshaped, the result of \c resize depends on the input storage order. 64 It thus behaves similarly to `reshaped<AutoOrder>`: 65 66 <table class="example"> 67 <tr><th>Example:</th></tr> 68 <tr><td> 69 \include Tutorial_reshaped_vs_resize_2.cpp 70 </td></tr> 71 <tr><th>Output:</th></tr> 72 <tr><td> 73 \verbinclude Tutorial_reshaped_vs_resize_2.out 74 </td></tr></table> 75 76 Finally, assigning a reshaped matrix to itself is currently not supported and will result to undefined-behavior because of \link TopicAliasing aliasing \endlink. 77 The following is forbidden: \code A = A.reshaped(2,8); \endcode 78 This is OK: \code A = A.reshaped(2,8).eval(); \endcode 79 80 */ 81 82 }