1%%%%%%%%%%%%%%%%%%%
2% XLiFE++ is an extended library of finite elements written in C++
3% Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
4%
5% This program is free software: you can redistribute it and/or modify
6% it under the terms of the GNU General Public License as published by
7% the Free Software Foundation, either version 3 of the License, or
8% (at your option) any later version.
9% This program is distributed in the hope that it will be useful,
10% but WITHOUT ANY WARRANTY; without even the implied warranty of
11% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12% GNU General Public License for more details.
13% You should have received a copy of the GNU General Public License
14% along with this program.  If not, see <http://www.gnu.org/licenses/>.
15%%%%%%%%%%%%%%%%%%%
16
17\xlifepp allows you to apply geometrical transformations on {\class Mesh},  {\class Geometry} and {\class Geometry} children objects. The main type is {\class Transformation}. It can be a canonical transformation or a composition of transformations.
18
19\subsection{Canonical transformations}
20
21In the following, we will consider straight lines and planes.
22
23A straight line is fully defined by a point and a direction. The latter is a vector of components (2 or 3). This is a reason why we will write a straight line as follows : $\left(\Omega, \vec{d}\right)$
24
25A plane is fully defined by a point and a normal vector. This is a reason why we will write a plane as follows : $\left[\Omega, \vec{n}\right]$
26
27\subsubsection{Translations}
28
29Point B is the image of point A by a translation of vector $\vec{u}$ if and only if
30$$
31\overrightarrow{AB}=\vec{u}
32$$
33
34A translation can be defined by a STL vector (size 2 or 3) or its components :
35
36\begin{lstlisting}
37Vector<Real> u;
38Real ux, uy, uz;
39Translation t1(u), t2(ux, uy), t3(ux, uy, uz);
40\end{lstlisting}
41
42\begin{remark}
43{\tt u} can be omitted. If so, its default value is the 3d zero vector. {\tt uy} and {\tt uz} can be omitted too. If so, their default value is 0.
44\end{remark}
45
46\begin{remark}
47As the {\class Vector} class inherits from {\cmd std::vector} you can use it in place of  {\class Vector} because all prototypes are based on {\cmd std::vector}.
48\end{remark}
49
50\subsubsection{2d rotations}
51
52Point B is the image of point A by the 2d rotation of center $\Omega$ and of angle $\theta$ if and only if
53$$
54\overrightarrow{\Omega B} = \left(
55\begin{array}{cc}
56\cos\theta & -\sin\theta \\
57\sin\theta & \cos\theta
58\end{array}
59\right) \overrightarrow{\Omega A}
60$$
61
62A 2d rotation is defined by a point and an angle (in radians) :
63
64\begin{lstlisting}
65Point c;
66Real angle;
67Rotation2d r(c, angle);
68\end{lstlisting}
69
70\begin{remark}
71{\tt angle} can be omitted. If so, its default value is 0 and  {\tt c} can be omitted too. If so, its default value is the 3d zero point.
72\end{remark}
73
74\subsubsection{3d rotations}
75
76Point B is the image of point A by the 3d rotation of axis $\left(\Omega, \vec{d}\right)$ and of angle $\theta$ (in radians) if and only if
77$$
78\overrightarrow{\Omega B} = \cos\theta \; \overrightarrow{\Omega A} + \left( 1 -\cos\theta\right) \; \overrightarrow{\Omega A} \cdot \vec{n} + \sin\theta \; \vec{n} \wedge \overrightarrow{\Omega A} \quad \text{(Rodrigues' rotation formulae)}
79$$
80
81where $\displaystyle \vec{n}=\frac{\vec{u}}{||\vec{u}||}$ (the unitary direction).
82
83\medskip
84
85The direction can be defined by a STL vector or by its components :
86
87\begin{lstlisting}
88Point c;
89Vector<Real> d;
90Real dx, dy, dz;
91Real angle;
92Rotation3d r1(c, d, angle), r2(c, dx, dy, dz, angle);
93\end{lstlisting}
94
95\begin{remark}
96In the first syntax, {\tt angle} can be omitted. If so, its default value is 0. and {\tt d} can also be omitted. If so, its default value is the 3d zero vector. \\
97In the second syntax, {\tt dz} can be omitted too. If so, its default value is 0. .
98\end{remark}
99
100\subsubsection{Homotheties}
101
102Point B is the image of point A by the homothety of center $\Omega$ and of factor $k$ if and only if
103$$
104\overrightarrow{\Omega B} = k \; \overrightarrow{\Omega A}
105$$
106
107\begin{lstlisting}
108Point c;
109Real factor;
110Homothety h(c, factor);
111\end{lstlisting}
112
113\begin{remark}
114{\tt factor} can be omitted. If so, its default value is 0. and {\tt c} can also be omitted. If so, its default value is the 3d zero vector.
115\end{remark}
116
117\subsubsection{Point reflections}
118
119Point B is the image of point A by the point reflection of center $\Omega$ if and only if
120$$
121\overrightarrow{\Omega B} = - \overrightarrow{\Omega A}
122$$
123
124It is an homothety of factor -1 and same center.
125
126\begin{lstlisting}
127Point c;
128PointReflection h(c);
129\end{lstlisting}
130
131\begin{remark}
132{\tt c} can also be omitted. If so, its default value is the 3d zero vector.
133\end{remark}
134
135\subsubsection{2d reflections}
136
137Point B is the image of point A by the 2d reflection of axis $\left(\Omega,\vec{d}\right)$ if and only if
138$$
139\overrightarrow{AB} =  2 \overrightarrow{AH} \quad \text{where $H$ is the orthogonal projection of $A$ on $\left(\Omega,\vec{d}\right)$}
140$$
141
142\begin{lstlisting}
143Point c;
144Vector<Real> d;
145Real dx, dy;
146Reflection2d r1(c, d), r2(c, dx, dy);
147\end{lstlisting}
148
149\begin{remark}
150In the first syntax, {\tt d} can be omitted. If so, its default value is the 2d zero vector and {\tt c} can be omitted. If so, its default value is the 2d zero point.
151\end{remark}
152
153\subsubsection{3d reflections}
154
155Point B is the image of point A by the 2d reflection of plane $\left[\Omega,\vec{n}\right]$ if and only if
156$$
157\overrightarrow{AB} =  2 \overrightarrow{AH} \quad \text{where $H$ is the orthogonal projection of $A$ on $\left[\Omega,\vec{n}\right]$}
158$$
159
160\begin{lstlisting}[deletekeywords={[3] nx, ny, nz}]
161Point c;
162Vector<Real> n;
163Real nx, ny, nz;
164Reflection3d r1(c, n), r2(c, nx, ny, nz);
165\end{lstlisting}
166
167\begin{remark}
168In the first syntax, {\tt n} can be omitted. If so, its default value is the 3d zero vector and {\tt c} can be omitted. If so, its default value is the 3d zero point.
169\end{remark}
170
171\subsection{Composition of transformations}
172
173To define a composition of transformations, you can use the operator * between canonical transformations, an is the following example :
174
175\begin{lstlisting}
176Rotation2d r1(Point(0.,0.), 120.);
177Reflection2d r2(Point(1.,-1.), 1.,2.5, -3.);
178Translation t1(-1.,4.);
179Homothety h (Point(-1.,0.), -3.2);
180Transformation t = r1*h*r2*t1;
181\end{lstlisting}
182
183Composition * has to be understood as usual composition operator $\circ$ : {\tt t(P)=r1(h(r2(t1(P))))}.
184
185\subsection{Applying transformations}
186
187\subsubsection{How to apply a transformation ?}
188
189In this paragraph, we will look at the {\class Cube} object, but you have same functions for any canonical or composite {\class Geometry}.
190
191If you want to apply a transformation and modify the input object, you can use one of the following functions :
192
193\begin{lstlisting}
194//! apply a geometrical transformation on a Cube
195Cube& Cube::transform(const Transformation& t);
196//! apply a translation on a Cube
197Cube& Cube::translate(std::vector<Real> u = std::vector<Real>(3,0.));
198Cube& Cube::translate(Real ux, Real uy = 0., Real uz = 0.);
199//! apply a rotation 2d on a Cube
200Cube& Cube::rotate2d(const Point& c = Point(0.,0.), Real angle = 0.);
201//! apply a rotation 3d on a Cube
202Cube& Cube::rotate3d(const Point& c = Point(0.,0.,0.), std::vector<Real> u = std::vector<Real>(3,0.), Real angle = 0.);
203Cube& Cube::rotate3d(Real ux, Real uy, Real angle);
204Cube& Cube::rotate3d(Real ux, Real uy, Real uz, Real angle);
205Cube& Cube::rotate3d(const Point& c, Real ux, Real uy, Real angle);
206Cube& Cube::rotate3d(const Point& c, Real ux, Real uy, Real uz, Real angle);
207//! apply a homothety on a Cube
208Cube& Cube::homothetize(const Point& c = Point(0.,0.,0.), Real factor = 1.);
209Cube& Cube::homothetize(Real factor);
210//! apply a point reflection on a Cube
211Cube& Cube::pointReflect(const Point& c = Point(0.,0.,0.));
212//! apply a reflection2d on a Cube
213Cube& Cube::reflect2d(const Point& c = Point(0.,0.), std::vector<Real> u = std::vector<Real>(2,0.));
214Cube& Cube::reflect2d(const Point& c, Real ux, Real uy = 0.);
215//! apply a reflection3d on a Cube
216Cube& Cube::reflect3d(const Point& c = Point(0.,0.,0.), std::vector<Real> u = std::vector<Real>(3,0.));
217Cube& Cube::reflect3d(const Point& c, Real ux, Real uy, Real uz = 0.);
218\end{lstlisting}
219
220For instance,
221
222\begin{lstlisting}
223Cube c;
224c.translate(0.,0.,1.);
225\end{lstlisting}
226
227If you want now to create a new {\class Cube} by applying a transformation on a {\class Cube}, you should use one of the following functions instead :
228
229\begin{lstlisting}
230//! apply a geometrical transformation on a Cube (external)
231Cube transform(const Cube& m, const Transformation& t);
232//! apply a translation on a Cube (external)
233Cube translate(const Cube& m, std::vector<Real> u = std::vector<Real>(3,0.));
234Cube translate(const Cube& m, Real ux, Real uy = 0., Real uz = 0.);
235//! apply a rotation 2d on a Cube (external)
236Cube rotate2d(const Cube& m, const Point& c = Point(0.,0.), Real angle = 0.);
237//! apply a rotation 3d on a Cube (external)
238Cube rotate3d(const Cube& m, const Point& c = Point(0.,0.,0.), std::vector<Real> u = std::vector<Real>(3,0.), Real angle = 0.);
239Cube rotate3d(const Cube& m, Real ux, Real uy, Real angle);
240Cube rotate3d(const Cube& m, Real ux, Real uy, Real uz, Real angle);
241Cube rotate3d(const Cube& m, const Point& c, Real ux, Real uy, Real angle);
242Cube rotate3d(const Cube& m, const Point& c, Real ux, Real uy, Real uz, Real angle);
243//! apply a homothety on a Cube (external)
244Cube homothetize(const Cube& m, const Point& c = Point(0.,0.,0.), Real factor = 1.);
245Cube homothetize(const Cube& m, Real factor);
246//! apply a point reflection on a Cube (external)
247Cube pointReflect(const Cube& m, const Point& c = Point(0.,0.,0.));
248//! apply a reflection2d on a Cube (external)
249Cube reflect2d(const Cube& m, const Point& c = Point(0.,0.), std::vector<Real> u = std::vector<Real>(2,0.));
250Cube reflect2d(const Cube& m, const Point& c, Real ux, Real uy = 0.);
251//! apply a reflection3d on a Cube (external)
252Cube reflect3d(const Cube& m, const Point& c = Point(0.,0.,0.), std::vector<Real> u = std::vector<Real>(3,0.));
253Cube reflect3d(const Cube& m, const Point& c, Real ux, Real uy, Real uz = 0.);
254\end{lstlisting}
255
256For instance,
257
258\begin{lstlisting}
259Cube c1;
260Cube c2=translate(c1,0.,0.,1.);
261\end{lstlisting}
262
263\begin{remark}
264Of course, you can not apply a 2d rotation or a 2d reflection for geometries defined by 3d points !
265\end{remark}
266
267\subsubsection{What does a transformation really do ?}
268
269Applying a transformation on an object means computing the image of each point defining the object. But it can also change names.
270
271When you create a new object by applying a transformation on a object, names are modified. Indeed, the transformation add a suffix "\_{}prime". It concerns geometry names and sidenames.
272
273\begin{remark}
274When you transform a {\class Geometry}, it also apply the transformation on the underlying bounding box.
275\end{remark}
276