1 // Copyright (c) 1991-1999 Matra Datavision
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.
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
22 #include <gp_Ax2.hxx>
23 #include <Standard_Real.hxx>
24 #include <gp_Ax1.hxx>
25 #include <gp_Pnt.hxx>
26 class Standard_ConstructionError;
27 class Standard_DomainError;
28 class gp_Ax2;
29 class gp_Ax1;
30 class gp_Pnt;
31 class gp_Trsf;
32 class gp_Vec;
35 //! Describes a branch of a hyperbola in 3D space.
36 //! A hyperbola is defined by its major and minor radii and
37 //! positioned in space with a coordinate system (a gp_Ax2
38 //! object) of which:
39 //! -   the origin is the center of the hyperbola,
40 //! -   the "X Direction" defines the major axis of the
41 //! hyperbola, and
42 //! - the "Y Direction" defines the minor axis of the hyperbola.
43 //! The origin, "X Direction" and "Y Direction" of this
44 //! coordinate system together define the plane of the
45 //! hyperbola. This coordinate system is the "local
46 //! coordinate system" of the hyperbola. In this coordinate
47 //! system, the equation of the hyperbola is:
49 //! The branch of the hyperbola described is the one located
50 //! on the positive side of the major axis.
51 //! The "main Direction" of the local coordinate system is a
52 //! normal vector to the plane of the hyperbola. This vector
53 //! gives an implicit orientation to the hyperbola. We refer to
54 //! the "main Axis" of the local coordinate system as the
55 //! "Axis" of the hyperbola.
56 //! The following schema shows the plane of the hyperbola,
57 //! and in it, the respective positions of the three branches of
58 //! hyperbolas constructed with the functions OtherBranch,
59 //! ConjugateBranch1, and ConjugateBranch2:
60 //! @code
61 //! ^YAxis
62 //! |
63 //! FirstConjugateBranch
64 //! |
65 //! Other            |                Main
66 //! --------------------- C ------------------------------>XAxis
67 //! Branch           |                Branch
68 //! |
69 //! |
70 //! SecondConjugateBranch
71 //! |                  ^YAxis
72 //! @endcode
73 //! Warning
74 //! The major radius can be less than the minor radius.
75 //! See Also
76 //! gce_MakeHypr which provides functions for more
77 //! complex hyperbola constructions
78 //! Geom_Hyperbola which provides additional functions for
79 //! constructing hyperbolas and works, in particular, with the
80 //! parametric equations of hyperbolas
81 class gp_Hypr
82 {
83 public:
85   DEFINE_STANDARD_ALLOC
88   //! Creates of an indefinite hyperbola.
89     gp_Hypr();
92   //! MinorRadius, positioned in the space by the
93   //! coordinate system A2 such that:
94   //! -   the origin of A2 is the center of the hyperbola,
95   //! -   the "X Direction" of A2 defines the major axis of
96   //! the hyperbola, that is, the major radius
97   //! MajorRadius is measured along this axis, and
98   //! -   the "Y Direction" of A2 defines the minor axis of
99   //! the hyperbola, that is, the minor radius
100   //! MinorRadius is measured along this axis.
101   //! Note: This class does not prevent the creation of a
102   //! hyperbola where:
103   //! -   MajorAxis is equal to MinorAxis, or
104   //! -   MajorAxis is less than MinorAxis.
105   //! Exceptions
106   //! Standard_ConstructionError if MajorAxis or MinorAxis is negative.
107   //! Raises ConstructionError if MajorRadius < 0.0 or MinorRadius < 0.0
111   //! Modifies this hyperbola, by redefining its local coordinate
112   //! system so that:
113   //! -   its origin and "main Direction" become those of the
114   //! axis A1 (the "X Direction" and "Y Direction" are then
115   //! recomputed in the same way as for any gp_Ax2).
116   //! Raises ConstructionError if the direction of A1 is parallel to the direction of
117   //! the "XAxis" of the hyperbola.
118     void SetAxis (const gp_Ax1& A1);
120   //! Modifies this hyperbola, by redefining its local coordinate
121   //! system so that its origin becomes P.
122     void SetLocation (const gp_Pnt& P);
125   //! Modifies the major  radius of this hyperbola.
126   //! Exceptions
127   //! Standard_ConstructionError if MajorRadius is negative.
131   //! Modifies the minor  radius of this hyperbola.
132   //! Exceptions
133   //! Standard_ConstructionError if MinorRadius is negative.
136   //! Modifies this hyperbola, by redefining its local coordinate
137   //! system so that it becomes A2.
138     void SetPosition (const gp_Ax2& A2);
141   //! In the local coordinate system of the hyperbola the equation of
142   //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
143   //! equation of the first asymptote is Y = (B/A)*X
144   //! where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
145     gp_Ax1 Asymptote1() const;
148   //! In the local coordinate system of the hyperbola the equation of
149   //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
150   //! equation of the first asymptote is Y = -(B/A)*X.
151   //! where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
152     gp_Ax1 Asymptote2() const;
154   //! Returns the axis passing through the center,
155   //! and normal to the plane of this hyperbola.
156     const gp_Ax1& Axis() const;
159   //! Computes the branch of hyperbola which is on the positive side of the
160   //! "YAxis" of <me>.
161     gp_Hypr ConjugateBranch1() const;
164   //! Computes the branch of hyperbola which is on the negative side of the
165   //! "YAxis" of <me>.
166     gp_Hypr ConjugateBranch2() const;
169   //! This directrix is the line normal to the XAxis of the hyperbola
170   //! in the local plane (Z = 0) at a distance d = MajorRadius / e
171   //! from the center of the hyperbola, where e is the eccentricity of
172   //! the hyperbola.
173   //! This line is parallel to the "YAxis". The intersection point
174   //! between the directrix1 and the "XAxis" is the "Location" point
175   //! of the directrix1. This point is on the positive side of the
176   //! "XAxis".
177     gp_Ax1 Directrix1() const;
180   //! This line is obtained by the symmetrical transformation
181   //! of "Directrix1" with respect to the "YAxis" of the hyperbola.
182     gp_Ax1 Directrix2() const;
185   //! Returns the eccentricity of the hyperbola (e > 1).
186   //! If f is the distance between the location of the hyperbola
187   //! and the Focus1 then the eccentricity e = f / MajorRadius. Raises DomainError if MajorRadius = 0.0
188     Standard_Real Eccentricity() const;
191   //! Computes the focal distance. It is the distance between the
192   //! the two focus of the hyperbola.
193     Standard_Real Focal() const;
196   //! Returns the first focus of the hyperbola. This focus is on the
197   //! positive side of the "XAxis" of the hyperbola.
198     gp_Pnt Focus1() const;
201   //! Returns the second focus of the hyperbola. This focus is on the
202   //! negative side of the "XAxis" of the hyperbola.
203     gp_Pnt Focus2() const;
206   //! Returns  the location point of the hyperbola. It is the
207   //! intersection point between the "XAxis" and the "YAxis".
208     const gp_Pnt& Location() const;
211   //! Returns the major radius of the hyperbola. It is the radius
212   //! on the "XAxis" of the hyperbola.
216   //! Returns the minor radius of the hyperbola. It is the radius
217   //! on the "YAxis" of the hyperbola.
221   //! Returns the branch of hyperbola obtained by doing the
222   //! symmetrical transformation of <me> with respect to the
223   //! "YAxis"  of <me>.
224     gp_Hypr OtherBranch() const;
227   //! Returns p = (e * e - 1) * MajorRadius where e is the
228   //! eccentricity of the hyperbola.
229   //! Raises DomainError if MajorRadius = 0.0
230     Standard_Real Parameter() const;
232   //! Returns the coordinate system of the hyperbola.
233     const gp_Ax2& Position() const;
235   //! Computes an axis, whose
236   //! -   the origin is the center of this hyperbola, and
237   //! -   the unit vector is the "X Direction"
238   //! of the local coordinate system of this hyperbola.
239   //! These axes are, the major axis (the "X
240   //! Axis") and  of this hyperboReturns the "XAxis" of the hyperbola.
241     gp_Ax1 XAxis() const;
243   //! Computes an axis, whose
244   //! -   the origin is the center of this hyperbola, and
245   //! -   the unit vector is the "Y Direction"
246   //! of the local coordinate system of this hyperbola.
247   //! These axes are the minor axis (the "Y Axis") of this hyperbola
248     gp_Ax1 YAxis() const;
250   Standard_EXPORT void Mirror (const gp_Pnt& P);
253   //! Performs the symmetrical transformation of an hyperbola with
254   //! respect  to the point P which is the center of the symmetry.
255   Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Pnt& P) const;
257   Standard_EXPORT void Mirror (const gp_Ax1& A1);
260   //! Performs the symmetrical transformation of an hyperbola with
261   //! respect to an axis placement which is the axis of the symmetry.
262   Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Ax1& A1) const;
264   Standard_EXPORT void Mirror (const gp_Ax2& A2);
267   //! Performs the symmetrical transformation of an hyperbola with
268   //! respect to a plane. The axis placement A2 locates the plane
269   //! of the symmetry (Location, XDirection, YDirection).
270   Standard_NODISCARD Standard_EXPORT gp_Hypr Mirrored (const gp_Ax2& A2) const;
272     void Rotate (const gp_Ax1& A1, const Standard_Real Ang);
275   //! Rotates an hyperbola. A1 is the axis of the rotation.
276   //! Ang is the angular value of the rotation in radians.
277     Standard_NODISCARD gp_Hypr Rotated (const gp_Ax1& A1, const Standard_Real Ang) const;
279     void Scale (const gp_Pnt& P, const Standard_Real S);
282   //! Scales an hyperbola. S is the scaling value.
283     Standard_NODISCARD gp_Hypr Scaled (const gp_Pnt& P, const Standard_Real S) const;
285     void Transform (const gp_Trsf& T);
288   //! Transforms an hyperbola with the transformation T from
289   //! class Trsf.
290     Standard_NODISCARD gp_Hypr Transformed (const gp_Trsf& T) const;
292     void Translate (const gp_Vec& V);
295   //! Translates an hyperbola in the direction of the vector V.
296   //! The magnitude of the translation is the vector's magnitude.
297     Standard_NODISCARD gp_Hypr Translated (const gp_Vec& V) const;
299     void Translate (const gp_Pnt& P1, const gp_Pnt& P2);
302   //! Translates an hyperbola from the point P1 to the point P2.
303     Standard_NODISCARD gp_Hypr Translated (const gp_Pnt& P1, const gp_Pnt& P2) const;
308 protected:
314 private:
318   gp_Ax2 pos;