diff options
author | Yi Kong <yikong@google.com> | 2022-02-25 17:02:53 +0000 |
---|---|---|
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | 2022-02-25 17:02:53 +0000 |
commit | edb0ad5bb04b48aab7dd0978f0475edd3550de7c (patch) | |
tree | fb979fb4cf4f8052c8cc66b1ec9516d91fcd859b /doc/TutorialReshape.dox | |
parent | 8fd413e275f78a4c240f1442ce5cf77c73a20a55 (diff) | |
parent | bc0f5df265caa21a2120c22453655a7fcc941991 (diff) | |
download | eigen-7ecd5586f9218fe07c97ede8e405561aca973d78.tar.gz |
Merge changes Iee153445,Iee274471 am: 79df15ea88 am: 10f298fc41 am: 7cb5001398 am: bc0f5df265aml_uwb_331910010aml_uwb_331820070aml_uwb_331613010aml_uwb_331611010aml_uwb_331410010aml_uwb_331310030aml_uwb_331115000aml_uwb_331015040aml_uwb_330810010aml_tz4_332714070aml_tz4_332714050aml_tz4_332714010aml_tz4_331910000aml_tz4_331314030aml_tz4_331314020aml_tz4_331314010aml_tz4_331012050aml_tz4_331012040aml_tz4_331012000aml_ase_331311020aml_ase_331112000aml_ase_331011020android13-mainline-uwb-releaseandroid13-mainline-tzdata4-releaseandroid13-mainline-appsearch-releaseaml_tz4_332714010
Original change: https://android-review.googlesource.com/c/platform/external/eigen/+/1999079
Change-Id: Ife39d10c8b23d3eeb174cd52f462f9d20527ad03
Diffstat (limited to 'doc/TutorialReshape.dox')
-rw-r--r-- | doc/TutorialReshape.dox | 82 |
1 files changed, 82 insertions, 0 deletions
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 <i> view </i> 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: + +<table class="example"> +<tr><th>Example:</th><th>Output:</th></tr> +<tr><td> +\include MatrixBase_reshaped_int_int.cpp +</td> +<td> +\verbinclude MatrixBase_reshaped_int_int.out +</td></tr></table> + +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: + +<table class="example"> +<tr><th>Example:</th></tr> +<tr><td> +\include MatrixBase_reshaped_to_vector.cpp +</td></tr> +<tr><th>Output:</th></tr> +<tr><td> +\verbinclude MatrixBase_reshaped_to_vector.out +</td></tr></table> + +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): + +<table class="example"> +<tr><th>Example:</th></tr> +<tr><td> +\include Tutorial_reshaped_vs_resize_1.cpp +</td></tr> +<tr><th>Output:</th></tr> +<tr><td> +\verbinclude Tutorial_reshaped_vs_resize_1.out +</td></tr></table> + +However beware that unlike \c reshaped, the result of \c resize depends on the input storage order. +It thus behaves similarly to `reshaped<AutoOrder>`: + +<table class="example"> +<tr><th>Example:</th></tr> +<tr><td> +\include Tutorial_reshaped_vs_resize_2.cpp +</td></tr> +<tr><th>Output:</th></tr> +<tr><td> +\verbinclude Tutorial_reshaped_vs_resize_2.out +</td></tr></table> + +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 + +*/ + +} |