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