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_GTrsf2d_HeaderFile
16 #define _gp_GTrsf2d_HeaderFile
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
22 #include <gp_Mat2d.hxx>
24 #include <gp_TrsfForm.hxx>
25 #include <Standard_Real.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_Boolean.hxx>
28 class Standard_ConstructionError;
29 class Standard_OutOfRange;
37 //! Defines a non persistent transformation in 2D space.
38 //! This transformation is a general transformation.
39 //! It can be a Trsf2d from package gp, an affinity, or you can
40 //! define your own transformation giving the corresponding
41 //! matrix of transformation.
43 //! With a GTrsf2d you can transform only a doublet of coordinates
44 //! XY. It is not possible to transform other geometric objects
45 //! because these transformations can change the nature of non-
46 //! elementary geometric objects.
47 //! A GTrsf2d is represented with a 2 rows * 3 columns matrix :
50 //! | a11 a12 a14 | | x | | x'|
51 //! | a21 a22 a24 | | y | | y'|
52 //! | 0 0 1 | | 1 | | 1 |
54 //! where {V1, V2} defines the vectorial part of the
55 //! transformation and T defines the translation part of
56 //! the transformation.
58 //! A GTrsf2d transformation is only applicable on
59 //! coordinates. Be careful if you apply such a
60 //! transformation to all the points of a geometric object,
61 //! as this can change the nature of the object and thus
62 //! render it incoherent!
63 //! Typically, a circle is transformed into an ellipse by an
64 //! affinity transformation. To avoid modifying the nature of
65 //! an object, use a gp_Trsf2d transformation instead, as
66 //! objects of this class respect the nature of geometric objects.
74 //! returns identity transformation.
77 //! Converts the gp_Trsf2d transformation T into a
78 //! general transformation.
79 gp_GTrsf2d(const gp_Trsf2d& T);
81 //! Creates a transformation based on the matrix M and the
82 //! vector V where M defines the vectorial part of the
83 //! transformation, and V the translation part.
84 gp_GTrsf2d(const gp_Mat2d& M, const gp_XY& V);
87 //! Changes this transformation into an affinity of ratio Ratio
88 //! with respect to the axis A.
89 //! Note: An affinity is a point-by-point transformation that
90 //! transforms any point P into a point P' such that if H is
91 //! the orthogonal projection of P on the axis A, the vectors
92 //! HP and HP' satisfy: HP' = Ratio * HP.
93 Standard_EXPORT void SetAffinity (const gp_Ax2d& A, const Standard_Real Ratio);
96 //! Replaces the coefficient (Row, Col) of the matrix representing
97 //! this transformation by Value,
98 //! Raises OutOfRange if Row < 1 or Row > 2 or Col < 1 or Col > 3
99 void SetValue (const Standard_Integer Row, const Standard_Integer Col, const Standard_Real Value);
101 //! Replacesthe translation part of this
102 //! transformation by the coordinates of the number pair Coord.
103 Standard_EXPORT void SetTranslationPart (const gp_XY& Coord);
106 //! Assigns the vectorial and translation parts of T to this transformation.
107 void SetTrsf2d (const gp_Trsf2d& T);
110 //! Replaces the vectorial part of this transformation by Matrix.
111 void SetVectorialPart (const gp_Mat2d& Matrix);
114 //! Returns true if the determinant of the vectorial part of
115 //! this transformation is negative.
116 Standard_Boolean IsNegative() const;
118 //! Returns true if this transformation is singular (and
119 //! therefore, cannot be inverted).
120 //! Note: The Gauss LU decomposition is used to invert the
121 //! transformation matrix. Consequently, the transformation
122 //! is considered as singular if the largest pivot found is less
123 //! than or equal to gp::Resolution().
125 //! If this transformation is singular, it cannot be inverted.
126 Standard_Boolean IsSingular() const;
129 //! Returns the nature of the transformation. It can be
130 //! an identity transformation, a rotation, a translation, a mirror
131 //! transformation (relative to a point or axis), a scaling
132 //! transformation, a compound transformation or some
133 //! other type of transformation.
134 gp_TrsfForm Form() const;
136 //! Returns the translation part of the GTrsf2d.
137 const gp_XY& TranslationPart() const;
140 //! Computes the vectorial part of the GTrsf2d. The returned
141 //! Matrix is a 2*2 matrix.
142 const gp_Mat2d& VectorialPart() const;
145 //! Returns the coefficients of the global matrix of transformation.
146 //! Raised OutOfRange if Row < 1 or Row > 2 or Col < 1 or Col > 3
147 Standard_Real Value (const Standard_Integer Row, const Standard_Integer Col) const;
148 Standard_Real operator() (const Standard_Integer Row, const Standard_Integer Col) const
150 return Value(Row,Col);
153 Standard_EXPORT void Invert();
156 //! Computes the reverse transformation.
157 //! Raised an exception if the matrix of the transformation
158 //! is not inversible.
159 Standard_NODISCARD gp_GTrsf2d Inverted() const;
162 //! Computes the transformation composed with T and <me>.
163 //! In a C++ implementation you can also write Tcomposed = <me> * T.
165 //! GTrsf2d T1, T2, Tcomp; ...............
167 //! Tcomp = T2.Multiplied(T1); // or (Tcomp = T2 * T1)
168 //! // transformation of a point
171 //! Tcomp.Transforms(P1); //using Tcomp
173 //! T1.Transforms(P2); //using T1 then T2
174 //! T2.Transforms(P2); // P1 = P2 !!!
175 Standard_NODISCARD gp_GTrsf2d Multiplied (const gp_GTrsf2d& T) const;
176 Standard_NODISCARD gp_GTrsf2d operator * (const gp_GTrsf2d& T) const
178 return Multiplied(T);
181 Standard_EXPORT void Multiply (const gp_GTrsf2d& T);
182 void operator *= (const gp_GTrsf2d& T)
188 //! Computes the product of the transformation T and this
189 //! transformation, and assigns the result to this transformation:
191 Standard_EXPORT void PreMultiply (const gp_GTrsf2d& T);
193 Standard_EXPORT void Power (const Standard_Integer N);
196 //! Computes the following composition of transformations
197 //! <me> * <me> * .......* <me>, N time.
198 //! if N = 0 <me> = Identity
199 //! if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
201 //! Raises an exception if N < 0 and if the matrix of the
202 //! transformation is not inversible.
203 Standard_NODISCARD gp_GTrsf2d Powered (const Standard_Integer N) const;
205 void Transforms (gp_XY& Coord) const;
207 Standard_NODISCARD gp_XY Transformed (const gp_XY& Coord) const;
210 //! Applies this transformation to the coordinates:
211 //! - of the number pair Coord, or
215 //! - Transforms modifies X, Y, or the coordinate pair Coord, while
216 //! - Transformed creates a new coordinate pair.
217 void Transforms (Standard_Real& X, Standard_Real& Y) const;
220 //! Converts this transformation into a gp_Trsf2d transformation.
222 //! Standard_ConstructionError if this transformation
223 //! cannot be converted, i.e. if its form is gp_Other.
224 Standard_EXPORT gp_Trsf2d Trsf2d() const;
248 #include <gp_GTrsf2d.lxx>
254 #endif // _gp_GTrsf2d_HeaderFile