[occt.git] / src / gp / gp_Mat.cdl

-- Copyright (c) 1991-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class Mat   from gp
   ---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;
Commit	Line	Data
b311480e	1	-- Copyright (c) 1991-1999 Matra Datavision
973c2be1	2	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	3	--
973c2be1	4	-- This file is part of Open CASCADE Technology software library.
b311480e	5	--
d5f74e42	6	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	7	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	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.
b311480e	11	--
973c2be1	12	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	13	-- commercial license or contractual agreement.
b311480e	14
087da3bd	15	class Mat from gp
7fd59977	16	---Purpose:
	17	-- Describes a three column, three row matrix. This sort of
	18	-- object is used in various vectorial or matrix computations.
	19
	20	uses XYZ from gp,
	21	Address from Standard
	22
	23	raises ConstructionError from Standard,
	24	OutOfRange from Standard
	25
	26	is
	27
	28
	29	Create returns Mat;
	30	--- Purpose : creates a matrix with null coefficients.
	31	---C++: inline
	32
	33
	34	Create(a11,a12,a13,a21,a22,a23,a31,a32,a33: Real from Standard);
	35	---C++: inline
	36
	37	Create (Col1, Col2, Col3 : XYZ) returns Mat;
	38	--- Purpose : Creates a matrix.
	39	-- Col1, Col2, Col3 are the 3 columns of the matrix.
	40
	41
	42	SetCol (me : in out; Col : Integer; Value : XYZ)
	43	--- Purpose : Assigns the three coordinates of Value to the column of index
	44	-- Col of this matrix.
	45	-- Raises OutOfRange if Col < 1 or Col > 3.
	46	raises OutOfRange
	47	is static;
	48
	49
	50	SetCols (me : in out; Col1, Col2, Col3 : XYZ) is static;
	51	--- Purpose : Assigns the number triples Col1, Col2, Col3 to the three
	52	-- columns of this matrix.
	53
	54
	55	SetCross (me : in out; Ref : XYZ) is static;
	56	--- Purpose :
	57	-- Modifies the matrix M so that applying it to any number
	58	-- triple (X, Y, Z) produces the same result as the cross
	59	-- product of Ref and the number triple (X, Y, Z):
	60	-- i.e.: M * {X,Y,Z}t = Ref.Cross({X, Y ,Z})
	61	-- this matrix is anti symmetric. To apply this matrix to the
	62	-- triplet {XYZ} is the same as to do the cross product between the
	63	-- triplet Ref and the triplet {XYZ}.
	64	-- Note: this matrix is anti-symmetric.
	65
	66	SetDiagonal (me : in out; X1, X2, X3 : Real) is static;
	67	---C++: inline
	68	--- Purpose :
	69	-- Modifies the main diagonal of the matrix.
	70	-- <me>.Value (1, 1) = X1
	71	-- <me>.Value (2, 2) = X2
	72	-- <me>.Value (3, 3) = X3
	73	-- The other coefficients of the matrix are not modified.
	74
	75	SetDot (me : in out; Ref : XYZ) is static;
	76	--- Purpose :
	77	-- Modifies this matrix so that applying it to any number
	78	-- triple (X, Y, Z) produces the same result as the scalar
	79	-- product of Ref and the number triple (X, Y, Z):
80	-- this * (X,Y,Z) = Ref.(X,Y,Z)
81	-- Note: this matrix is symmetric.
82
83
84	SetIdentity (me : in out) is static;
85	---C++: inline
86	--- Purpose : Modifies this matrix so that it represents the Identity matrix.
87
88	SetRotation (me : in out; Axis : XYZ; Ang : Real)
89	--- Purpose :
90	-- Modifies this matrix so that it represents a rotation. Ang is the angular value in
91	-- radians and the XYZ axis gives the direction of the
92	-- rotation.
93	-- Raises ConstructionError if XYZ.Modulus() <= Resolution()
94	raises ConstructionError
95	is static;
96
97
98	SetRow (me : in out; Row : Integer; Value : XYZ)
99	--- Purpose : Assigns the three coordinates of Value to the row of index
100	-- Row of this matrix. Raises OutOfRange if Row < 1 or Row > 3.
101	raises OutOfRange
102	is static;
103
104
105	SetRows (me : in out; Row1, Row2, Row3 : XYZ) is static;
106	--- Purpose : Assigns the number triples Row1, Row2, Row3 to the three
107	-- rows of this matrix.
108
109
110	SetScale (me : in out; S : Real) is static;
111	---C++: inline
112	--- Purpose :
113	-- Modifies the the matrix so that it represents
114	-- a scaling transformation, where S is the scale factor. :
115	-- \| S 0.0 0.0 \|
116	-- <me> = \| 0.0 S 0.0 \|
117	-- \| 0.0 0.0 S \|
118
119	SetValue (me : in out; Row, Col : Integer; Value : Real)
120	---C++: inline
121	--- Purpose : Assigns <Value> to the coefficient of row Row, column Col of this matrix.
122	-- Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
123	raises OutOfRange
124	is static;
125
126
127
128	Column (me; Col : Integer) returns XYZ
129	--- Purpose : Returns the column of Col index.
130	-- Raises OutOfRange if Col < 1 or Col > 3
131	raises OutOfRange
132	is static;
133
134
135	Determinant (me) returns Real is static;
136	---C++: inline
137	--- Purpose : Computes the determinant of the matrix.
138
139
140	Diagonal (me) returns XYZ is static;
141	--- Purpose : Returns the main diagonal of the matrix.
142
143
144	Row (me; Row : Integer) returns XYZ
145	--- Purpose : returns the row of Row index.
146	-- Raises OutOfRange if Row < 1 or Row > 3
147	raises OutOfRange
148	is static;
149
150
151	Value (me; Row, Col : Integer) returns Real
152	---C++: inline
153	---C++: return const &
154	---C++: alias operator()
155	--- Purpose : Returns the coefficient of range (Row, Col)
156	-- Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
157	raises OutOfRange
158	--
159	is static;
160
161
162	ChangeValue (me : in out; Row, Col : Integer) returns Real
163	---C++: inline
164	---C++: return &
165	---C++: alias operator()
166	--- Purpose : Returns the coefficient of range (Row, Col)
167	-- Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 3
168	raises OutOfRange
169	--
170	is static;
171
172
173	IsSingular (me) returns Boolean is static;
174	---C++: inline
175	--- Purpose :
176	-- The Gauss LU decomposition is used to invert the matrix
177	-- (see Math package) so the matrix is considered as singular if
178	-- the largest pivot found is lower or equal to Resolution from gp.
179
180
181
182
183
184	Add (me : in out; Other : Mat) is static;
185	---C++: inline
186	---C++: alias operator +=
187
188	Added (me; Other : Mat) returns Mat is static;
189	---C++: inline
190	---C++: alias operator +
191	--- Purpose : Computes the sum of this matrix and
192	-- the matrix Other for each coefficient of the matrix :
193	-- <me>.Coef(i,j) + <Other>.Coef(i,j)
194
195
196
197
198	Divide (me : in out; Scalar : Real) is static;
199	---C++: inline
200	---C++: alias operator /=
201
202	Divided (me; Scalar : Real) returns Mat is static;
203	---C++: inline
204	---C++: alias operator /
205	--- Purpose : Divides all the coefficients of the matrix by Scalar
206
207
208
209
210	Invert (me : in out) raises ConstructionError is static;
211
212	Inverted (me) returns Mat raises ConstructionError is static;
213	--- Purpose :
214	-- Inverses the matrix and raises if the matrix is singular.
215	-- - Invert assigns the result to this matrix, while
216	-- - Inverted creates a new one.
217	-- Warning
218	-- The Gauss LU decomposition is used to invert the matrix.
219	-- Consequently, the matrix is considered as singular if the
220	-- largest pivot found is less than or equal to gp::Resolution().
221	-- Exceptions
222	-- Standard_ConstructionError if this matrix is singular,
223	-- and therefore cannot be inverted.
224
225
226	Multiplied (me; Other : Mat) returns Mat is static;
227	---C++: inline
228	---C++: alias operator *
229	--- Purpose :
230	-- Computes the product of two matrices <me> * <Other>
231
232	Multiply (me : in out; Other : Mat) is static;
233	---C++: inline
234	---C++: alias operator *=
235	---Purpose: Computes the product of two matrices <me> = <Other> * <me>.
236
237	PreMultiply (me : in out; Other : Mat) is static;
238	---C++: inline
239	--Purpose :
240	-- Modifies this matrix by premultiplying it by the matrix
241	-- Other:
242	-- this = Other * this
243	-- Computes the product of two matrices <me> = <Other> * <me>.
244
245
246
247
248	Multiplied (me; Scalar : Real) returns Mat is static;
249	---C++: inline
250	---C++: alias operator *
251
252	Multiply (me : in out; Scalar : Real) is static;
253	---C++: inline
254	---C++: alias operator *=
255	--- Purpose :
256	-- Multiplies all the coefficients of the matrix by Scalar
257
258	Power (me : in out; N : Integer) raises ConstructionError is static;
259
260	Powered (me; N : Integer) returns Mat raises ConstructionError is static;
261	---C++: inline
262	--- Purpose :
263	-- Computes <me> = <me> * <me> * .......* <me>, N time.
264	-- if N = 0 <me> = Identity
265	-- if N < 0 <me> = <me>.Invert() ........... <me>.Invert().
266	-- If N < 0 an exception will be raised if the matrix is not
267	-- inversible
268
269
270
271	Subtract (me : in out; Other : Mat) is static;
272	---C++: inline
273	---C++: alias operator -=
274
275	Subtracted (me; Other : Mat) returns Mat is static;
276	---C++: inline
277	---C++: alias operator -
278	--- Purpose :
279	-- cOmputes for each coefficient of the matrix :
280	-- <me>.Coef(i,j) - <Other>.Coef(i,j)
281
282	Transpose (me : in out) is static;
283	---C++: inline
284
285	Transposed (me) returns Mat
286	---C++: inline
287	--- Purpose :
288	-- Transposes the matrix. A(j, i) -> A (i, j)
289	is static;
290
291	fields
292
293	matrix : Real[3, 3];
294
295	friends
296	class XYZ from gp,
297	class Trsf from gp,
298	class GTrsf from gp
299
300	end;