src/Geom2d/Geom2d_Hyperbola.cdl

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