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 #ifndef _gp_Trsf_HeaderFile
16 #define _gp_Trsf_HeaderFile
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
22 #include <Standard_Real.hxx>
23 #include <gp_TrsfForm.hxx>
26 #include <Standard_Boolean.hxx>
27 #include <Standard_Integer.hxx>
28 class Standard_ConstructionError;
29 class Standard_OutOfRange;
42 //! Defines a non-persistent transformation in 3D space.
43 //! The following transformations are implemented :
44 //! . Translation, Rotation, Scale
45 //! . Symmetry with respect to a point, a line, a plane.
46 //! Complex transformations can be obtained by combining the
47 //! previous elementary transformations using the method
49 //! The transformations can be represented as follow :
51 //! V1 V2 V3 T XYZ XYZ
52 //! | a11 a12 a13 a14 | | x | | x'|
53 //! | a21 a22 a23 a24 | | y | | y'|
54 //! | a31 a32 a33 a34 | | z | = | z'|
55 //! | 0 0 0 1 | | 1 | | 1 |
57 //! where {V1, V2, V3} defines the vectorial part of the
58 //! transformation and T defines the translation part of the
60 //! This transformation never change the nature of the objects.
68 //! Returns the identity transformation.
71 //! Creates a 3D transformation from the 2D transformation T.
72 //! The resulting transformation has a homogeneous
73 //! vectorial part, V3, and a translation part, T3, built from T:
80 //! It also has the same scale factor as T. This
81 //! guarantees (by projection) that the transformation
82 //! which would be performed by T in a plane (2D space)
83 //! is performed by the resulting transformation in the xOy
84 //! plane of the 3D space, (i.e. in the plane defined by the
85 //! origin (0., 0., 0.) and the vectors DX (1., 0., 0.), and DY
86 //! (0., 1., 0.)). The scale factor is applied to the entire space.
87 Standard_EXPORT gp_Trsf(const gp_Trsf2d& T);
90 //! Makes the transformation into a symmetrical transformation.
91 //! P is the center of the symmetry.
92 void SetMirror (const gp_Pnt& P);
95 //! Makes the transformation into a symmetrical transformation.
96 //! A1 is the center of the axial symmetry.
97 Standard_EXPORT void SetMirror (const gp_Ax1& A1);
100 //! Makes the transformation into a symmetrical transformation.
101 //! A2 is the center of the planar symmetry
102 //! and defines the plane of symmetry by its origin, "X
103 //! Direction" and "Y Direction".
104 Standard_EXPORT void SetMirror (const gp_Ax2& A2);
107 //! Changes the transformation into a rotation.
108 //! A1 is the rotation axis and Ang is the angular value of the
109 //! rotation in radians.
110 Standard_EXPORT void SetRotation (const gp_Ax1& A1, const Standard_Real Ang);
113 //! Changes the transformation into a rotation defined by quaternion.
114 //! Note that rotation is performed around origin, i.e.
115 //! no translation is involved.
116 Standard_EXPORT void SetRotation (const gp_Quaternion& R);
119 //! Changes the transformation into a scale.
120 //! P is the center of the scale and S is the scaling value.
121 //! Raises ConstructionError If <S> is null.
122 Standard_EXPORT void SetScale (const gp_Pnt& P, const Standard_Real S);
125 //! Modifies this transformation so that it transforms the
126 //! coordinate system defined by FromSystem1 into the
127 //! one defined by ToSystem2. After this modification, this
128 //! transformation transforms:
129 //! - the origin of FromSystem1 into the origin of ToSystem2,
130 //! - the "X Direction" of FromSystem1 into the "X
131 //! Direction" of ToSystem2,
132 //! - the "Y Direction" of FromSystem1 into the "Y
133 //! Direction" of ToSystem2, and
134 //! - the "main Direction" of FromSystem1 into the "main
135 //! Direction" of ToSystem2.
137 //! When you know the coordinates of a point in one
138 //! coordinate system and you want to express these
139 //! coordinates in another one, do not use the
140 //! transformation resulting from this function. Use the
141 //! transformation that results from SetTransformation instead.
142 //! SetDisplacement and SetTransformation create
143 //! related transformations: the vectorial part of one is the
144 //! inverse of the vectorial part of the other.
145 Standard_EXPORT void SetDisplacement (const gp_Ax3& FromSystem1, const gp_Ax3& ToSystem2);
147 //! Modifies this transformation so that it transforms the
148 //! coordinates of any point, (x, y, z), relative to a source
149 //! coordinate system into the coordinates (x', y', z') which
150 //! are relative to a target coordinate system, but which
151 //! represent the same point
152 //! The transformation is from the coordinate
153 //! system "FromSystem1" to the coordinate system "ToSystem2".
155 //! In a C++ implementation :
156 //! Real x1, y1, z1; // are the coordinates of a point in the
157 //! // local system FromSystem1
158 //! Real x2, y2, z2; // are the coordinates of a point in the
159 //! // local system ToSystem2
160 //! gp_Pnt P1 (x1, y1, z1)
162 //! T.SetTransformation (FromSystem1, ToSystem2);
163 //! gp_Pnt P2 = P1.Transformed (T);
164 //! P2.Coord (x2, y2, z2);
165 Standard_EXPORT void SetTransformation (const gp_Ax3& FromSystem1, const gp_Ax3& ToSystem2);
167 //! Modifies this transformation so that it transforms the
168 //! coordinates of any point, (x, y, z), relative to a source
169 //! coordinate system into the coordinates (x', y', z') which
170 //! are relative to a target coordinate system, but which
171 //! represent the same point
172 //! The transformation is from the default coordinate system
173 //! {P(0.,0.,0.), VX (1.,0.,0.), VY (0.,1.,0.), VZ (0., 0. ,1.) }
174 //! to the local coordinate system defined with the Ax3 ToSystem.
175 //! Use in the same way as the previous method. FromSystem1 is
176 //! defaulted to the absolute coordinate system.
177 Standard_EXPORT void SetTransformation (const gp_Ax3& ToSystem);
180 //! Sets transformation by directly specified rotation and translation.
181 Standard_EXPORT void SetTransformation (const gp_Quaternion& R, const gp_Vec& T);
184 //! Changes the transformation into a translation.
185 //! V is the vector of the translation.
186 void SetTranslation (const gp_Vec& V);
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 void SetTranslation (const gp_Pnt& P1, const gp_Pnt& P2);
193 //! Replaces the translation vector with the vector V.
194 Standard_EXPORT void SetTranslationPart (const gp_Vec& V);
196 //! Modifies the scale factor.
197 //! Raises ConstructionError If S is null.
198 Standard_EXPORT void SetScaleFactor (const Standard_Real S);
200 Standard_EXPORT void SetForm (const gp_TrsfForm P);
202 //! Sets the coefficients of the transformation. The
203 //! transformation of the point x,y,z is the point
206 //! x' = a11 x + a12 y + a13 z + a14
207 //! y' = a21 x + a22 y + a23 z + a24
208 //! z' = a31 x + a32 y + a33 z + a34
210 //! The method Value(i,j) will return aij.
211 //! Raises ConstructionError if the determinant of the aij is null.
212 //! The matrix is orthogonalized before future using.
213 Standard_EXPORT void SetValues (const Standard_Real a11, const Standard_Real a12, const Standard_Real a13, const Standard_Real a14, const Standard_Real a21, const Standard_Real a22, const Standard_Real a23, const Standard_Real a24, const Standard_Real a31, const Standard_Real a32, const Standard_Real a33, const Standard_Real a34);
215 //! Returns true if the determinant of the vectorial part of
216 //! this transformation is negative.
217 Standard_Boolean IsNegative() const;
220 //! Returns the nature of the transformation. It can be: an
221 //! identity transformation, a rotation, a translation, a mirror
222 //! transformation (relative to a point, an axis or a plane), a
223 //! scaling transformation, or a compound transformation.
224 gp_TrsfForm Form() const;
226 //! Returns the scale factor.
227 Standard_Real ScaleFactor() const;
230 //! Returns the translation part of the transformation's matrix
231 const gp_XYZ& TranslationPart() const;
234 //! Returns the boolean True if there is non-zero rotation.
235 //! In the presence of rotation, the output parameters store the axis
236 //! and the angle of rotation. The method always returns positive
237 //! value "theAngle", i.e., 0. < theAngle <= PI.
238 //! Note that this rotation is defined only by the vectorial part of
239 //! the transformation; generally you would need to check also the
240 //! translational part to obtain the axis (gp_Ax1) of rotation.
241 Standard_EXPORT Standard_Boolean GetRotation (gp_XYZ& theAxis, Standard_Real& theAngle) const;
244 //! Returns quaternion representing rotational part of the transformation.
245 Standard_EXPORT gp_Quaternion GetRotation() const;
248 //! Returns the vectorial part of the transformation. It is
249 //! a 3*3 matrix which includes the scale factor.
250 Standard_EXPORT gp_Mat VectorialPart() const;
253 //! Computes the homogeneous vectorial part of the transformation.
254 //! It is a 3*3 matrix which doesn't include the scale factor.
255 //! In other words, the vectorial part of this transformation is equal
256 //! to its homogeneous vectorial part, multiplied by the scale factor.
257 //! The coefficients of this matrix must be multiplied by the
258 //! scale factor to obtain the coefficients of the transformation.
259 const gp_Mat& HVectorialPart() const;
262 //! Returns the coefficients of the transformation's matrix.
263 //! It is a 3 rows * 4 columns matrix.
264 //! This coefficient includes the scale factor.
265 //! Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
266 Standard_Real Value (const Standard_Integer Row, const Standard_Integer Col) const;
268 Standard_EXPORT void Invert();
271 //! Computes the reverse transformation
272 //! Raises an exception if the matrix of the transformation
273 //! is not inversible, it means that the scale factor is lower
274 //! or equal to Resolution from package gp.
275 //! Computes the transformation composed with T and <me>.
276 //! In a C++ implementation you can also write Tcomposed = <me> * T.
278 //! Trsf T1, T2, Tcomp; ...............
279 //! Tcomp = T2.Multiplied(T1); // or (Tcomp = T2 * T1)
280 //! Pnt P1(10.,3.,4.);
281 //! Pnt P2 = P1.Transformed(Tcomp); //using Tcomp
282 //! Pnt P3 = P1.Transformed(T1); //using T1 then T2
283 //! P3.Transform(T2); // P3 = P2 !!!
284 gp_Trsf Inverted() const;
286 gp_Trsf Multiplied (const gp_Trsf& T) const;
287 gp_Trsf operator * (const gp_Trsf& T) const
289 return Multiplied(T);
293 //! Computes the transformation composed with <me> and T.
295 Standard_EXPORT void Multiply (const gp_Trsf& T);
296 void operator *= (const gp_Trsf& T)
302 //! Computes the transformation composed with <me> and T.
304 Standard_EXPORT void PreMultiply (const gp_Trsf& T);
306 Standard_EXPORT void Power (const Standard_Integer N);
309 //! Computes the following composition of transformations
310 //! <me> * <me> * .......* <me>, N time.
311 //! if N = 0 <me> = Identity
312 //! if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
314 //! Raises if N < 0 and if the matrix of the transformation not
316 gp_Trsf Powered (const Standard_Integer N) const;
318 void Transforms (Standard_Real& X, Standard_Real& Y, Standard_Real& Z) const;
320 //! Transformation of a triplet XYZ with a Trsf
321 void Transforms (gp_XYZ& Coord) const;
324 friend class gp_GTrsf;
330 //! Makes orthogonalization of "matrix"
331 Standard_EXPORT void Orthogonalize();
349 #include <gp_Trsf.lxx>
355 #endif // _gp_Trsf_HeaderFile