1 -- Created on: 1993-03-24
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
24 class Ellipse from Geom2d inherits Conic from Geom2d
26 --- Purpose : Describes an ellipse in the plane (2D space).
27 -- An ellipse is defined by its major and minor radii and,
28 -- as with any conic curve, is positioned in the plane
29 -- with a coordinate system (gp_Ax22d object) where:
30 -- - the origin is the center of the ellipse,
31 -- - the "X Direction" defines the major axis, and
32 -- - the "Y Direction" defines the minor axis.
33 -- This coordinate system is the local coordinate system of the ellipse.
34 -- The orientation (direct or indirect) of the local
35 -- coordinate system gives an explicit orientation to the
36 -- ellipse, determining the direction in which the
37 -- parameter increases along the ellipse.
38 -- The Geom2d_Ellipse ellipse is parameterized by an angle:
39 -- P(U) = O + MajorRad*Cos(U)*XDir + MinorRad*Sin(U)*YDir
41 -- - P is the point of parameter U,
42 -- - O, XDir and YDir are respectively the origin, "X
43 -- Direction" and "Y Direction" of its local coordinate system,
44 -- - MajorRad and MinorRad are the major and
45 -- minor radii of the ellipse.
46 -- The "X Axis" of the local coordinate system therefore
47 -- defines the origin of the parameter of the ellipse.
48 -- An ellipse is a closed and periodic curve. The period
49 -- is 2.*Pi and the parameter range is [ 0,2.*Pi [.
51 -- GCE2d_MakeEllipse which provides functions for
52 -- more complex ellipse constructions
54 -- gp_Elips2d for an equivalent, non-parameterized data structure
65 raises ConstructionError from Standard,
66 RangeError from Standard
72 Create (E : Elips2d) returns mutable Ellipse;
74 -- Creates an ellipse by conversion of the gp_Elips2d ellipse E.
77 Create (MajorAxis : Ax2d; MajorRadius, MinorRadius : Real;
78 Sense: Boolean from Standard = Standard_True)
79 returns mutable Ellipse
80 --- Purpose : Creates an ellipse defined by its major and minor radii,
81 -- MajorRadius and MinorRadius, and positioned
82 -- in the plane by its major axis MajorAxis; the
83 -- center of the ellipse is the origin of MajorAxis
84 -- and the unit vector of MajorAxis is the "X
85 -- Direction" of the local coordinate system of the
86 -- ellipse; this coordinate system is direct if Sense
87 -- is true (default value) or indirect if Sense is false.
89 -- It is not forbidden to create an ellipse with MajorRadius =
92 -- Standard_ConstructionError if:
93 -- - MajorRadius is less than MinorRadius, or
94 -- - MinorRadius is less than 0.
95 raises ConstructionError;
98 Create (Axis : Ax22d; MajorRadius, MinorRadius : Real)
99 returns mutable Ellipse
100 --- Purpose : Creates an ellipse defined by its major and minor radii,
101 -- MajorRadius and MinorRadius, where the
102 -- coordinate system Axis locates the ellipse and
103 -- defines its orientation in the plane such that:
104 -- - the center of the ellipse is the origin of Axis,
105 -- - the "X Direction" of Axis defines the major
106 -- axis of the ellipse,
107 -- - the "Y Direction" of Axis defines the minor
108 -- axis of the ellipse,
109 -- - the orientation of Axis (direct or indirect)
110 -- gives the orientation of the ellipse.
112 -- It is not forbidden to create an ellipse with MajorRadius =
115 -- Standard_ConstructionError if:
116 -- - MajorRadius is less than MinorRadius, or
117 -- - MinorRadius is less than 0.
118 raises ConstructionError;
121 SetElips2d (me : mutable; E : Elips2d);
122 --- Purpose: Converts the gp_Elips2d ellipse E into this ellipse.
126 SetMajorRadius (me : mutable; MajorRadius : Real)
127 raises ConstructionError;
128 --- Purpose : Assigns a value to the major radius of this ellipse.
130 -- Standard_ConstructionError if:
131 -- - the major radius of this ellipse becomes less than
132 -- the minor radius, or
133 -- - MinorRadius is less than 0.
136 SetMinorRadius (me : mutable; MinorRadius : Real)
137 raises ConstructionError;
138 --- Purpose : Assigns a value to the minor radius of this ellipse.
140 -- Standard_ConstructionError if:
141 -- - the major radius of this ellipse becomes less than
142 -- the minor radius, or
143 -- - MinorRadius is less than 0.
146 Elips2d (me) returns Elips2d;
147 --- Purpose : Converts this ellipse into a gp_Elips2d ellipse.
150 ReversedParameter(me; U : Real) returns Real is redefined static;
151 ---Purpose: Computes the parameter on the reversed ellipse for
152 -- the point of parameter U on this ellipse.
153 -- For an ellipse, the returned value is: 2.*Pi - U.
156 Directrix1 (me) returns Ax2d
157 --- Purpose : Computes the directrices of this ellipse.
158 -- This directrix is the line normal to the XAxis of the ellipse
159 -- in the local plane (Z = 0) at a distance d = MajorRadius / e
160 -- from the center of the ellipse, where e is the eccentricity of
162 -- This line is parallel to the "YAxis". The intersection point
163 -- between directrix1 and the "XAxis" is the "Location" point
164 -- of the directrix1. This point is on the positive side of
166 -- Raises ConstructionError if Eccentricity = 0.0. (The ellipse degenerates
168 raises ConstructionError;
172 Directrix2 (me) returns Ax2d
174 -- This line is obtained by the symmetrical transformation
175 -- of "Directrix1" with respect to the "YAxis" of the ellipse.
176 -- Raises ConstructionError if Eccentricity = 0.0. (The ellipse degenerates into a
178 raises ConstructionError;
180 Eccentricity (me) returns Real is redefined static;
182 -- Returns the eccentricity of the ellipse between 0.0 and 1.0
183 -- If f is the distance between the center of the ellipse and
184 -- the Focus1 then the eccentricity e = f / MajorRadius.
185 -- Returns 0 if MajorRadius = 0
188 Focal (me) returns Real;
190 -- Computes the focal distance. The focal distance is the distance between the center
191 -- and a focus of the ellipse.
193 Focus1 (me) returns Pnt2d;
195 -- Returns the first focus of the ellipse. This focus is on the
196 -- positive side of the "XAxis" of the ellipse.
199 Focus2 (me) returns Pnt2d;
201 -- Returns the second focus of the ellipse. This focus is on
202 -- the negative side of the "XAxis" of the ellipse.
205 MajorRadius (me) returns Real;
206 ---Purpose: Returns the major radius of this ellipse.
208 MinorRadius (me) returns Real;
209 ---Purpose: Returns the minor radius of this ellipse.
211 Parameter (me) returns Real;
213 -- Computes the parameter of this ellipse. This value is
214 -- given by the formula p = (1 - e * e) * MajorRadius where e is the eccentricity
216 -- Returns 0 if MajorRadius = 0
219 FirstParameter (me) returns Real is redefined static;
220 --- Purpose : Returns the value of the first parameter of this
221 -- ellipse. This is 0.0, which gives the start point of this ellipse.
222 -- The start point and end point of an ellipse are coincident.
225 LastParameter (me) returns Real is redefined static;
226 --- Purpose : Returns the value of the last parameter of this
227 -- ellipse. This is 2.*Pi, which gives the end point of this ellipse.
228 -- The start point and end point of an ellipse are coincident.
232 IsClosed (me) returns Boolean is redefined static;
233 --- Purpose : return True.
236 IsPeriodic (me) returns Boolean is redefined static;
237 --- Purpose : return True.
240 D0(me; U : Real; P : out Pnt2d) is redefined static;
241 ---Purpose: Returns in P the point of parameter U.
242 -- P = C + MajorRadius * Cos (U) * XDir + MinorRadius * Sin (U) * YDir
243 -- where C is the center of the ellipse , XDir the direction of
244 -- the "XAxis" and "YDir" the "YAxis" of the ellipse.
248 D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d) is redefined static;
250 -- Returns the point P of parameter U and the first derivative
254 D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d) is redefined static;
256 -- Returns the point P of parameter U. The vectors V1 and V2
257 -- are the first and second derivatives at this point.
260 D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d) is redefined static;
262 -- Returns the point P of parameter U, the first second and
263 -- third derivatives V1 V2 and V3.
266 DN (me; U : Real; N : Integer) returns Vec2d
267 --- Purpose : For the point of parameter U of this ellipse,
268 -- computes the vector corresponding to the Nth derivative.
269 -- Exceptions Standard_RangeError if N is less than 1.
276 Transform (me : mutable; T : Trsf2d) is redefined static;
278 ---Purpose: Applies the transformation T to this ellipse.
280 Copy (me) returns mutable like me
282 ---Purpose: Creates a new object which is a copy of this ellipse.