0025180: Visualization - Homogeneous transformation API in TKV3d
[occt.git] / src / gp / gp_Trsf.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_Trsf_HeaderFile
16 #define _gp_Trsf_HeaderFile
17
18 #include <gp_TrsfForm.hxx>
19 #include <gp_Mat.hxx>
20 #include <gp_XYZ.hxx>
21 #include <NCollection_Mat4.hxx>
22 #include <Standard.hxx>
23 #include <Standard_Boolean.hxx>
24 #include <Standard_DefineAlloc.hxx>
25 #include <Standard_Integer.hxx>
26 #include <Standard_Handle.hxx>
27 #include <Standard_Real.hxx>
28
29 class Standard_ConstructionError;
30 class Standard_OutOfRange;
31 class gp_Pnt;
32 class gp_Ax1;
33 class gp_Ax2;
34 class gp_Quaternion;
35 class gp_Ax3;
36 class gp_Vec;
37
38 //! Defines a non-persistent transformation in 3D space.
39 //! The following transformations are implemented :
40 //! . Translation, Rotation, Scale
41 //! . Symmetry with respect to a point, a line, a plane.
42 //! Complex transformations can be obtained by combining the
43 //! previous elementary transformations using the method
44 //! Multiply.
45 //! The transformations can be represented as follow :
46 //!
47 //! V1   V2   V3    T       XYZ        XYZ
48 //! | a11  a12  a13   a14 |   | x |      | x'|
49 //! | a21  a22  a23   a24 |   | y |      | y'|
50 //! | a31  a32  a33   a34 |   | z |   =  | z'|
51 //! |  0    0    0     1  |   | 1 |      | 1 |
52 //!
53 //! where {V1, V2, V3} defines the vectorial part of the
54 //! transformation and T defines the translation part of the
55 //! transformation.
56 //! This transformation never change the nature of the objects.
57 class gp_Trsf 
58 {
59 public:
60
61   DEFINE_STANDARD_ALLOC
62
63   
64   //! Returns the identity transformation.
65     gp_Trsf();
66   
67   //! Creates  a 3D transformation from the 2D transformation T.
68   //! The resulting transformation has a homogeneous
69   //! vectorial part, V3, and a translation part, T3, built from T:
70   //! a11    a12
71   //! 0             a13
72   //! V3 =    a21    a22    0       T3
73   //! =   a23
74   //! 0    0    1.
75   //! 0
76   //! It also has the same scale factor as T. This
77   //! guarantees (by projection) that the transformation
78   //! which would be performed by T in a plane (2D space)
79   //! is performed by the resulting transformation in the xOy
80   //! plane of the 3D space, (i.e. in the plane defined by the
81   //! origin (0., 0., 0.) and the vectors DX (1., 0., 0.), and DY
82   //! (0., 1., 0.)). The scale factor is applied to the entire space.
83   Standard_EXPORT gp_Trsf(const gp_Trsf2d& T);
84   
85
86   //! Makes the transformation into a symmetrical transformation.
87   //! P is the center of the symmetry.
88     void SetMirror (const gp_Pnt& P);
89   
90
91   //! Makes the transformation into a symmetrical transformation.
92   //! A1 is the center of the axial symmetry.
93   Standard_EXPORT void SetMirror (const gp_Ax1& A1);
94   
95
96   //! Makes the transformation into a symmetrical transformation.
97   //! A2 is the center of the planar symmetry
98   //! and defines the plane of symmetry by its origin, "X
99   //! Direction" and "Y Direction".
100   Standard_EXPORT void SetMirror (const gp_Ax2& A2);
101   
102
103   //! Changes the transformation into a rotation.
104   //! A1 is the rotation axis and Ang is the angular value of the
105   //! rotation in radians.
106   Standard_EXPORT void SetRotation (const gp_Ax1& A1, const Standard_Real Ang);
107   
108
109   //! Changes the transformation into a rotation defined by quaternion.
110   //! Note that rotation is performed around origin, i.e.
111   //! no translation is involved.
112   Standard_EXPORT void SetRotation (const gp_Quaternion& R);
113   
114
115   //! Changes the transformation into a scale.
116   //! P is the center of the scale and S is the scaling value.
117   //! Raises ConstructionError  If <S> is null.
118   Standard_EXPORT void SetScale (const gp_Pnt& P, const Standard_Real S);
119   
120
121   //! Modifies this transformation so that it transforms the
122   //! coordinate system defined by FromSystem1 into the
123   //! one defined by ToSystem2. After this modification, this
124   //! transformation transforms:
125   //! -   the origin of FromSystem1 into the origin of ToSystem2,
126   //! -   the "X Direction" of FromSystem1 into the "X
127   //! Direction" of ToSystem2,
128   //! -   the "Y Direction" of FromSystem1 into the "Y
129   //! Direction" of ToSystem2, and
130   //! -   the "main Direction" of FromSystem1 into the "main
131   //! Direction" of ToSystem2.
132   //! Warning
133   //! When you know the coordinates of a point in one
134   //! coordinate system and you want to express these
135   //! coordinates in another one, do not use the
136   //! transformation resulting from this function. Use the
137   //! transformation that results from SetTransformation instead.
138   //! SetDisplacement and SetTransformation create
139   //! related transformations: the vectorial part of one is the
140   //! inverse of the vectorial part of the other.
141   Standard_EXPORT void SetDisplacement (const gp_Ax3& FromSystem1, const gp_Ax3& ToSystem2);
142   
143   //! Modifies this transformation so that it transforms the
144   //! coordinates of any point, (x, y, z), relative to a source
145   //! coordinate system into the coordinates (x', y', z') which
146   //! are relative to a target coordinate system, but which
147   //! represent the same point
148   //! The transformation is from the coordinate
149   //! system "FromSystem1" to the coordinate system "ToSystem2".
150   //! Example :
151   //! In a C++ implementation :
152   //! Real x1, y1, z1;  // are the coordinates of a point in the
153   //! // local system FromSystem1
154   //! Real x2, y2, z2;  // are the coordinates of a point in the
155   //! // local system ToSystem2
156   //! gp_Pnt P1 (x1, y1, z1)
157   //! Trsf T;
158   //! T.SetTransformation (FromSystem1, ToSystem2);
159   //! gp_Pnt P2 = P1.Transformed (T);
160   //! P2.Coord (x2, y2, z2);
161   Standard_EXPORT void SetTransformation (const gp_Ax3& FromSystem1, const gp_Ax3& ToSystem2);
162   
163   //! Modifies this transformation so that it transforms the
164   //! coordinates of any point, (x, y, z), relative to a source
165   //! coordinate system into the coordinates (x', y', z') which
166   //! are relative to a target coordinate system, but which
167   //! represent the same point
168   //! The transformation is from the default coordinate system
169   //! {P(0.,0.,0.), VX (1.,0.,0.), VY (0.,1.,0.), VZ (0., 0. ,1.) }
170   //! to the local coordinate system defined with the Ax3 ToSystem.
171   //! Use in the same way  as the previous method. FromSystem1 is
172   //! defaulted to the absolute coordinate system.
173   Standard_EXPORT void SetTransformation (const gp_Ax3& ToSystem);
174   
175
176   //! Sets transformation by directly specified rotation and translation.
177   Standard_EXPORT void SetTransformation (const gp_Quaternion& R, const gp_Vec& T);
178   
179
180   //! Changes the transformation into a translation.
181   //! V is the vector of the translation.
182     void SetTranslation (const gp_Vec& V);
183   
184
185   //! Makes the transformation into a translation where the translation vector
186   //! is the vector (P1, P2) defined from point P1 to point P2.
187     void SetTranslation (const gp_Pnt& P1, const gp_Pnt& P2);
188   
189   //! Replaces the translation vector with the vector V.
190   Standard_EXPORT void SetTranslationPart (const gp_Vec& V);
191   
192   //! Modifies the scale factor.
193   //! Raises ConstructionError  If S is null.
194   Standard_EXPORT void SetScaleFactor (const Standard_Real S);
195   
196   void SetForm (const gp_TrsfForm P);
197   
198   //! Sets the coefficients  of the transformation.  The
199   //! transformation  of the  point  x,y,z is  the point
200   //! x',y',z' with :
201   //!
202   //! x' = a11 x + a12 y + a13 z + a14
203   //! y' = a21 x + a22 y + a23 z + a24
204   //! z' = a31 x + a32 y + a33 z + a34
205   //!
206   //! The method Value(i,j) will return aij.
207   //! Raises ConstructionError if the determinant of  the aij is null.
208   //! The matrix is orthogonalized before future using.
209   Standard_EXPORT void SetValues (const Standard_Real a11, const Standard_Real a12, const Standard_Real a13, const Standard_Real a14, const Standard_Real a21, const Standard_Real a22, const Standard_Real a23, const Standard_Real a24, const Standard_Real a31, const Standard_Real a32, const Standard_Real a33, const Standard_Real a34);
210   
211   //! Returns true if the determinant of the vectorial part of
212   //! this transformation is negative.
213     Standard_Boolean IsNegative() const;
214   
215
216   //! Returns the nature of the transformation. It can be: an
217   //! identity transformation, a rotation, a translation, a mirror
218   //! transformation (relative to a point, an axis or a plane), a
219   //! scaling transformation, or a compound transformation.
220     gp_TrsfForm Form() const;
221   
222   //! Returns the scale factor.
223     Standard_Real ScaleFactor() const;
224   
225
226   //! Returns the translation part of the transformation's matrix
227     const gp_XYZ& TranslationPart() const;
228   
229
230   //! Returns the boolean True if there is non-zero rotation.
231   //! In the presence of rotation, the output parameters store the axis
232   //! and the angle of rotation. The method always returns positive
233   //! value "theAngle", i.e., 0. < theAngle <= PI.
234   //! Note that this rotation is defined only by the vectorial part of
235   //! the transformation; generally you would need to check also the
236   //! translational part to obtain the axis (gp_Ax1) of rotation.
237   Standard_EXPORT Standard_Boolean GetRotation (gp_XYZ& theAxis, Standard_Real& theAngle) const;
238   
239
240   //! Returns quaternion representing rotational part of the transformation.
241   Standard_EXPORT gp_Quaternion GetRotation() const;
242   
243
244   //! Returns the vectorial part of the transformation. It is
245   //! a 3*3 matrix which includes the scale factor.
246   Standard_EXPORT gp_Mat VectorialPart() const;
247   
248
249   //! Computes the homogeneous vectorial part of the transformation.
250   //! It is a 3*3 matrix which doesn't include the scale factor.
251   //! In other words, the vectorial part of this transformation is equal
252   //! to its homogeneous vectorial part, multiplied by the scale factor.
253   //! The coefficients of this matrix must be multiplied by the
254   //! scale factor to obtain the coefficients of the transformation.
255     const gp_Mat& HVectorialPart() const;
256   
257
258   //! Returns the coefficients of the transformation's matrix.
259   //! It is a 3 rows * 4 columns matrix.
260   //! This coefficient includes the scale factor.
261   //! Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
262     Standard_Real Value (const Standard_Integer Row, const Standard_Integer Col) const;
263   
264   Standard_EXPORT void Invert();
265   
266
267   //! Computes the reverse transformation
268   //! Raises an exception if the matrix of the transformation
269   //! is not inversible, it means that the scale factor is lower
270   //! or equal to Resolution from package gp.
271   //! Computes the transformation composed with T and  <me>.
272   //! In a C++ implementation you can also write Tcomposed = <me> * T.
273   //! Example :
274   //! Trsf T1, T2, Tcomp; ...............
275   //! Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
276   //! Pnt P1(10.,3.,4.);
277   //! Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
278   //! Pnt P3 = P1.Transformed(T1);       //using T1 then T2
279   //! P3.Transform(T2);                  // P3 = P2 !!!
280     gp_Trsf Inverted() const;
281   
282     gp_Trsf Multiplied (const gp_Trsf& T) const;
283   gp_Trsf operator * (const gp_Trsf& T) const
284 {
285   return Multiplied(T);
286 }
287   
288
289   //! Computes the transformation composed with <me> and T.
290   //! <me> = <me> * T
291   Standard_EXPORT void Multiply (const gp_Trsf& T);
292 void operator *= (const gp_Trsf& T)
293 {
294   Multiply(T);
295 }
296   
297
298   //! Computes the transformation composed with <me> and T.
299   //! <me> = T * <me>
300   Standard_EXPORT void PreMultiply (const gp_Trsf& T);
301   
302   Standard_EXPORT void Power (const Standard_Integer N);
303   
304
305   //! Computes the following composition of transformations
306   //! <me> * <me> * .......* <me>, N time.
307   //! if N = 0 <me> = Identity
308   //! if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
309   //!
310   //! Raises if N < 0 and if the matrix of the transformation not
311   //! inversible.
312     gp_Trsf Powered (const Standard_Integer N) const;
313   
314     void Transforms (Standard_Real& X, Standard_Real& Y, Standard_Real& Z) const;
315   
316   //! Transformation of a triplet XYZ with a Trsf
317     void Transforms (gp_XYZ& Coord) const;
318
319   //! Convert transformation to 4x4 matrix.
320   template<class T>
321   void GetMat4 (NCollection_Mat4<T>& theMat) const
322   {
323     if (shape == gp_Identity)
324     {
325       theMat.InitIdentity();
326       return;
327     }
328
329     theMat.SetValue (0, 0, static_cast<T> (Value (1, 1)));
330     theMat.SetValue (0, 1, static_cast<T> (Value (1, 2)));
331     theMat.SetValue (0, 2, static_cast<T> (Value (1, 3)));
332     theMat.SetValue (0, 3, static_cast<T> (Value (1, 4)));
333     theMat.SetValue (1, 0, static_cast<T> (Value (2, 1)));
334     theMat.SetValue (1, 1, static_cast<T> (Value (2, 2)));
335     theMat.SetValue (1, 2, static_cast<T> (Value (2, 3)));
336     theMat.SetValue (1, 3, static_cast<T> (Value (2, 4)));
337     theMat.SetValue (2, 0, static_cast<T> (Value (3, 1)));
338     theMat.SetValue (2, 1, static_cast<T> (Value (3, 2)));
339     theMat.SetValue (2, 2, static_cast<T> (Value (3, 3)));
340     theMat.SetValue (2, 3, static_cast<T> (Value (3, 4)));
341     theMat.SetValue (3, 0, static_cast<T> (0));
342     theMat.SetValue (3, 1, static_cast<T> (0));
343     theMat.SetValue (3, 2, static_cast<T> (0));
344     theMat.SetValue (3, 3, static_cast<T> (1));
345   }
346
347 friend class gp_GTrsf;
348
349 protected:
350
351   //! Makes orthogonalization of "matrix"
352   Standard_EXPORT void Orthogonalize();
353
354 private:
355
356   Standard_Real scale;
357   gp_TrsfForm shape;
358   gp_Mat matrix;
359   gp_XYZ loc;
360
361 };
362
363 #include <gp_Trsf.lxx>
364
365 #endif // _gp_Trsf_HeaderFile