0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / gp / gp_Ax3.hxx
1 // Created on: 1993-08-02
2 // Created by: Laurent BOURESCHE
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 _gp_Ax3_HeaderFile
18 #define _gp_Ax3_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <gp_Ax1.hxx>
25 #include <gp_Dir.hxx>
26 #include <Standard_Real.hxx>
27 #include <Standard_Boolean.hxx>
28 class Standard_ConstructionError;
29 class gp_Ax2;
30 class gp_Pnt;
31 class gp_Dir;
32 class gp_Ax1;
33 class gp_Trsf;
34 class gp_Vec;
35
36
37 //! Describes a coordinate system in 3D space. Unlike a
38 //! gp_Ax2 coordinate system, a gp_Ax3 can be
39 //! right-handed ("direct sense") or left-handed ("indirect sense").
40 //! A coordinate system is defined by:
41 //! -   its origin (also referred to as its "Location point"), and
42 //! -   three orthogonal unit vectors, termed the "X
43 //! Direction", the "Y Direction" and the "Direction" (also
44 //! referred to as the "main Direction").
45 //! The "Direction" of the coordinate system is called its
46 //! "main Direction" because whenever this unit vector is
47 //! modified, the "X Direction" and the "Y Direction" are
48 //! recomputed. However, when we modify either the "X
49 //! Direction" or the "Y Direction", "Direction" is not modified.
50 //! "Direction" is also the "Z Direction".
51 //! The "main Direction" is always parallel to the cross
52 //! product of its "X Direction" and "Y Direction".
53 //! If the coordinate system is right-handed, it satisfies the equation:
54 //! "main Direction" = "X Direction" ^ "Y Direction"
55 //! and if it is left-handed, it satisfies the equation:
56 //! "main Direction" = -"X Direction" ^ "Y Direction"
57 //! A coordinate system is used:
58 //! -   to describe geometric entities, in particular to position
59 //! them. The local coordinate system of a geometric
60 //! entity serves the same purpose as the STEP function
61 //! "axis placement three axes", or
62 //! -   to define geometric transformations.
63 //! Note:
64 //! -   We refer to the "X Axis", "Y Axis" and "Z Axis",
65 //! respectively, as the axes having:
66 //! -   the origin of the coordinate system as their origin, and
67 //! -   the unit vectors "X Direction", "Y Direction" and
68 //! "main Direction", respectively, as their unit vectors.
69 //! -   The "Z Axis" is also the "main Axis".
70 //! -   gp_Ax2 is used to define a coordinate system that must be always right-handed.
71 class gp_Ax3 
72 {
73 public:
74
75   DEFINE_STANDARD_ALLOC
76
77   
78   //! Creates an object corresponding to the reference
79   //! coordinate system (OXYZ).
80   gp_Ax3();
81   
82   //! Creates  a  coordinate  system from a right-handed
83   //! coordinate system.
84   gp_Ax3(const gp_Ax2& A);
85   
86   //! Creates a  right handed axis placement with the
87   //! "Location"  point  P  and  two  directions, N    gives the
88   //! "Direction" and Vx gives the "XDirection".
89   //! Raises ConstructionError if N and Vx are parallel (same or opposite orientation).
90   gp_Ax3(const gp_Pnt& P, const gp_Dir& N, const gp_Dir& Vx);
91   
92
93   //! Creates an axis placement with the  "Location" point <P>
94   //! and the normal direction <V>.
95   Standard_EXPORT gp_Ax3(const gp_Pnt& P, const gp_Dir& V);
96   
97   //! Reverses the X direction of <me>.
98   void XReverse();
99   
100   //! Reverses the Y direction of <me>.
101   void YReverse();
102   
103   //! Reverses the Z direction of <me>.
104   void ZReverse();
105   
106   //! Assigns the origin and "main Direction" of the axis A1 to
107   //! this coordinate system, then recomputes its "X Direction" and "Y Direction".
108   //! Note:
109   //! -   The new "X Direction" is computed as follows:
110   //! new "X Direction" = V1 ^(previous "X Direction" ^ V)
111   //! where V is the "Direction" of A1.
112   //! -   The orientation of this coordinate system
113   //! (right-handed or left-handed) is not modified.
114   //! Raises ConstructionError  if the "Direction" of <A1> and the "XDirection" of <me>
115   //! are parallel (same or opposite orientation) because it is
116   //! impossible to calculate the new "XDirection" and the new
117   //! "YDirection".
118   void SetAxis (const gp_Ax1& A1);
119   
120
121   //! Changes the main direction of this coordinate system,
122   //! then recomputes its "X Direction" and "Y Direction".
123   //! Note:
124   //! -   The new "X Direction" is computed as follows:
125   //! new "X Direction" = V ^ (previous "X Direction" ^ V).
126   //! -   The orientation of this coordinate system (left- or right-handed) is not modified.
127   //! Raises ConstructionError if <V< and the previous "XDirection" are parallel
128   //! because it is impossible to calculate the new "XDirection"
129   //! and the new "YDirection".
130   void SetDirection (const gp_Dir& V);
131   
132
133   //! Changes the "Location" point (origin) of <me>.
134   void SetLocation (const gp_Pnt& P);
135   
136
137   //! Changes the "Xdirection" of <me>. The main direction
138   //! "Direction" is not modified, the "Ydirection" is modified.
139   //! If <Vx> is not normal to the main direction then <XDirection>
140   //! is computed as follows XDirection = Direction ^ (Vx ^ Direction).
141   //! Raises ConstructionError if <Vx> is parallel (same or opposite
142   //! orientation) to the main direction of <me>
143   void SetXDirection (const gp_Dir& Vx);
144   
145
146   //! Changes the "Ydirection" of <me>. The main direction is not
147   //! modified but the "Xdirection" is changed.
148   //! If <Vy> is not normal to the main direction then "YDirection"
149   //! is computed as  follows
150   //! YDirection = Direction ^ (<Vy> ^ Direction).
151   //! Raises ConstructionError if <Vy> is parallel to the main direction of <me>
152     void SetYDirection (const gp_Dir& Vy);
153   
154
155   //! Computes the angular value between the main direction of
156   //! <me> and the main direction of <Other>. Returns the angle
157   //! between 0 and PI in radians.
158     Standard_Real Angle (const gp_Ax3& Other) const;
159   
160
161   //! Returns the main axis of <me>. It is the "Location" point
162   //! and the main "Direction".
163     const gp_Ax1& Axis() const;
164   
165   //! Computes a right-handed coordinate system with the
166   //! same "X Direction" and "Y Direction" as those of this
167   //! coordinate system, then recomputes the "main Direction".
168   //! If this coordinate system is right-handed, the result
169   //! returned is the same coordinate system. If this
170   //! coordinate system is left-handed, the result is reversed.
171   gp_Ax2 Ax2() const;
172   
173
174   //! Returns the main direction of <me>.
175     const gp_Dir& Direction() const;
176   
177
178   //! Returns the "Location" point (origin) of <me>.
179     const gp_Pnt& Location() const;
180   
181
182   //! Returns the "XDirection" of <me>.
183     const gp_Dir& XDirection() const;
184   
185
186   //! Returns the "YDirection" of <me>.
187     const gp_Dir& YDirection() const;
188   
189   //! Returns  True if  the  coordinate  system is right-handed. i.e.
190   //! XDirection().Crossed(YDirection()).Dot(Direction()) > 0
191     Standard_Boolean Direct() const;
192   
193
194   //! Returns True if
195   //! . the distance between the "Location" point of <me> and
196   //! <Other> is lower or equal to LinearTolerance and
197   //! . the distance between the "Location" point of <Other> and
198   //! <me> is lower or equal to LinearTolerance and
199   //! . the main direction of <me> and the main direction of
200   //! <Other> are parallel (same or opposite orientation).
201     Standard_Boolean IsCoplanar (const gp_Ax3& Other, const Standard_Real LinearTolerance, const Standard_Real AngularTolerance) const;
202   
203   //! Returns True if
204   //! . the distance between <me> and the "Location" point of A1
205   //! is lower of equal to LinearTolerance and
206   //! . the distance between A1 and the "Location" point of <me>
207   //! is lower or equal to LinearTolerance and
208   //! . the main direction of <me> and the direction of A1 are normal.
209     Standard_Boolean IsCoplanar (const gp_Ax1& A1, const Standard_Real LinearTolerance, const Standard_Real AngularTolerance) const;
210   
211   Standard_EXPORT void Mirror (const gp_Pnt& P);
212   
213
214   //! Performs the symmetrical transformation of an axis
215   //! placement with respect to the point P which is the
216   //! center of the symmetry.
217   //! Warnings :
218   //! The main direction of the axis placement is not changed.
219   //! The "XDirection" and the "YDirection" are reversed.
220   //! So the axis placement stay right handed.
221   Standard_NODISCARD Standard_EXPORT gp_Ax3 Mirrored (const gp_Pnt& P) const;
222   
223   Standard_EXPORT void Mirror (const gp_Ax1& A1);
224   
225
226   //! Performs the symmetrical transformation of an axis
227   //! placement with respect to an axis placement which
228   //! is the axis of the symmetry.
229   //! The transformation is performed on the "Location"
230   //! point, on the "XDirection" and "YDirection".
231   //! The resulting main "Direction" is the cross product between
232   //! the "XDirection" and the "YDirection" after transformation.
233   Standard_NODISCARD Standard_EXPORT gp_Ax3 Mirrored (const gp_Ax1& A1) const;
234   
235   Standard_EXPORT void Mirror (const gp_Ax2& A2);
236   
237
238   //! Performs the symmetrical transformation of an axis
239   //! placement with respect to a plane.
240   //! The axis placement  <A2> locates the plane of the symmetry :
241   //! (Location, XDirection, YDirection).
242   //! The transformation is performed on the "Location"
243   //! point, on the "XDirection" and "YDirection".
244   //! The resulting main "Direction" is the cross product between
245   //! the "XDirection" and the "YDirection" after transformation.
246   Standard_NODISCARD Standard_EXPORT gp_Ax3 Mirrored (const gp_Ax2& A2) const;
247   
248   void Rotate (const gp_Ax1& A1, const Standard_Real Ang);
249   
250
251   //! Rotates an axis placement. <A1> is the axis of the
252   //! rotation . Ang is the angular value of the rotation
253   //! in radians.
254   Standard_NODISCARD gp_Ax3 Rotated (const gp_Ax1& A1, const Standard_Real Ang) const;
255   
256   void Scale (const gp_Pnt& P, const Standard_Real S);
257   
258
259   //! Applies a scaling transformation on the axis placement.
260   //! The "Location" point of the axisplacement is modified.
261   //! Warnings :
262   //! If the scale <S> is negative :
263   //! . the main direction of the axis placement is not changed.
264   //! . The "XDirection" and the "YDirection" are reversed.
265   //! So the axis placement stay right handed.
266   Standard_NODISCARD gp_Ax3 Scaled (const gp_Pnt& P, const Standard_Real S) const;
267   
268   void Transform (const gp_Trsf& T);
269   
270
271   //! Transforms an axis placement with a Trsf.
272   //! The "Location" point, the "XDirection" and the
273   //! "YDirection" are transformed with T.  The resulting
274   //! main "Direction" of <me> is the cross product between
275   //! the "XDirection" and the "YDirection" after transformation.
276   Standard_NODISCARD gp_Ax3 Transformed (const gp_Trsf& T) const;
277   
278   void Translate (const gp_Vec& V);
279   
280
281   //! Translates an axis plaxement in the direction of the vector
282   //! <V>. The magnitude of the translation is the vector's magnitude.
283   Standard_NODISCARD gp_Ax3 Translated (const gp_Vec& V) const;
284   
285   void Translate (const gp_Pnt& P1, const gp_Pnt& P2);
286   
287
288   //! Translates an axis placement from the point <P1> to the
289   //! point <P2>.
290   Standard_NODISCARD gp_Ax3 Translated (const gp_Pnt& P1, const gp_Pnt& P2) const;
291
292
293   //! Dumps the content of me into the stream
294   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
295
296
297
298 protected:
299
300
301
302
303
304 private:
305
306
307
308   gp_Ax1 axis;
309   gp_Dir vydir;
310   gp_Dir vxdir;
311
312
313 };
314
315
316 #include <gp_Ax3.lxx>
317
318
319
320
321
322 #endif // _gp_Ax3_HeaderFile