0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / Geom2d / Geom2d_Hyperbola.hxx
1 // Created on: 1993-03-24
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 _Geom2d_Hyperbola_HeaderFile
18 #define _Geom2d_Hyperbola_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
22
23 #include <Standard_Real.hxx>
24 #include <Geom2d_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_Hypr2d;
31 class gp_Ax2d;
32 class gp_Ax22d;
33 class gp_Pnt2d;
34 class gp_Vec2d;
35 class gp_Trsf2d;
36 class Geom2d_Geometry;
37
38
39 class Geom2d_Hyperbola;
40 DEFINE_STANDARD_HANDLE(Geom2d_Hyperbola, Geom2d_Conic)
41
42 //! Describes a branch of a hyperbola in the plane (2D space).
43 //! A hyperbola is defined by its major and minor radii
44 //! and, as with any conic curve, is positioned in the
45 //! plane with a coordinate system (gp_Ax22d 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 //! This coordinate system is the local coordinate
50 //! system of the hyperbola.
51 //! The branch of the hyperbola described is the one
52 //! located on the positive side of the major axis.
53 //! The orientation (direct or indirect) of the local
54 //! coordinate system gives an explicit orientation to the
55 //! hyperbola, determining the direction in which the
56 //! parameter increases along the hyperbola.
57 //! The Geom2d_Hyperbola hyperbola is parameterized as follows:
58 //! P(U) = O + MajRad*Cosh(U)*XDir + MinRad*Sinh(U)*YDir
59 //! where:
60 //! - P is the point of parameter U,
61 //! - O, XDir and YDir are respectively the origin, "X
62 //! Direction" and "Y Direction" of its local coordinate system,
63 //! - MajRad and MinRad are the major and minor radii of the hyperbola.
64 //! The "X Axis" of the local coordinate system therefore
65 //! defines the origin of the parameter of the hyperbola.
66 //! The parameter range is ] -infinite,+infinite [.
67 //! The following diagram illustrates the respective
68 //! positions, in the plane of the hyperbola, of the three
69 //! branches of hyperbolas constructed using the
70 //! functions OtherBranch, ConjugateBranch1 and
71 //! ConjugateBranch2:
72 //! ^YAxis
73 //! |
74 //! FirstConjugateBranch
75 //! |
76 //! Other         |          Main
77 //! --------------------- C
78 //! --------------------->XAxis
79 //! Branch       |
80 //! Branch
81 //! |
82 //! SecondConjugateBranch
83 //! |
84 //! Warning
85 //! The value of the major radius (on the major axis) can
86 //! be less than the value of the minor radius (on the minor axis).
87 //! See Also
88 //! GCE2d_MakeHyperbola which provides functions for
89 //! more complex hyperbola constructions
90 //! gp_Ax22d
91 //! gp_Hypr2d for an equivalent, non-parameterized data structure
92 class Geom2d_Hyperbola : public Geom2d_Conic
93 {
94
95 public:
96
97   
98   //! Creates  an Hyperbola from a non persistent one from package gp
99   Standard_EXPORT Geom2d_Hyperbola(const gp_Hypr2d& H);
100   
101
102   //! MajorAxis is the "XAxis" of the hyperbola.
103   //! The YAxis is in the direct sense if "Sense" is True;
104   //! The major radius of the hyperbola is on this "XAxis" and
105   //! the minor radius is on the "YAxis" of the hyperbola.
106   //! Raised if MajorRadius < 0.0 or if MinorRadius < 0.0
107   Standard_EXPORT Geom2d_Hyperbola(const gp_Ax2d& MajorAxis, const Standard_Real MajorRadius, const Standard_Real MinorRadius, const Standard_Boolean Sense = Standard_True);
108   
109
110   //! The XDirection of "Axis" is the "XAxis" of the hyperbola and
111   //! the YDirection of "Axis" is the "YAxis".
112   //! The major radius of the hyperbola is on this "XAxis" and
113   //! the minor radius is on the "YAxis" of the hyperbola.
114   //! Raised if MajorRadius < 0.0 or if MinorRadius < 0.0
115   Standard_EXPORT Geom2d_Hyperbola(const gp_Ax22d& Axis, const Standard_Real MajorRadius, const Standard_Real MinorRadius);
116   
117   //! Converts the gp_Hypr2d hyperbola H into this hyperbola.
118   Standard_EXPORT void SetHypr2d (const gp_Hypr2d& H);
119   
120   //! Assigns a value to the major or minor radius of this hyperbola.
121   //! Exceptions
122   //! Standard_ConstructionError if:
123   //! - MajorRadius is less than 0.0,
124   //! - MinorRadius is less than 0.0.
125   Standard_EXPORT void SetMajorRadius (const Standard_Real MajorRadius);
126   
127   //! Assigns a value to the major or minor radius of this hyperbola.
128   //! Exceptions
129   //! Standard_ConstructionError if:
130   //! - MajorRadius is less than 0.0,
131   //! - MinorRadius is less than 0.0.
132   Standard_EXPORT void SetMinorRadius (const Standard_Real MinorRadius);
133   
134   //! Converts this hyperbola into a gp_Hypr2d one.
135   Standard_EXPORT gp_Hypr2d Hypr2d() const;
136   
137   //! Computes the parameter on the reversed hyperbola,
138   //! for the point of parameter U on this hyperbola.
139   //! For a hyperbola, the returned value is -U.
140   Standard_EXPORT Standard_Real ReversedParameter (const Standard_Real U) const Standard_OVERRIDE;
141   
142   //! Returns RealFirst from Standard.
143   Standard_EXPORT Standard_Real FirstParameter() const Standard_OVERRIDE;
144   
145   //! returns RealLast from Standard.
146   Standard_EXPORT Standard_Real LastParameter() const Standard_OVERRIDE;
147   
148   //! Returns False.
149   Standard_EXPORT Standard_Boolean IsClosed() const Standard_OVERRIDE;
150   
151   //! return False for an hyperbola.
152   Standard_EXPORT Standard_Boolean IsPeriodic() const Standard_OVERRIDE;
153   
154
155   //! In the local coordinate system of the hyperbola the
156   //! equation of the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0
157   //! and the equation of the first asymptote is Y = (B/A)*X
158   //! where A is the major radius of the hyperbola and B is the
159   //! minor radius of the hyperbola.
160   //! Raised if MajorRadius = 0.0
161   Standard_EXPORT gp_Ax2d Asymptote1() const;
162   
163
164   //! In the local coordinate system of the hyperbola the
165   //! equation of the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0
166   //! and the equation of the first asymptote is Y = -(B/A)*X.
167   //! where A is the major radius of the hyperbola and B is the
168   //! minor radius of the hyperbola.
169   //! raised if MajorRadius = 0.0
170   Standard_EXPORT gp_Ax2d Asymptote2() const;
171   
172   //! Computes the first conjugate branch relative to this hyperbola.
173   //! Note: The diagram given under the class purpose
174   //! indicates where these two branches of hyperbola are
175   //! positioned in relation to this branch of hyperbola.
176   Standard_EXPORT gp_Hypr2d ConjugateBranch1() const;
177   
178   //! Computes the second conjugate branch relative to this hyperbola.
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_Hypr2d 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
190   //! between directrix1 and the "XAxis" is the location point of the
191   //! directrix1. This point is on the positive side of the "XAxis".
192   Standard_EXPORT gp_Ax2d 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_Ax2d 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_Pnt2d 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_Pnt2d 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
234   //! Computes the "other" branch of this hyperbola. This
235   //! is a symmetrical branch with respect to the center of this hyperbola.
236   //! Note: The diagram given under the class purpose
237   //! indicates where the "other" branch is positioned in
238   //! relation to this branch of the hyperbola.
239   //! ^ YAxis
240   //! |
241   //! FirstConjugateBranch
242   //! |
243   //! Other   | Main
244   //! ---------------------------- C
245   //! ------------------------------------------&gtXAxis
246   //! Branch |  Branch
247   //! |
248   //! |
249   //! SecondConjugateBranch
250   //! |
251   //! Warning
252   //! The major radius can be less than the minor radius.
253   Standard_EXPORT gp_Hypr2d OtherBranch() const;
254   
255   //! Computes the parameter of this hyperbola.
256   //! The parameter is:
257   //! p = (e*e - 1) * MajorRadius
258   //! where e is the eccentricity of this hyperbola and
259   //! MajorRadius its major radius.
260   //! Exceptions
261   //! Standard_DomainError if the major radius of this
262   //! hyperbola is null.
263   Standard_EXPORT Standard_Real Parameter() const;
264   
265   //! Returns in P the point of parameter U.
266   //! P = C + MajorRadius * Cosh (U) * XDir +
267   //! MinorRadius * Sinh (U) * YDir
268   //! where C is the center of the hyperbola , XDir the XDirection and
269   //! YDir the YDirection of the hyperbola's local coordinate system.
270   Standard_EXPORT void D0 (const Standard_Real U, gp_Pnt2d& P) const Standard_OVERRIDE;
271   
272
273   //! Returns the point P of parameter U and the first derivative V1.
274   Standard_EXPORT void D1 (const Standard_Real U, gp_Pnt2d& P, gp_Vec2d& V1) const Standard_OVERRIDE;
275   
276
277   //! Returns the point P of parameter U, the first and second
278   //! derivatives V1 and V2.
279   Standard_EXPORT void D2 (const Standard_Real U, gp_Pnt2d& P, gp_Vec2d& V1, gp_Vec2d& V2) const Standard_OVERRIDE;
280   
281
282   //! Returns the point P of parameter U, the first second and
283   //! third derivatives V1 V2 and V3.
284   Standard_EXPORT void D3 (const Standard_Real U, gp_Pnt2d& P, gp_Vec2d& V1, gp_Vec2d& V2, gp_Vec2d& V3) const Standard_OVERRIDE;
285   
286   //! For the point of parameter U of this hyperbola,
287   //! computes the vector corresponding to the Nth derivative.
288   //! Exceptions Standard_RangeError if N is less than 1.
289   Standard_EXPORT gp_Vec2d DN (const Standard_Real U, const Standard_Integer N) const Standard_OVERRIDE;
290   
291   //! Applies the transformation T to this hyperbola.
292   Standard_EXPORT void Transform (const gp_Trsf2d& T) Standard_OVERRIDE;
293   
294   //! Creates a new object which is a copy of this hyperbola.
295   Standard_EXPORT Handle(Geom2d_Geometry) Copy() const Standard_OVERRIDE;
296
297   //! Dumps the content of me into the stream
298   Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const Standard_OVERRIDE;
299
300
301
302
303   DEFINE_STANDARD_RTTIEXT(Geom2d_Hyperbola,Geom2d_Conic)
304
305 protected:
306
307
308
309
310 private:
311
312
313   Standard_Real majorRadius;
314   Standard_Real minorRadius;
315
316
317 };
318
319
320
321
322
323
324
325 #endif // _Geom2d_Hyperbola_HeaderFile