1 -- Created on: 1993-03-24
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
6 -- This file is part of Open CASCADE Technology software library.
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
17 class Ellipse from Geom2d inherits Conic from Geom2d
19 --- Purpose : Describes an ellipse in the plane (2D space).
20 -- An ellipse is defined by its major and minor radii and,
21 -- as with any conic curve, is positioned in the plane
22 -- with a coordinate system (gp_Ax22d object) where:
23 -- - the origin is the center of the ellipse,
24 -- - the "X Direction" defines the major axis, and
25 -- - the "Y Direction" defines the minor axis.
26 -- This coordinate system is the local coordinate system of the ellipse.
27 -- The orientation (direct or indirect) of the local
28 -- coordinate system gives an explicit orientation to the
29 -- ellipse, determining the direction in which the
30 -- parameter increases along the ellipse.
31 -- The Geom2d_Ellipse ellipse is parameterized by an angle:
32 -- P(U) = O + MajorRad*Cos(U)*XDir + MinorRad*Sin(U)*YDir
34 -- - P is the point of parameter U,
35 -- - O, XDir and YDir are respectively the origin, "X
36 -- Direction" and "Y Direction" of its local coordinate system,
37 -- - MajorRad and MinorRad are the major and
38 -- minor radii of the ellipse.
39 -- The "X Axis" of the local coordinate system therefore
40 -- defines the origin of the parameter of the ellipse.
41 -- An ellipse is a closed and periodic curve. The period
42 -- is 2.*Pi and the parameter range is [ 0,2.*Pi [.
44 -- GCE2d_MakeEllipse which provides functions for
45 -- more complex ellipse constructions
47 -- gp_Elips2d for an equivalent, non-parameterized data structure
58 raises ConstructionError from Standard,
59 RangeError from Standard
65 Create (E : Elips2d) returns Ellipse;
67 -- Creates an ellipse by conversion of the gp_Elips2d ellipse E.
70 Create (MajorAxis : Ax2d; MajorRadius, MinorRadius : Real;
71 Sense: Boolean from Standard = Standard_True)
73 --- Purpose : Creates an ellipse defined by its major and minor radii,
74 -- MajorRadius and MinorRadius, and positioned
75 -- in the plane by its major axis MajorAxis; the
76 -- center of the ellipse is the origin of MajorAxis
77 -- and the unit vector of MajorAxis is the "X
78 -- Direction" of the local coordinate system of the
79 -- ellipse; this coordinate system is direct if Sense
80 -- is true (default value) or indirect if Sense is false.
82 -- It is not forbidden to create an ellipse with MajorRadius =
85 -- Standard_ConstructionError if:
86 -- - MajorRadius is less than MinorRadius, or
87 -- - MinorRadius is less than 0.
88 raises ConstructionError;
91 Create (Axis : Ax22d; MajorRadius, MinorRadius : Real)
93 --- Purpose : Creates an ellipse defined by its major and minor radii,
94 -- MajorRadius and MinorRadius, where the
95 -- coordinate system Axis locates the ellipse and
96 -- defines its orientation in the plane such that:
97 -- - the center of the ellipse is the origin of Axis,
98 -- - the "X Direction" of Axis defines the major
99 -- axis of the ellipse,
100 -- - the "Y Direction" of Axis defines the minor
101 -- axis of the ellipse,
102 -- - the orientation of Axis (direct or indirect)
103 -- gives the orientation of the ellipse.
105 -- It is not forbidden to create an ellipse with MajorRadius =
108 -- Standard_ConstructionError if:
109 -- - MajorRadius is less than MinorRadius, or
110 -- - MinorRadius is less than 0.
111 raises ConstructionError;
114 SetElips2d (me : mutable; E : Elips2d);
115 --- Purpose: Converts the gp_Elips2d ellipse E into this ellipse.
119 SetMajorRadius (me : mutable; MajorRadius : Real)
120 raises ConstructionError;
121 --- Purpose : Assigns a value to the major radius of this ellipse.
123 -- Standard_ConstructionError if:
124 -- - the major radius of this ellipse becomes less than
125 -- the minor radius, or
126 -- - MinorRadius is less than 0.
129 SetMinorRadius (me : mutable; MinorRadius : Real)
130 raises ConstructionError;
131 --- Purpose : Assigns a value to the minor radius of this ellipse.
133 -- Standard_ConstructionError if:
134 -- - the major radius of this ellipse becomes less than
135 -- the minor radius, or
136 -- - MinorRadius is less than 0.
139 Elips2d (me) returns Elips2d;
140 --- Purpose : Converts this ellipse into a gp_Elips2d ellipse.
143 ReversedParameter(me; U : Real) returns Real is redefined static;
144 ---Purpose: Computes the parameter on the reversed ellipse for
145 -- the point of parameter U on this ellipse.
146 -- For an ellipse, the returned value is: 2.*Pi - U.
149 Directrix1 (me) returns Ax2d
150 --- Purpose : Computes the directrices of this ellipse.
151 -- This directrix is the line normal to the XAxis of the ellipse
152 -- in the local plane (Z = 0) at a distance d = MajorRadius / e
153 -- from the center of the ellipse, where e is the eccentricity of
155 -- This line is parallel to the "YAxis". The intersection point
156 -- between directrix1 and the "XAxis" is the "Location" point
157 -- of the directrix1. This point is on the positive side of
159 -- Raises ConstructionError if Eccentricity = 0.0. (The ellipse degenerates
161 raises ConstructionError;
165 Directrix2 (me) returns Ax2d
167 -- This line is obtained by the symmetrical transformation
168 -- of "Directrix1" with respect to the "YAxis" of the ellipse.
169 -- Raises ConstructionError if Eccentricity = 0.0. (The ellipse degenerates into a
171 raises ConstructionError;
173 Eccentricity (me) returns Real is redefined static;
175 -- Returns the eccentricity of the ellipse between 0.0 and 1.0
176 -- If f is the distance between the center of the ellipse and
177 -- the Focus1 then the eccentricity e = f / MajorRadius.
178 -- Returns 0 if MajorRadius = 0
181 Focal (me) returns Real;
183 -- Computes the focal distance. The focal distance is the distance between the center
184 -- and a focus of the ellipse.
186 Focus1 (me) returns Pnt2d;
188 -- Returns the first focus of the ellipse. This focus is on the
189 -- positive side of the "XAxis" of the ellipse.
192 Focus2 (me) returns Pnt2d;
194 -- Returns the second focus of the ellipse. This focus is on
195 -- the negative side of the "XAxis" of the ellipse.
198 MajorRadius (me) returns Real;
199 ---Purpose: Returns the major radius of this ellipse.
201 MinorRadius (me) returns Real;
202 ---Purpose: Returns the minor radius of this ellipse.
204 Parameter (me) returns Real;
206 -- Computes the parameter of this ellipse. This value is
207 -- given by the formula p = (1 - e * e) * MajorRadius where e is the eccentricity
209 -- Returns 0 if MajorRadius = 0
212 FirstParameter (me) returns Real is redefined static;
213 --- Purpose : Returns the value of the first parameter of this
214 -- ellipse. This is 0.0, which gives the start point of this ellipse.
215 -- The start point and end point of an ellipse are coincident.
218 LastParameter (me) returns Real is redefined static;
219 --- Purpose : Returns the value of the last parameter of this
220 -- ellipse. This is 2.*Pi, which gives the end point of this ellipse.
221 -- The start point and end point of an ellipse are coincident.
225 IsClosed (me) returns Boolean is redefined static;
226 --- Purpose : return True.
229 IsPeriodic (me) returns Boolean is redefined static;
230 --- Purpose : return True.
233 D0(me; U : Real; P : out Pnt2d) is redefined static;
234 ---Purpose: Returns in P the point of parameter U.
235 -- P = C + MajorRadius * Cos (U) * XDir + MinorRadius * Sin (U) * YDir
236 -- where C is the center of the ellipse , XDir the direction of
237 -- the "XAxis" and "YDir" the "YAxis" of the ellipse.
241 D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d) is redefined static;
243 -- Returns the point P of parameter U and the first derivative
247 D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d) is redefined static;
249 -- Returns the point P of parameter U. The vectors V1 and V2
250 -- are the first and second derivatives at this point.
253 D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d) is redefined static;
255 -- Returns the point P of parameter U, the first second and
256 -- third derivatives V1 V2 and V3.
259 DN (me; U : Real; N : Integer) returns Vec2d
260 --- Purpose : For the point of parameter U of this ellipse,
261 -- computes the vector corresponding to the Nth derivative.
262 -- Exceptions Standard_RangeError if N is less than 1.
269 Transform (me : mutable; T : Trsf2d) is redefined static;
271 ---Purpose: Applies the transformation T to this ellipse.
273 Copy (me) returns like me
275 ---Purpose: Creates a new object which is a copy of this ellipse.