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_Hypr_HeaderFile
16 #define _gp_Hypr_HeaderFile
22 #include <Standard_DomainError.hxx>
23 #include <Standard_ConstructionError.hxx>
25 //! Describes a branch of a hyperbola in 3D space.
26 //! A hyperbola is defined by its major and minor radii and
27 //! positioned in space with a coordinate system (a gp_Ax2
29 //! - the origin is the center of the hyperbola,
30 //! - the "X Direction" defines the major axis of the
32 //! - the "Y Direction" defines the minor axis of the hyperbola.
33 //! The origin, "X Direction" and "Y Direction" of this
34 //! coordinate system together define the plane of the
35 //! hyperbola. This coordinate system is the "local
36 //! coordinate system" of the hyperbola. In this coordinate
37 //! system, the equation of the hyperbola is:
38 //! X*X/(MajorRadius**2)-Y*Y/(MinorRadius**2) = 1.0
39 //! The branch of the hyperbola described is the one located
40 //! on the positive side of the major axis.
41 //! The "main Direction" of the local coordinate system is a
42 //! normal vector to the plane of the hyperbola. This vector
43 //! gives an implicit orientation to the hyperbola. We refer to
44 //! the "main Axis" of the local coordinate system as the
45 //! "Axis" of the hyperbola.
46 //! The following schema shows the plane of the hyperbola,
47 //! and in it, the respective positions of the three branches of
48 //! hyperbolas constructed with the functions OtherBranch,
49 //! ConjugateBranch1, and ConjugateBranch2:
53 //! FirstConjugateBranch
56 //! --------------------- C ------------------------------>XAxis
60 //! SecondConjugateBranch
64 //! The major radius can be less than the minor radius.
66 //! gce_MakeHypr which provides functions for more
67 //! complex hyperbola constructions
68 //! Geom_Hyperbola which provides additional functions for
69 //! constructing hyperbolas and works, in particular, with the
70 //! parametric equations of hyperbolas
77 //! Creates of an indefinite hyperbola.
79 : majorRadius (RealLast()),
80 minorRadius (RealFirst())
83 //! Creates a hyperbola with radius theMajorRadius and
84 //! theMinorRadius, positioned in the space by the
85 //! coordinate system theA2 such that:
86 //! - the origin of theA2 is the center of the hyperbola,
87 //! - the "X Direction" of theA2 defines the major axis of
88 //! the hyperbola, that is, the major radius
89 //! theMajorRadius is measured along this axis, and
90 //! - the "Y Direction" of theA2 defines the minor axis of
91 //! the hyperbola, that is, the minor radius
92 //! theMinorRadius is measured along this axis.
93 //! Note: This class does not prevent the creation of a
95 //! - theMajorAxis is equal to theMinorAxis, or
96 //! - theMajorAxis is less than theMinorAxis.
98 //! Standard_ConstructionError if theMajorAxis or theMinorAxis is negative.
99 //! Raises ConstructionError if theMajorRadius < 0.0 or theMinorRadius < 0.0
100 //! Raised if theMajorRadius < 0.0 or theMinorRadius < 0.0
101 gp_Hypr (const gp_Ax2& theA2, const Standard_Real theMajorRadius, const Standard_Real theMinorRadius)
103 majorRadius (theMajorRadius),
104 minorRadius (theMinorRadius)
106 Standard_ConstructionError_Raise_if (theMinorRadius < 0.0 || theMajorRadius < 0.0,
107 "gp_Hypr() - invalid construction parameters");
110 //! Modifies this hyperbola, by redefining its local coordinate
112 //! - its origin and "main Direction" become those of the
113 //! axis theA1 (the "X Direction" and "Y Direction" are then
114 //! recomputed in the same way as for any gp_Ax2).
115 //! Raises ConstructionError if the direction of theA1 is parallel to the direction of
116 //! the "XAxis" of the hyperbola.
117 void SetAxis (const gp_Ax1& theA1) { pos.SetAxis (theA1); }
119 //! Modifies this hyperbola, by redefining its local coordinate
120 //! system so that its origin becomes theP.
121 void SetLocation (const gp_Pnt& theP) { pos = gp_Ax2 (theP, pos.Direction(), pos.XDirection()); }
123 //! Modifies the major radius of this hyperbola.
125 //! Standard_ConstructionError if theMajorRadius is negative.
126 void SetMajorRadius (const Standard_Real theMajorRadius)
128 Standard_ConstructionError_Raise_if (theMajorRadius < 0.0,
129 "gp_Hypr::SetMajorRadius() - major radius should be greater or equal zero");
130 majorRadius = theMajorRadius;
133 //! Modifies the minor radius of this hyperbola.
135 //! Standard_ConstructionError if theMinorRadius is negative.
136 void SetMinorRadius (const Standard_Real theMinorRadius)
138 Standard_ConstructionError_Raise_if (theMinorRadius < 0.0,
139 "gp_Hypr::SetMinorRadius() - minor radius should be greater or equal zero");
140 minorRadius = theMinorRadius;
143 //! Modifies this hyperbola, by redefining its local coordinate
144 //! system so that it becomes A2.
145 void SetPosition (const gp_Ax2& theA2) { pos = theA2; }
147 //! In the local coordinate system of the hyperbola the equation of
148 //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
149 //! equation of the first asymptote is Y = (B/A)*X
150 //! where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
151 gp_Ax1 Asymptote1() const;
153 //! In the local coordinate system of the hyperbola the equation of
154 //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
155 //! equation of the first asymptote is Y = -(B/A)*X.
156 //! where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
157 gp_Ax1 Asymptote2() const;
159 //! Returns the axis passing through the center,
160 //! and normal to the plane of this hyperbola.
161 const gp_Ax1& Axis() const { return pos.Axis(); }
163 //! Computes the branch of hyperbola which is on the positive side of the
165 gp_Hypr ConjugateBranch1() const
167 return gp_Hypr (gp_Ax2 (pos.Location(), pos.Direction(), pos.YDirection()), minorRadius, majorRadius);
170 //! Computes the branch of hyperbola which is on the negative side of the
172 gp_Hypr ConjugateBranch2() const
174 gp_Dir aD = pos.YDirection();
176 return gp_Hypr (gp_Ax2(pos.Location(), pos.Direction(), aD), minorRadius, majorRadius);
179 //! This directrix is the line normal to the XAxis of the hyperbola
180 //! in the local plane (Z = 0) at a distance d = MajorRadius / e
181 //! from the center of the hyperbola, where e is the eccentricity of
183 //! This line is parallel to the "YAxis". The intersection point
184 //! between the directrix1 and the "XAxis" is the "Location" point
185 //! of the directrix1. This point is on the positive side of the
187 gp_Ax1 Directrix1() const;
189 //! This line is obtained by the symmetrical transformation
190 //! of "Directrix1" with respect to the "YAxis" of the hyperbola.
191 gp_Ax1 Directrix2() const;
193 //! Returns the eccentricity of the hyperbola (e > 1).
194 //! If f is the distance between the location of the hyperbola
195 //! and the Focus1 then the eccentricity e = f / MajorRadius. Raises DomainError if MajorRadius = 0.0
196 Standard_Real Eccentricity() const
198 Standard_DomainError_Raise_if (majorRadius <= gp::Resolution(),
199 "gp_Hypr::Eccentricity() - major radius is zero");
200 return sqrt (majorRadius * majorRadius + minorRadius * minorRadius) / majorRadius;
203 //! Computes the focal distance. It is the distance between the
204 //! the two focus of the hyperbola.
205 Standard_Real Focal() const
207 return 2.0 * sqrt (majorRadius * majorRadius + minorRadius * minorRadius);
210 //! Returns the first focus of the hyperbola. This focus is on the
211 //! positive side of the "XAxis" of the hyperbola.
212 gp_Pnt Focus1() const;
214 //! Returns the second focus of the hyperbola. This focus is on the
215 //! negative side of the "XAxis" of the hyperbola.
216 gp_Pnt Focus2() const;
218 //! Returns the location point of the hyperbola. It is the
219 //! intersection point between the "XAxis" and the "YAxis".
220 const gp_Pnt& Location() const { return pos.Location(); }
222 //! Returns the major radius of the hyperbola. It is the radius
223 //! on the "XAxis" of the hyperbola.
224 Standard_Real MajorRadius() const { return majorRadius; }
226 //! Returns the minor radius of the hyperbola. It is the radius
227 //! on the "YAxis" of the hyperbola.
228 Standard_Real MinorRadius() const { return minorRadius; }
230 //! Returns the branch of hyperbola obtained by doing the
231 //! symmetrical transformation of <me> with respect to the
233 gp_Hypr OtherBranch() const
235 gp_Dir aD = pos.XDirection();
237 return gp_Hypr (gp_Ax2 (pos.Location(), pos.Direction(), aD), majorRadius, minorRadius);
240 //! Returns p = (e * e - 1) * MajorRadius where e is the
241 //! eccentricity of the hyperbola.
242 //! Raises DomainError if MajorRadius = 0.0
243 Standard_Real Parameter() const
245 Standard_DomainError_Raise_if (majorRadius <= gp::Resolution(),
246 "gp_Hypr::Parameter() - major radius is zero");
247 return (minorRadius * minorRadius) / majorRadius;
250 //! Returns the coordinate system of the hyperbola.
251 const gp_Ax2& Position() const { return pos; }
253 //! Computes an axis, whose
254 //! - the origin is the center of this hyperbola, and
255 //! - the unit vector is the "X Direction"
256 //! of the local coordinate system of this hyperbola.
257 //! These axes are, the major axis (the "X
258 //! Axis") and of this hyperboReturns the "XAxis" of the hyperbola.
259 gp_Ax1 XAxis() const { return gp_Ax1 (pos.Location(), pos.XDirection()); }
261 //! Computes an axis, whose
262 //! - the origin is the center of this hyperbola, and
263 //! - the unit vector is the "Y Direction"
264 //! of the local coordinate system of this hyperbola.
265 //! These axes are the minor axis (the "Y Axis") of this hyperbola
266 gp_Ax1 YAxis() const { return gp_Ax1 (pos.Location(), pos.YDirection()); }
268 Standard_EXPORT void Mirror (const gp_Pnt& theP);
270 //! Performs the symmetrical transformation of an hyperbola with
271 //! respect to the point theP which is the center of the symmetry.
272 Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Pnt& theP) const;
274 Standard_EXPORT void Mirror (const gp_Ax1& theA1);
276 //! Performs the symmetrical transformation of an hyperbola with
277 //! respect to an axis placement which is the axis of the symmetry.
278 Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Ax1& theA1) const;
280 Standard_EXPORT void Mirror (const gp_Ax2& theA2);
282 //! Performs the symmetrical transformation of an hyperbola with
283 //! respect to a plane. The axis placement theA2 locates the plane
284 //! of the symmetry (Location, XDirection, YDirection).
285 Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Ax2& theA2) const;
287 void Rotate (const gp_Ax1& theA1, const Standard_Real theAng) { pos.Rotate (theA1, theAng); }
289 //! Rotates an hyperbola. theA1 is the axis of the rotation.
290 //! theAng is the angular value of the rotation in radians.
291 Standard_NODISCARD gp_Hypr Rotated (const gp_Ax1& theA1, const Standard_Real theAng) const
294 aH.pos.Rotate (theA1, theAng);
298 void Scale (const gp_Pnt& theP, const Standard_Real theS);
300 //! Scales an hyperbola. theS is the scaling value.
301 Standard_NODISCARD gp_Hypr Scaled (const gp_Pnt& theP, const Standard_Real theS) const;
303 void Transform (const gp_Trsf& theT);
305 //! Transforms an hyperbola with the transformation theT from
307 Standard_NODISCARD gp_Hypr Transformed (const gp_Trsf& theT) const;
309 void Translate (const gp_Vec& theV) { pos.Translate (theV); }
311 //! Translates an hyperbola in the direction of the vector theV.
312 //! The magnitude of the translation is the vector's magnitude.
313 Standard_NODISCARD gp_Hypr Translated (const gp_Vec& theV) const
316 aH.pos.Translate (theV);
320 void Translate (const gp_Pnt& theP1, const gp_Pnt& theP2) { pos.Translate (theP1, theP2); }
322 //! Translates an hyperbola from the point theP1 to the point theP2.
323 Standard_NODISCARD gp_Hypr Translated (const gp_Pnt& theP1, const gp_Pnt& theP2) const
326 aH.pos.Translate (theP1, theP2);
333 Standard_Real majorRadius;
334 Standard_Real minorRadius;
338 //=======================================================================
339 //function : Asymptote1
341 //=======================================================================
342 inline gp_Ax1 gp_Hypr::Asymptote1() const
344 Standard_ConstructionError_Raise_if (majorRadius <= gp::Resolution(),
345 "gp_Hypr::Asymptote1() - major radius is zero");
346 gp_Vec aV1 = gp_Vec (pos.YDirection());
347 aV1.Multiply (minorRadius / majorRadius);
348 gp_Vec aV = gp_Vec (pos.XDirection());
350 return gp_Ax1 (pos.Location(), gp_Dir (aV));
353 //=======================================================================
354 //function : Asymptote2
356 //=======================================================================
357 inline gp_Ax1 gp_Hypr::Asymptote2() const
359 Standard_ConstructionError_Raise_if (majorRadius <= gp::Resolution(),
360 "gp_Hypr::Asymptote1() - major radius is zero");
361 gp_Vec aV1 = gp_Vec (pos.YDirection());
362 aV1.Multiply (-minorRadius / majorRadius);
363 gp_Vec aV = gp_Vec (pos.XDirection());
365 return gp_Ax1 ( pos.Location(), gp_Dir (aV));
368 //=======================================================================
371 //=======================================================================
372 inline gp_Pnt gp_Hypr::Focus1() const
374 Standard_Real aC = sqrt (majorRadius * majorRadius + minorRadius * minorRadius);
375 const gp_Pnt& aPP = pos.Location ();
376 const gp_Dir& aDD = pos.XDirection();
377 return gp_Pnt (aPP.X() + aC * aDD.X(),
378 aPP.Y() + aC * aDD.Y(),
379 aPP.Z() + aC * aDD.Z());
382 //=======================================================================
385 //=======================================================================
386 inline gp_Pnt gp_Hypr::Focus2 () const
388 Standard_Real aC = sqrt (majorRadius * majorRadius + minorRadius * minorRadius);
389 const gp_Pnt& aPP = pos.Location ();
390 const gp_Dir& aDD = pos.XDirection();
391 return gp_Pnt (aPP.X() - aC * aDD.X(),
392 aPP.Y() - aC * aDD.Y(),
393 aPP.Z() - aC * aDD.Z());
396 //=======================================================================
399 //=======================================================================
400 inline void gp_Hypr::Scale (const gp_Pnt& theP,
401 const Standard_Real theS)
406 majorRadius = -majorRadius;
411 minorRadius = -minorRadius;
413 pos.Scale (theP, theS);
416 //=======================================================================
419 //=======================================================================
420 inline gp_Hypr gp_Hypr::Scaled (const gp_Pnt& theP,
421 const Standard_Real theS) const
424 aH.majorRadius *= theS;
425 if (aH.majorRadius < 0)
427 aH.majorRadius = -aH.majorRadius;
429 aH.minorRadius *= theS;
430 if (aH.minorRadius < 0)
432 aH.minorRadius = -aH.minorRadius;
434 aH.pos.Scale (theP, theS);
438 //=======================================================================
439 //function : Transform
441 //=======================================================================
442 inline void gp_Hypr::Transform (const gp_Trsf& theT)
444 majorRadius *= theT.ScaleFactor();
447 majorRadius = -majorRadius;
449 minorRadius *= theT.ScaleFactor();
452 minorRadius = -minorRadius;
454 pos.Transform (theT);
457 //=======================================================================
458 //function : Transformed
460 //=======================================================================
461 inline gp_Hypr gp_Hypr::Transformed (const gp_Trsf& theT) const
464 aH.majorRadius *= theT.ScaleFactor();
465 if (aH.majorRadius < 0)
467 aH.majorRadius = -aH.majorRadius;
469 aH.minorRadius *= theT.ScaleFactor();
470 if (aH.minorRadius < 0)
472 aH.minorRadius = -aH.minorRadius;
474 aH.pos.Transform (theT);
478 //=======================================================================
479 //function : Directrix1
481 //=======================================================================
482 inline gp_Ax1 gp_Hypr::Directrix1 () const
484 Standard_Real anE = Eccentricity();
485 gp_XYZ anOrig = pos.XDirection().XYZ();
486 anOrig.Multiply (majorRadius / anE);
487 anOrig.Add (pos.Location().XYZ());
488 return gp_Ax1 (gp_Pnt (anOrig), pos.YDirection());
491 //=======================================================================
492 //function : Directrix2
494 //=======================================================================
495 inline gp_Ax1 gp_Hypr::Directrix2 () const
497 Standard_Real anE = Eccentricity();
498 gp_XYZ anOrig = pos.XDirection().XYZ();
499 anOrig.Multiply (-majorRadius / anE);
500 anOrig.Add (pos.Location().XYZ());
501 return gp_Ax1 (gp_Pnt (anOrig), pos.YDirection());
504 #endif // _gp_Hypr_HeaderFile