1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
4 -- This file is part of Open CASCADE Technology software library.
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.
12 -- Alternatively, this file may be used under the terms of Open CASCADE
13 -- commercial license or contractual agreement.
15 class Trsf from gp inherits Storable
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
24 -- The transformations can be represented as follow :
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 |
32 -- where {V1, V2, V3} defines the vectorial part of the
33 -- transformation and T defines the translation part of the
35 -- This transformation never change the nature of the objects.
49 raises ConstructionError from Standard,
50 OutOfRange from Standard
54 Create returns Trsf from gp;
56 --- Purpose : Returns the identity transformation.
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:
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.
76 SetMirror (me : in out; P : Pnt) is static;
79 -- Makes the transformation into a symmetrical transformation.
80 -- P is the center of the symmetry.
83 SetMirror (me : in out; A1 : Ax1) is static;
85 -- Makes the transformation into a symmetrical transformation.
86 -- A1 is the center of the axial symmetry.
89 SetMirror (me : in out; A2 : Ax2) is static;
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".
97 SetRotation (me : in out; A1 : Ax1; Ang : Real) is static;
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.
103 SetRotation (me : in out; R : Quaternion) is static;
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.
109 SetScale (me : in out; P : Pnt; S : Real)
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.
115 ConstructionError from Standard
118 SetDisplacement (me : in out; FromSystem1, ToSystem2 : Ax3) is static;
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.
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.
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".
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)
158 -- T.SetTransformation (FromSystem1, ToSystem2);
159 -- gp_Pnt P2 = P1.Transformed (T);
160 -- P2.Coord (x2, y2, z2);
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.
176 SetTransformation (me : in out; R : Quaternion; T : Vec) is static;
178 -- Sets transformation by directly specified rotation and translation.
180 SetTranslation (me : in out; V : Vec) is static;
183 -- Changes the transformation into a translation.
184 -- V is the vector of the translation.
186 SetTranslation (me : in out; P1, P2 : Pnt) is static;
189 -- Makes the transformation into a translation where the translation vector
190 -- is the vector (P1, P2) defined from point P1 to point P2.
193 SetTranslationPart (me : in out; V : Vec) is static;
194 --- Purpose : Replaces the translation vector with the vector V.
197 SetScaleFactor (me : in out; S : Real)
198 --- Purpose : Modifies the scale factor.
199 -- Raises ConstructionError If S is null.
201 ConstructionError from Standard
204 SetValues(me : in out;
207 a31, a32, a33, a34 : Real;
208 Tolang, TolDist : Real)
210 ---Purpose: Sets the coefficients of the transformation. The
211 -- transformation of the point x,y,z is the point
214 -- x' = a11 x + a12 y + a13 z + a14
215 -- y' = a21 x + a22 y + a23 z + a24
216 -- z' = a31 x + a32 y + a43 z + a34
218 -- Tolang and TolDist are used to test for null
219 -- angles and null distances to determine the form of
220 -- the transformation (identity, translation, etc..).
222 -- The method Value(i,j) will return aij.
223 -- Raises ConstructionError if the determinant of the aij is null. Or if
224 -- the matrix as not a uniform scale.
227 ConstructionError from Standard
232 IsNegative (me) returns Boolean is static;
234 --- Purpose : Returns true if the determinant of the vectorial part of
235 -- this transformation is negative.
237 Form (me) returns TrsfForm is static;
239 -- Returns the nature of the transformation. It can be: an
240 -- identity transformation, a rotation, a translation, a mirror
241 -- transformation (relative to a point, an axis or a plane), a
242 -- scaling transformation, or a compound transformation.
245 ScaleFactor (me) returns Real is static;
246 --- Purpose : Returns the scale factor.
250 TranslationPart (me) returns XYZ is static;
252 -- Returns the translation part of the transformation's matrix
254 ---C++: return const&
256 GetRotation (me; theAxis : out XYZ from gp;
257 theAngle: out Real from Standard)
258 returns Boolean from Standard is static;
260 -- Returns the boolean True if there is non-zero rotation.
261 -- In the presence of rotation, the output parameters store the axis
262 -- and the angle of rotation. The method always returns positive
263 -- value "theAngle", i.e., 0. < theAngle <= PI.
264 -- Note that this rotation is defined only by the vectorial part of
265 -- the transformation; generally you would need to check also the
266 -- translational part to obtain the axis (gp_Ax1) of rotation.
268 GetRotation (me) returns Quaternion from gp is static;
270 -- Returns quaternion representing rotational part of the transformation.
272 VectorialPart (me) returns Mat is static;
274 -- Returns the vectorial part of the transformation. It is
275 -- a 3*3 matrix which includes the scale factor.
278 HVectorialPart (me) returns Mat is static;
280 -- Computes the homogeneous vectorial part of the transformation.
281 -- It is a 3*3 matrix which doesn't include the scale factor.
282 -- In other words, the vectorial part of this transformation is equal
283 -- to its homogeneous vectorial part, multiplied by the scale factor.
284 -- The coefficients of this matrix must be multiplied by the
285 -- scale factor to obtain the coefficients of the transformation.
287 ---C++: return const&
290 Value (me; Row, Col : Integer) returns Real
293 -- Returns the coefficients of the transformation's matrix.
294 -- It is a 3 rows * 4 columns matrix.
295 -- This coefficient includes the scale factor.
296 -- Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
304 Invert (me : in out) raises ConstructionError is static;
306 Inverted (me) returns Trsf raises ConstructionError is static;
308 -- Computes the reverse transformation
309 -- Raises an exception if the matrix of the transformation
310 -- is not inversible, it means that the scale factor is lower
311 -- or equal to Resolution from package gp.
312 -- Computes the transformation composed with T and <me>.
313 -- In a C++ implementation you can also write Tcomposed = <me> * T.
315 -- Trsf T1, T2, Tcomp; ...............
316 -- Tcomp = T2.Multiplied(T1); // or (Tcomp = T2 * T1)
317 -- Pnt P1(10.,3.,4.);
318 -- Pnt P2 = P1.Transformed(Tcomp); //using Tcomp
319 -- Pnt P3 = P1.Transformed(T1); //using T1 then T2
320 -- P3.Transform(T2); // P3 = P2 !!!
323 Multiplied (me; T : Trsf) returns Trsf is static;
325 ---C++: alias operator *
327 Multiply (me : in out; T : Trsf) is static;
328 ---C++: alias operator *=
330 -- Computes the transformation composed with T and <me>.
331 -- In a C++ implementation you can also write Tcomposed = <me> * T.
333 -- Trsf T1, T2, Tcomp; ...............
335 -- Tcomp = T2.Multiplied(T1); // or (Tcomp = T2 * T1)
336 -- // transformation of a point
337 -- Pnt P1(10.,3.,4.);
338 -- Pnt P2 = P1.Transformed(Tcomp); //using Tcomp
339 -- Pnt P3 = P1.Transformed(T1); //using T1 then T2
340 -- P3.Transform(T2); // P3 = P2 !!!
341 -- Computes the transformation composed with <me> and T.
344 PreMultiply (me : in out; T : Trsf) is static;
346 -- Computes the transformation composed with <me> and T.
350 Power (me : in out; N : Integer) raises ConstructionError is static;
352 Powered (me : in out; N : Integer) returns Trsf
355 -- Computes the following composition of transformations
356 -- <me> * <me> * .......* <me>, N time.
357 -- if N = 0 <me> = Identity
358 -- if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
360 -- Raises if N < 0 and if the matrix of the transformation not
362 raises ConstructionError
367 Transforms (me; X, Y, Z : out Real) is static;
370 Transforms (me; Coord : out XYZ) is static;
372 --- Purpose : Transformation of a triplet XYZ with a Trsf