src/gp/gp_Elips.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 Elips   from gp  inherits Storable
  16         --- Purpose :
  17         --      Describes an ellipse in 3D space.
  18         -- An ellipse is defined by its major and minor radii and
  19         -- positioned in space with a coordinate system (a gp_Ax2 object) as follows:
  20         -- -   the origin of the coordinate system is the center of the ellipse,
  21         -- -   its "X Direction" defines the major axis of the ellipse, and
  22         -- - its "Y Direction" defines the minor axis of the ellipse.
  23         -- Together, the origin, "X Direction" and "Y Direction" of
  24         -- this coordinate system define the plane of the ellipse.
  25         -- This coordinate system is the "local coordinate system"
  26         -- of the ellipse. In this coordinate system, the equation of
  27         -- the ellipse is:
  28         -- X*X / (MajorRadius**2) + Y*Y / (MinorRadius**2) = 1.0
  29         -- The "main Direction" of the local coordinate system gives
  30         -- the normal vector to the plane of the ellipse. This vector
  31         -- gives an implicit orientation to the ellipse (definition of the
  32         -- trigonometric sense). We refer to the "main Axis" of the
  33         -- local coordinate system as the "Axis" of the ellipse.
  34         -- See Also
  35         -- gce_MakeElips which provides functions for more
  36         -- complex ellipse constructions
  37         -- Geom_Ellipse which provides additional functions for
  38         -- constructing ellipses and works, in particular, with the
  39         -- parametric equations of ellipses
  40
  41 uses  Ax1  from gp,
  42       Ax2  from gp,
  43       Pnt  from gp,
  44       Trsf from gp,
  45       Vec  from gp
  46
  47 raises ConstructionError from Standard
  48
  49 is
  50
  51
  52   Create  returns Elips;
  53         ---C++:inline
  54         --- Purpose : Creates an indefinite ellipse.
  55
  56
  57   Create (A2 : Ax2; MajorRadius, MinorRadius : Real)   returns Elips
  58         ---C++: inline
  59         --- Purpose :
  60         --  The major radius of the ellipse is on the "XAxis" and the
  61         --  minor radius is on the "YAxis" of the ellipse. The "XAxis"
  62         --  is defined with the "XDirection" of A2 and the "YAxis" is
  63         --  defined with the "YDirection" of A2.
  64         -- Warnings :
  65         --  It is not forbidden to create an ellipse with MajorRadius =
  66         --  MinorRadius.
  67         --  Raises ConstructionError if MajorRadius < MinorRadius or MinorRadius < 0.
  68      raises ConstructionError;
  69
  70
  71
  72   SetAxis (me : in out; A1 : Ax1)
  73         ---C++:inline
  74         --- Purpose :
  75         --  Changes the axis normal to the plane of the ellipse.
  76         --  It modifies the definition of this plane.
  77         --  The "XAxis" and the "YAxis" are recomputed.
  78         -- The local coordinate system is redefined so that:
  79         -- -   its origin and "main Direction" become those of the
  80         --   axis A1 (the "X Direction" and "Y Direction" are then
  81         --   recomputed in the same way as for any gp_Ax2), or
  82         --  Raises ConstructionError if the direction of A1
  83         -- is parallel to the direction of the "XAxis" of the ellipse.
  84     raises ConstructionError
  85
  86      is static;
  87
  88
  89   SetLocation (me : in out; P : Pnt)   is static;
  90         ---C++: inline
  91         --- Purpose :Modifies this ellipse, by redefining its local coordinate
  92         -- so that its origin becomes P.
  93
  94
  95   SetMajorRadius (me : in out; MajorRadius : Real)
  96         ---C++: inline
  97         --- Purpose :
  98         --  The major radius of the ellipse is on the "XAxis" (major axis)
  99         --  of the ellipse.
 100         --  Raises ConstructionError if MajorRadius < MinorRadius.
 101      raises ConstructionError
 102      is static;
 103
 104
 105   SetMinorRadius (me : in out; MinorRadius : Real)
 106         ---C++: inline
 107         --- Purpose :
 108         --  The minor radius of the ellipse is on the "YAxis" (minor axis)
 109         --  of the ellipse.
 110         --  Raises ConstructionError if MinorRadius > MajorRadius or MinorRadius < 0.
 111      raises ConstructionError
 112
 113      is static;
 114
 115
 116   SetPosition (me : in out; A2 : Ax2)   is static;
 117         ---C++: inline
 118         --- Purpose : Modifies this ellipse, by redefining its local coordinate
 119         -- so that it becomes A2e.
 120
 121
 122   Area (me)   returns Real   is static;
 123         --- Purpose : Computes the area of the Ellipse.
 124         ---C++: inline
 125
 126
 127   Axis (me)  returns Ax1   is static;
 128         ---C++: inline
 129         --- Purpose:
 130         --  Computes the axis normal to the plane of the ellipse.
 131         ---C++: return const&
 132
 133
 134   Directrix1 (me)  returns Ax1
 135         ---C++:inline
 136         --- Purpose : Computes the first or second directrix of this ellipse.
 137         -- These are the lines, in the plane of the ellipse, normal to
 138         -- the major axis, at a distance equal to
 139         -- MajorRadius/e from the center of the ellipse, where
 140         -- e is the eccentricity of the ellipse.
 141         -- The first directrix (Directrix1) is on the positive side of
 142         -- the major axis. The second directrix (Directrix2) is on
 143         -- the negative side.
 144         -- The directrix is returned as an axis (gp_Ax1 object), the
 145         -- origin of which is situated on the "X Axis" of the local
 146         -- coordinate system of this ellipse.
 147         -- Exceptions
 148         -- Standard_ConstructionError if the eccentricity is null
 149         -- (the ellipse has degenerated into a circle).
 150
 151      raises ConstructionError
 152
 153      is static;
 154
 155
 156   Directrix2 (me)    returns Ax1
 157         ---C++:inline
 158         --- Purpose :
 159         --  This line is obtained by the symmetrical transformation
 160         --  of "Directrix1" with respect to the "YAxis" of the ellipse.
 161         -- Exceptions
 162         -- Standard_ConstructionError if the eccentricity is null
 163         -- (the ellipse has degenerated into a circle).
 164     raises ConstructionError
 165
 166      is static;
 167
 168
 169   Eccentricity (me)   returns Real
 170         ---C++:inline
 171         --- Purpose :
 172         --  Returns the eccentricity of the ellipse  between 0.0 and 1.0
 173         --  If f is the distance between the center of the ellipse and
 174         --  the Focus1 then the eccentricity e = f / MajorRadius.
 175         --   Raises ConstructionError if MajorRadius = 0.0
 176      raises ConstructionError
 177      is static;
 178
 179
 180   Focal (me)   returns Real   is static;
 181         ---C++:inline
 182         --- Purpose :
 183         --  Computes the focal distance. It is the distance between the
 184         --  two focus focus1 and focus2 of the ellipse.
 185
 186
 187   Focus1( me)   returns Pnt   is static;
 188         ---C++:inline
 189         --- Purpose :
 190         --  Returns the first focus of the ellipse. This focus is on the
 191         --  positive side of the "XAxis" of the ellipse.
 192
 193
 194   Focus2 (me)  returns Pnt  is static;
 195         ---C++:inline
 196         --- Purpose :
 197         --  Returns the second focus of the ellipse. This focus is on the
 198         --  negative side of the "XAxis" of the ellipse.
 199
 200
 201   Location (me)  returns Pnt   is static;
 202         ---C++:inline
 203         --- Purpose :
 204         --  Returns the center of the ellipse. It is the "Location"
 205         --  point of the coordinate system of the ellipse.
 206         ---C++: return const&
 207
 208
 209   MajorRadius (me)   returns Real   is static;
 210         --- Purpose : Returns the major radius of the ellipse.
 211         ---C++: inline
 212
 213
 214   MinorRadius (me)   returns Real  is static;
 215         --- Purpose : Returns the minor radius of the ellipse.
 216         ---C++: inline
 217
 218
 219   Parameter (me)   returns Real   is static;
 220         ---C++: inline
 221         --- Purpose :
 222         --  Returns p = (1 - e * e) * MajorRadius where e is the eccentricity
 223         --  of the ellipse.
 224         --  Returns 0 if MajorRadius = 0
 225
 226
 227   Position (me)    returns Ax2    is static;
 228         --- Purpose : Returns the coordinate system of the ellipse.
 229         ---C++: inline
 230         ---C++: return const&
 231
 232
 233   XAxis (me)  returns Ax1   is static;
 234         ---C++:inline
 235         --- Purpose :
 236         --  Returns the "XAxis" of the ellipse whose origin
 237         -- is the center of this ellipse. It is the major axis of the
 238         --  ellipse.
 239
 240
 241   YAxis (me)  returns Ax1   is static;
 242         ---C++:inline
 243         --- Purpose :
 244         --  Returns the "YAxis" of the ellipse whose unit vector is the "X Direction" or the "Y Direction"
 245         --  of the local coordinate system of this ellipse.
 246         -- This is the minor axis of the ellipse.
 247
 248
 249   Mirror (me : in out; P : Pnt)
 250         is static;
 251
 252   Mirrored (me; P : Pnt)   returns Elips  is static;
 253
 254
 255         --- Purpose :
 256         --  Performs the symmetrical transformation of an ellipse with
 257         --  respect to the point P which is the center of the symmetry.
 258
 259
 260   Mirror (me : in out; A1 : Ax1)
 261            is static;
 262
 263   Mirrored (me; A1 : Ax1)   returns Elips  is static;
 264
 265         --- Purpose :
 266         --  Performs the symmetrical transformation of an ellipse with
 267         --  respect to an axis placement which is the axis of the symmetry.
 268
 269
 270   Mirror (me : in out; A2 : Ax2)
 271          is static;
 272
 273   Mirrored (me; A2 : Ax2)  returns Elips  is static;
 274
 275    --- Purpose :
 276         --  Performs the symmetrical transformation of an ellipse with
 277         --  respect to a plane. The axis placement A2 locates the plane
 278         --  of the symmetry (Location, XDirection, YDirection).
 279
 280   Rotate (me : in out; A1 : Ax1; Ang : Real)
 281         ---C++: inline
 282          is static;
 283
 284   Rotated (me; A1 : Ax1; Ang : Real)  returns Elips  is static;
 285         ---C++: inline
 286         --- Purpose :
 287         --  Rotates an ellipse. A1 is the axis of the rotation.
 288         --  Ang is the angular value of the rotation in radians.
 289
 290
 291
 292
 293   Scale (me : in out; P : Pnt; S : Real)          is static;
 294         ---C++: inline
 295
 296   Scaled (me; P : Pnt; S : Real)   returns Elips  is static;
 297         ---C++: inline
 298         --- Purpose :
 299         --  Scales an ellipse. S is the scaling value.
 300
 301
 302
 303   Transform (me : in out; T : Trsf)           is static;
 304         ---C++: inline
 305
 306   Transformed (me; T : Trsf)   returns Elips  is static;
 307         ---C++: inline
 308         --- Purpose :
 309         --  Transforms an ellipse with the transformation T from class Trsf.
 310
 311
 312
 313   Translate (me : in out; V : Vec)
 314         ---C++: inline
 315           is static;
 316
 317   Translated (me; V : Vec)  returns Elips   is static;
 318         ---C++: inline
 319         --- Purpose :
 320         --  Translates an ellipse in the direction of the vector V.
 321         --  The magnitude of the translation is the vector's magnitude.
 322
 323
 324
 325   Translate (me : in out; P1, P2 : Pnt)
 326         ---C++: inline
 327          is static;
 328
 329   Translated (me; P1, P2 : Pnt)   returns Elips  is static;
 330         ---C++: inline
 331         --- Purpose :
 332         --  Translates an ellipse from the point P1 to the point P2.
 333
 334 fields
 335
 336      pos         : Ax2;
 337      majorRadius : Real;
 338      minorRadius : Real;
 339
 340 end;
 341