0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / Geom / Geom_Hyperbola.hxx
1 // Created on: 1993-03-10
2 // Created by: JCV
3 // Copyright (c) 1993-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 //
6 // This file is part of Open CASCADE Technology software library.
7 //
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.
13 //
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
16
17 #ifndef _Geom_Hyperbola_HeaderFile
18 #define _Geom_Hyperbola_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
22
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;
30 class gp_Hypr;
31 class gp_Ax2;
32 class gp_Ax1;
33 class gp_Pnt;
34 class gp_Vec;
35 class gp_Trsf;
36 class Geom_Geometry;
37
38
39 class Geom_Hyperbola;
40 DEFINE_STANDARD_HANDLE(Geom_Hyperbola, Geom_Conic)
41
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.
79 //! ^YAxis
80 //! |
81 //! FirstConjugateBranch
82 //! |
83 //! Other            |                Main
84 //! --------------------- C ------------------------------>XAxis
85 //! Branch           |                Branch
86 //! |
87 //! SecondConjugateBranch
88 //! |
89 //! Warning
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
93 {
94
95 public:
96
97   
98   //! Constructs a hyperbola by conversion of the gp_Hypr hyperbola H.
99   Standard_EXPORT Geom_Hyperbola(const gp_Hypr& H);
100   
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.
112   //! Exceptions
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);
117   
118   //! Converts the gp_Hypr hyperbola H into this hyperbola.
119   Standard_EXPORT void SetHypr (const gp_Hypr& H);
120   
121   //! Assigns a value to the major radius of this hyperbola.
122   //! Exceptions
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);
127   
128   //! Assigns a value to the minor radius of this hyperbola.
129   //! Exceptions
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);
134   
135
136   //! returns the non transient parabola from gp with the same
137   //! geometric properties as <me>.
138   Standard_EXPORT gp_Hypr Hypr() const;
139   
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;
144   
145   //! Returns RealFirst from Standard.
146   Standard_EXPORT Standard_Real FirstParameter() const Standard_OVERRIDE;
147   
148   //! returns RealLast from Standard.
149   Standard_EXPORT Standard_Real LastParameter() const Standard_OVERRIDE;
150   
151   //! Returns False.
152   Standard_EXPORT Standard_Boolean IsClosed() const Standard_OVERRIDE;
153   
154   //! return False for an hyperbola.
155   Standard_EXPORT Standard_Boolean IsPeriodic() const Standard_OVERRIDE;
156   
157
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;
163   
164
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;
170   
171
172   //! This branch of hyperbola is on the positive side of the
173   //! YAxis of <me>.
174   Standard_EXPORT gp_Hypr ConjugateBranch1() const;
175   
176
177   //! This branch of hyperbola is on the negative side of the
178   //! YAxis of <me>.
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;
183   
184
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
188   //! the hyperbola.
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;
193   
194
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;
198   
199
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;
205   
206
207   //! Computes the focal distance. It is the distance between the
208   //! two focus of the hyperbola.
209   Standard_EXPORT Standard_Real Focal() const;
210   
211
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;
215   
216
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;
220   
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;
226   
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;
232   
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;
239   
240
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;
245   
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;
252   
253
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;
256   
257
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;
261   
262
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;
266   
267
268   //! The returned vector gives the value of the derivative for the
269   //! order of derivation N.
270   //! Raised if N < 1.
271   Standard_EXPORT gp_Vec DN (const Standard_Real U, const Standard_Integer N) const Standard_OVERRIDE;
272   
273   //! Applies the transformation T to this hyperbola.
274   Standard_EXPORT void Transform (const gp_Trsf& T) Standard_OVERRIDE;
275   
276   //! Creates a new object which is a copy of this hyperbola.
277   Standard_EXPORT Handle(Geom_Geometry) Copy() const Standard_OVERRIDE;
278
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;
281
282
283
284
285   DEFINE_STANDARD_RTTIEXT(Geom_Hyperbola,Geom_Conic)
286
287 protected:
288
289
290
291
292 private:
293
294
295   Standard_Real majorRadius;
296   Standard_Real minorRadius;
297
298
299 };
300
301
302
303
304
305
306
307 #endif // _Geom_Hyperbola_HeaderFile