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