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
 259 friend class gp_XYZ;
 260 friend class gp_Trsf;
 261 friend class gp_GTrsf;
 262
 263
 264 protected:
 265
 266
 267
 268
 269
 270 private:
 271
 272
 273
 274   Standard_Real matrix[3][3];
 275
 276
 277 };
 278
 279
 280 #include <gp_Mat.lxx>
 281
 282
 283
 284
 285
 286 #endif // _gp_Mat_HeaderFile