e5dd8e34754972288904545a38c140931fc89403
[occt.git] / src / gp / gp_Trsf.cdl
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 class Trsf   from gp   inherits Storable
16
17         --- Purpose: Defines a non-persistent transformation in 3D space.
18         --  The following transformations are implemented :  
19         --  . Translation, Rotation, Scale
20         --  . Symmetry with respect to a point, a line, a plane.
21         --  Complex transformations can be obtained by combining the
22         --  previous elementary transformations using the method 
23         --  Multiply.
24         --  The transformations can be represented as follow :
25         --  
26         --       V1   V2   V3    T       XYZ        XYZ
27         --    | a11  a12  a13   a14 |   | x |      | x'|
28         --    | a21  a22  a23   a24 |   | y |      | y'|
29         --    | a31  a32  a33   a34 |   | z |   =  | z'|
30         --    |  0    0    0     1  |   | 1 |      | 1 |
31         --
32         --    where {V1, V2, V3} defines the vectorial part of the
33         --    transformation and T defines the translation part of the 
34         --    transformation.
35         --  This transformation never change the nature of the objects.
36  
37
38 uses Ax1      from gp,
39      Ax2      from gp,
40      Ax3      from gp,
41      Mat      from gp,
42      Pnt      from gp,
43      TrsfForm from gp,
44      Vec      from gp,
45      XYZ      from gp,
46      Trsf2d   from gp,
47      Quaternion from gp
48
49 raises ConstructionError from Standard,
50        OutOfRange        from Standard
51
52 is
53  
54   Create   returns Trsf from gp;
55         ---C++: inline
56         --- Purpose : Returns the identity transformation.
57
58   Create(T : Trsf2d from gp) returns Trsf from gp;
59         ---Purpose: Creates  a 3D transformation from the 2D transformation T.
60         -- The resulting transformation has a homogeneous
61         -- vectorial part, V3, and a translation part, T3, built from T:
62         --       a11    a12   
63         -- 0             a13
64         -- V3 =    a21    a22    0       T3
65         -- =   a23
66         --           0    0    1.            
67         -- 0
68         -- It also has the same scale factor as T. This
69         -- guarantees (by projection) that the transformation
70         -- which would be performed by T in a plane (2D space)
71         -- is performed by the resulting transformation in the xOy
72         -- plane of the 3D space, (i.e. in the plane defined by the
73         -- origin (0., 0., 0.) and the vectors DX (1., 0., 0.), and DY
74         -- (0., 1., 0.)). The scale factor is applied to the entire space.
75
76   SetMirror (me : in out; P : Pnt)   is static;
77         ---C++: inline
78         --- Purpose :
79         --  Makes the transformation into a symmetrical transformation.
80         --  P is the center of the symmetry.
81
82
83   SetMirror (me : in out; A1 : Ax1)   is static;
84         --- Purpose :
85         --  Makes the transformation into a symmetrical transformation.
86         --  A1 is the center of the axial symmetry.
87
88
89   SetMirror (me : in out; A2 : Ax2)   is static;
90         --- Purpose :
91         --  Makes the transformation into a symmetrical transformation.
92         --  A2 is the center of the planar symmetry 
93         --  and defines the plane of symmetry by its origin, "X
94         --  Direction" and "Y Direction".
95
96
97   SetRotation (me : in out; A1 : Ax1; Ang : Real)    is static;
98         --- Purpose :
99         --  Changes the transformation into a rotation.
100         --  A1 is the rotation axis and Ang is the angular value of the 
101         --  rotation in radians.
102
103   SetRotation (me : in out; R : Quaternion) is static;
104         --- Purpose :
105         --  Changes the transformation into a rotation defined by quaternion.
106         --  Note that rotation is performed around origin, i.e. 
107         --  no translation is involved.
108   
109   SetScale (me : in out; P : Pnt; S : Real)
110         --- Purpose :
111         --  Changes the transformation into a scale.
112         --  P is the center of the scale and S is the scaling value. 
113         --  Raises ConstructionError  If <S> is null.
114   raises
115     ConstructionError from Standard
116   is static;
117
118   SetDisplacement (me : in out; FromSystem1, ToSystem2 : Ax3)   is static;
119         --- Purpose :
120         --  Modifies this transformation so that it transforms the
121         --  coordinate system defined by FromSystem1 into the
122         --  one defined by ToSystem2. After this modification, this
123         --  transformation transforms:
124         -- -   the origin of FromSystem1 into the origin of ToSystem2,
125         -- -   the "X Direction" of FromSystem1 into the "X
126         --   Direction" of ToSystem2,
127         -- -   the "Y Direction" of FromSystem1 into the "Y
128         --   Direction" of ToSystem2, and
129         -- -   the "main Direction" of FromSystem1 into the "main
130         --   Direction" of ToSystem2.
131         -- Warning
132         -- When you know the coordinates of a point in one
133         -- coordinate system and you want to express these
134         -- coordinates in another one, do not use the
135         -- transformation resulting from this function. Use the
136         -- transformation that results from SetTransformation instead.
137         -- SetDisplacement and SetTransformation create
138         -- related transformations: the vectorial part of one is the
139         -- inverse of the vectorial part of the other.
140
141
142   SetTransformation (me : in out; FromSystem1, ToSystem2 : Ax3)   is static;
143         --- Purpose : Modifies this transformation so that it transforms the
144         -- coordinates of any point, (x, y, z), relative to a source
145         -- coordinate system into the coordinates (x', y', z') which
146         -- are relative to a target coordinate system, but which
147         -- represent the same point
148         --  The transformation is from the coordinate
149         --  system "FromSystem1" to the coordinate system "ToSystem2".
150         -- Example :
151         --  In a C++ implementation :
152         --  Real x1, y1, z1;  // are the coordinates of a point in the
153         --                    // local system FromSystem1
154         --  Real x2, y2, z2;  // are the coordinates of a point in the
155         --                    // local system ToSystem2
156         --  gp_Pnt P1 (x1, y1, z1) 
157         --  Trsf T;
158         --  T.SetTransformation (FromSystem1, ToSystem2);
159         --  gp_Pnt P2 = P1.Transformed (T);
160         --  P2.Coord (x2, y2, z2);
161
162
163   SetTransformation (me : in out; ToSystem : Ax3)    is static;
164         --- Purpose : Modifies this transformation so that it transforms the
165         --  coordinates of any point, (x, y, z), relative to a source
166         --  coordinate system into the coordinates (x', y', z') which
167         --  are relative to a target coordinate system, but which
168         --  represent the same point
169         --  The transformation is from the default coordinate system
170         --  {P(0.,0.,0.), VX (1.,0.,0.), VY (0.,1.,0.), VZ (0., 0. ,1.) }
171         --  to the local coordinate system defined with the Ax3 ToSystem.
172         --  Use in the same way  as the previous method. FromSystem1 is
173         --  defaulted to the absolute coordinate system.
174
175
176   SetTransformation (me : in out; R : Quaternion; T : Vec) is static;
177         --- Purpose :
178         --  Sets transformation by directly specified rotation and translation.
179   
180   SetTranslation (me : in out; V : Vec)   is static;
181         ---C++: inline
182         --- Purpose :
183         --  Changes the transformation into a translation.
184         --  V is the vector of the translation.
185
186   SetTranslation (me : in out; P1, P2 : Pnt)   is static;
187         ---C++: inline
188         --- Purpose :
189         -- Makes the transformation into a translation where the translation vector
190         -- is the vector (P1, P2) defined from point P1 to point P2.
191
192
193   SetTranslationPart (me : in out; V : Vec)    is static;
194         --- Purpose :  Replaces the translation vector with the vector V.
195
196
197   SetScaleFactor (me : in out; S : Real) 
198         --- Purpose :  Modifies the scale factor. 
199         -- Raises ConstructionError  If S is null.
200   raises
201     ConstructionError from Standard
202   is static;
203
204   SetValues(me : in out;
205             a11, a12, a13, a14,
206             a21, a22, a23, a24,
207             a31, a32, a33, a34 : Real)
208
209         ---Purpose: Sets the coefficients  of the transformation.  The
210         --          transformation  of the  point  x,y,z is  the point
211         --          x',y',z' with :
212         --          
213         --          x' = a11 x + a12 y + a13 z + a14
214         --          y' = a21 x + a22 y + a23 z + a24
215         --          z' = a31 x + a32 y + a33 z + a34
216         --          
217         --          The method Value(i,j) will return aij.
218         --          Raises ConstructionError if the determinant of  the aij is null.
219         --          The matrix is orthogonalized before future using.
220     raises
221         ConstructionError from Standard
222
223     is static;
224      
225
226   IsNegative (me)  returns Boolean    is static;
227         ---C++: inline
228         --- Purpose : Returns true if the determinant of the vectorial part of
229         -- this transformation is negative.
230
231   Form (me)  returns TrsfForm   is static;
232         --- Purpose :
233         --  Returns the nature of the transformation. It can be: an
234         -- identity transformation, a rotation, a translation, a mirror
235         -- transformation (relative to a point, an axis or a plane), a
236         -- scaling transformation, or a compound transformation.
237         ---C++: inline
238
239   ScaleFactor (me)  returns Real   is static;
240         --- Purpose : Returns the scale factor.
241         ---C++: inline
242
243
244   TranslationPart (me)   returns XYZ   is static;
245         --- Purpose :
246         --  Returns the translation part of the transformation's matrix
247         ---C++: inline
248         ---C++: return const&
249
250   GetRotation (me; theAxis : out XYZ  from gp;
251                    theAngle: out Real from Standard)
252         returns Boolean from Standard is static;
253         --- Purpose : 
254         --  Returns the boolean True if there is non-zero rotation.
255         --  In the presence of rotation, the output parameters store the axis
256         --  and the angle of rotation. The method always returns positive
257         --  value "theAngle", i.e., 0. < theAngle <= PI. 
258         --  Note that this rotation is defined only by the vectorial part of
259         --  the transformation; generally you would need to check also the
260         --  translational part to obtain the axis (gp_Ax1) of rotation.
261
262   GetRotation (me) returns Quaternion from gp is static;
263         --- Purpose : 
264         --  Returns quaternion representing rotational part of the transformation.
265
266   VectorialPart (me)   returns Mat   is static;
267         --- Purpose : 
268         --  Returns the vectorial part of the transformation. It is 
269         --  a 3*3 matrix which includes the scale factor.
270
271
272   HVectorialPart (me)   returns Mat   is static;
273         --- Purpose : 
274         --  Computes the homogeneous vectorial part of the transformation.
275         --  It is a 3*3 matrix which doesn't include the scale factor.
276         --  In other words, the vectorial part of this transformation is equal
277         --  to its homogeneous vectorial part, multiplied by the scale factor.
278         --  The coefficients of this matrix must be multiplied by the
279         --  scale factor to obtain the coefficients of the transformation.
280         ---C++: inline
281         ---C++: return const&       
282
283
284   Value (me; Row, Col : Integer)   returns Real
285         ---C++: inline
286         --- Purpose :
287         --  Returns the coefficients of the transformation's matrix.
288         --  It is a 3 rows * 4 columns matrix.
289         --  This coefficient includes the scale factor.
290         --  Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
291      raises OutOfRange
292      is static;
293
294
295
296
297      
298   Invert (me : in out)        raises ConstructionError  is static;
299
300   Inverted (me) returns Trsf  raises ConstructionError  is static;
301         --- Purpose :
302         --  Computes the reverse transformation
303         --  Raises an exception if the matrix of the transformation
304         --  is not inversible, it means that the scale factor is lower
305         --  or equal to Resolution from package gp.
306         --  Computes the transformation composed with T and  <me>.
307         --  In a C++ implementation you can also write Tcomposed = <me> * T.
308         --- Example :
309         --      Trsf T1, T2, Tcomp; ...............
310         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
311         --        Pnt P1(10.,3.,4.);
312         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
313         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
314         --        P3.Transform(T2);                  // P3 = P2 !!!
315         ---C++: inline
316
317   Multiplied (me; T : Trsf)   returns Trsf  is static;
318         ---C++: inline
319         ---C++: alias operator *
320         --  Computes the transformation composed from T and <me>.
321         --  In a C++ implementation you can also write Tcomposed = <me> * T.
322         --  Example :
323         --      Trsf T1, T2, Tcomp; ...............
324         --      //composition :
325         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
326         --      // transformation of a point
327         --        Pnt P1(10.,3.,4.);
328         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
329         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
330         --        P3.Transform(T2);                  // P3 = P2 !!!
331
332   Multiply (me : in out; T : Trsf)          is static;
333         ---C++: alias operator *=
334         --- Purpose :
335         --  Computes the transformation composed with <me> and T.
336         --  <me> = <me> * T
337
338   PreMultiply (me : in out; T : Trsf)  is static;
339         --- Purpose :
340         --  Computes the transformation composed with <me> and T.
341         --  <me> = T * <me>
342     
343
344   Power (me : in out; N : Integer)   raises ConstructionError   is static;
345
346   Powered (me : in out; N : Integer)  returns Trsf
347         ---C++: inline
348         --- Purpose :
349         --  Computes the following composition of transformations
350         --  <me> * <me> * .......* <me>, N time.
351         --  if N = 0 <me> = Identity
352         --  if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
353         --
354         --  Raises if N < 0 and if the matrix of the transformation not
355         --  inversible.
356      raises ConstructionError
357      is static;
358
359
360     
361   Transforms (me; X, Y, Z : out Real)   is static;
362         ---C++: inline
363
364   Transforms (me; Coord : out XYZ)      is static;
365         ---C++: inline
366         --- Purpose : Transformation of a triplet XYZ with a Trsf
367
368   Orthogonalize(me: in out)
369     is protected;
370         --- Purpose : Makes orthogonalization of "matrix"
371
372 fields
373
374   scale  : Real;
375   shape  : TrsfForm;
376   matrix : Mat;
377   loc    : XYZ; 
378
379
380 friends 
381
382   class GTrsf
383
384 end;