0031313: Foundation Classes - Dump improvement for classes
[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 <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
21
22 #include <gp_Mat.hxx>
23 #include <gp_XYZ.hxx>
24 #include <gp_TrsfForm.hxx>
25 #include <Standard_Real.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_Boolean.hxx>
28 #include <gp_Trsf.hxx>
29 class Standard_ConstructionError;
30 class Standard_OutOfRange;
31 class gp_Trsf;
32 class gp_Mat;
33 class gp_XYZ;
34 class gp_Ax1;
35 class gp_Ax2;
36
37 // Avoid possible conflict with SetForm macro defined by windows.h
38 #ifdef SetForm
39 #undef SetForm
40 #endif
41
42 //! Defines a non-persistent transformation in 3D space.
43 //! This transformation is a general transformation.
44 //! It can be a Trsf from gp, an affinity, or you can define
45 //! your own transformation giving the matrix of transformation.
46 //!
47 //! With a Gtrsf you can transform only a triplet of coordinates
48 //! XYZ. It is not possible to transform other geometric objects
49 //! because these transformations can change the nature of non-
50 //! elementary geometric objects.
51 //! The transformation GTrsf can be represented as follow :
52 //!
53 //! V1   V2   V3    T       XYZ        XYZ
54 //! | a11  a12  a13   a14 |   | x |      | x'|
55 //! | a21  a22  a23   a24 |   | y |      | y'|
56 //! | a31  a32  a33   a34 |   | z |   =  | z'|
57 //! |  0    0    0     1  |   | 1 |      | 1 |
58 //!
59 //! where {V1, V2, V3} define the vectorial part of the
60 //! transformation and T defines the translation part of the
61 //! transformation.
62 //! Warning
63 //! A GTrsf transformation is only applicable to
64 //! coordinates. Be careful if you apply such a
65 //! transformation to all points of a geometric object, as
66 //! this can change the nature of the object and thus
67 //! render it incoherent!
68 //! Typically, a circle is transformed into an ellipse by an
69 //! affinity transformation. To avoid modifying the nature of
70 //! an object, use a gp_Trsf transformation instead, as
71 //! objects of this class respect the nature of geometric objects.
72 class gp_GTrsf 
73 {
74 public:
75
76   DEFINE_STANDARD_ALLOC
77
78   
79   //! Returns the Identity transformation.
80     gp_GTrsf();
81   
82
83   //! Converts the gp_Trsf transformation T into a
84   //! general transformation, i.e. Returns a GTrsf with
85   //! the same matrix of coefficients as the Trsf T.
86     gp_GTrsf(const gp_Trsf& T);
87   
88
89   //! Creates a transformation based on the matrix M and the
90   //! vector V where M defines the vectorial part of
91   //! the transformation, and V the translation part, or
92     gp_GTrsf(const gp_Mat& M, const gp_XYZ& V);
93   
94   //! Changes this transformation into an affinity of ratio Ratio
95   //! with respect to the axis A1.
96   //! Note: an affinity is a point-by-point transformation that
97   //! transforms any point P into a point P' such that if H is
98   //! the orthogonal projection of P on the axis A1 or the
99   //! plane A2, the vectors HP and HP' satisfy:
100   //! HP' = Ratio * HP.
101     void SetAffinity (const gp_Ax1& A1, const Standard_Real Ratio);
102   
103   //! Changes this transformation into an affinity of ratio Ratio
104   //! with respect to  the plane defined by the origin, the "X Direction" and
105   //! the "Y Direction" of coordinate system A2.
106   //! Note: an affinity is a point-by-point transformation that
107   //! transforms any point P into a point P' such that if H is
108   //! the orthogonal projection of P on the axis A1 or the
109   //! plane A2, the vectors HP and HP' satisfy:
110   //! HP' = Ratio * HP.
111     void SetAffinity (const gp_Ax2& A2, const Standard_Real Ratio);
112   
113
114   //! Replaces  the coefficient (Row, Col) of the matrix representing
115   //! this transformation by Value.  Raises OutOfRange
116   //! if  Row < 1 or Row > 3 or Col < 1 or Col > 4
117     void SetValue (const Standard_Integer Row, const Standard_Integer Col, const Standard_Real Value);
118   
119   //! Replaces the vectorial part of this transformation by Matrix.
120     void SetVectorialPart (const gp_Mat& Matrix);
121   
122   //! Replaces the translation part of
123   //! this transformation by the coordinates of the number triple Coord.
124   Standard_EXPORT void SetTranslationPart (const gp_XYZ& Coord);
125   
126   //! Assigns the vectorial and translation parts of T to this transformation.
127     void SetTrsf (const gp_Trsf& T);
128   
129
130   //! Returns true if the determinant of the vectorial part of
131   //! this transformation is negative.
132     Standard_Boolean IsNegative() const;
133   
134
135   //! Returns true if this transformation is singular (and
136   //! therefore, cannot be inverted).
137   //! Note: The Gauss LU decomposition is used to invert the
138   //! transformation matrix. Consequently, the transformation
139   //! is considered as singular if the largest pivot found is less
140   //! than or equal to gp::Resolution().
141   //! Warning
142   //! If this transformation is singular, it cannot be inverted.
143     Standard_Boolean IsSingular() const;
144   
145
146   //! Returns the nature of the transformation.  It can be an
147   //! identity transformation, a rotation, a translation, a mirror
148   //! transformation (relative to a point, an axis or a plane), a
149   //! scaling transformation, a compound transformation or
150   //! some other type of transformation.
151   gp_TrsfForm Form() const;
152   
153
154   //! verify and set the shape of the GTrsf Other or CompoundTrsf
155   //! Ex :
156   //! myGTrsf.SetValue(row1,col1,val1);
157   //! myGTrsf.SetValue(row2,col2,val2);
158   //! ...
159   //! myGTrsf.SetForm();
160   Standard_EXPORT void SetForm();
161   
162   //! Returns the translation part of the GTrsf.
163     const gp_XYZ& TranslationPart() const;
164   
165
166   //! Computes the vectorial part of the GTrsf. The returned Matrix
167   //! is a  3*3 matrix.
168     const gp_Mat& VectorialPart() const;
169   
170
171   //! Returns the coefficients of the global matrix of transformation.
172   //! Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 4
173     Standard_Real Value (const Standard_Integer Row, const Standard_Integer Col) const;
174   Standard_Real operator() (const Standard_Integer Row, const Standard_Integer Col) const
175 {
176   return Value(Row,Col);
177 }
178   
179   Standard_EXPORT void Invert();
180   
181
182   //! Computes the reverse transformation.
183   //! Raises an exception if the matrix of the transformation
184   //! is not inversible.
185   Standard_NODISCARD gp_GTrsf Inverted() const;
186   
187
188   //! Computes the transformation composed from T and <me>.
189   //! In a C++ implementation you can also write Tcomposed = <me> * T.
190   //! Example :
191   //! GTrsf T1, T2, Tcomp; ...............
192   //! //composition :
193   //! Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
194   //! // transformation of a point
195   //! XYZ P(10.,3.,4.);
196   //! XYZ P1(P);
197   //! Tcomp.Transforms(P1);               //using Tcomp
198   //! XYZ P2(P);
199   //! T1.Transforms(P2);                  //using T1 then T2
200   //! T2.Transforms(P2);                  // P1 = P2 !!!
201   Standard_NODISCARD gp_GTrsf Multiplied (const gp_GTrsf& T) const;
202   Standard_NODISCARD gp_GTrsf operator * (const gp_GTrsf& T)  const
203   {
204     return Multiplied(T);
205   }
206   
207
208   //! Computes the transformation composed with <me> and T.
209   //! <me> = <me> * T
210   Standard_EXPORT void Multiply (const gp_GTrsf& T);
211   void operator *= (const gp_GTrsf& T) 
212   {
213     Multiply(T);
214   }
215   
216
217   //! Computes the product of the transformation T and this
218   //! transformation and assigns the result to this transformation.
219   //! this = T * this
220   Standard_EXPORT void PreMultiply (const gp_GTrsf& T);
221   
222   Standard_EXPORT void Power (const Standard_Integer N);
223   
224
225   //! Computes:
226   //! -   the product of this transformation multiplied by itself
227   //! N times, if N is positive, or
228   //! -   the product of the inverse of this transformation
229   //! multiplied by itself |N| times, if N is negative.
230   //! If N equals zero, the result is equal to the Identity
231   //! transformation.
232   //! I.e.:  <me> * <me> * .......* <me>, N time.
233   //! if N =0 <me> = Identity
234   //! if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
235   //!
236   //! Raises an exception if N < 0 and if the matrix of the
237   //! transformation not inversible.
238   Standard_NODISCARD gp_GTrsf Powered (const Standard_Integer N) const;
239   
240     void Transforms (gp_XYZ& Coord) const;
241   
242   //! Transforms a triplet XYZ with a GTrsf.
243     void Transforms (Standard_Real& X, Standard_Real& Y, Standard_Real& Z) const;
244   
245     gp_Trsf Trsf() const;
246
247   //! Dumps the content of me into the stream
248   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
249
250
251
252
253 protected:
254
255
256
257
258
259 private:
260
261
262
263   gp_Mat matrix;
264   gp_XYZ loc;
265   gp_TrsfForm shape;
266   Standard_Real scale;
267
268
269 };
270
271
272 #include <gp_GTrsf.lxx>
273
274
275
276
277
278 #endif // _gp_GTrsf_HeaderFile