1 // Created on: 1993-03-10
3 // Copyright (c) 1993-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Geom_Hyperbola_HeaderFile
18 #define _Geom_Hyperbola_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <Standard_Real.hxx>
24 #include <Geom_Conic.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Standard_Integer.hxx>
27 class Standard_ConstructionError;
28 class Standard_DomainError;
29 class Standard_RangeError;
40 DEFINE_STANDARD_HANDLE(Geom_Hyperbola, Geom_Conic)
42 //! Describes a branch of a hyperbola in 3D space.
43 //! A hyperbola is defined by its major and minor radii
44 //! and, as with any conic curve, is positioned in space
45 //! with a right-handed coordinate system (gp_Ax2 object) where:
46 //! - the origin is the center of the hyperbola,
47 //! - the "X Direction" defines the major axis, and
48 //! - the "Y Direction" defines the minor axis.
49 //! The origin, "X Direction" and "Y Direction" of this
50 //! coordinate system define the plane of the hyperbola.
51 //! The coordinate system is the local coordinate
52 //! system of the hyperbola.
53 //! The branch of the hyperbola described is the one
54 //! located on the positive side of the major axis.
55 //! The "main Direction" of the local coordinate system is
56 //! a vector normal to the plane of the hyperbola. The
57 //! axis, of which the origin and unit vector are
58 //! respectively the origin and "main Direction" of the
59 //! local coordinate system, is termed the "Axis" or "main
60 //! Axis" of the hyperbola.
61 //! The "main Direction" of the local coordinate system
62 //! gives an explicit orientation to the hyperbola,
63 //! determining the direction in which the parameter
64 //! increases along the hyperbola.
65 //! The Geom_Hyperbola hyperbola is parameterized as follows:
66 //! P(U) = O + MajRad*Cosh(U)*XDir + MinRad*Sinh(U)*YDir, where:
67 //! - P is the point of parameter U,
68 //! - O, XDir and YDir are respectively the origin, "X
69 //! Direction" and "Y Direction" of its local coordinate system,
70 //! - MajRad and MinRad are the major and minor radii of the hyperbola.
71 //! The "X Axis" of the local coordinate system therefore
72 //! defines the origin of the parameter of the hyperbola.
73 //! The parameter range is ] -infinite, +infinite [.
74 //! The following diagram illustrates the respective
75 //! positions, in the plane of the hyperbola, of the three
76 //! branches of hyperbolas constructed using the
77 //! functions OtherBranch, ConjugateBranch1 and
78 //! ConjugateBranch2: Defines the main branch of an hyperbola.
81 //! FirstConjugateBranch
84 //! --------------------- C ------------------------------>XAxis
87 //! SecondConjugateBranch
90 //! The value of the major radius (on the major axis) can
91 //! be less than the value of the minor radius (on the minor axis).
92 class Geom_Hyperbola : public Geom_Conic
98 //! Constructs a hyperbola by conversion of the gp_Hypr hyperbola H.
99 Standard_EXPORT Geom_Hyperbola(const gp_Hypr& H);
101 //! Constructs a hyperbola defined by its major and
102 //! minor radii, MajorRadius and MinorRadius, where A2 locates the
103 //! hyperbola and defines its orientation in 3D space such that:
104 //! - the center of the hyperbola is the origin of A2,
105 //! - the "X Direction" of A2 defines the major axis
106 //! of the hyperbola, i.e. the major radius
107 //! MajorRadius is measured along this axis,
108 //! - the "Y Direction" of A2 defines the minor axis
109 //! of the hyperbola, i.e. the minor radius
110 //! MinorRadius is measured along this axis,
111 //! - A2 is the local coordinate system of the hyperbola.
113 //! Standard_ConstructionError if:
114 //! - MajorRadius is less than 0.0,
115 //! - MinorRadius is less than 0.0.
116 Standard_EXPORT Geom_Hyperbola(const gp_Ax2& A2, const Standard_Real MajorRadius, const Standard_Real MinorRadius);
118 //! Converts the gp_Hypr hyperbola H into this hyperbola.
119 Standard_EXPORT void SetHypr (const gp_Hypr& H);
121 //! Assigns a value to the major radius of this hyperbola.
123 //! Standard_ConstructionError if:
124 //! - MajorRadius is less than 0.0, or
125 //! - MinorRadius is less than 0.0.Raised if MajorRadius < 0.0
126 Standard_EXPORT void SetMajorRadius (const Standard_Real MajorRadius);
128 //! Assigns a value to the minor radius of this hyperbola.
130 //! Standard_ConstructionError if:
131 //! - MajorRadius is less than 0.0, or
132 //! - MinorRadius is less than 0.0.Raised if MajorRadius < 0.0
133 Standard_EXPORT void SetMinorRadius (const Standard_Real MinorRadius);
136 //! returns the non transient parabola from gp with the same
137 //! geometric properties as <me>.
138 Standard_EXPORT gp_Hypr Hypr() const;
140 //! Computes the parameter on the reversed hyperbola,
141 //! for the point of parameter U on this hyperbola.
142 //! For a hyperbola, the returned value is: -U.
143 Standard_EXPORT Standard_Real ReversedParameter (const Standard_Real U) const Standard_OVERRIDE;
145 //! Returns RealFirst from Standard.
146 Standard_EXPORT Standard_Real FirstParameter() const Standard_OVERRIDE;
148 //! returns RealLast from Standard.
149 Standard_EXPORT Standard_Real LastParameter() const Standard_OVERRIDE;
152 Standard_EXPORT Standard_Boolean IsClosed() const Standard_OVERRIDE;
154 //! return False for an hyperbola.
155 Standard_EXPORT Standard_Boolean IsPeriodic() const Standard_OVERRIDE;
158 //! In the local coordinate system of the hyperbola the equation of
159 //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
160 //! equation of the first asymptote is Y = (B/A)*X.
161 //! Raises ConstructionError if MajorRadius = 0.0
162 Standard_EXPORT gp_Ax1 Asymptote1() const;
165 //! In the local coordinate system of the hyperbola the equation of
166 //! the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
167 //! equation of the first asymptote is Y = -(B/A)*X.
168 //! Raises ConstructionError if MajorRadius = 0.0
169 Standard_EXPORT gp_Ax1 Asymptote2() const;
172 //! This branch of hyperbola is on the positive side of the
174 Standard_EXPORT gp_Hypr ConjugateBranch1() const;
177 //! This branch of hyperbola is on the negative side of the
179 //! Note: The diagram given under the class purpose
180 //! indicates where these two branches of hyperbola are
181 //! positioned in relation to this branch of hyperbola.
182 Standard_EXPORT gp_Hypr ConjugateBranch2() const;
185 //! This directrix is the line normal to the XAxis of the hyperbola
186 //! in the local plane (Z = 0) at a distance d = MajorRadius / e
187 //! from the center of the hyperbola, where e is the eccentricity of
189 //! This line is parallel to the YAxis. The intersection point between
190 //! directrix1 and the XAxis is the location point of the directrix1.
191 //! This point is on the positive side of the XAxis.
192 Standard_EXPORT gp_Ax1 Directrix1() const;
195 //! This line is obtained by the symmetrical transformation
196 //! of "directrix1" with respect to the YAxis of the hyperbola.
197 Standard_EXPORT gp_Ax1 Directrix2() const;
200 //! Returns the excentricity of the hyperbola (e > 1).
201 //! If f is the distance between the location of the hyperbola
202 //! and the Focus1 then the eccentricity e = f / MajorRadius.
203 //! raised if MajorRadius = 0.0
204 Standard_EXPORT Standard_Real Eccentricity() const Standard_OVERRIDE;
207 //! Computes the focal distance. It is the distance between the
208 //! two focus of the hyperbola.
209 Standard_EXPORT Standard_Real Focal() const;
212 //! Returns the first focus of the hyperbola. This focus is on the
213 //! positive side of the XAxis of the hyperbola.
214 Standard_EXPORT gp_Pnt Focus1() const;
217 //! Returns the second focus of the hyperbola. This focus is on the
218 //! negative side of the XAxis of the hyperbola.
219 Standard_EXPORT gp_Pnt Focus2() const;
221 //! Returns the major or minor radius of this hyperbola.
222 //! The major radius is also the distance between the
223 //! center of the hyperbola and the apex of the main
224 //! branch (located on the "X Axis" of the hyperbola).
225 Standard_EXPORT Standard_Real MajorRadius() const;
227 //! Returns the major or minor radius of this hyperbola.
228 //! The minor radius is also the distance between the
229 //! center of the hyperbola and the apex of a conjugate
230 //! branch (located on the "Y Axis" of the hyperbola).
231 Standard_EXPORT Standard_Real MinorRadius() const;
233 //! Computes the "other" branch of this hyperbola. This
234 //! is the symmetrical branch with respect to the center of this hyperbola.
235 //! Note: The diagram given under the class purpose
236 //! indicates where the "other" branch is positioned in
237 //! relation to this branch of the hyperbola.
238 Standard_EXPORT gp_Hypr OtherBranch() const;
241 //! Returns p = (e * e - 1) * MajorRadius where e is the
242 //! eccentricity of the hyperbola.
243 //! raised if MajorRadius = 0.0
244 Standard_EXPORT Standard_Real Parameter() const;
246 //! Returns in P the point of parameter U.
247 //! P = C + MajorRadius * Cosh (U) * XDir +
248 //! MinorRadius * Sinh (U) * YDir
249 //! where C is the center of the hyperbola , XDir the XDirection and
250 //! YDir the YDirection of the hyperbola's local coordinate system.
251 Standard_EXPORT void D0 (const Standard_Real U, gp_Pnt& P) const Standard_OVERRIDE;
254 //! Returns the point P of parameter U and the first derivative V1.
255 Standard_EXPORT void D1 (const Standard_Real U, gp_Pnt& P, gp_Vec& V1) const Standard_OVERRIDE;
258 //! Returns the point P of parameter U, the first and second
259 //! derivatives V1 and V2.
260 Standard_EXPORT void D2 (const Standard_Real U, gp_Pnt& P, gp_Vec& V1, gp_Vec& V2) const Standard_OVERRIDE;
263 //! Returns the point P of parameter U, the first second and
264 //! third derivatives V1 V2 and V3.
265 Standard_EXPORT void D3 (const Standard_Real U, gp_Pnt& P, gp_Vec& V1, gp_Vec& V2, gp_Vec& V3) const Standard_OVERRIDE;
268 //! The returned vector gives the value of the derivative for the
269 //! order of derivation N.
271 Standard_EXPORT gp_Vec DN (const Standard_Real U, const Standard_Integer N) const Standard_OVERRIDE;
273 //! Applies the transformation T to this hyperbola.
274 Standard_EXPORT void Transform (const gp_Trsf& T) Standard_OVERRIDE;
276 //! Creates a new object which is a copy of this hyperbola.
277 Standard_EXPORT Handle(Geom_Geometry) Copy() const Standard_OVERRIDE;
279 //! Dumps the content of me into the stream
280 Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const Standard_OVERRIDE;
285 DEFINE_STANDARD_RTTIEXT(Geom_Hyperbola,Geom_Conic)
295 Standard_Real majorRadius;
296 Standard_Real minorRadius;
307 #endif // _Geom_Hyperbola_HeaderFile