From 010afe1619c9200b885f74d3c3937e000ec76b1d Mon Sep 17 00:00:00 2001
From: Gael Guennebaud <g.gael@free.fr>
Date: Sat, 6 Feb 2016 22:49:18 +0100
Subject: Add exemples for reshaping/slicing with Map.

---
 doc/Manual.dox                           |  2 +
 doc/TutorialReshapeSlicing.dox           | 65 ++++++++++++++++++++++++++++++++
 doc/snippets/Tutorial_ReshapeMat2Mat.cpp |  6 +++
 doc/snippets/Tutorial_ReshapeMat2Vec.cpp | 11 ++++++
 doc/snippets/Tutorial_SlicingCol.cpp     | 11 ++++++
 doc/snippets/Tutorial_SlicingVec.cpp     |  4 ++
 6 files changed, 99 insertions(+)
 create mode 100644 doc/TutorialReshapeSlicing.dox
 create mode 100644 doc/snippets/Tutorial_ReshapeMat2Mat.cpp
 create mode 100644 doc/snippets/Tutorial_ReshapeMat2Vec.cpp
 create mode 100644 doc/snippets/Tutorial_SlicingCol.cpp
 create mode 100644 doc/snippets/Tutorial_SlicingVec.cpp

(limited to 'doc')

diff --git a/doc/Manual.dox b/doc/Manual.dox
index c10c490a7..70aaa9a42 100644
--- a/doc/Manual.dox
+++ b/doc/Manual.dox
@@ -59,6 +59,8 @@ namespace Eigen {
     \ingroup DenseMatrixManipulation_chapter */
 /** \addtogroup TutorialMapClass
     \ingroup DenseMatrixManipulation_chapter */
+/** \addtogroup TutorialReshapeSlicing
+    \ingroup DenseMatrixManipulation_chapter */
 /** \addtogroup TopicAliasing
     \ingroup DenseMatrixManipulation_chapter */
 /** \addtogroup TopicStorageOrders
diff --git a/doc/TutorialReshapeSlicing.dox b/doc/TutorialReshapeSlicing.dox
new file mode 100644
index 000000000..eb0fb0df0
--- /dev/null
+++ b/doc/TutorialReshapeSlicing.dox
@@ -0,0 +1,65 @@
+namespace Eigen {
+
+/** \eigenManualPage TutorialReshapeSlicing Reshape and Slicing
+
+%Eigen does not expose convenient methods to take slices or to reshape a matrix yet.
+Nonetheless, such features can easily be emulated using the Map class.
+
+\eigenAutoToc
+
+\section TutorialReshape Reshape
+
+A reshape operation consists in modifying the sizes of a matrix while keeping the same coefficients.
+Instead of modifying the input matrix itself, which is not possible for compile-time sizes, the approach consist in creating a different \em view on the storage using class Map.
+Here is a typical example creating a 1D linear view of a matrix:
+
+<table class="example">
+<tr><th>Example:</th><th>Output:</th></tr>
+<tr><td>
+\include Tutorial_ReshapeMat2Vec.cpp
+</td>
+<td>
+\verbinclude Tutorial_ReshapeMat2Vec.out
+</td></tr></table>
+
+Remark how the storage order of the input matrix modifies the order of the coefficients in the linear view.
+Here is another example reshaping a 2x6 matrix to a 6x2 one:
+<table class="example">
+<tr><th>Example:</th><th>Output:</th></tr>
+<tr><td>
+\include Tutorial_ReshapeMat2Mat.cpp
+</td>
+<td>
+\verbinclude Tutorial_ReshapeMat2Mat.out
+</td></tr></table>
+
+
+
+\section TutorialSlicing Slicing
+
+Slicing consists in taking a set of rows, or columns, or elements, uniformly spaced within a matrix.
+Again, the class Map allows to easily mimic this feature.
+
+For instance, one can take skip every P elements in a vector:
+<table class="example">
+<tr><th>Example:</th><th>Output:</th></tr>
+<tr><td>
+\include Tutorial_SlicingVec.cpp
+</td>
+<td>
+\verbinclude Tutorial_SlicingVec.out
+</td></tr></table>
+
+One can olso take one column over three using an adequate outer-stride or inner-stride depending on the actual storage order:
+<table class="example">
+<tr><th>Example:</th><th>Output:</th></tr>
+<tr><td>
+\include Tutorial_SlicingCol.cpp
+</td>
+<td>
+\verbinclude Tutorial_SlicingCol.out
+</td></tr></table>
+
+*/
+
+}
diff --git a/doc/snippets/Tutorial_ReshapeMat2Mat.cpp b/doc/snippets/Tutorial_ReshapeMat2Mat.cpp
new file mode 100644
index 000000000..f84d6e76d
--- /dev/null
+++ b/doc/snippets/Tutorial_ReshapeMat2Mat.cpp
@@ -0,0 +1,6 @@
+MatrixXf M1(2,6);    // Column-major storage
+M1 << 1, 2, 3,  4,  5,  6,
+      7, 8, 9, 10, 11, 12;
+
+Map<MatrixXf> M2(M1.data(), 6,2);
+cout << "M2:" << endl << M2 << endl;
\ No newline at end of file
diff --git a/doc/snippets/Tutorial_ReshapeMat2Vec.cpp b/doc/snippets/Tutorial_ReshapeMat2Vec.cpp
new file mode 100644
index 000000000..95bd4e0e6
--- /dev/null
+++ b/doc/snippets/Tutorial_ReshapeMat2Vec.cpp
@@ -0,0 +1,11 @@
+MatrixXf M1(3,3);    // Column-major storage
+M1 << 1, 2, 3,
+      4, 5, 6,
+      7, 8, 9;
+
+Map<RowVectorXf> v1(M1.data(), M1.size());
+cout << "v1:" << endl << v1 << endl;
+
+Matrix<float,Dynamic,Dynamic,RowMajor> M2(M1);
+Map<RowVectorXf> v2(M2.data(), M2.size());
+cout << "v2:" << endl << v2 << endl;
\ No newline at end of file
diff --git a/doc/snippets/Tutorial_SlicingCol.cpp b/doc/snippets/Tutorial_SlicingCol.cpp
new file mode 100644
index 000000000..f667ff689
--- /dev/null
+++ b/doc/snippets/Tutorial_SlicingCol.cpp
@@ -0,0 +1,11 @@
+MatrixXf M1 = MatrixXf::Random(3,8);
+cout << "Column major input:" << endl << M1 << "\n";
+Map<MatrixXf,0,OuterStride<> > M2(M1.data(), M1.rows(), (M1.cols()+2)/3, OuterStride<>(M1.outerStride()*3));
+cout << "1 column over 3:" << endl << M2 << "\n";
+
+typedef Matrix<float,Dynamic,Dynamic,RowMajor> RowMajorMatrixXf;
+RowMajorMatrixXf M3(M1);
+cout << "Row major input:" << endl << M3 << "\n";
+Map<RowMajorMatrixXf,0,Stride<Dynamic,3> > M4(M3.data(), M3.rows(), (M3.cols()+2)/3,
+                                              Stride<Dynamic,3>(M3.outerStride(),3));
+cout << "1 column over 3:" << endl << M4 << "\n";
\ No newline at end of file
diff --git a/doc/snippets/Tutorial_SlicingVec.cpp b/doc/snippets/Tutorial_SlicingVec.cpp
new file mode 100644
index 000000000..07e10bf69
--- /dev/null
+++ b/doc/snippets/Tutorial_SlicingVec.cpp
@@ -0,0 +1,4 @@
+RowVectorXf v = RowVectorXf::LinSpaced(20,0,19);
+cout << "Input:" << endl << v << endl;
+Map<RowVectorXf,0,InnerStride<2> > v2(v.data(), v.size()/2);
+cout << "Even:" << v2 << endl;
\ No newline at end of file
-- 
cgit v1.2.3