src/gp/gp_Hypr.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 Hypr   from gp
  16
  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:
  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 "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
  62
  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
  69
  70 raises ConstructionError from Standard,
  71        DomainError       from Standard
  72
  73 is
  74
  75
  76
  77   Create   returns Hypr;
  78         ---C++: inline
  79         --- Purpose : Creates of an indefinite hyperbola.
  80
  81
  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
 101
 102      raises ConstructionError;
 103         --- Purpose : Raised if MajorRadius < 0.0 or MinorRadius < 0.0
 104
 105
 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
 116
 117      is static;
 118
 119
 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.
 124
 125
 126
 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;
 135
 136
 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;
 145
 146
 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.
 151
 152
 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;
 162
 163
 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;
 173
 174
 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&
 180
 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>.
 186
 187
 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>.
 193
 194
 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".
 206
 207
 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.
 213
 214
 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;
 223
 224
 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.
 230
 231
 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.
 237
 238
 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.
 244
 245
 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&
 252
 253
 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.
 259
 260
 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.
 266
 267
 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>.
 274
 275
 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;
 284
 285
 286   Position (me)   returns Ax2   is static;
 287         --- Purpose : Returns the coordinate system of the hyperbola.
 288         ---C++: inline
 289         ---C++: return const&
 290
 291
 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.
 300
 301
 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
 309
 310
 311
 312   Mirror (me : in out; P : Pnt)          is static;
 313
 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.
 318
 319   Mirror (me : in out; A1 : Ax1)          is static;
 320
 321   Mirrored (me; A1 : Ax1)   returns Hypr  is static;
 322
 323
 324         --- Purpose :
 325         --  Performs the symmetrical transformation of an hyperbola with
 326         --  respect to an axis placement which is the axis of the symmetry.
 327
 328
 329   Mirror (me : in out; A2 : Ax2)         is static;
 330
 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).
 336
 337
 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.
 345
 346
 347
 348   Scale (me : in out; P : Pnt; S : Real)         is static;
 349         ---C++: inline
 350
 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.
 355
 356
 357
 358   Transform (me : in out; T : Trsf)          is static;
 359         ---C++: inline
 360
 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.
 366
 367
 368
 369   Translate (me : in out; V : Vec)         is static;
 370         ---C++: inline
 371
 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.
 377
 378
 379   Translate(me : in out; P1, P2 : Pnt)          is static;
 380         ---C++: inline
 381
 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.
 386
 387
 388 fields
 389
 390      pos         : Ax2;
 391      majorRadius : Real;
 392      minorRadius : Real;
 393
 394
 395 end;
 396