path: root/src/gp/gp_Mat.cdl

---Copyright:   Matra Datavision 1991
                     
class Mat   from gp  inherits Storable
   ---Purpose:
   -- Describes a three column, three row matrix. This sort of
   -- object is used in various vectorial or matrix computations.
        
uses XYZ     from gp,
     Address from Standard

raises ConstructionError from Standard,
       OutOfRange        from Standard

is


  Create  returns Mat;
        --- Purpose : creates  a matrix with null coefficients.
    	---C++: inline


  Create(a11,a12,a13,a21,a22,a23,a31,a32,a33: Real from Standard);
    	---C++: inline

  Create (Col1, Col2, Col3 : XYZ)   returns Mat;
        --- Purpose : Creates a matrix.
        --  Col1, Col2, Col3 are the 3 columns of the matrix.


  SetCol (me : in out; Col : Integer; Value : XYZ)
        --- Purpose : Assigns the three coordinates of Value to the column of index
        --   Col of this matrix. 
        -- Raises OutOfRange if Col < 1 or Col > 3.
     raises OutOfRange
     is static;


  SetCols (me : in out; Col1, Col2, Col3 : XYZ)     is static;
        --- Purpose : Assigns the number triples Col1, Col2, Col3 to the three
        --   columns of this matrix.


  SetCross (me : in out; Ref : XYZ)    is static;
        --- Purpose :
        --  Modifies the matrix  M so that applying it to any number
    	-- triple (X, Y, Z) produces the same result as the cross
    	-- product of Ref and the number triple (X, Y, Z):
        -- i.e.: M * {X,Y,Z}t = Ref.Cross({X, Y ,Z})
        --  this matrix is anti symmetric. To apply this matrix to the 
        --  triplet  {XYZ} is the same as to do the cross product between the
        --  triplet Ref and the triplet {XYZ}.
    	-- Note: this matrix is anti-symmetric.

  SetDiagonal (me : in out; X1, X2, X3 : Real)    is static;
       ---C++: inline
       --- Purpose : 
       --  Modifies the main diagonal of the matrix.
       --  <me>.Value (1, 1) = X1
       --  <me>.Value (2, 2) = X2
       --  <me>.Value (3, 3) = X3
       --  The other coefficients of the matrix are not modified.

  SetDot (me : in out; Ref : XYZ)   is static;
       --- Purpose :
       --  Modifies this matrix so that applying it to any number
       -- triple (X, Y, Z) produces the same result as the scalar
       -- product of Ref and the number triple (X, Y, Z):
       -- this * (X,Y,Z) = Ref.(X,Y,Z)
       -- Note: this matrix is symmetric.


  SetIdentity (me : in out)    is static;
    	---C++: inline
        --- Purpose : Modifies this matrix so that it represents the Identity matrix.

  SetRotation (me : in out; Axis : XYZ; Ang : Real)
        --- Purpose :
        --  Modifies this matrix so that it represents a rotation. Ang is the angular value in 
        --  radians and the XYZ axis gives the direction of the
        --  rotation. 
        --  Raises ConstructionError if XYZ.Modulus() <= Resolution()
     raises ConstructionError
     is static;


  SetRow (me : in out; Row : Integer; Value : XYZ)
        --- Purpose : Assigns the three coordinates of Value to the row of index
    	--   Row of this matrix. Raises OutOfRange if Row < 1 or Row > 3.
     raises OutOfRange
     is static;


  SetRows (me : in out; Row1, Row2, Row3 : XYZ)    is static;
        --- Purpose : Assigns the number triples Row1, Row2, Row3 to the three
    	--   rows of this matrix.


  SetScale (me : in out; S : Real)     is static;
       ---C++: inline
       --- Purpose :
       --  Modifies the the matrix so that it represents 
       -- a scaling transformation, where S is the scale factor. :
       --           | S    0.0  0.0 |
       --   <me> =  | 0.0   S   0.0 |
       --           | 0.0  0.0   S  |

  SetValue (me : in out; Row, Col : Integer; Value : Real)
    	---C++: inline
        --- Purpose : Assigns <Value> to the coefficient of row Row, column Col of   this matrix.  
        -- Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
     raises OutOfRange
     is static;



  Column (me; Col : Integer)   returns XYZ
        --- Purpose : Returns the column of Col index.  
        --   Raises OutOfRange if Col < 1 or Col > 3
     raises OutOfRange
     is static;


  Determinant (me)   returns Real     is static;
    	---C++: inline
        --- Purpose : Computes the determinant of the matrix.


  Diagonal (me)  returns XYZ    is static;
        --- Purpose : Returns the main diagonal of the matrix.


  Row (me; Row : Integer)  returns XYZ
        --- Purpose : returns the row of Row index.  
        --  Raises OutOfRange if Row < 1 or Row > 3 
     raises OutOfRange
     is static;


  Value (me; Row, Col : Integer)  returns Real
        ---C++: inline
    	---C++: return const &
     	---C++: alias operator() 
        --- Purpose : Returns the coefficient of range (Row, Col)
	--  Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
     raises OutOfRange
     --
     is static;


  ChangeValue (me : in out; Row, Col : Integer)  returns Real
    	---C++: inline
    	---C++: return &
    	---C++: alias operator()   
        --- Purpose : Returns the coefficient of range (Row, Col)
        --  Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
     raises OutOfRange
     --
     is static;


  IsSingular (me)   returns Boolean   is static;
	---C++: inline
        --- Purpose :
        --  The Gauss LU decomposition is used to invert the matrix 
        --  (see Math package) so the matrix is considered as singular if
        --  the largest pivot found is lower or equal to Resolution from gp.





  Add (me : in out; Other : Mat)    is static;
    	---C++: inline
        ---C++: alias operator +=

  Added (me; Other : Mat)   returns Mat   is static;
    	---C++: inline
        ---C++: alias operator +
        --- Purpose : Computes the sum of this matrix and
        --  the matrix Other for each coefficient of the matrix :
        --  <me>.Coef(i,j) + <Other>.Coef(i,j)



     
  Divide (me : in out; Scalar : Real)    is static;
    	---C++: inline
        ---C++: alias operator /=

  Divided (me; Scalar : Real)   returns Mat     is static;
    	---C++: inline
        ---C++: alias operator /
        --- Purpose : Divides all the coefficients of the matrix by Scalar



    
  Invert (me : in out)   raises ConstructionError   is static;

  Inverted (me)  returns Mat    raises ConstructionError   is static;
        --- Purpose :
        --  Inverses the matrix and raises if the matrix is singular.
        -- -   Invert assigns the result to this matrix, while
        -- -   Inverted creates a new one.
        -- Warning
        -- The Gauss LU decomposition is used to invert the matrix.
        -- Consequently, the matrix is considered as singular if the
        -- largest pivot found is less than or equal to gp::Resolution().
        -- Exceptions
        -- Standard_ConstructionError if this matrix is singular,
        -- and therefore cannot be inverted.


  Multiplied (me; Other : Mat)   returns Mat    is static;
    	---C++: inline    
        ---C++: alias operator *
        --- Purpose :
        --  Computes  the product of two matrices <me> * <Other>

  Multiply (me : in out; Other : Mat)           is static;
    	---C++: inline
        ---C++: alias operator *=
    	---Purpose: Computes the product of two matrices <me> = <Other> * <me>.

  PreMultiply (me : in out; Other : Mat)        is static;
    	---C++: inline     
    	--Purpose : 
    	-- Modifies this matrix by premultiplying it by the matrix
    	-- Other:
    	-- this = Other * this
    	-- Computes the product of two matrices <me> = <Other> * <me>.
     
     
   

  Multiplied (me; Scalar : Real)   returns Mat    is static;
    	---C++: inline
        ---C++: alias operator *

  Multiply (me : in out; Scalar : Real)           is static;
    	---C++: inline
        ---C++: alias operator *=
     	--- Purpose :
        --  Multiplies all the coefficients of the matrix by Scalar

  Power (me : in out; N : Integer)   raises ConstructionError   is static;

  Powered (me; N : Integer)  returns Mat  raises ConstructionError  is static;
	---C++: inline
    	--- Purpose :
        --  Computes <me> = <me> * <me> * .......* <me>,   N time.
        --  if N = 0 <me> = Identity
        --  if N < 0 <me> = <me>.Invert() *...........* <me>.Invert().
        --  If N < 0 an exception will be raised if the matrix is not
        --  inversible

   

  Subtract (me : in out; Other : Mat)        is static;
      	---C++: inline
        ---C++: alias operator -=

  Subtracted (me; Other : Mat)  returns Mat  is static;
    	---C++: inline
        ---C++: alias operator -
     	--- Purpose :
        --  cOmputes for each coefficient of the matrix :
        --  <me>.Coef(i,j) - <Other>.Coef(i,j)

  Transpose (me : in out)        is static;
      	---C++: inline

  Transposed (me)  returns Mat   
      	---C++: inline
        --- Purpose : 
        --  Transposes the matrix. A(j, i) -> A (i, j)
     is static;

fields

  matrix : Real[3, 3];

friends
  class XYZ    from gp,
  class Trsf   from gp,
  class GTrsf  from gp

end;