0025180: Visualization - Homogeneous transformation API in TKV3d
[occt.git] / src / Geom / Geom_Transformation.hxx
1 // Created on: 1993-03-10
2 // Created by: JCV
3 // Copyright (c) 1993-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 //
6 // This file is part of Open CASCADE Technology software library.
7 //
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
13 //
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
16
17 #ifndef _Geom_Transformation_HeaderFile
18 #define _Geom_Transformation_HeaderFile
19
20 #include <gp_Trsf.hxx>
21 #include <Standard.hxx>
22 #include <Standard_Boolean.hxx>
23 #include <Standard_Integer.hxx>
24 #include <Standard_Real.hxx>
25 #include <Standard_Type.hxx>
26 #include <Standard_Transient.hxx>
27
28 DEFINE_STANDARD_HANDLE(Geom_Transformation, Standard_Transient)
29
30 //! Describes how to construct the following elementary transformations
31 //! - translations,
32 //! - rotations,
33 //! - symmetries,
34 //! - scales.
35 //! The Transformation class can also be used to
36 //! construct complex transformations by combining these
37 //! elementary transformations.
38 //! However, these transformations can never change
39 //! the type of an object. For example, the projection
40 //! transformation can change a circle into an ellipse, and
41 //! therefore change the real type of the object. Such a
42 //! transformation is forbidden in this environment and
43 //! cannot be a Geom_Transformation.
44 //! The transformation can be represented as follow :
45 //!
46 //! V1   V2   V3    T
47 //! | a11  a12  a13   a14 |   | x |      | x'|
48 //! | a21  a22  a23   a24 |   | y |      | y'|
49 //! | a31  a32  a33   a34 |   | z |   =  | z'|
50 //! |  0    0    0     1  |   | 1 |      | 1 |
51 //!
52 //! where {V1, V2, V3} defines the vectorial part of the
53 //! transformation and T defines the translation part of
54 //! the transformation.
55 //! Note: Geom_Transformation transformations
56 //! provide the same kind of "geometric" services as
57 //! gp_Trsf ones but have more complex data structures.
58 //! The geometric objects provided by the Geom
59 //! package use gp_Trsf transformations in the syntaxes
60 //! Transform and Transformed.
61 //! Geom_Transformation transformations are used in
62 //! a context where they can be shared by several
63 //! objects contained inside a common data structure.
64 class Geom_Transformation : public Standard_Transient
65 {
66   DEFINE_STANDARD_RTTIEXT(Geom_Transformation, Standard_Transient)
67 public:
68   
69   //! Creates an identity transformation.
70   Standard_EXPORT Geom_Transformation();
71   
72   //! Creates a transient copy of T.
73   Standard_EXPORT Geom_Transformation(const gp_Trsf& T);
74
75   //! Makes the transformation into a symmetrical transformation
76   //! with respect to a point P.
77   //! P is the center of the symmetry.
78   void SetMirror (const gp_Pnt& thePnt) { gpTrsf.SetMirror (thePnt); }
79
80   //! Makes the transformation into a symmetrical transformation
81   //! with respect to an axis A1.
82   //! A1 is the center of the axial symmetry.
83   void SetMirror (const gp_Ax1& theA1) { gpTrsf.SetMirror (theA1); }
84
85   //! Makes the transformation into a symmetrical transformation
86   //! with respect to a plane.  The plane of the symmetry is
87   //! defined with the axis placement A2. It is the plane
88   //! (Location, XDirection, YDirection).
89   void SetMirror (const gp_Ax2& theA2) { gpTrsf.SetMirror (theA2); }
90
91   //! Makes the transformation into a rotation.
92   //! A1 is the axis rotation and Ang is the angular value
93   //! of the rotation in radians.
94   void SetRotation (const gp_Ax1& theA1, const Standard_Real theAng) { gpTrsf.SetRotation (theA1, theAng); }
95
96   //! Makes the transformation into a scale. P is the center of
97   //! the scale and S is the scaling value.
98   void SetScale (const gp_Pnt& thePnt, const Standard_Real theScale) { gpTrsf.SetScale (thePnt, theScale); }
99
100   //! Makes a transformation allowing passage from the coordinate
101   //! system "FromSystem1" to the coordinate system "ToSystem2".
102   //! Example :
103   //! In a C++ implementation :
104   //! Real x1, y1, z1;  // are the coordinates of a point in the
105   //! // local system FromSystem1
106   //! Real x2, y2, z2;  // are the coordinates of a point in the
107   //! // local system ToSystem2
108   //! gp_Pnt P1 (x1, y1, z1)
109   //! Geom_Transformation T;
110   //! T.SetTransformation (FromSystem1, ToSystem2);
111   //! gp_Pnt P2 = P1.Transformed (T);
112   //! P2.Coord (x2, y2, z2);
113   void SetTransformation (const gp_Ax3& theFromSystem1, const gp_Ax3& theToSystem2) { gpTrsf.SetTransformation (theFromSystem1, theToSystem2); }
114
115   //! Makes the transformation allowing passage from the basic
116   //! coordinate system
117   //! {P(0.,0.,0.), VX (1.,0.,0.), VY (0.,1.,0.), VZ (0., 0. ,1.) }
118   //! to the local coordinate system defined with the Ax2 ToSystem.
119   //! Same utilisation as the previous method. FromSystem1 is
120   //! defaulted to the absolute coordinate system.
121   void SetTransformation (const gp_Ax3& theToSystem) { gpTrsf.SetTransformation (theToSystem); }
122
123   //! Makes the transformation into a translation.
124   //! V is the vector of the translation.
125   void SetTranslation (const gp_Vec& theVec) { gpTrsf.SetTranslation (theVec); }
126
127   //! Makes the transformation into a translation from the point
128   //! P1 to the point P2.
129   void SetTranslation (const gp_Pnt& P1, const gp_Pnt& P2) { gpTrsf.SetTranslation (P1, P2); }
130
131   //! Converts the gp_Trsf transformation T into this transformation.
132   void SetTrsf (const gp_Trsf& theTrsf) { gpTrsf = theTrsf; }
133   
134   //! Checks whether this transformation is an indirect
135   //! transformation: returns true if the determinant of the
136   //! matrix of the vectorial part of the transformation is less than 0.
137   Standard_Boolean IsNegative() const { return gpTrsf.IsNegative(); }
138   
139   //! Returns the nature of this transformation as a value
140   //! of the gp_TrsfForm enumeration.
141   gp_TrsfForm Form() const { return gpTrsf.Form(); }
142
143   //! Returns the scale value of the transformation.
144   Standard_Real ScaleFactor() const { return gpTrsf.ScaleFactor(); }
145
146   //! Returns a non transient copy of <me>.
147   const gp_Trsf& Trsf() const { return gpTrsf; }
148
149   //! Returns the coefficients of the global matrix of transformation.
150   //! It is a 3 rows X 4 columns matrix.
151   //!
152   //! Raised if  Row < 1 or Row > 3  or  Col < 1 or Col > 4
153   Standard_Real Value (const Standard_Integer theRow, const Standard_Integer theCol) const { return gpTrsf.Value (theRow, theCol); }
154
155   //! Raised if the the transformation is singular. This means that
156   //! the ScaleFactor is lower or equal to Resolution from
157   //! package gp.
158   void Invert() { gpTrsf.Invert(); }
159
160   //! Raised if the the transformation is singular. This means that
161   //! the ScaleFactor is lower or equal to Resolution from
162   //! package gp.
163   Standard_EXPORT Handle(Geom_Transformation) Inverted() const;
164
165   //! Computes the transformation composed with Other and <me>.
166   //! <me> * Other.
167   //! Returns a new transformation
168   Standard_EXPORT Handle(Geom_Transformation) Multiplied (const Handle(Geom_Transformation)& Other) const;
169
170   //! Computes the transformation composed with Other and <me> .
171   //! <me> = <me> * Other.
172   void Multiply (const Handle(Geom_Transformation)& theOther) { gpTrsf.Multiply (theOther->Trsf()); }
173
174   //! Computes the following composition of transformations
175   //! if N > 0  <me> * <me> * .......* <me>.
176   //! if N = 0  Identity
177   //! if N < 0  <me>.Invert() * .........* <me>.Invert()
178   //!
179   //! Raised if N < 0 and if the transformation is not inversible
180   void Power (const Standard_Integer N) { gpTrsf.Power (N); }
181
182   //! Raised if N < 0 and if the transformation is not inversible
183   Standard_EXPORT Handle(Geom_Transformation) Powered (const Standard_Integer N) const;
184
185   //! Computes the matrix of the transformation composed with
186   //! <me> and Other.     <me> = Other * <me>
187   Standard_EXPORT void PreMultiply (const Handle(Geom_Transformation)& Other);
188
189   //! Applies the transformation <me> to the triplet {X, Y, Z}.
190   void Transforms (Standard_Real& theX, Standard_Real& theY, Standard_Real& theZ) const { gpTrsf.Transforms (theX, theY, theZ); }
191   
192   //! Creates a new object which is a copy of this transformation.
193   Standard_EXPORT Handle(Geom_Transformation) Copy() const;
194
195 private:
196
197   gp_Trsf gpTrsf;
198
199 };
200
201 #endif // _Geom_Transformation_HeaderFile