0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / gp / gp_Mat.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_Mat_HeaderFile
16 #define _gp_Mat_HeaderFile
17
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
21
22 #include <Standard_Real.hxx>
23 #include <Standard_Integer.hxx>
24 #include <Standard_Boolean.hxx>
25 class Standard_ConstructionError;
26 class Standard_OutOfRange;
27 class gp_XYZ;
28 class gp_Trsf;
29 class gp_GTrsf;
30
31
32
33 //! Describes a three column, three row matrix. This sort of
34 //! object is used in various vectorial or matrix computations.
35 class gp_Mat 
36 {
37 public:
38
39   DEFINE_STANDARD_ALLOC
40
41   
42   //! creates  a matrix with null coefficients.
43     gp_Mat();
44   
45     gp_Mat(const Standard_Real a11, const Standard_Real a12, const Standard_Real a13, const Standard_Real a21, const Standard_Real a22, const Standard_Real a23, const Standard_Real a31, const Standard_Real a32, const Standard_Real a33);
46   
47   //! Creates a matrix.
48   //! Col1, Col2, Col3 are the 3 columns of the matrix.
49   Standard_EXPORT gp_Mat(const gp_XYZ& Col1, const gp_XYZ& Col2, const gp_XYZ& Col3);
50   
51   //! Assigns the three coordinates of Value to the column of index
52   //! Col of this matrix.
53   //! Raises OutOfRange if Col < 1 or Col > 3.
54   Standard_EXPORT void SetCol (const Standard_Integer Col, const gp_XYZ& Value);
55   
56   //! Assigns the number triples Col1, Col2, Col3 to the three
57   //! columns of this matrix.
58   Standard_EXPORT void SetCols (const gp_XYZ& Col1, const gp_XYZ& Col2, const gp_XYZ& Col3);
59   
60
61   //! Modifies the matrix  M so that applying it to any number
62   //! triple (X, Y, Z) produces the same result as the cross
63   //! product of Ref and the number triple (X, Y, Z):
64   //! i.e.: M * {X,Y,Z}t = Ref.Cross({X, Y ,Z})
65   //! this matrix is anti symmetric. To apply this matrix to the
66   //! triplet  {XYZ} is the same as to do the cross product between the
67   //! triplet Ref and the triplet {XYZ}.
68   //! Note: this matrix is anti-symmetric.
69   Standard_EXPORT void SetCross (const gp_XYZ& Ref);
70   
71
72   //! Modifies the main diagonal of the matrix.
73   //! <me>.Value (1, 1) = X1
74   //! <me>.Value (2, 2) = X2
75   //! <me>.Value (3, 3) = X3
76   //! The other coefficients of the matrix are not modified.
77     void SetDiagonal (const Standard_Real X1, const Standard_Real X2, const Standard_Real X3);
78   
79
80   //! Modifies this matrix so that applying it to any number
81   //! triple (X, Y, Z) produces the same result as the scalar
82   //! product of Ref and the number triple (X, Y, Z):
83   //! this * (X,Y,Z) = Ref.(X,Y,Z)
84   //! Note: this matrix is symmetric.
85   Standard_EXPORT void SetDot (const gp_XYZ& Ref);
86   
87   //! Modifies this matrix so that it represents the Identity matrix.
88     void SetIdentity();
89   
90
91   //! Modifies this matrix so that it represents a rotation. Ang is the angular value in
92   //! radians and the XYZ axis gives the direction of the
93   //! rotation.
94   //! Raises ConstructionError if XYZ.Modulus() <= Resolution()
95   Standard_EXPORT void SetRotation (const gp_XYZ& Axis, const Standard_Real Ang);
96   
97   //! Assigns the three coordinates of Value to the row of index
98   //! Row of this matrix. Raises OutOfRange if Row < 1 or Row > 3.
99   Standard_EXPORT void SetRow (const Standard_Integer Row, const gp_XYZ& Value);
100   
101   //! Assigns the number triples Row1, Row2, Row3 to the three
102   //! rows of this matrix.
103   Standard_EXPORT void SetRows (const gp_XYZ& Row1, const gp_XYZ& Row2, const gp_XYZ& Row3);
104   
105
106   //! Modifies the the matrix so that it represents
107   //! a scaling transformation, where S is the scale factor. :
108   //! | S    0.0  0.0 |
109   //! <me> =  | 0.0   S   0.0 |
110   //! | 0.0  0.0   S  |
111     void SetScale (const Standard_Real S);
112   
113   //! Assigns <Value> to the coefficient of row Row, column Col of   this matrix.
114   //! Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
115     void SetValue (const Standard_Integer Row, const Standard_Integer Col, const Standard_Real Value);
116   
117   //! Returns the column of Col index.
118   //! Raises OutOfRange if Col < 1 or Col > 3
119   Standard_EXPORT gp_XYZ Column (const Standard_Integer Col) const;
120   
121   //! Computes the determinant of the matrix.
122     Standard_Real Determinant() const;
123   
124   //! Returns the main diagonal of the matrix.
125   Standard_EXPORT gp_XYZ Diagonal() const;
126   
127   //! returns the row of Row index.
128   //! Raises OutOfRange if Row < 1 or Row > 3
129   Standard_EXPORT gp_XYZ Row (const Standard_Integer Row) const;
130   
131   //! Returns the coefficient of range (Row, Col)
132   //! Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
133     const Standard_Real& Value (const Standard_Integer Row, const Standard_Integer Col) const;
134   const Standard_Real& operator() (const Standard_Integer Row, const Standard_Integer Col) const
135 {
136   return Value(Row,Col);
137 }
138   
139   //! Returns the coefficient of range (Row, Col)
140   //! Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
141     Standard_Real& ChangeValue (const Standard_Integer Row, const Standard_Integer Col);
142   Standard_Real& operator() (const Standard_Integer Row, const Standard_Integer Col)
143 {
144   return ChangeValue(Row,Col);
145 }
146   
147
148   //! The Gauss LU decomposition is used to invert the matrix
149   //! (see Math package) so the matrix is considered as singular if
150   //! the largest pivot found is lower or equal to Resolution from gp.
151     Standard_Boolean IsSingular() const;
152   
153     void Add (const gp_Mat& Other);
154   void operator += (const gp_Mat& Other)
155 {
156   Add(Other);
157 }
158   
159   //! Computes the sum of this matrix and
160   //! the matrix Other for each coefficient of the matrix :
161   //! <me>.Coef(i,j) + <Other>.Coef(i,j)
162   Standard_NODISCARD gp_Mat Added (const gp_Mat& Other) const;
163   Standard_NODISCARD gp_Mat operator + (const gp_Mat& Other) const
164 {
165   return Added(Other);
166 }
167   
168     void Divide (const Standard_Real Scalar);
169   void operator /= (const Standard_Real Scalar)
170 {
171   Divide(Scalar);
172 }
173   
174   //! Divides all the coefficients of the matrix by Scalar
175   Standard_NODISCARD gp_Mat Divided (const Standard_Real Scalar) const;
176   Standard_NODISCARD gp_Mat operator / (const Standard_Real Scalar) const
177 {
178   return Divided(Scalar);
179 }
180   
181   Standard_EXPORT void Invert();
182   
183
184   //! Inverses the matrix and raises if the matrix is singular.
185   //! -   Invert assigns the result to this matrix, while
186   //! -   Inverted creates a new one.
187   //! Warning
188   //! The Gauss LU decomposition is used to invert the matrix.
189   //! Consequently, the matrix is considered as singular if the
190   //! largest pivot found is less than or equal to gp::Resolution().
191   //! Exceptions
192   //! Standard_ConstructionError if this matrix is singular,
193   //! and therefore cannot be inverted.
194   Standard_NODISCARD Standard_EXPORT gp_Mat Inverted() const;
195   
196
197   //! Computes  the product of two matrices <me> * <Other>
198   Standard_NODISCARD gp_Mat Multiplied (const gp_Mat& Other) const;
199   Standard_NODISCARD gp_Mat operator * (const gp_Mat& Other) const
200 {
201   return Multiplied(Other);
202 }
203   
204   //! Computes the product of two matrices <me> = <Other> * <me>.
205     void Multiply (const gp_Mat& Other);
206   void operator *= (const gp_Mat& Other)
207 {
208   Multiply(Other);
209 }
210   
211     void PreMultiply (const gp_Mat& Other);
212   
213     Standard_NODISCARD gp_Mat Multiplied (const Standard_Real Scalar) const;
214   Standard_NODISCARD gp_Mat operator * (const Standard_Real Scalar) const
215 {
216   return Multiplied(Scalar);
217 }
218   
219
220   //! Multiplies all the coefficients of the matrix by Scalar
221     void Multiply (const Standard_Real Scalar);
222   void operator *= (const Standard_Real Scalar)
223 {
224   Multiply(Scalar);
225 }
226   
227   Standard_EXPORT void Power (const Standard_Integer N);
228   
229
230   //! Computes <me> = <me> * <me> * .......* <me>,   N time.
231   //! if N = 0 <me> = Identity
232   //! if N < 0 <me> = <me>.Invert() *...........* <me>.Invert().
233   //! If N < 0 an exception will be raised if the matrix is not
234   //! inversible
235   Standard_NODISCARD gp_Mat Powered (const Standard_Integer N) const;
236   
237     void Subtract (const gp_Mat& Other);
238   void operator -= (const gp_Mat& Other)
239 {
240   Subtract(Other);
241 }
242   
243
244   //! cOmputes for each coefficient of the matrix :
245   //! <me>.Coef(i,j) - <Other>.Coef(i,j)
246   Standard_NODISCARD gp_Mat Subtracted (const gp_Mat& Other) const;
247   Standard_NODISCARD gp_Mat operator - (const gp_Mat& Other) const
248 {
249   return Subtracted(Other);
250 }
251   
252     void Transpose();
253   
254
255   //! Transposes the matrix. A(j, i) -> A (i, j)
256     Standard_NODISCARD gp_Mat Transposed() const;
257
258   //! Dumps the content of me into the stream
259   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
260
261
262 friend class gp_XYZ;
263 friend class gp_Trsf;
264 friend class gp_GTrsf;
265
266
267 protected:
268
269
270
271
272
273 private:
274
275
276
277   Standard_Real matrix[3][3];
278
279
280 };
281
282
283 #include <gp_Mat.lxx>
284
285
286
287
288
289 #endif // _gp_Mat_HeaderFile