0024927: Getting rid of "Persistent" functionality -- Storable
[occt.git] / src / gp / gp_Hypr2d.cdl
1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
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.
14
15 class Hypr2d   from gp
16
17         ---Purpose:
18         -- Describes a branch of a hyperbola in the plane (2D space).
19         -- A hyperbola is defined by its major and minor radii, and
20         -- positioned in the plane with a coordinate system (a
21         -- gp_Ax22d object) of which:
22         -- -   the origin is the center of the hyperbola,
23         -- -   the "X Direction" defines the major axis of the hyperbola, and
24         -- -   the "Y Direction" defines the minor axis of the hyperbola.
25         --   This coordinate system is the "local coordinate system"
26         -- of the hyperbola. The orientation of this coordinate
27         -- system (direct or indirect) gives an implicit orientation to
28         -- the hyperbola. In this coordinate system, the equation of
29         -- the hyperbola is:
30         -- X*X/(MajorRadius**2)-Y*Y/(MinorRadius**2) = 1.0
31         -- The branch of the hyperbola described is the one located
32         -- on the positive side of the major axis.
33         -- The following schema shows the plane of the hyperbola,
34         -- and in it, the respective positions of the three branches of
35         -- hyperbolas constructed with the functions OtherBranch,
36         -- ConjugateBranch1, and ConjugateBranch2:     
37         --                         ^YAxis                
38         --                         |                   
39         --                  FirstConjugateBranch     
40         --                         |        
41         --        Other            |                Main
42         --   --------------------- C ------------------------------>XAxis
43         --        Branch           |                Branch
44         --                         |
45         --                         |         
46         --                   SecondConjugateBranch
47         --                         |         
48         --
49         -- Warning
50         -- The major radius can be less than the minor radius.
51         -- See Also
52         -- gce_MakeHypr2d which provides functions for more
53         -- complex hyperbola constructions
54         -- Geom2d_Hyperbola which provides additional functions
55         -- for constructing hyperbolas and works, in particular, with
56         -- the parametric equations of hyperbolas
57
58 uses Ax2d   from gp,
59      Ax22d  from gp, 
60      Pnt2d  from gp,
61      Trsf2d from gp,
62      Vec2d  from gp
63
64 raises ConstructionError from Standard,
65        DomainError       from Standard
66
67 is
68
69   Create   returns Hypr2d;
70         ---C++: inline
71         --- Purpose : Creates of an indefinite hyperbola.
72
73
74   Create (MajorAxis : Ax2d; 
75           MajorRadius, MinorRadius : Real;
76           Sense : Boolean from Standard = Standard_True)
77      returns Hypr2d
78         --- Purpose :
79         --  Creates a hyperbola with radii MajorRadius and
80         --   MinorRadius, centered on the origin of MajorAxis
81         --   and where the unit vector of MajorAxis is the "X
82         --   Direction" of the local coordinate system of the
83         --   hyperbola. This coordinate system is direct if Sense
84         --   is true (the default value), and indirect if Sense is false.
85         --  Warnings :
86         --  It is yet  possible to create an Hyperbola with 
87         --  MajorRadius <= MinorRadius. 
88         -- Raises ConstructionError if MajorRadius < 0.0 or MinorRadius < 0.0
89      raises ConstructionError;
90
91   Create (A : Ax22d; MajorRadius, MinorRadius : Real)
92      returns Hypr2d
93         ---C++: inline
94         --- Purpose :
95         --  a hyperbola with radii MajorRadius and
96         --   MinorRadius, positioned in the plane by coordinate system A where:
97         --   -   the origin of A is the center of the hyperbola,
98         --   -   the "X Direction" of A defines the major axis of
99         --    the hyperbola, that is, the major radius
100         --    MajorRadius is measured along this axis, and
101         --   -   the "Y Direction" of A defines the minor axis of
102         --    the hyperbola, that is, the minor radius
103         --    MinorRadius is measured along this axis, and
104         --   -   the orientation (direct or indirect sense) of A
105         --    gives the implicit orientation of the hyperbola.
106         --  Warnings :
107         --  It is yet  possible to create an Hyperbola with 
108         --  MajorRadius <= MinorRadius.  
109         -- Raises ConstructionError if MajorRadius < 0.0 or MinorRadius < 0.0
110      raises ConstructionError;
111         
112
113   SetLocation (me : in out; P : Pnt2d)   is static;
114         ---C++: inline
115         --- Purpose : Modifies this hyperbola, by redefining its local
116         -- coordinate system so that its origin becomes P.
117
118
119   SetMajorRadius (me : in out; MajorRadius : Real)
120      raises ConstructionError
121         ---C++: inline
122         ---Purpose: Modifies the major or minor radius of this hyperbola.
123         -- Exceptions
124         -- Standard_ConstructionError if MajorRadius or
125         -- MinorRadius is negative.
126      is static;
127
128
129   SetMinorRadius (me : in out; MinorRadius : Real)
130      raises ConstructionError
131         ---C++: inline
132         ---Purpose: Modifies the major or minor radius of this hyperbola.
133         -- Exceptions
134         -- Standard_ConstructionError if MajorRadius or
135         -- MinorRadius is negative.
136      is static;
137
138
139   SetAxis (me : in out; A : Ax22d)   is static;
140         ---C++: inline
141         --- Purpose : Modifies this hyperbola, by redefining its local
142         -- coordinate system so that it becomes A.
143
144
145   SetXAxis (me : in out; A : Ax2d)   is static;
146         ---C++: inline
147         --- Purpose :
148         --  Changes the major axis of the hyperbola. The minor axis is
149         --  recomputed and the location of the hyperbola too.
150
151
152   SetYAxis (me : in out; A : Ax2d) is static;
153         ---C++: inline
154         --- Purpose :
155         --  Changes the minor axis of the hyperbola.The minor axis is
156         --  recomputed and the location of the hyperbola too.
157
158
159   Asymptote1 (me)   returns Ax2d
160         ---C++: inline
161         --- Purpose :
162         --  In the local coordinate system of the hyperbola the equation of
163         --  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
164         --  equation of the first asymptote is Y = (B/A)*X
165         --  where A is the major radius of the hyperbola and B the minor
166         --  radius of the hyperbola. 
167         -- Raises ConstructionError if MajorRadius = 0.0
168      raises ConstructionError
169      is static;
170
171
172   Asymptote2 (me)  returns Ax2d
173         ---C++: inline
174         --- Purpose :
175         --  In the local coordinate system of the hyperbola the equation of
176         --  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
177         --  equation of the first asymptote is Y = -(B/A)*X
178         --  where A is the major radius of the hyperbola and B the minor
179         --  radius of the hyperbola. 
180         -- Raises ConstructionError if MajorRadius = 0.0
181      raises ConstructionError
182      is static;
183
184
185   Coefficients (me; A, B, C, D, E, F : out Real)   is static;
186         --- Purpose :
187         --  Computes the coefficients of the implicit equation of 
188         --  the hyperbola :
189         --  A * (X**2) + B * (Y**2) + 2*C*(X*Y) + 2*D*X + 2*E*Y + F = 0.
190
191
192   ConjugateBranch1 (me)  returns Hypr2d   is static;
193         ---C++: inline
194         --- Purpose :
195         --  Computes the branch of hyperbola which is on the positive side of the 
196         --  "YAxis" of <me>.
197
198
199   ConjugateBranch2 (me)   returns Hypr2d  is static;
200         ---C++: inline
201         --- Purpose :
202         -- Computes the branch of hyperbola which is on the negative side of the 
203         --  "YAxis" of <me>.
204
205
206   Directrix1 (me)   returns Ax2d   is static;
207         ---C++: inline
208         --- Purpose :
209         --  Computes the directrix which is the line normal to the XAxis of the hyperbola
210         --  in the local plane (Z = 0) at a distance d = MajorRadius / e 
211         --  from the center of the hyperbola, where e is the eccentricity of
212         --  the hyperbola.
213         --  This line is parallel to the "YAxis". The intersection point
214         --  between the "Directrix1" and the "XAxis" is the "Location" point
215         --  of the "Directrix1".
216         --  This point is on the positive side of the "XAxis".
217
218
219   Directrix2 (me)  returns Ax2d is static;
220         ---C++: inline
221         --- Purpose :
222         --  This line is obtained by the symmetrical transformation 
223         --  of "Directrix1" with respect to the "YAxis" of the hyperbola.
224
225
226   Eccentricity (me)  returns Real
227         ---C++: inline
228         --- Purpose :
229         --  Returns the excentricity of the hyperbola (e > 1).
230         --  If f is the distance between the location of the hyperbola
231         --  and the Focus1 then the eccentricity e = f / MajorRadius. Raises DomainError if MajorRadius = 0.0.
232      raises DomainError
233      is static;
234
235
236   Focal (me)   returns Real  is static;
237         ---C++: inline
238         --- Purpose :
239         --  Computes the focal distance. It is the distance between the
240         --  "Location" of the hyperbola and "Focus1" or "Focus2".
241
242
243   Focus1 (me)    returns Pnt2d  is static;
244         ---C++: inline
245         --- Purpose :
246         --  Returns the first focus of the hyperbola. This focus is on the
247         --  positive side of the "XAxis" of the hyperbola.
248
249
250   Focus2 (me)  returns Pnt2d  is static;
251         ---C++: inline
252         --- Purpose :
253         --  Returns the second focus of the hyperbola. This focus is on the
254         --  negative side of the "XAxis" of the hyperbola.
255
256
257   Location (me)   returns Pnt2d  is static;
258         ---C++: inline
259         --- Purpose : 
260         --  Returns  the location point of the hyperbola.
261         --  It is the intersection point between the "XAxis" and 
262         --  the "YAxis".
263         ---C++: return const&
264
265
266   MajorRadius (me)   returns Real  is static;
267         ---C++: inline
268         --- Purpose :
269         --  Returns the major radius of the hyperbola (it is the radius
270         --  corresponding to the "XAxis" of the hyperbola).
271
272
273   MinorRadius (me)   returns Real  is static;
274         ---C++: inline
275         --- Purpose :
276         --  Returns the minor radius of the hyperbola (it is the radius
277         --  corresponding to the "YAxis" of the hyperbola).
278
279
280   OtherBranch (me)   returns Hypr2d   is static;
281         ---C++: inline
282         --- Purpose :
283         --  Returns the branch of hyperbola obtained by doing the 
284         --  symmetrical transformation of <me> with respect to the 
285         --  "YAxis" of <me>.
286
287
288   Parameter (me)   returns Real
289         ---C++: inline
290         --- Purpose :
291         --  Returns p = (e * e - 1) * MajorRadius where e is the 
292         --  eccentricity of the hyperbola.
293         -- Raises DomainError if MajorRadius = 0.0
294      raises DomainError
295      is static;
296
297
298   Axis (me)   returns Ax22d   is static;
299         --- Purpose : Returns the axisplacement of the hyperbola.
300         ---C++: inline
301         ---C++: return const&
302   
303
304
305   XAxis (me)   returns Ax2d   is static;
306         --- Purpose : Computes an axis whose
307         -- -   the origin is the center of this hyperbola, and
308         -- -   the unit vector is the "X Direction" or "Y Direction"
309         -- respectively of the local coordinate system of this hyperbola
310         --        Returns the major axis of the hyperbola.
311
312
313   YAxis (me)   returns Ax2d   is static;
314         ---C++: inline
315         --- Purpose : Computes an axis whose
316         -- -   the origin is the center of this hyperbola, and
317         -- -   the unit vector is the "X Direction" or "Y Direction"
318         --  respectively of the local coordinate system of this hyperbola
319         --  Returns the minor axis of the hyperbola.
320
321
322
323   Reverse (me : in out)         is static;
324         ---C++: inline
325
326   Reversed (me)  returns Hypr2d  is static;
327         ---C++: inline
328         ---Purpose: Reverses the orientation of the local coordinate system
329         -- of this hyperbola (the "Y Axis" is reversed). Therefore,
330         -- the implicit orientation of this hyperbola is reversed.
331         -- Note:
332         -- -   Reverse assigns the result to this hyperbola, while
333         -- -   Reversed creates a new one.
334     
335   IsDirect (me)  returns Boolean  is static;
336         ---C++: inline
337         --- Purpose : Returns true if the local coordinate system is direct
338         --            and false in the other case.
339
340
341
342
343   Mirror (me : in out; P : Pnt2d)            is static;
344
345   Mirrored (me; P : Pnt2d)   returns Hypr2d  is static;
346
347         --- Purpose :
348         --  Performs the symmetrical transformation of an hyperbola with 
349         --  respect  to the point P which is the center of the symmetry.
350
351
352
353   Mirror (me : in out; A : Ax2d)             is static;
354
355   Mirrored (me; A : Ax2d)   returns Hypr2d   is static;
356
357         --- Purpose :
358         --  Performs the symmetrical transformation of an hyperbola with 
359         --  respect to an axis placement which is the axis of the symmetry.
360       
361   Rotate (me : in out; P : Pnt2d; Ang : Real)           is static;
362         ---C++: inline
363   
364   Rotated (me; P : Pnt2d; Ang : Real)  returns Hypr2d   is static;
365         ---C++: inline
366         --- Purpose :
367         --  Rotates an hyperbola. P is the center of the rotation.
368         --  Ang is the angular value of the rotation in radians.
369      
370    
371
372   Scale (me : in out; P : Pnt2d; S : Real)           is static;
373         ---C++: inline
374
375   Scaled (me; P : Pnt2d; S : Real)  returns Hypr2d   is static;
376         ---C++: inline  
377         --- Purpose : 
378         --  Scales an hyperbola. <S> is the scaling value.
379         --  If <S> is positive only the location point is 
380         --  modified. But if <S> is negative the "XAxis" is 
381         --  reversed and the "YAxis" too.   
382
383
384
385   Transform (me : in out; T : Trsf2d)            is static;
386         ---C++: inline
387
388   Transformed (me; T : Trsf2d)  returns Hypr2d   is static;
389         ---C++: inline
390         --- Purpose :
391         --  Transforms an hyperbola with the transformation T from 
392         --  class Trsf2d.
393
394
395   
396
397   Translate (me : in out; V : Vec2d)            is static;
398         ---C++: inline
399
400   Translated (me; V : Vec2d)   returns Hypr2d   is static;
401         ---C++: inline
402         --- Purpose :
403         --  Translates an hyperbola in the direction of the vector V.
404         --  The magnitude of the translation is the vector's magnitude.
405
406
407    
408   Translate (me : in out; P1, P2 : Pnt2d)           is static;
409         ---C++: inline
410
411   Translated (me; P1, P2 : Pnt2d)   returns Hypr2d  is static;
412         ---C++: inline
413         --- Purpose :
414         --  Translates an hyperbola from the point P1 to the point P2.
415
416
417 fields
418
419   pos         : Ax22d;
420   majorRadius : Real;
421   minorRadius : Real;
422
423
424 end;
425