From d7c644213cbf548f67aeb7ed6f872aef96c1dbd2 Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Fri, 9 Nov 2018 11:35:27 +0100 Subject: Add and update manual pages for slicing, indexing, and reshaping. --- doc/TutorialReshape.dox | 82 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 doc/TutorialReshape.dox (limited to 'doc/TutorialReshape.dox') diff --git a/doc/TutorialReshape.dox b/doc/TutorialReshape.dox new file mode 100644 index 000000000..5b4022a3b --- /dev/null +++ b/doc/TutorialReshape.dox @@ -0,0 +1,82 @@ +namespace Eigen { + +/** \eigenManualPage TutorialReshape Reshape + +Since the version 3.4, %Eigen exposes convenient methods to reshape a matrix to another matrix of different sizes or vector. +All cases are handled via the DenseBase::reshaped(NRowsType,NColsType) and DenseBase::reshaped() functions. +Those functions do not perform in-place reshaping, but instead return a view on the input expression. + +\eigenAutoToc + +\section TutorialReshapeMat2Mat Reshaped 2D views + +The more general reshaping transformation is handled via: `reshaped(nrows,ncols)`. +Here is an example reshaping a 4x4 matrix to a 2x8 one: + + + + +
Example:Output:
+\include MatrixBase_reshaped_int_int.cpp + +\verbinclude MatrixBase_reshaped_int_int.out +
+ +By default, the input coefficients are always interpreted in column-major order regardless of the storage order of the input expression. +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. + + +\section TutorialReshapeMat2Vec 1D linear views + +A very common usage of reshaping is to create a 1D linear view over a given 2D matrix or expression. +In this case, sizes can be deduced and thus omitted as in the following example: + + + + + +
Example:
+\include MatrixBase_reshaped_to_vector.cpp +
Output:
+\verbinclude MatrixBase_reshaped_to_vector.out +
+ +This shortcut always returns a column vector and by default input coefficients are always interpreted in column-major order. +Again, see the documentation of DenseBase::reshaped() for more control on the ordering. + +\section TutorialReshapeInPlace + +The above examples create reshaped views, but what about reshaping inplace a given matrix? +Of course this task in only conceivable for matrix and arrays having runtime dimensions. +In many cases, this can be accomplished via PlainObjectBase::resize(Index,Index): + + + + + +
Example:
+\include Tutorial_reshaped_vs_resize_1.cpp +
Output:
+\verbinclude Tutorial_reshaped_vs_resize_1.out +
+ +However beware that unlike \c reshaped, the result of \c resize depends on the input storage order. +It thus behaves similarly to `reshaped`: + + + + + +
Example:
+\include Tutorial_reshaped_vs_resize_2.cpp +
Output:
+\verbinclude Tutorial_reshaped_vs_resize_2.out +
+ +Finally, assigning a reshaped matrix to itself is currently not supported and will result to undefined-behavior because of \link TopicAliasing aliasing \endlink. +The following is forbidden: \code A = A.reshaped(2,8); \endcode +This is OK: \code A = A.reshaped(2,8).eval(); \endcode + +*/ + +} -- cgit v1.2.3