0032137: Coding Rules - merge redundant .lxx files into header files within Package gp
[occt.git] / src / gp / gp_Pln.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_Pln_HeaderFile
16 #define _gp_Pln_HeaderFile
17
18 #include <gp_Ax1.hxx>
19 #include <gp_Ax3.hxx>
20 #include <gp_Lin.hxx>
21 #include <gp_Pnt.hxx>
22 #include <gp_Trsf.hxx>
23 #include <gp_Vec.hxx>
24 #include <Standard_ConstructionError.hxx>
25
26 //! Describes a plane.
27 //! A plane is positioned in space with a coordinate system
28 //! (a gp_Ax3 object), such that the plane is defined by the
29 //! origin, "X Direction" and "Y Direction" of this coordinate
30 //! system, which is the "local coordinate system" of the
31 //! plane. The "main Direction" of the coordinate system is a
32 //! vector normal to the plane. It gives the plane an implicit
33 //! orientation such that the plane is said to be "direct", if the
34 //! coordinate system is right-handed, or "indirect" in the other case.
35 //! Note: when a gp_Pln plane is converted into a
36 //! Geom_Plane plane, some implicit properties of its local
37 //! coordinate system are used explicitly:
38 //! -   its origin defines the origin of the two parameters of
39 //! the planar surface,
40 //! -   its implicit orientation is also that of the Geom_Plane.
41 //! See Also
42 //! gce_MakePln which provides functions for more complex
43 //! plane constructions
44 //! Geom_Plane which provides additional functions for
45 //! constructing planes and works, in particular, with the
46 //! parametric equations of planes
47 class gp_Pln 
48 {
49 public:
50
51   DEFINE_STANDARD_ALLOC
52
53   //! Creates a plane coincident with OXY plane of the
54   //! reference coordinate system.
55   gp_Pln() {}
56
57   //! The coordinate system of the plane is defined with the axis
58   //! placement theA3.
59   //! The "Direction" of theA3 defines the normal to the plane.
60   //! The "Location" of theA3 defines the location (origin) of the plane.
61   //! The "XDirection" and "YDirection" of theA3 define the "XAxis" and
62   //! the "YAxis" of the plane used to parametrize the plane.
63   gp_Pln (const gp_Ax3& theA3)
64   : pos (theA3)
65   {}
66
67   //! Creates a plane with the  "Location" point <theP>
68   //! and the normal direction <theV>.
69   Standard_EXPORT gp_Pln (const gp_Pnt& theP, const gp_Dir& theV);
70
71   //! Creates a plane from its cartesian equation :
72   //! @code
73   //! theA * X + theB * Y + theC * Z + theD = 0.0
74   //! @endcode
75   //! Raises ConstructionError if Sqrt (theA*theA + theB*theB + theC*theC) <= Resolution from gp.
76   Standard_EXPORT gp_Pln (const Standard_Real theA, const Standard_Real theB, const Standard_Real theC, const Standard_Real theD);
77
78   //! Returns the coefficients of the plane's cartesian equation :
79   //! @code
80   //! theA * X + theB * Y + theC * Z + theD = 0.
81   //! @endcode
82   void Coefficients (Standard_Real& theA, Standard_Real& theB, Standard_Real& theC, Standard_Real& theD) const;
83
84   //! Modifies this plane, by redefining its local coordinate system so that
85   //! -   its origin and "main Direction" become those of the
86   //! axis theA1 (the "X Direction" and "Y Direction" are then recomputed).
87   //! Raises ConstructionError if the theA1 is parallel to the "XAxis" of the plane.
88   void SetAxis (const gp_Ax1& theA1) { pos.SetAxis (theA1); }
89
90   //! Changes the origin of the plane.
91   void SetLocation (const gp_Pnt& theLoc) { pos.SetLocation (theLoc); }
92
93   //! Changes the local coordinate system of the plane.
94   void SetPosition (const gp_Ax3& theA3) { pos = theA3; }
95
96   //! Reverses the   U   parametrization of   the  plane
97   //! reversing the XAxis.
98   void UReverse() { pos.XReverse(); }
99
100   //! Reverses the   V   parametrization of   the  plane
101   //! reversing the YAxis.
102   void VReverse() { pos.YReverse(); }
103
104   //! returns true if the Ax3 is right handed.
105   Standard_Boolean Direct() const { return pos.Direct(); }
106
107   //! Returns the plane's normal Axis.
108   const gp_Ax1& Axis() const { return pos.Axis(); }
109
110   //! Returns the plane's location (origin).
111   const gp_Pnt& Location() const { return pos.Location(); }
112
113   //! Returns the local coordinate system of the plane .
114   const gp_Ax3& Position() const { return pos; }
115
116   //! Computes the distance between <me> and the point <theP>.
117   Standard_Real Distance (const gp_Pnt& theP) const;
118
119   //! Computes the distance between <me> and the line <theL>.
120   Standard_Real Distance (const gp_Lin& theL) const;
121
122   //! Computes the distance between two planes.
123   Standard_Real Distance (const gp_Pln& theOther) const;
124
125   //! Computes the square distance between <me> and the point <theP>.
126   Standard_Real SquareDistance (const gp_Pnt& theP) const
127   {
128     Standard_Real aD = Distance (theP);
129     return aD * aD;
130   }
131
132   //! Computes the square distance between <me> and the line <theL>.
133   Standard_Real SquareDistance (const gp_Lin& theL) const
134   {
135     Standard_Real aD = Distance (theL);
136     return aD * aD;
137   }
138
139   //! Computes the square distance between two planes.
140   Standard_Real SquareDistance (const gp_Pln& theOther) const
141   {
142     Standard_Real aD = Distance (theOther);
143     return aD * aD;
144   }
145
146   //! Returns the X axis of the plane.
147   gp_Ax1 XAxis() const { return gp_Ax1 (pos.Location(), pos.XDirection()); }
148
149   //! Returns the Y axis  of the plane.
150   gp_Ax1 YAxis() const { return gp_Ax1 (pos.Location(), pos.YDirection()); }
151
152   //! Returns true if this plane contains the point theP. This means that
153   //! -   the distance between point theP and this plane is less
154   //! than or equal to theLinearTolerance, or
155   //! -   line L is normal to the "main Axis" of the local
156   //! coordinate system of this plane, within the tolerance
157   //! AngularTolerance, and the distance between the origin
158   //! of line L and this plane is less than or equal to
159   //! theLinearTolerance.
160   Standard_Boolean Contains (const gp_Pnt& theP, const Standard_Real theLinearTolerance) const
161   {
162     return Distance (theP) <= theLinearTolerance;
163   }
164
165   //! Returns true if this plane contains the line theL. This means that
166   //! -   the distance between point P and this plane is less
167   //! than or equal to LinearTolerance, or
168   //! -   line theL is normal to the "main Axis" of the local
169   //! coordinate system of this plane, within the tolerance
170   //! theAngularTolerance, and the distance between the origin
171   //! of line theL and this plane is less than or equal to
172   //! theLinearTolerance.
173   Standard_Boolean Contains (const gp_Lin& theL, const Standard_Real theLinearTolerance, const Standard_Real theAngularTolerance) const
174   {
175     return Contains (theL.Location(), theLinearTolerance) &&
176                      pos.Direction().IsNormal (theL.Direction(), theAngularTolerance);
177   }
178
179   Standard_EXPORT void Mirror (const gp_Pnt& theP);
180
181   //! Performs the symmetrical transformation of a plane with respect
182   //! to the point <theP> which is the center of the symmetry
183   //! Warnings :
184   //! The normal direction to the plane is not changed.
185   //! The "XAxis" and the "YAxis" are reversed.
186   Standard_NODISCARD Standard_EXPORT gp_Pln Mirrored (const gp_Pnt& theP) const;
187
188   Standard_EXPORT void Mirror (const gp_Ax1& theA1);
189
190   //! Performs   the symmetrical transformation  of a
191   //! plane with respect to an axis placement  which is the axis
192   //! of  the symmetry.  The  transformation is performed on the
193   //! "Location" point, on  the "XAxis"  and the "YAxis".    The
194   //! resulting normal  direction  is  the cross product between
195   //! the "XDirection" and the "YDirection" after transformation
196   //! if  the  initial plane was right  handed,  else  it is the
197   //! opposite.
198   Standard_NODISCARD Standard_EXPORT gp_Pln Mirrored (const gp_Ax1& theA1) const;
199
200   Standard_EXPORT void Mirror (const gp_Ax2& theA2);
201
202   //! Performs the  symmetrical transformation  of  a
203   //! plane    with respect to    an axis  placement.   The axis
204   //! placement  <A2> locates the plane  of  the symmetry.   The
205   //! transformation is performed  on  the  "Location" point, on
206   //! the  "XAxis" and  the    "YAxis".  The resulting    normal
207   //! direction is the cross  product between   the "XDirection"
208   //! and the "YDirection"  after  transformation if the initial
209   //! plane was right handed, else it is the opposite.
210   Standard_NODISCARD Standard_EXPORT gp_Pln Mirrored (const gp_Ax2& theA2) const;
211
212   void Rotate (const gp_Ax1& theA1, const Standard_Real theAng) { pos.Rotate (theA1, theAng); }
213
214   //! rotates a plane. theA1 is the axis of the rotation.
215   //! theAng is the angular value of the rotation in radians.
216   Standard_NODISCARD gp_Pln Rotated (const gp_Ax1& theA1, const Standard_Real theAng) const
217   {
218     gp_Pln aPl = *this;
219     aPl.pos.Rotate (theA1, theAng);
220     return aPl;
221   }
222
223   void Scale (const gp_Pnt& theP, const Standard_Real theS) { pos.Scale (theP, theS); }
224
225   //! Scales a plane. theS is the scaling value.
226   Standard_NODISCARD gp_Pln Scaled (const gp_Pnt& theP, const Standard_Real theS) const
227   {
228     gp_Pln aPl = *this;
229     aPl.pos.Scale (theP, theS);
230     return aPl;
231   }
232
233   void Transform (const gp_Trsf& theT) { pos.Transform (theT); }
234
235   //! Transforms a plane with the transformation theT from class Trsf.
236   //! The transformation is performed on the "Location"
237   //! point, on the "XAxis" and the "YAxis".
238   //! The resulting normal direction is the cross product between
239   //! the "XDirection" and the "YDirection" after transformation.
240   Standard_NODISCARD gp_Pln Transformed (const gp_Trsf& theT) const
241   {
242     gp_Pln aPl = *this;
243     aPl.pos.Transform (theT);
244     return aPl;
245   }
246
247   void Translate (const gp_Vec& theV) { pos.Translate (theV); }
248
249   //! Translates a plane in the direction of the vector theV.
250   //! The magnitude of the translation is the vector's magnitude.
251   Standard_NODISCARD gp_Pln Translated (const gp_Vec& theV) const
252   {
253     gp_Pln aPl = *this;
254     aPl.pos.Translate (theV);
255     return aPl;
256   }
257
258    void Translate (const gp_Pnt& theP1, const gp_Pnt& theP2) { pos.Translate (theP1, theP2); }
259
260   //! Translates a plane from the point theP1 to the point theP2.
261   Standard_NODISCARD gp_Pln Translated (const gp_Pnt& theP1, const gp_Pnt& theP2) const
262   {
263     gp_Pln aPl = *this;
264     aPl.pos.Translate (theP1, theP2);
265     return aPl;
266   }
267
268   //! Dumps the content of me into the stream
269   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
270
271 private:
272
273   gp_Ax3 pos;
274
275 };
276
277 #include <gp_Lin.hxx>
278
279 //=======================================================================
280 //function : Coefficients
281 // purpose :
282 //=======================================================================
283 inline void gp_Pln::Coefficients (Standard_Real& theA,
284                                   Standard_Real& theB,
285                                   Standard_Real& theC,
286                                   Standard_Real& theD) const
287 {
288   const gp_Dir& aDir = pos.Direction();
289   if (pos.Direct())
290   {
291     theA = aDir.X();
292     theB = aDir.Y();
293     theC = aDir.Z();
294   }
295   else
296   {
297     theA = -aDir.X();
298     theB = -aDir.Y();
299     theC = -aDir.Z();
300   }
301   const gp_Pnt& aP = pos.Location();
302   theD = -(theA * aP.X() + theB * aP.Y() + theC * aP.Z());
303 }
304
305 //=======================================================================
306 //function : Distance
307 // purpose :
308 //=======================================================================
309 inline Standard_Real gp_Pln::Distance (const gp_Pnt& theP) const
310 {
311   const gp_Pnt& aLoc = pos.Location ();
312   const gp_Dir& aDir = pos.Direction();
313   Standard_Real aD = (aDir.X() * (theP.X() - aLoc.X()) +
314                       aDir.Y() * (theP.Y() - aLoc.Y()) +
315                       aDir.Z() * (theP.Z() - aLoc.Z()));
316   if (aD < 0)
317   {
318     aD = -aD;
319   }
320   return aD;
321 }
322
323 //=======================================================================
324 //function : Distance
325 // purpose :
326 //=======================================================================
327 inline Standard_Real gp_Pln::Distance (const gp_Lin& theL)  const
328 {
329   Standard_Real aD = 0.0;
330   if ((pos.Direction()).IsNormal (theL.Direction(), gp::Resolution()))
331   {
332     const gp_Pnt& aP = theL.Location();
333     const gp_Pnt& aLoc = pos.Location();
334     const gp_Dir& aDir = pos.Direction();
335     aD = (aDir.X() * (aP.X() - aLoc.X()) +
336           aDir.Y() * (aP.Y() - aLoc.Y()) +
337           aDir.Z() * (aP.Z() - aLoc.Z()));
338     if (aD < 0)
339     {
340       aD = -aD;
341     }
342   }
343   return aD;
344 }
345
346 //=======================================================================
347 //function : Distance
348 // purpose :
349 //=======================================================================
350 inline Standard_Real gp_Pln::Distance (const gp_Pln& theOther) const
351 {
352   Standard_Real aD = 0.0;
353   if ((pos.Direction()).IsParallel (theOther.pos.Direction(), gp::Resolution()))
354   {
355     const gp_Pnt& aP = theOther.pos.Location();
356     const gp_Pnt& aLoc = pos.Location ();
357     const gp_Dir& aDir = pos.Direction();
358     aD = (aDir.X() * (aP.X() - aLoc.X()) +
359           aDir.Y() * (aP.Y() - aLoc.Y()) +
360           aDir.Z() * (aP.Z() - aLoc.Z()));
361     if (aD < 0)
362     {
363       aD = -aD;
364     }
365   }
366   return aD;
367 }
368
369 #endif // _gp_Pln_HeaderFile