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