0032137: Coding Rules - merge redundant .lxx files into header files within Package gp
[occt.git] / src / gp / gp_GTrsf.hxx
1 // Copyright (c) 1991-1999 Matra Datavision
2 // Copyright (c) 1999-2014 OPEN CASCADE SAS
3 //
4 // This file is part of Open CASCADE Technology software library.
5 //
6 // This library is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU Lesser General Public License version 2.1 as published
8 // by the Free Software Foundation, with special exception defined in the file
9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 // distribution for complete text of the license and disclaimer of any warranty.
11 //
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
14
15 #ifndef _gp_GTrsf_HeaderFile
16 #define _gp_GTrsf_HeaderFile
17
18 #include <gp_Ax1.hxx>
19 #include <gp_Ax2.hxx>
20 #include <gp_Mat.hxx>
21 #include <gp_Trsf.hxx>
22 #include <gp_TrsfForm.hxx>
23 #include <gp_XYZ.hxx>
24 #include <Standard_ConstructionError.hxx>
25 #include <Standard_OutOfRange.hxx>
26
27 class gp_Trsf;
28 class gp_Mat;
29
30 // Avoid possible conflict with SetForm macro defined by windows.h
31 #ifdef SetForm
32 #undef SetForm
33 #endif
34
35 //! Defines a non-persistent transformation in 3D space.
36 //! This transformation is a general transformation.
37 //! It can be a gp_Trsf, an affinity, or you can define
38 //! your own transformation giving the matrix of transformation.
39 //!
40 //! With a gp_GTrsf you can transform only a triplet of coordinates gp_XYZ.
41 //! It is not possible to transform other geometric objects
42 //! because these transformations can change the nature of non-elementary geometric objects.
43 //! The transformation gp_GTrsf can be represented as follow:
44 //! @code
45 //!    V1   V2   V3    T       XYZ        XYZ
46 //! | a11  a12  a13   a14 |   | x |      | x'|
47 //! | a21  a22  a23   a24 |   | y |      | y'|
48 //! | a31  a32  a33   a34 |   | z |   =  | z'|
49 //! |  0    0    0     1  |   | 1 |      | 1 |
50 //! @endcode
51 //! where {V1, V2, V3} define the vectorial part of the
52 //! transformation and T defines the translation part of the transformation.
53 //! Warning
54 //! A gp_GTrsf transformation is only applicable to coordinates.
55 //! Be careful if you apply such a transformation to all points of a geometric object,
56 //! as this can change the nature of the object and thus render it incoherent!
57 //! Typically, a circle is transformed into an ellipse by an affinity transformation.
58 //! To avoid modifying the nature of an object, use a gp_Trsf transformation instead,
59 //! as objects of this class respect the nature of geometric objects.
60 class gp_GTrsf 
61 {
62 public:
63
64   DEFINE_STANDARD_ALLOC
65
66   //! Returns the Identity transformation.
67   gp_GTrsf()
68   {
69     shape = gp_Identity;
70     matrix.SetScale (1.0);
71     loc.SetCoord (0.0, 0.0, 0.0);
72     scale = 1.0;
73   }
74
75   //! Converts the gp_Trsf transformation theT into a
76   //! general transformation, i.e. Returns a GTrsf with
77   //! the same matrix of coefficients as the Trsf theT.
78   gp_GTrsf (const gp_Trsf& theT)
79   {
80     shape = theT.Form();
81     matrix = theT.matrix;
82     loc = theT.TranslationPart();
83     scale = theT.ScaleFactor();
84   }
85
86   //! Creates a transformation based on the matrix theM and the
87   //! vector theV where theM defines the vectorial part of
88   //! the transformation, and V the translation part, or
89   gp_GTrsf (const gp_Mat& theM, const gp_XYZ& theV)
90   : matrix (theM),
91     loc (theV)
92   {
93     shape = gp_Other;
94     scale = 0.0;
95   }
96
97   //! Changes this transformation into an affinity of ratio theRatio
98   //! with respect to the axis theA1.
99   //! Note: an affinity is a point-by-point transformation that
100   //! transforms any point P into a point P' such that if H is
101   //! the orthogonal projection of P on the axis theA1 or the
102   //! plane A2, the vectors HP and HP' satisfy:
103   //! HP' = theRatio * HP.
104   void SetAffinity (const gp_Ax1& theA1, const Standard_Real theRatio);
105
106   //! Changes this transformation into an affinity of ratio theRatio
107   //! with respect to  the plane defined by the origin, the "X Direction" and
108   //! the "Y Direction" of coordinate system theA2.
109   //! Note: an affinity is a point-by-point transformation that
110   //! transforms any point P into a point P' such that if H is
111   //! the orthogonal projection of P on the axis A1 or the
112   //! plane theA2, the vectors HP and HP' satisfy:
113   //! HP' = theRatio * HP.
114   void SetAffinity (const gp_Ax2& theA2, const Standard_Real theRatio);
115
116   //! Replaces  the coefficient (theRow, theCol) of the matrix representing
117   //! this transformation by theValue.  Raises OutOfRange
118   //! if  theRow < 1 or theRow > 3 or theCol < 1 or theCol > 4
119   void SetValue (const Standard_Integer theRow, const Standard_Integer theCol, const Standard_Real theValue);
120
121   //! Replaces the vectorial part of this transformation by theMatrix.
122   void SetVectorialPart (const gp_Mat& theMatrix)
123   {
124     matrix = theMatrix;
125     shape = gp_Other;
126     scale = 0.0;
127   }
128
129   //! Replaces the translation part of
130   //! this transformation by the coordinates of the number triple theCoord.
131   Standard_EXPORT void SetTranslationPart (const gp_XYZ& theCoord);
132
133   //! Assigns the vectorial and translation parts of theT to this transformation.
134   void SetTrsf (const gp_Trsf& theT)
135   {
136     shape = theT.shape;
137     matrix = theT.matrix;
138     loc = theT.loc;
139     scale = theT.scale;
140   }
141
142   //! Returns true if the determinant of the vectorial part of
143   //! this transformation is negative.
144   Standard_Boolean IsNegative() const { return matrix.Determinant() < 0.0; }
145
146   //! Returns true if this transformation is singular (and
147   //! therefore, cannot be inverted).
148   //! Note: The Gauss LU decomposition is used to invert the
149   //! transformation matrix. Consequently, the transformation
150   //! is considered as singular if the largest pivot found is less
151   //! than or equal to gp::Resolution().
152   //! Warning
153   //! If this transformation is singular, it cannot be inverted.
154   Standard_Boolean IsSingular() const { return matrix.IsSingular(); }
155
156   //! Returns the nature of the transformation.  It can be an
157   //! identity transformation, a rotation, a translation, a mirror
158   //! transformation (relative to a point, an axis or a plane), a
159   //! scaling transformation, a compound transformation or
160   //! some other type of transformation.
161   gp_TrsfForm Form() const { return shape; }
162
163   //! verify and set the shape of the GTrsf Other or CompoundTrsf
164   //! Ex :
165   //! @code
166   //! myGTrsf.SetValue(row1,col1,val1);
167   //! myGTrsf.SetValue(row2,col2,val2);
168   //! ...
169   //! myGTrsf.SetForm();
170   //! @endcode
171   Standard_EXPORT void SetForm();
172
173   //! Returns the translation part of the GTrsf.
174   const gp_XYZ& TranslationPart() const { return loc; }
175
176   //! Computes the vectorial part of the GTrsf. The returned Matrix
177   //! is a  3*3 matrix.
178   const gp_Mat& VectorialPart() const { return matrix; }
179
180   //! Returns the coefficients of the global matrix of transformation.
181   //! Raises OutOfRange if theRow < 1 or theRow > 3 or theCol < 1 or theCol > 4
182   Standard_Real Value (const Standard_Integer theRow, const Standard_Integer theCol) const;
183
184   Standard_Real operator() (const Standard_Integer theRow, const Standard_Integer theCol) const { return Value (theRow, theCol); }
185
186   Standard_EXPORT void Invert();
187
188   //! Computes the reverse transformation.
189   //! Raises an exception if the matrix of the transformation
190   //! is not inversible.
191   Standard_NODISCARD gp_GTrsf Inverted() const
192   {
193     gp_GTrsf aT = *this;
194     aT.Invert();
195     return aT;
196   }
197
198   //! Computes the transformation composed from theT and <me>.
199   //! In a C++ implementation you can also write Tcomposed = <me> * theT.
200   //! Example :
201   //! @code
202   //! gp_GTrsf T1, T2, Tcomp; ...............
203   //! //composition :
204   //! Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
205   //! // transformation of a point
206   //! gp_XYZ P(10.,3.,4.);
207   //! gp_XYZ P1(P);
208   //! Tcomp.Transforms(P1);               //using Tcomp
209   //! gp_XYZ P2(P);
210   //! T1.Transforms(P2);                  //using T1 then T2
211   //! T2.Transforms(P2);                  // P1 = P2 !!!
212   //! @endcode
213   Standard_NODISCARD gp_GTrsf Multiplied (const gp_GTrsf& theT) const
214    {
215     gp_GTrsf aTres = *this;
216     aTres.Multiply (theT);
217     return aTres;
218   }
219
220   Standard_NODISCARD gp_GTrsf operator * (const gp_GTrsf& theT)  const { return Multiplied (theT); }
221
222   //! Computes the transformation composed with <me> and theT.
223   //! <me> = <me> * theT
224   Standard_EXPORT void Multiply (const gp_GTrsf& theT);
225
226   void operator *= (const gp_GTrsf& theT) { Multiply (theT); }
227
228   //! Computes the product of the transformation theT and this
229   //! transformation and assigns the result to this transformation.
230   //! this = theT * this
231   Standard_EXPORT void PreMultiply (const gp_GTrsf& theT);
232
233   Standard_EXPORT void Power (const Standard_Integer theN);
234
235   //! Computes:
236   //! -   the product of this transformation multiplied by itself
237   //! theN times, if theN is positive, or
238   //! -   the product of the inverse of this transformation
239   //! multiplied by itself |theN| times, if theN is negative.
240   //! If theN equals zero, the result is equal to the Identity
241   //! transformation.
242   //! I.e.:  <me> * <me> * .......* <me>, theN time.
243   //! if theN =0 <me> = Identity
244   //! if theN < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
245   //!
246   //! Raises an exception if N < 0 and if the matrix of the
247   //! transformation not inversible.
248   Standard_NODISCARD gp_GTrsf Powered (const Standard_Integer theN) const
249   {
250     gp_GTrsf aT = *this;
251     aT.Power (theN);
252     return aT;
253   }
254
255   void Transforms (gp_XYZ& theCoord) const;
256
257   //! Transforms a triplet XYZ with a GTrsf.
258   void Transforms (Standard_Real& theX, Standard_Real& theY, Standard_Real& theZ) const;
259
260   gp_Trsf Trsf() const;
261
262   //! Convert transformation to 4x4 matrix.
263   template<class T>
264   void GetMat4 (NCollection_Mat4<T>& theMat) const
265   {
266     if (shape == gp_Identity)
267     {
268       theMat.InitIdentity();
269       return;
270     }
271
272     theMat.SetValue (0, 0, static_cast<T> (Value (1, 1)));
273     theMat.SetValue (0, 1, static_cast<T> (Value (1, 2)));
274     theMat.SetValue (0, 2, static_cast<T> (Value (1, 3)));
275     theMat.SetValue (0, 3, static_cast<T> (Value (1, 4)));
276     theMat.SetValue (1, 0, static_cast<T> (Value (2, 1)));
277     theMat.SetValue (1, 1, static_cast<T> (Value (2, 2)));
278     theMat.SetValue (1, 2, static_cast<T> (Value (2, 3)));
279     theMat.SetValue (1, 3, static_cast<T> (Value (2, 4)));
280     theMat.SetValue (2, 0, static_cast<T> (Value (3, 1)));
281     theMat.SetValue (2, 1, static_cast<T> (Value (3, 2)));
282     theMat.SetValue (2, 2, static_cast<T> (Value (3, 3)));
283     theMat.SetValue (2, 3, static_cast<T> (Value (3, 4)));
284     theMat.SetValue (3, 0, static_cast<T> (0));
285     theMat.SetValue (3, 1, static_cast<T> (0));
286     theMat.SetValue (3, 2, static_cast<T> (0));
287     theMat.SetValue (3, 3, static_cast<T> (1));
288   }
289
290   //! Dumps the content of me into the stream
291   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
292
293 private:
294
295   gp_Mat matrix;
296   gp_XYZ loc;
297   gp_TrsfForm shape;
298   Standard_Real scale;
299
300 };
301
302
303 //=======================================================================
304 //function : SetAffinity
305 // purpose :
306 //=======================================================================
307 inline void gp_GTrsf::SetAffinity (const gp_Ax1& theA1, const Standard_Real theRatio)
308 {
309   shape = gp_Other;
310   scale = 0.0;
311   matrix.SetDot (theA1.Direction().XYZ());
312   matrix.Multiply (1.0 - theRatio);
313   matrix.SetDiagonal (matrix.Value (1,1) + theRatio,
314                       matrix.Value (2,2) + theRatio,
315                       matrix.Value (3,3) + theRatio);
316   loc = theA1.Location().XYZ();
317   loc.Reverse ();
318   loc.Multiply (matrix);
319   loc.Add (theA1.Location().XYZ());
320 }
321
322 //=======================================================================
323 //function : SetAffinity
324 // purpose :
325 //=======================================================================
326 inline void gp_GTrsf::SetAffinity (const gp_Ax2& theA2, const Standard_Real theRatio)
327 {
328   shape = gp_Other;
329   scale = 0.0;
330   matrix.SetDot (theA2.Direction().XYZ());
331   matrix.Multiply (theRatio - 1.);
332   loc = theA2.Location().XYZ();
333   loc.Reverse ();
334   loc.Multiply (matrix);
335   matrix.SetDiagonal (matrix.Value (1,1) + 1.,
336                       matrix.Value (2,2) + 1.,
337                       matrix.Value (3,3) + 1.);
338 }
339
340 //=======================================================================
341 //function : SetValue
342 // purpose :
343 //=======================================================================
344 inline void gp_GTrsf::SetValue (const Standard_Integer theRow,
345                                 const Standard_Integer theCol,
346                                 const Standard_Real theValue)
347 {
348   Standard_OutOfRange_Raise_if
349     (theRow < 1 || theRow > 3 || theCol < 1 || theCol > 4, " ");
350   if (theCol == 4)
351   {
352     loc.SetCoord (theRow, theValue);
353     if (shape == gp_Identity)
354     {
355       shape = gp_Translation;
356     }
357     return;
358   }
359   else
360   {
361     if (!(shape == gp_Other) && !(scale == 1.0))
362     {
363       matrix.Multiply (scale);
364     }
365     matrix.SetValue (theRow, theCol, theValue);
366     shape = gp_Other;
367     scale = 0.0;
368     return;
369   }
370 }
371
372 //=======================================================================
373 //function : Value
374 // purpose :
375 //=======================================================================
376 inline Standard_Real gp_GTrsf::Value (const Standard_Integer theRow,
377                                       const Standard_Integer theCol) const
378 {
379   Standard_OutOfRange_Raise_if
380     (theRow < 1 || theRow > 3 || theCol < 1 || theCol > 4, " ");
381   if (theCol == 4)
382   {
383     return loc.Coord (theRow);
384   }
385   if (shape == gp_Other)
386   {
387     return matrix.Value (theRow, theCol);
388   }
389   return scale * matrix.Value (theRow, theCol);
390 }
391
392 //=======================================================================
393 //function : Transforms
394 // purpose :
395 //=======================================================================
396 inline void gp_GTrsf::Transforms (gp_XYZ& theCoord) const
397 {
398   theCoord.Multiply (matrix);
399   if (!(shape == gp_Other) && !(scale == 1.0))
400   {
401     theCoord.Multiply (scale);
402   }
403   theCoord.Add (loc);
404 }
405
406 //=======================================================================
407 //function : Transforms
408 // purpose :
409 //=======================================================================
410 inline void gp_GTrsf::Transforms (Standard_Real& theX, Standard_Real& theY, Standard_Real& theZ) const
411 {
412   gp_XYZ aTriplet (theX, theY, theZ);
413   aTriplet.Multiply (matrix);
414   if (!(shape == gp_Other) && !(scale == 1.0))
415   {
416     aTriplet.Multiply (scale);
417   }
418   aTriplet.Add (loc);
419   aTriplet.Coord (theX, theY, theZ);
420 }
421
422 //=======================================================================
423 //function : Trsf
424 // purpose :
425 //=======================================================================
426 inline gp_Trsf gp_GTrsf::Trsf() const
427 {
428   if (Form() == gp_Other)
429   {
430     throw Standard_ConstructionError("gp_GTrsf::Trsf() - non-orthogonal GTrsf");
431   }
432   gp_Trsf aT;
433   aT.shape = shape;
434   aT.scale = scale;
435   aT.matrix = matrix;
436   aT.loc = loc;
437   return aT;
438 }
439
440 #endif // _gp_GTrsf_HeaderFile