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