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