src/Geom2d/Geom2d_Hyperbola.cdl

   1 -- File:        Geom2d_Hyperbola.cdl
   2 -- Created:     Wed Mar 24 18:06:32 1993
   3 -- Author:      JCV
   4 --              <fid@sdsun2>
   5 -- Copyright:    Matra Datavision 1993
   6
   7 ---Copyright:   Matra Datavision 1991, 1992
   8
   9
  10 class Hyperbola from Geom2d inherits Conic from Geom2d
  11
  12         --- Purpose : Describes a branch of a hyperbola in the plane (2D space).
  13         -- A hyperbola is defined by its major and minor radii
  14         -- and, as with any conic curve, is positioned in the
  15         -- plane with a coordinate system (gp_Ax22d object) where:
  16         -- - the origin is the center of the hyperbola,
  17         -- - the "X Direction" defines the major axis, and
  18         -- - the "Y Direction" defines the minor axis.
  19         --   This coordinate system is the local coordinate
  20         -- system of the hyperbola.
  21         -- The branch of the hyperbola described is the one
  22         -- located on the positive side of the major axis.
  23         -- The orientation (direct or indirect) of the local
  24         -- coordinate system gives an explicit orientation to the
  25         -- hyperbola, determining the direction in which the
  26         -- parameter increases along the hyperbola.
  27         -- The Geom2d_Hyperbola hyperbola is parameterized as follows:
  28         -- P(U) = O + MajRad*Cosh(U)*XDir + MinRad*Sinh(U)*YDir
  29         -- where:
  30         -- - P is the point of parameter U,
  31         -- - O, XDir and YDir are respectively the origin, "X
  32         --   Direction" and "Y Direction" of its local coordinate system,
  33         -- - MajRad and MinRad are the major and minor radii of the hyperbola.
  34         -- The "X Axis" of the local coordinate system therefore
  35         -- defines the origin of the parameter of the hyperbola.
  36         -- The parameter range is ] -infinite,+infinite [.
  37         -- The following diagram illustrates the respective
  38         -- positions, in the plane of the hyperbola, of the three
  39         -- branches of hyperbolas constructed using the
  40         -- functions OtherBranch, ConjugateBranch1 and
  41         -- ConjugateBranch2:
  42         --                 ^YAxis
  43         --                 |
  44         --           FirstConjugateBranch
  45         --                 |
  46         --     Other         |          Main
  47         -- --------------------- C
  48         -- --------------------->XAxis
  49         --     Branch       |
  50         -- Branch
  51         --                 |
  52         --           SecondConjugateBranch
  53         --                 |
  54         -- Warning
  55         -- The value of the major radius (on the major axis) can
  56         -- be less than the value of the minor radius (on the minor axis).
  57         -- See Also
  58         -- GCE2d_MakeHyperbola which provides functions for
  59         -- more complex hyperbola constructions
  60         -- gp_Ax22d
  61         -- gp_Hypr2d for an equivalent, non-parameterized data structure
  62
  63
  64 uses Ax2d     from gp,
  65      Ax22d    from gp,
  66      Hypr2d   from gp,
  67      Pnt2d    from gp,
  68      Trsf2d   from gp,
  69      Vec2d    from gp,
  70      Geometry from Geom2d
  71
  72
  73 raises ConstructionError from Standard,
  74        DomainError       from Standard,
  75        RangeError        from Standard
  76
  77
  78 is
  79
  80   Create (H : Hypr2d)   returns mutable Hyperbola;
  81         --- Purpose : Creates  an Hyperbola from a non persistent one from package gp
  82
  83
  84   Create (MajorAxis : Ax2d; MajorRadius, MinorRadius : Real;
  85           Sense: Boolean from Standard = Standard_True)
  86      returns mutable Hyperbola
  87         --- Purpose :
  88         --  MajorAxis is the "XAxis" of the hyperbola.
  89         --  The YAxis is in the direct sense if "Sense" is True;
  90         --  The major radius of the hyperbola is on this "XAxis" and
  91         --  the minor radius is on the "YAxis" of the hyperbola.
  92      raises ConstructionError;
  93         --- Purpose : Raised if MajorRadius < 0.0 or if MinorRadius < 0.0
  94
  95   Create (Axis : Ax22d; MajorRadius, MinorRadius : Real)
  96      returns mutable Hyperbola
  97         --- Purpose :
  98         --  The XDirection of "Axis" is the "XAxis" of the hyperbola and
  99         --  the YDirection of "Axis" is the "YAxis".
 100         --  The major radius of the hyperbola is on this "XAxis" and
 101         --  the minor radius is on the "YAxis" of the hyperbola.
 102      raises ConstructionError;
 103         --- Purpose : Raised if MajorRadius < 0.0 or if MinorRadius < 0.0
 104
 105
 106
 107   SetHypr2d (me : mutable; H : Hypr2d);
 108         --- Purpose: Converts the gp_Hypr2d hyperbola H into this hyperbola.
 109
 110
 111
 112   SetMajorRadius (me : mutable; MajorRadius : Real)
 113      raises ConstructionError;
 114         ---Purpose : Assigns a value to the major or minor radius of this hyperbola.
 115         --  Exceptions
 116         -- Standard_ConstructionError if:
 117         -- - MajorRadius is less than 0.0,
 118         -- - MinorRadius is less than 0.0.
 119
 120   SetMinorRadius (me : mutable; MinorRadius : Real)
 121      raises ConstructionError;
 122         --- Purpose : Assigns a value to the major or minor radius of this hyperbola.
 123         --  Exceptions
 124         -- Standard_ConstructionError if:
 125         -- - MajorRadius is less than 0.0,
 126         -- - MinorRadius is less than 0.0.
 127
 128   Hypr2d (me)  returns Hypr2d;
 129         --- Purpose : Converts this hyperbola into a gp_Hypr2d one.
 130
 131
 132
 133   ReversedParameter(me; U : Real) returns Real is redefined static;
 134         ---Purpose: Computes the parameter on the reversed hyperbola,
 135         -- for the point of parameter U on this hyperbola.
 136         -- For a hyperbola, the returned value is -U.
 137
 138
 139   FirstParameter (me)   returns Real is redefined static;
 140         --- Purpose : Returns RealFirst from Standard.
 141
 142
 143   LastParameter (me)   returns Real is redefined static;
 144         --- Purpose : returns RealLast from Standard.
 145
 146
 147   IsClosed (me)   returns Boolean is redefined static;
 148         --- Purpose : Returns False.
 149
 150
 151   IsPeriodic (me)   returns Boolean is redefined static;
 152         --- Purpose : return False for an hyperbola.
 153
 154
 155   Asymptote1 (me)  returns Ax2d
 156         --- Purpose :
 157         --  In the local coordinate system of the hyperbola the
 158         --  equation of the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0
 159         --  and the equation of the first asymptote is Y = (B/A)*X
 160         --  where A is the major radius of the hyperbola and B is the
 161         --  minor radius of the hyperbola.
 162      raises ConstructionError;
 163         --- Purpose : Raised if MajorRadius = 0.0
 164
 165
 166   Asymptote2 (me)    returns Ax2d
 167         --- Purpose :
 168         --  In the local coordinate system of the hyperbola the
 169         --  equation of the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0
 170         --  and the equation of the first asymptote is Y = -(B/A)*X.
 171         --  where A is the major radius of the hyperbola and B is the
 172         --  minor radius of the hyperbola.
 173      raises ConstructionError;
 174         --- Purpose : raised if MajorRadius = 0.0
 175
 176
 177   ConjugateBranch1 (me)   returns Hypr2d;
 178         --- Purpose : Computes the first 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
 183   ConjugateBranch2 (me)  returns Hypr2d;
 184         --- Purpose : Computes the second conjugate branch relative to this hyperbola.
 185         -- Note: The diagram given under the class purpose
 186         -- indicates where these two branches of hyperbola are
 187         -- positioned in relation to this branch of hyperbola.
 188
 189
 190   Directrix1 (me)   returns Ax2d;
 191         --- Purpose :
 192         --  This directrix is the line normal to the XAxis of the hyperbola
 193         --  in the local plane (Z = 0) at a distance d = MajorRadius / e
 194         --  from the center of the hyperbola, where e is the eccentricity of
 195         --  the hyperbola.
 196         --  This line is parallel to the "YAxis". The intersection point
 197         --  between directrix1 and the "XAxis" is the location point of the
 198         --  directrix1. This point is on the positive side of the "XAxis".
 199
 200
 201   Directrix2 (me)   returns Ax2d;
 202         --- Purpose :
 203         --  This line is obtained by the symmetrical transformation
 204         --  of "Directrix1" with respect to the "YAxis" of the hyperbola.
 205
 206
 207   Eccentricity (me)   returns Real
 208         --- Purpose :
 209         --  Returns the excentricity of the hyperbola (e > 1).
 210         --  If f is the distance between the location of the hyperbola
 211         --  and the Focus1 then the eccentricity e = f / MajorRadius.
 212      raises DomainError is redefined static;
 213         --- Purpose : raised if MajorRadius = 0.0
 214
 215
 216   Focal (me)   returns Real;
 217         --- Purpose :
 218         --  Computes the focal distance. It is the distance between the
 219         --  two focus of the hyperbola.
 220
 221
 222   Focus1 (me)   returns Pnt2d;
 223         --- Purpose :
 224         --  Returns the first focus of the hyperbola. This focus is on the
 225         --  positive side of the "XAxis" of the hyperbola.
 226
 227
 228   Focus2 (me)  returns Pnt2d;
 229         --- Purpose :
 230         --  Returns the second focus of the hyperbola. This focus is on the
 231         --  negative side of the "XAxis" of the hyperbola.
 232
 233
 234   MajorRadius (me)  returns Real;
 235         ---Purpose: Returns the major or minor radius of this hyperbola.
 236         -- The major radius is also the distance between the
 237         -- center of the hyperbola and the apex of the main
 238         -- branch (located on the "X Axis" of the hyperbola).
 239
 240
 241   MinorRadius (me)  returns Real;
 242         ---Purpose: Returns the major or minor radius of this hyperbola.
 243         -- The minor radius is also the distance between the
 244         -- center of the hyperbola and the apex of a conjugate
 245         -- branch (located on the "Y Axis" of the hyperbola).
 246
 247   OtherBranch (me)   returns Hypr2d;
 248         --- Purpose :
 249         --  Computes the "other" branch of this hyperbola. This
 250         -- is a symmetrical branch with respect to the center of this hyperbola.
 251         -- Note: The diagram given under the class purpose
 252         -- indicates where the "other" branch is positioned in
 253         -- relation to this branch of the hyperbola.
 254         --   ^ YAxis
 255         -- |
 256         -- FirstConjugateBranch
 257         --   |
 258         -- Other   | Main
 259         -- ---------------------------- C
 260         -- ------------------------------------------&gtXAxis
 261         -- Branch |  Branch
 262         --   |
 263         -- |
 264         -- SecondConjugateBranch
 265         --   |
 266         -- Warning
 267         -- The major radius can be less than the minor radius.
 268
 269   Parameter (me)  returns Real
 270         --- Purpose : Computes the parameter of this hyperbola.
 271         -- The parameter is:
 272         -- p = (e*e - 1) * MajorRadius
 273         -- where e is the eccentricity of this hyperbola and
 274         -- MajorRadius its major radius.
 275         -- Exceptions
 276         -- Standard_DomainError if the major radius of this
 277         -- hyperbola is null.
 278              raises DomainError;
 279
 280
 281   D0(me; U : Real; P : out Pnt2d) is redefined static;
 282         ---Purpose: Returns in P the point of parameter U.
 283         --  P = C + MajorRadius * Cosh (U) * XDir +
 284         --          MinorRadius * Sinh (U) * YDir
 285         --  where C is the center of the hyperbola , XDir the XDirection and
 286         --  YDir the YDirection of the hyperbola's local coordinate system.
 287
 288
 289   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d) is redefined static;
 290         --- Purpose :
 291         --  Returns the point P of parameter U and the first derivative V1.
 292
 293
 294   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d) is redefined static;
 295         --- Purpose :
 296         --  Returns the point P of parameter U, the first and second
 297         --  derivatives V1 and V2.
 298
 299
 300   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d) is redefined static;
 301         --- Purpose :
 302         --  Returns the point P of parameter U, the first second and
 303         --  third derivatives V1 V2 and V3.
 304
 305
 306
 307   DN (me; U : Real; N : Integer)   returns Vec2d
 308         --- Purpose : For the point of parameter U of this hyperbola,
 309         -- computes the vector corresponding to the Nth derivative.
 310         -- Exceptions Standard_RangeError if N is less than 1.
 311             raises RangeError is redefined static;
 312
 313
 314
 315   Transform (me : mutable; T : Trsf2d) is redefined static;
 316
 317         ---Purpose: Applies the transformation T to this hyperbola.
 318
 319   Copy (me)  returns mutable like me is redefined static;
 320         ---Purpose: Creates a new object which is a copy of this hyperbola.
 321
 322 fields
 323
 324      majorRadius : Real;
 325      minorRadius : Real;
 326
 327 end;
 328