src/gp/gp_Hypr.cdl

   1 -- Copyright (c) 1991-1999 Matra Datavision
   2 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   3 --
   4 -- The content of this file is subject to the Open CASCADE Technology Public
   5 -- License Version 6.5 (the "License"). You may not use the content of this file
   6 -- except in compliance with the License. Please obtain a copy of the License
   7 -- at http://www.opencascade.org and read it completely before using this file.
   8 --
   9 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  10 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  11 --
  12 -- The Original Code and all software distributed under the License is
  13 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  14 -- Initial Developer hereby disclaims all such warranties, including without
  15 -- limitation, any warranties of merchantability, fitness for a particular
  16 -- purpose or non-infringement. Please see the License for the specific terms
  17 -- and conditions governing the rights and limitations under the License.
  18
  19
  20
  21
  22
  23 class Hypr   from gp   inherits Storable
  24
  25         --- Purpose : Describes a branch of a hyperbola in 3D space.
  26         -- A hyperbola is defined by its major and minor radii and
  27         -- positioned in space with a coordinate system (a gp_Ax2
  28         -- object) of which:
  29         -- -   the origin is the center of the hyperbola,
  30         -- -   the "X Direction" defines the major axis of the
  31         --   hyperbola, and
  32         -- - the "Y Direction" defines the minor axis of the hyperbola.
  33         -- The origin, "X Direction" and "Y Direction" of this
  34         -- coordinate system together define the plane of the
  35         -- hyperbola. This coordinate system is the "local
  36         -- coordinate system" of the hyperbola. In this coordinate
  37         -- system, the equation of the hyperbola is:
  38         -- X*X/(MajorRadius**2)-Y*Y/(MinorRadius**2) = 1.0
  39         -- The branch of the hyperbola described is the one located
  40         -- on the positive side of the major axis.
  41         -- The "main Direction" of the local coordinate system is a
  42         -- normal vector to the plane of the hyperbola. This vector
  43         -- gives an implicit orientation to the hyperbola. We refer to
  44         -- the "main Axis" of the local coordinate system as the
  45         -- "Axis" of the hyperbola.
  46         -- The following schema shows the plane of the hyperbola,
  47         -- and in it, the respective positions of the three branches of
  48         -- hyperbolas constructed with the functions OtherBranch,
  49         -- ConjugateBranch1, and ConjugateBranch2:
  50         --
  51         --                         ^YAxis
  52         --                         |
  53         --                  FirstConjugateBranch
  54         --                         |
  55         --        Other            |                Main
  56         --   --------------------- C ------------------------------>XAxis
  57         --        Branch           |                Branch
  58         --                         |
  59         --                         |
  60         --                   SecondConjugateBranch
  61         --                         |                  ^YAxis
  62         -- Warning
  63         -- The major radius can be less than the minor radius.
  64         -- See Also
  65         -- gce_MakeHypr which provides functions for more
  66         -- complex hyperbola constructions
  67         -- Geom_Hyperbola which provides additional functions for
  68         -- constructing hyperbolas and works, in particular, with the
  69         -- parametric equations of hyperbolas
  70
  71 uses Ax1  from gp,
  72      Ax2  from gp,
  73      Pln  from gp,
  74      Pnt  from gp,
  75      Trsf from gp,
  76      Vec  from gp
  77
  78 raises ConstructionError from Standard,
  79        DomainError       from Standard
  80
  81 is
  82
  83
  84
  85   Create   returns Hypr;
  86         ---C++: inline
  87         --- Purpose : Creates of an indefinite hyperbola.
  88
  89
  90   Create (A2 : Ax2; MajorRadius, MinorRadius : Real)  returns Hypr
  91         ---C++: inline
  92         --- Purpose : Creates a hyperbola with radii MajorRadius and
  93         --   MinorRadius, positioned in the space by the
  94         --   coordinate system A2 such that:
  95         --   -   the origin of A2 is the center of the hyperbola,
  96         --   -   the "X Direction" of A2 defines the major axis of
  97         --    the hyperbola, that is, the major radius
  98         --    MajorRadius is measured along this axis, and
  99         --   -   the "Y Direction" of A2 defines the minor axis of
 100         --    the hyperbola, that is, the minor radius
 101         --    MinorRadius is measured along this axis.
 102         -- Note: This class does not prevent the creation of a
 103         -- hyperbola where:
 104         -- -   MajorAxis is equal to MinorAxis, or
 105         -- -   MajorAxis is less than MinorAxis.
 106         -- Exceptions
 107         -- Standard_ConstructionError if MajorAxis or MinorAxis is negative.
 108         --     Raises ConstructionError if MajorRadius < 0.0 or MinorRadius < 0.0
 109
 110      raises ConstructionError;
 111         --- Purpose : Raised if MajorRadius < 0.0 or MinorRadius < 0.0
 112
 113
 114   SetAxis (me : in out; A1 : Ax1)
 115         ---C++: inline
 116         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
 117         -- system so that:
 118         -- -   its origin and "main Direction" become those of the
 119         --   axis A1 (the "X Direction" and "Y Direction" are then
 120         --   recomputed in the same way as for any gp_Ax2).
 121         -- Raises ConstructionError if the direction of A1 is parallel to the direction of
 122         --  the "XAxis" of the hyperbola.
 123      raises ConstructionError
 124
 125      is static;
 126
 127
 128   SetLocation (me : in out; P : Pnt)   is static;
 129         ---C++: inline
 130         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
 131         -- system so that its origin becomes P.
 132
 133
 134
 135   SetMajorRadius (me : in out; MajorRadius : Real)
 136         ---C++: inline
 137         --- Purpose:
 138         -- Modifies the major  radius of this hyperbola.
 139         -- Exceptions
 140         -- Standard_ConstructionError if MajorRadius is negative.
 141      raises ConstructionError
 142      is static;
 143
 144
 145   SetMinorRadius (me : in out; MinorRadius : Real)
 146         ---C++: inline
 147         --- Purpose:
 148         -- Modifies the minor  radius of this hyperbola.
 149         -- Exceptions
 150         -- Standard_ConstructionError if MinorRadius is negative.
 151      raises ConstructionError
 152      is static;
 153
 154
 155   SetPosition (me : in out; A2 : Ax2)   is static;
 156         ---C++: inline
 157         --- Purpose : Modifies this hyperbola, by redefining its local coordinate
 158         -- system so that it becomes A2.
 159
 160
 161   Asymptote1 (me)   returns Ax1
 162         ---C++: inline
 163         --- Purpose :
 164         --  In the local coordinate system of the hyperbola the equation of
 165         --  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
 166         --  equation of the first asymptote is Y = (B/A)*X
 167         --  where A is the major radius and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
 168      raises ConstructionError
 169      is static;
 170
 171
 172   Asymptote2 (me)   returns Ax1
 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 and B is the minor radius. Raises ConstructionError if MajorRadius = 0.0
 179      raises ConstructionError
 180      is static;
 181
 182
 183   Axis (me)  returns Ax1  is static;
 184         ---C++: inline
 185         --- Purpose : Returns the axis passing through the center,
 186         -- and normal to the plane of this hyperbola.
 187         ---C++: return const&
 188
 189   ConjugateBranch1 (me)  returns Hypr  is static;
 190         ---C++: inline
 191         --- Purpose :
 192         --  Computes the branch of hyperbola which is on the positive side of the
 193         --  "YAxis" of <me>.
 194
 195
 196   ConjugateBranch2 (me)  returns Hypr  is static;
 197         ---C++: inline
 198         --- Purpose :
 199         --  Computes the branch of hyperbola which is on the negative side of the
 200         --  "YAxis" of <me>.
 201
 202
 203   Directrix1 (me)  returns Ax1   is static;
 204         ---C++: inline
 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 the directrix1 and the "XAxis" is the "Location" point
 212         --  of the directrix1. This point is on the positive side of the
 213         --  "XAxis".
 214
 215
 216   Directrix2 (me)   returns Ax1  is static;
 217         ---C++: inline
 218         --- Purpose :
 219         --  This line is obtained by the symmetrical transformation
 220         --  of "Directrix1" with respect to the "YAxis" of the hyperbola.
 221
 222
 223   Eccentricity (me)   returns Real
 224         ---C++: inline
 225         --- Purpose :
 226         --  Returns the excentricity of the hyperbola (e > 1).
 227         --  If f is the distance between the location of the hyperbola
 228         --  and the Focus1 then the eccentricity e = f / MajorRadius. Raises DomainError if MajorRadius = 0.0
 229      raises DomainError
 230      is static;
 231
 232
 233   Focal (me)  returns Real  is static;
 234         ---C++: inline
 235         --- Purpose :
 236         --  Computes the focal distance. It is the distance between the
 237         --  the two focus of the hyperbola.
 238
 239
 240   Focus1 (me)   returns Pnt  is static;
 241         ---C++: inline
 242         --- Purpose :
 243         --  Returns the first focus of the hyperbola. This focus is on the
 244         --  positive side of the "XAxis" of the hyperbola.
 245
 246
 247   Focus2 (me)   returns Pnt  is static;
 248         ---C++: inline
 249         --- Purpose :
 250         --  Returns the second focus of the hyperbola. This focus is on the
 251         --  negative side of the "XAxis" of the hyperbola.
 252
 253
 254   Location (me)    returns Pnt   is static;
 255         ---C++: inline
 256         --- Purpose :
 257         --  Returns  the location point of the hyperbola. It is the
 258         --  intersection point between the "XAxis" and the "YAxis".
 259         ---C++: return const&
 260
 261
 262   MajorRadius (me)  returns Real is static;
 263         ---C++: inline
 264         --- Purpose :
 265         --  Returns the major radius of the hyperbola. It is the radius
 266         --  on the "XAxis" of the hyperbola.
 267
 268
 269   MinorRadius (me)   returns Real  is static;
 270         ---C++: inline
 271         --- Purpose :
 272         --  Returns the minor radius of the hyperbola. It is the radius
 273         --  on the "YAxis" of the hyperbola.
 274
 275
 276   OtherBranch (me)   returns Hypr is static;
 277         ---C++: inline
 278         --- Purpose :
 279         --  Returns the branch of hyperbola obtained by doing the
 280         --  symmetrical transformation of <me> with respect to the
 281         --  "YAxis"  of <me>.
 282
 283
 284   Parameter (me)  returns Real
 285         ---C++: inline
 286         --- Purpose :
 287         --  Returns p = (e * e - 1) * MajorRadius where e is the
 288         --  eccentricity of the hyperbola.
 289         --- Raises DomainError if MajorRadius = 0.0
 290      raises DomainError
 291      is static;
 292
 293
 294   Position (me)   returns Ax2   is static;
 295         --- Purpose : Returns the coordinate system of the hyperbola.
 296         ---C++: inline
 297         ---C++: return const&
 298
 299
 300   XAxis (me)  returns Ax1    is static;
 301         ---C++: inline
 302         --- Purpose : Computes an axis, whose
 303         -- -   the origin is the center of this hyperbola, and
 304         -- -   the unit vector is the "X Direction"
 305         --   of the local coordinate system of this hyperbola.
 306         -- These axes are, the major axis (the "X
 307         -- Axis") and  of this hyperboReturns the "XAxis" of the hyperbola.
 308
 309
 310   YAxis (me)  returns Ax1    is static;
 311         ---C++: inline
 312         --- Purpose :      Computes an axis, whose
 313         -- -   the origin is the center of this hyperbola, and
 314         -- -   the unit vector is the "Y Direction"
 315         --   of the local coordinate system of this hyperbola.
 316         -- These axes are the minor axis (the "Y Axis") of this hyperbola
 317
 318
 319
 320   Mirror (me : in out; P : Pnt)          is static;
 321
 322   Mirrored (me; P : Pnt)   returns Hypr  is static;
 323         --- Purpose :
 324         --  Performs the symmetrical transformation of an hyperbola with
 325         --  respect  to the point P which is the center of the symmetry.
 326
 327   Mirror (me : in out; A1 : Ax1)          is static;
 328
 329   Mirrored (me; A1 : Ax1)   returns Hypr  is static;
 330
 331
 332         --- Purpose :
 333         --  Performs the symmetrical transformation of an hyperbola with
 334         --  respect to an axis placement which is the axis of the symmetry.
 335
 336
 337   Mirror (me : in out; A2 : Ax2)         is static;
 338
 339   Mirrored (me; A2 : Ax2)  returns Hypr  is static;
 340         --- Purpose :
 341         --  Performs the symmetrical transformation of an hyperbola with
 342         --  respect to a plane. The axis placement A2 locates the plane
 343         --  of the symmetry (Location, XDirection, YDirection).
 344
 345
 346   Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
 347         ---C++: inline
 348   Rotated (me; A1 : Ax1; Ang : Real)   returns Hypr  is static;
 349         ---C++: inline
 350         --- Purpose :
 351         --  Rotates an hyperbola. A1 is the axis of the rotation.
 352         --  Ang is the angular value of the rotation in radians.
 353
 354
 355
 356   Scale (me : in out; P : Pnt; S : Real)         is static;
 357         ---C++: inline
 358
 359   Scaled (me; P : Pnt; S : Real)   returns Hypr  is static;
 360         ---C++: inline
 361         --- Purpose :
 362         --  Scales an hyperbola. S is the scaling value.
 363
 364
 365
 366   Transform (me : in out; T : Trsf)          is static;
 367         ---C++: inline
 368
 369   Transformed (me; T : Trsf)   returns Hypr   is static;
 370         ---C++: inline
 371         --- Purpose :
 372         --  Transforms an hyperbola with the transformation T from
 373         --  class Trsf.
 374
 375
 376
 377   Translate (me : in out; V : Vec)         is static;
 378         ---C++: inline
 379
 380   Translated (me; V : Vec)  returns Hypr   is static;
 381         ---C++: inline
 382         --- Purpose :
 383         --  Translates an hyperbola in the direction of the vector V.
 384         --  The magnitude of the translation is the vector's magnitude.
 385
 386
 387   Translate(me : in out; P1, P2 : Pnt)          is static;
 388         ---C++: inline
 389
 390   Translated (me; P1, P2 : Pnt)   returns Hypr  is static;
 391         ---C++: inline
 392         --- Purpose :
 393         --  Translates an hyperbola from the point P1 to the point P2.
 394
 395
 396 fields
 397
 398      pos         : Ax2;
 399      majorRadius : Real;
 400      minorRadius : Real;
 401
 402
 403 end;
 404