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_GTrsf_HeaderFile
16 #define _gp_GTrsf_HeaderFile
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
24 #include <gp_TrsfForm.hxx>
25 #include <Standard_Real.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_Boolean.hxx>
28 #include <gp_Trsf.hxx>
29 class Standard_ConstructionError;
30 class Standard_OutOfRange;
39 //! Defines a non-persistent transformation in 3D space.
40 //! This transformation is a general transformation.
41 //! It can be a Trsf from gp, an affinity, or you can define
42 //! your own transformation giving the matrix of transformation.
44 //! With a Gtrsf you can transform only a triplet of coordinates
45 //! XYZ. It is not possible to transform other geometric objects
46 //! because these transformations can change the nature of non-
47 //! elementary geometric objects.
48 //! The transformation GTrsf can be represented as follow :
50 //! V1 V2 V3 T XYZ XYZ
51 //! | a11 a12 a13 a14 | | x | | x'|
52 //! | a21 a22 a23 a24 | | y | | y'|
53 //! | a31 a32 a33 a34 | | z | = | z'|
54 //! | 0 0 0 1 | | 1 | | 1 |
56 //! where {V1, V2, V3} define the vectorial part of the
57 //! transformation and T defines the translation part of the
60 //! A GTrsf transformation is only applicable to
61 //! coordinates. Be careful if you apply such a
62 //! transformation to all points of a geometric object, as
63 //! this can change the nature of the object and thus
64 //! render it incoherent!
65 //! Typically, a circle is transformed into an ellipse by an
66 //! affinity transformation. To avoid modifying the nature of
67 //! an object, use a gp_Trsf transformation instead, as
68 //! objects of this class respect the nature of geometric objects.
76 //! Returns the Identity transformation.
80 //! Converts the gp_Trsf transformation T into a
81 //! general transformation, i.e. Returns a GTrsf with
82 //! the same matrix of coefficients as the Trsf T.
83 gp_GTrsf(const gp_Trsf& T);
86 //! Creates a transformation based on the matrix M and the
87 //! vector V where M defines the vectorial part of
88 //! the transformation, and V the translation part, or
89 gp_GTrsf(const gp_Mat& M, const gp_XYZ& V);
91 //! Changes this transformation into an affinity of ratio Ratio
92 //! with respect to the axis A1.
93 //! Note: an affinity is a point-by-point transformation that
94 //! transforms any point P into a point P' such that if H is
95 //! the orthogonal projection of P on the axis A1 or the
96 //! plane A2, the vectors HP and HP' satisfy:
98 void SetAffinity (const gp_Ax1& A1, const Standard_Real Ratio);
100 //! Changes this transformation into an affinity of ratio Ratio
101 //! with respect to the plane defined by the origin, the "X Direction" and
102 //! the "Y Direction" of coordinate system A2.
103 //! Note: an affinity is a point-by-point transformation that
104 //! transforms any point P into a point P' such that if H is
105 //! the orthogonal projection of P on the axis A1 or the
106 //! plane A2, the vectors HP and HP' satisfy:
107 //! HP' = Ratio * HP.
108 void SetAffinity (const gp_Ax2& A2, const Standard_Real Ratio);
111 //! Replaces the coefficient (Row, Col) of the matrix representing
112 //! this transformation by Value. Raises OutOfRange
113 //! if Row < 1 or Row > 3 or Col < 1 or Col > 4
114 void SetValue (const Standard_Integer Row, const Standard_Integer Col, const Standard_Real Value);
116 //! Replaces the vectorial part of this transformation by Matrix.
117 void SetVectorialPart (const gp_Mat& Matrix);
119 //! Replaces the translation part of
120 //! this transformation by the coordinates of the number triple Coord.
121 Standard_EXPORT void SetTranslationPart (const gp_XYZ& Coord);
123 //! Assigns the vectorial and translation parts of T to this transformation.
124 void SetTrsf (const gp_Trsf& T);
127 //! Returns true if the determinant of the vectorial part of
128 //! this transformation is negative.
129 Standard_Boolean IsNegative() const;
132 //! Returns true if this transformation is singular (and
133 //! therefore, cannot be inverted).
134 //! Note: The Gauss LU decomposition is used to invert the
135 //! transformation matrix. Consequently, the transformation
136 //! is considered as singular if the largest pivot found is less
137 //! than or equal to gp::Resolution().
139 //! If this transformation is singular, it cannot be inverted.
140 Standard_Boolean IsSingular() const;
143 //! Returns the nature of the transformation. It can be an
144 //! identity transformation, a rotation, a translation, a mirror
145 //! transformation (relative to a point, an axis or a plane), a
146 //! scaling transformation, a compound transformation or
147 //! some other type of transformation.
148 gp_TrsfForm Form() const;
151 //! verify and set the shape of the GTrsf Other or CompoundTrsf
153 //! myGTrsf.SetValue(row1,col1,val1);
154 //! myGTrsf.SetValue(row2,col2,val2);
156 //! myGTrsf.SetForm();
157 Standard_EXPORT void SetForm();
159 //! Returns the translation part of the GTrsf.
160 const gp_XYZ& TranslationPart() const;
163 //! Computes the vectorial part of the GTrsf. The returned Matrix
165 const gp_Mat& VectorialPart() const;
168 //! Returns the coefficients of the global matrix of transformation.
169 //! Raises OutOfRange if Row < 1 or Row > 3 or Col < 1 or Col > 4
170 Standard_Real Value (const Standard_Integer Row, const Standard_Integer Col) const;
171 Standard_Real operator() (const Standard_Integer Row, const Standard_Integer Col) const
173 return Value(Row,Col);
176 Standard_EXPORT void Invert();
179 //! Computes the reverse transformation.
180 //! Raises an exception if the matrix of the transformation
181 //! is not inversible.
182 gp_GTrsf Inverted() const;
185 //! Computes the transformation composed from T and <me>.
186 //! In a C++ implementation you can also write Tcomposed = <me> * T.
188 //! GTrsf T1, T2, Tcomp; ...............
190 //! Tcomp = T2.Multiplied(T1); // or (Tcomp = T2 * T1)
191 //! // transformation of a point
192 //! XYZ P(10.,3.,4.);
194 //! Tcomp.Transforms(P1); //using Tcomp
196 //! T1.Transforms(P2); //using T1 then T2
197 //! T2.Transforms(P2); // P1 = P2 !!!
198 gp_GTrsf Multiplied (const gp_GTrsf& T) const;
199 gp_GTrsf operator * (const gp_GTrsf& T) const
201 return Multiplied(T);
205 //! Computes the transformation composed with <me> and T.
207 Standard_EXPORT void Multiply (const gp_GTrsf& T);
208 void operator *= (const gp_GTrsf& T)
214 //! Computes the product of the transformation T and this
215 //! transformation and assigns the result to this transformation.
217 Standard_EXPORT void PreMultiply (const gp_GTrsf& T);
219 Standard_EXPORT void Power (const Standard_Integer N);
223 //! - the product of this transformation multiplied by itself
224 //! N times, if N is positive, or
225 //! - the product of the inverse of this transformation
226 //! multiplied by itself |N| times, if N is negative.
227 //! If N equals zero, the result is equal to the Identity
229 //! I.e.: <me> * <me> * .......* <me>, N time.
230 //! if N =0 <me> = Identity
231 //! if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
233 //! Raises an exception if N < 0 and if the matrix of the
234 //! transformation not inversible.
235 gp_GTrsf Powered (const Standard_Integer N) const;
237 void Transforms (gp_XYZ& Coord) const;
239 //! Transforms a triplet XYZ with a GTrsf.
240 void Transforms (Standard_Real& X, Standard_Real& Y, Standard_Real& Z) const;
242 gp_Trsf Trsf() const;
266 #include <gp_GTrsf.lxx>
272 #endif // _gp_GTrsf_HeaderFile