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.
15 class Hypr   from gp
17         --- Purpose : Describes a branch of a hyperbola in 3D space.
18         -- A hyperbola is defined by its major and minor radii and
19         -- positioned in space with a coordinate system (a gp_Ax2
20         -- object) of which:
21         -- -   the origin is the center of the hyperbola,
22         -- -   the "X Direction" defines the major axis of the
23         --   hyperbola, and
24         -- - the "Y Direction" defines the minor axis of the hyperbola.
25         -- The origin, "X Direction" and "Y Direction" of this
26         -- coordinate system together define the plane of the
27         -- hyperbola. This coordinate system is the "local
28         -- coordinate system" of the hyperbola. In this coordinate
29         -- system, the equation of the hyperbola is:
31         -- The branch of the hyperbola described is the one located
32         -- on the positive side of the major axis.
33         -- The "main Direction" of the local coordinate system is a
34         -- normal vector to the plane of the hyperbola. This vector
35         -- gives an implicit orientation to the hyperbola. We refer to
36         -- the "main Axis" of the local coordinate system as the
37         -- "Axis" of the hyperbola.
38         -- The following schema shows the plane of the hyperbola,
39         -- and in it, the respective positions of the three branches of
40         -- hyperbolas constructed with the functions OtherBranch,
41         -- ConjugateBranch1, and ConjugateBranch2:
42         --
43         --                         ^YAxis
44         --                         |
45         --                  FirstConjugateBranch
46         --                         |
47         --        Other            |                Main
48         --   --------------------- C ------------------------------>XAxis
49         --        Branch           |                Branch
50         --                         |
51         --                         |
52         --                   SecondConjugateBranch
53         --                         |                  ^YAxis
54         -- Warning
55         -- The major radius can be less than the minor radius.
56         -- See Also
57         -- gce_MakeHypr which provides functions for more
58         -- complex hyperbola constructions
59         -- Geom_Hyperbola which provides additional functions for
60         -- constructing hyperbolas and works, in particular, with the
61         -- parametric equations of hyperbolas
63 uses Ax1  from gp,
64      Ax2  from gp,
65      Pln  from gp,
66      Pnt  from gp,
67      Trsf from gp,
68      Vec  from gp
70 raises ConstructionError from Standard,
71        DomainError       from Standard
73 is
77   Create   returns Hypr;
78         ---C++: inline
79         --- Purpose : Creates of an indefinite hyperbola.
82   Create (A2 : Ax2; MajorRadius, MinorRadius : Real)  returns Hypr
83         ---C++: inline
84         --- Purpose : Creates a hyperbola with radii MajorRadius and
85         --   MinorRadius, positioned in the space by the
86         --   coordinate system A2 such that:
87         --   -   the origin of A2 is the center of the hyperbola,
88         --   -   the "X Direction" of A2 defines the major axis of
89         --    the hyperbola, that is, the major radius
90         --    MajorRadius is measured along this axis, and
91         --   -   the "Y Direction" of A2 defines the minor axis of
92         --    the hyperbola, that is, the minor radius
93         --    MinorRadius is measured along this axis.
94         -- Note: This class does not prevent the creation of a
95         -- hyperbola where:
96         -- -   MajorAxis is equal to MinorAxis, or
97         -- -   MajorAxis is less than MinorAxis.
98         -- Exceptions
99         -- Standard_ConstructionError if MajorAxis or MinorAxis is negative.
100         --     Raises ConstructionError if MajorRadius < 0.0 or MinorRadius < 0.0
102      raises ConstructionError;
103         --- Purpose : Raised if MajorRadius < 0.0 or MinorRadius < 0.0
106   SetAxis (me : in out; A1 : Ax1)
107         ---C++: inline
108         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
109         -- system so that:
110         -- -   its origin and "main Direction" become those of the
111         --   axis A1 (the "X Direction" and "Y Direction" are then
112         --   recomputed in the same way as for any gp_Ax2).
113         -- Raises ConstructionError if the direction of A1 is parallel to the direction of
114         --  the "XAxis" of the hyperbola.
115      raises ConstructionError
117      is static;
120   SetLocation (me : in out; P : Pnt)   is static;
121         ---C++: inline
122         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
123         -- system so that its origin becomes P.
127   SetMajorRadius (me : in out; MajorRadius : Real)
128         ---C++: inline
129         --- Purpose:
130         -- Modifies the major  radius of this hyperbola.
131         -- Exceptions
132         -- Standard_ConstructionError if MajorRadius is negative.
133      raises ConstructionError
134      is static;
137   SetMinorRadius (me : in out; MinorRadius : Real)
138         ---C++: inline
139         --- Purpose:
140         -- Modifies the minor  radius of this hyperbola.
141         -- Exceptions
142         -- Standard_ConstructionError if MinorRadius is negative.
143      raises ConstructionError
144      is static;
147   SetPosition (me : in out; A2 : Ax2)   is static;
148         ---C++: inline
149         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
150         -- system so that it becomes A2.
153   Asymptote1 (me)   returns Ax1
154         ---C++: inline
155         --- Purpose :
156         --  In the local coordinate system of the hyperbola the equation of
157         --  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
158         --  equation of the first asymptote is Y = (B/A)*X
159         --  where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
160      raises ConstructionError
161      is static;
164   Asymptote2 (me)   returns Ax1
165         ---C++: inline
166         --- Purpose :
167         --  In the local coordinate system of the hyperbola the equation of
168         --  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
169         --  equation of the first asymptote is Y = -(B/A)*X.
170         --  where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
171      raises ConstructionError
172      is static;
175   Axis (me)  returns Ax1  is static;
176         ---C++: inline
177         --- Purpose : Returns the axis passing through the center,
178         -- and normal to the plane of this hyperbola.
179         ---C++: return const&
181   ConjugateBranch1 (me)  returns Hypr  is static;
182         ---C++: inline
183         --- Purpose :
184         --  Computes the branch of hyperbola which is on the positive side of the
185         --  "YAxis" of <me>.
188   ConjugateBranch2 (me)  returns Hypr  is static;
189         ---C++: inline
190         --- Purpose :
191         --  Computes the branch of hyperbola which is on the negative side of the
192         --  "YAxis" of <me>.
195   Directrix1 (me)  returns Ax1   is static;
196         ---C++: inline
197         --- Purpose :
198         --  This directrix is the line normal to the XAxis of the hyperbola
199         --  in the local plane (Z = 0) at a distance d = MajorRadius / e
200         --  from the center of the hyperbola, where e is the eccentricity of
201         --  the hyperbola.
202         --  This line is parallel to the "YAxis". The intersection point
203         --  between the directrix1 and the "XAxis" is the "Location" point
204         --  of the directrix1. This point is on the positive side of the
205         --  "XAxis".
208   Directrix2 (me)   returns Ax1  is static;
209         ---C++: inline
210         --- Purpose :
211         --  This line is obtained by the symmetrical transformation
212         --  of "Directrix1" with respect to the "YAxis" of the hyperbola.
215   Eccentricity (me)   returns Real
216         ---C++: inline
217         --- Purpose :
218         --  Returns the excentricity of the hyperbola (e > 1).
219         --  If f is the distance between the location of the hyperbola
220         --  and the Focus1 then the eccentricity e = f / MajorRadius. Raises DomainError if MajorRadius = 0.0
221      raises DomainError
222      is static;
225   Focal (me)  returns Real  is static;
226         ---C++: inline
227         --- Purpose :
228         --  Computes the focal distance. It is the distance between the
229         --  the two focus of the hyperbola.
232   Focus1 (me)   returns Pnt  is static;
233         ---C++: inline
234         --- Purpose :
235         --  Returns the first focus of the hyperbola. This focus is on the
236         --  positive side of the "XAxis" of the hyperbola.
239   Focus2 (me)   returns Pnt  is static;
240         ---C++: inline
241         --- Purpose :
242         --  Returns the second focus of the hyperbola. This focus is on the
243         --  negative side of the "XAxis" of the hyperbola.
246   Location (me)    returns Pnt   is static;
247         ---C++: inline
248         --- Purpose :
249         --  Returns  the location point of the hyperbola. It is the
250         --  intersection point between the "XAxis" and the "YAxis".
251         ---C++: return const&
254   MajorRadius (me)  returns Real is static;
255         ---C++: inline
256         --- Purpose :
257         --  Returns the major radius of the hyperbola. It is the radius
258         --  on the "XAxis" of the hyperbola.
261   MinorRadius (me)   returns Real  is static;
262         ---C++: inline
263         --- Purpose :
264         --  Returns the minor radius of the hyperbola. It is the radius
265         --  on the "YAxis" of the hyperbola.
268   OtherBranch (me)   returns Hypr is static;
269         ---C++: inline
270         --- Purpose :
271         --  Returns the branch of hyperbola obtained by doing the
272         --  symmetrical transformation of <me> with respect to the
273         --  "YAxis"  of <me>.
276   Parameter (me)  returns Real
277         ---C++: inline
278         --- Purpose :
279         --  Returns p = (e * e - 1) * MajorRadius where e is the
280         --  eccentricity of the hyperbola.
281         --- Raises DomainError if MajorRadius = 0.0
282      raises DomainError
283      is static;
286   Position (me)   returns Ax2   is static;
287         --- Purpose : Returns the coordinate system of the hyperbola.
288         ---C++: inline
289         ---C++: return const&
292   XAxis (me)  returns Ax1    is static;
293         ---C++: inline
294         --- Purpose : Computes an axis, whose
295         -- -   the origin is the center of this hyperbola, and
296         -- -   the unit vector is the "X Direction"
297         --   of the local coordinate system of this hyperbola.
298         -- These axes are, the major axis (the "X
299         -- Axis") and  of this hyperboReturns the "XAxis" of the hyperbola.
302   YAxis (me)  returns Ax1    is static;
303         ---C++: inline
304         --- Purpose :      Computes an axis, whose
305         -- -   the origin is the center of this hyperbola, and
306         -- -   the unit vector is the "Y Direction"
307         --   of the local coordinate system of this hyperbola.
308         -- These axes are the minor axis (the "Y Axis") of this hyperbola
312   Mirror (me : in out; P : Pnt)          is static;
314   Mirrored (me; P : Pnt)   returns Hypr  is static;
315         --- Purpose :
316         --  Performs the symmetrical transformation of an hyperbola with
317         --  respect  to the point P which is the center of the symmetry.
319   Mirror (me : in out; A1 : Ax1)          is static;
321   Mirrored (me; A1 : Ax1)   returns Hypr  is static;
324         --- Purpose :
325         --  Performs the symmetrical transformation of an hyperbola with
326         --  respect to an axis placement which is the axis of the symmetry.
329   Mirror (me : in out; A2 : Ax2)         is static;
331   Mirrored (me; A2 : Ax2)  returns Hypr  is static;
332         --- Purpose :
333         --  Performs the symmetrical transformation of an hyperbola with
334         --  respect to a plane. The axis placement A2 locates the plane
335         --  of the symmetry (Location, XDirection, YDirection).
338   Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
339         ---C++: inline
340   Rotated (me; A1 : Ax1; Ang : Real)   returns Hypr  is static;
341         ---C++: inline
342         --- Purpose :
343         --  Rotates an hyperbola. A1 is the axis of the rotation.
344         --  Ang is the angular value of the rotation in radians.
348   Scale (me : in out; P : Pnt; S : Real)         is static;
349         ---C++: inline
351   Scaled (me; P : Pnt; S : Real)   returns Hypr  is static;
352         ---C++: inline
353         --- Purpose :
354         --  Scales an hyperbola. S is the scaling value.
358   Transform (me : in out; T : Trsf)          is static;
359         ---C++: inline
361   Transformed (me; T : Trsf)   returns Hypr   is static;
362         ---C++: inline
363         --- Purpose :
364         --  Transforms an hyperbola with the transformation T from
365         --  class Trsf.
369   Translate (me : in out; V : Vec)         is static;
370         ---C++: inline
372   Translated (me; V : Vec)  returns Hypr   is static;
373         ---C++: inline
374         --- Purpose :
375         --  Translates an hyperbola in the direction of the vector V.
376         --  The magnitude of the translation is the vector's magnitude.
379   Translate(me : in out; P1, P2 : Pnt)          is static;
380         ---C++: inline
382   Translated (me; P1, P2 : Pnt)   returns Hypr  is static;
383         ---C++: inline
384         --- Purpose :
385         --  Translates an hyperbola from the point P1 to the point P2.
388 fields
390      pos         : Ax2;
391      majorRadius : Real;
392      minorRadius : Real;
395 end;