@c ellipse.texi

@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: ellipse.texi,v 1.9 2004/01/14 18:09:36 lfinsto1 Exp lfinsto1 $
 
@node Ellipse Reference, Circle Reference, Regular Closed Plane Curve Reference, Top
@chapter Ellipse Reference

@tindex Ellipse
Class @code{Ellipse} is defined in @file{ellipses.web}.
It is derived from @code{Reg_Cl_Plane_Curve} using public derivation.  

@menu
* Ellipse Data Members::        
* Ellipse Constructors and Setting Functions::  
* Performing Transformations on Ellipses::  
* Ellipse Operators::           
* Labeling Ellipses::           
* Affine Transformations for Ellipses::  
* Querying Ellipses::           
* Returning Elements and Information for Ellipses::  
* Ellipse Intersections::       
* Solving Ellipses::            
* Rectangles for Ellipses::     
@end menu
  
@node Ellipse Data Members, Ellipse Constructors and Setting Functions, Ellipse Reference, Ellipse Reference
@section Data Members

@deftypevr {Protected variables} Point focus0
@deftypevrx {} Point focus1
The foci of the @code{Ellipse}.  They are located on the major axis of
the @code{Ellipse} at a distance of @code{linear_eccentricity} from
@code{center}, on opposite sides of the minor axis.
@end deftypevr

@deftypevr {Protected variable} real linear_eccentricity
@c
The linear eccentricity of the @code{Ellipse} @math{e}, such that 
@iftex
@tex
$e = \sqrt{\strut a^2 - b^2}$, 
@end tex
@end iftex
@ifnottex 
@math{e = \sqrt{a^2 - b^2}}, 
@end ifnottex 
@c
where @math{a} and @math{b} are half the lengths of the major
and minor axes, respectively.  Let @math{h} stand for @code{axis_h} and @math{v}
for @code{axis_v}.  If @math{h>v}, then @math{a = h/2} and @math{b = v/2}.  If @math{v>h},
then @math{a =v/2} and @math{b = h/2}.  If @math{h = v}, then the @code{Ellipse} is
circular (but not an object of type  @code{Circle}!), and @math{a = b = v/2 = h/2}.

The linear eccentricity is the distance along the major axis of the
@code{Ellipse} from @code{center} to @code{focus0} and @code{focus1}.  
@c
@c !! TO DO: Add example.
@c
@end deftypevr

@deftypevr {Protected variable} real numerical_eccentricity
The numerical eccentricity @math{\epsilon} of the @code{Ellipse}, 
such
that @math{\epsilon = e/a < 1}, where @math{e} is the linear eccentricity of the
@code{Ellipse}, and @math{a} is half the length of the major axis of the
@code{Ellipse}.  
@end deftypevr

@deftypevr {Protected variables} real axis_h
@deftypevrx {} real axis_v
The horizontal and vertical axes, respectively, of the @code{Ellipse}.  

Actually, they are only or vertical
horizontal by convention, since there are no restrictions on the
orientation of an @code{Ellipse}.
@end deftypevr 

@deftypevr {Protected static variable} {unsigned short} DEFAULT_NUMBER_OF_POINTS
The number of @code{Points} on an @code{Ellipse}, unless another number
is specified when an @code{Ellipse} constructor is invoked.
@end deftypevr 


@node Ellipse Constructors and Setting Functions, Performing Transformations on Ellipses, Ellipse Data Members, Ellipse Reference
@section Constructors and Setting Functions

@deftypefn {Default constructor} void Ellipse (void)
Creates an empty @code{Ellipse}.
@end deftypefn 

@deftypefn {Constructor} void Ellipse ({const Point&} @var{ccenter}, {const real} @var{aaxis_h}, {const real} @var{aaxis_v}, [{const real} @var{angle_x} = 0, [{const real} @var{angle_y} = 0, [{const real} @var{angle_z} = 0, [{const unsigned short} @var{nnumber_of_points} = DEFAULT_NUMBER_OF_POINTS]]]])
Creates an @code{Ellipse} in the x-z plane, centered at the origin, with
its horizontal axis 
@equiv{} @var{aaxis_h} and its vertical axis @equiv{} @var{aaxis_v}.  If
any of the arguments @var{angle_x}, @var{angle_y}, or @var{angle_z} is
non-zero, the @code{Ellipse} is rotated about the x, y, and z-axis in
that order, by the amounts indicated by the corresponding arguments.
Finally, the @code{Ellipse} is shifted such that its
center comes to lie at @var{ccenter}.  

@example
Ellipse e(origin, 6, 4);
e.draw();
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 6, 4);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{draw_axes(gray, 3.5, "d", "", "rt");    }
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.159.png"
alt="[Figure 159. Not displayed.]"
/>
<br>
<br>
Fig. 159.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 159 not displayed.]
@end ifinfo

@example
Point P(1, 1, 1);
Ellipse e(P, 6, 4, 15, 12, 11);
e.draw();
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(3, 5, -10, 2, 4, 10, 10, 180);}
\immediate\write\examples{Point P(1, 1, 1);}
\immediate\write\examples{Ellipse e(P, 6, 4, 15, 12, 11);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{draw_axes(gray, 0, "d", "d", "rt");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.160.png"
alt="[Figure 160. Not displayed.]"
/>
<br>
<br>
Fig. 160.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 160 not displayed.]
@end ifinfo

@c
@end deftypefn 



@deftypefn {Setting function} void set ({const Point&} @var{ccenter}, {const real} @var{aaxis_h}, {const real} @var{aaxis_v}, [{const real} @var{angle_x} = 0, [{const real} @var{angle_y} = 0, [{const real} @var{angle_z} = 0, [{const unsigned short} @var{nnumber_of_points} = DEFAULT_NUMBER_OF_POINTS]]]])
@c
Corresponds to the constructor above.
@end deftypefn 

@deftypefn {Template specializations} Ellipse* create_new<Ellipse> ({const Ellipse*} @var{e})
@c
@deftypefnx {} Ellipse* create_new<Ellipse> ({const Ellipse&} @var{e})
@c
Pseudo-constructors for dynamic allocation of @code{Ellipses}.
They create a @code{Ellipse} on the free store and allocate memory for it using 
@code{new(Ellipse)}.  They return a pointer to the new @code{Ellipse}.  

If @var{e} is a non-zero pointer or a reference,
the new @code{Ellipse} will be a copy of
@var{e}.  If the new object is not meant to be a
copy of an existing one, @samp{0} must be passed to
@code{create_new<Ellipse>()} as its argument.
@xref{Dynamic Allocation of Shapes}, for more information. 
@end deftypefn 

@node Performing Transformations on Ellipses, Ellipse Operators, Ellipse Constructors and Setting Functions, Ellipse Reference
@section Performing Transformations

@deftypefn {Virtual function} Transform do_transform ({const Transform&} @var{t}, [bool @var{check} = @code{false}])
@c
Performs a transformation on an @code{Ellipse}.  The @code{Points} on
the @code{Ellipse} are multiplied by @var{t}.
Then, if @var{check} is @code{true}, 
@code{is_elliptical()} is called on the @code{Ellipse}.
If the transformation has caused it to
become non-elliptical, @code{axis_h} and @code{axis_v} are set to
@code{INVALID_REAL}, and a warning is issued to @code{stderr}.  
@code{center}, @code{focus0}, and @code{focus1} are not set to
@code{INVALID_POINT}.  They may may no longer really be 
the center and foci of the (non-elliptical) @code{Ellipse}, but they may 
have some use for the programmer and/or user.

If @var{check} is @code{true}, and the transformation does not cause
@code{*this} to become non-elliptical, 
@code{axis_h}, @code{axis_v}, @code{linear_eccentricity}, 
@code{numerical_eccentricity}, @code{focus0}, and
@code{focus1} are recalculated.

@end deftypefn 

@node Ellipse Operators, Labeling Ellipses, Performing Transformations on Ellipses, Ellipse Reference
@section Operators

@deftypefn {Assignment operator} Ellipse& {operator=}  ({const Ellipse&} @var{e})
Makes the @code{Ellipse} a copy of @var{e}.
@end deftypefn 


@deftypefn {Virtual function} Transform {operator*=}  ({const Transform&} @var{t})
Calls @code{do_transform(t, true)}, and returns the latter's return
value.
@xref{Performing Transformations on Ellipses,,Ellipse Reference; 
Performing Transformations}. 
@end deftypefn 

@node Labeling Ellipses, Affine Transformations for Ellipses, Ellipse Operators, Ellipse Reference
@section Labeling

@deftypefn {@code{const} function} void label ([{const string} @var{pos} = "top", [{const bool} @var{dot} = @code{false}, [Picture& @var{picture} = @code{current_picture}]]]) 
Labels the @code{Points} on @code{points}, using lowercase letters.
@var{pos} is used to position all of the labels.  It is currently not
possible to have different positions for the labels.

@example
Ellipse e(origin, 6, 4);
e.draw();
e.label(); 
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 6, 4);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{e.label();} 
\immediate\write\examples{draw_axes(gray, 3.5, "d", "", "rt");    }
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.161.png"
alt="[Figure 161. Not displayed.]"
/>
<br>
<br>
Fig. 161.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 161 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {Inline @code{const} function} void dotlabel ([string @var{pos} = "top", [Picture& @var{picture} = @code{current_picture}]])
Like @code{label()}, except that the @code{Points} are dotted.

@example
Ellipse e(origin, 6, 4);
e.draw();
e.dotlabel();
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 6, 4);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{e.dotlabel();} 
\immediate\write\examples{draw_axes(gray, 3.5, "d", "", "rt");    }
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.162.png"
alt="[Figure 162. Not displayed.]"
/>
<br>
<br>
Fig. 162.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 162 not displayed.]
@end ifinfo

@end deftypefn 

@node Affine Transformations for Ellipses, Querying Ellipses, Labeling Ellipses, Ellipse Reference
@section Affine Transformations

@deftypefn {Virtual function} Transform rotate ({const real} @var{x}, [{const real} @var{y} = 0, [{const real} @var{z} = 0]])
@deftypefnx {Virtual function} Transform rotate ({const Point&} @var{p0}, {const Point&} @var{p1}, [{const real} @var{angle} = 180])
@deftypefnx {Virtual function} Transform rotate ({const Path&} @var{p}, [{const real} @var{angle} = 180])
@deftypefnx {Virtual function} Transform scale (real @var{x}, [real @var{y} = 1, [real @var{z} = 1]])
@deftypefnx {Virtual function} Transform shear (real @var{xy}, [real @var{xz} = 0, [real @var{yx} = 0, [real @var{yz} = 0, [real @var{zx} = 0, [real @var{zy} = 0]]]]])
@deftypefnx {Virtual function} Transform shift (real @var{x}, [real @var{y} = 0, [real @var{z} = 0]])
@deftypefnx {Virtual function} Transform shift ({const Point&} @var{p})
@deftypefnx {Virtual function} void shift_times (real @var{x}, [real @var{y} = 1, [real @var{z} = 1]])
@deftypefnx {Virtual function} void shift_times ({const Point&} @var{p})
@c
These create a @code{Transform} @var{t} locally, and call
@code{do_transform(t)}.
@xref{Performing Transformations on Ellipses,,Ellipse Reference;
Performing Transformations}.  

Rotating and shifting an @code{Ellipse} neither change the size of an
@code{Ellipse}, nor cause it to become
non-elliptical.  However, scaling and shearing can have these effects.
For this reason, in @code{scale()} and @code{shear()},
@code{do_transform()} is called with @code{true} as its @var{check}
argument, while it is @code{false} in @code{rotate()}, @code{shift()},
and @code{shift_times()}.

If scaling or shearing is performed on an @code{Ellipse}, and it is
still elliptical after the transformation, @code{focus0}, @code{focus1}, 
@code{axis_h}, @code{axis_v}, @code{linear_eccentricity}, and 
@code{numerical_eccentricity} are all
recalculated.  If the @code{Ellipse} is non-elliptical after the
transformation, @code{axis_h}, @code{axis_v},
@code{linear_eccentricity}, and @code{numerical_eccentricity}
are all set to @code{INVALID_REAL}.  @code{center}, @code{focus0}, and
@code{focus1} are not set to @code{INVALID_POINT}.  Although they are no
longer the center and foci of an elliptical @code{Ellipse}, they may
still have some use for the user or programmer.
@end deftypefn 

@node Querying Ellipses, Returning Elements and Information for Ellipses, Affine Transformations for Ellipses, Ellipse Reference
@section Querying 

@deftypefn {@code{const} function} bool is_elliptical (void)
Returns @code{true} if the @code{Ellipse} is elliptical, otherwise
@code{false}. 

Certain transformations, such as shearing and scaling, can cause
@code{Ellipses} to become non-elliptical.
@end deftypefn 


@deftypefn {Inline @code{const} function} bool is_quadratic (@code{void}) 
Returns @code{true}, because the equation 
for an ellipse in the x-y plane with its center at the
origin is the quadratic equation
@iftex 
@tex 
$$x^2/a^2 + y^2/b^2 = 1$$
@end tex
@end iftex
@ifnottex 
@math{x^2/a^2 + y^2/b^2 = 1}
@end ifnottex 
@c
where @math{a} is half the horizontal axis
and @math{b} is half the vertical axis. 


@example
Ellipse e(origin, 5, 2, 90);
e.draw();
Point P(e.angle_point(-35));
cout << ((P.get_x() * P.get_x()) 
         / (e.get_axis_h()/2 * e.get_axis_h()/2)) 
        + ((P.get_y() * P.get_y()) 
           / (e.get_axis_v()/2 * e.get_axis_v()/2));
@print{} 1
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 5, 2, 90);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Point P(e.angle_point(-35));}
\immediate\write\examples{stringstream s;}
\immediate\write\examples{s << "$P=(" << P.get_x() << ", " << P.get_y() << ")$";}
\immediate\write\examples{P.dotlabel(s.str(), "urt");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.163.png"
alt="[Figure 163. Not displayed.]"
/>
<br>
<br>
Fig. 163.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 163 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} virtual functions} bool is_cubic (@code{void}) 
@deftypefnx {} bool is_quartic (@code{void}) 
These functions both return @code{false}, because the equation of an
ellipse is neither a cubic nor a quartic function.
@end deftypefn 

@node Returning Elements and Information for Ellipses, Ellipse Intersections, Querying Ellipses, Ellipse Reference
@section Returning Elements and Information

@deftypefn {Virtual function} Point& get_center (@code{void})
@deftypefnx {@code{const} virtual function} Point get_center (@code{void}) 
These functions return @code{center}.
@c !! TO DO: Add example.  
@end deftypefn 

@deftypefn {Function} {const Point&} get_focus ({const unsigned short} @var{s})
@deftypefnx {@code{const} function} Point get_focus ({const unsigned short} @var{s})
@c
These functions return @code{focus0} or @code{focus1}, depending on the
value of @var{s}, which must be 0 or 1.  If @var{s} is not 0 or 1,
@code{get_focus()} returns @code{INVALID_POINT}.
@c !! TO DO: Add example.
@end deftypefn 

@deftypefn {@code{const} function} real get_linear_eccentricity (void)
Returns @code{linear_eccentricity}.  
@c !! TO DO: Add example.
@end deftypefn 

@deftypefn {@code{const} function} real get_numerical_eccentricity (void)
Returns @code{numerical_eccentricity}.  
@c !! TO DO: Add example.
@end deftypefn 

@deftypefn {Function} real get_axis_v (@code{void}) 
@deftypefnx {@code{const} function} real get_axis_v (@code{void}) 
Calculates and returns the value of @code{axis_h}.

@code{get_axis_v()} first checks if the @code{Ellipse} is still
elliptical, using @code{is_elliptical()} 
(@pxref{Querying Ellipses,,Ellipse Reference; Querying}).  
Operations such as @code{scale()} and @code{shear()} can
cause an @code{Ellipse} to become non-elliptical.  
If this is the case, this function returns @code{INVALID_REAL}. 

If the @code{Ellipse} is still elliptical, @code{axis_v} is
recalculated and returned.  In the non-@code{const} version,
@code{axis_v} is also reset to the new value.
@end deftypefn 

@deftypefn {Function} real get_axis_h (@code{void}) 
@deftypefnx {@code{const} function} real get_axis_h (@code{void}) 
Calculates and returns the value of @code{axis_h}.

@code{get_axis_h()} first checks if the @code{Ellipse} is still
elliptical, using @code{is_elliptical()} 
(@pxref{Querying Ellipses,,Ellipse Reference; Querying}).  
Operations such as @code{scale()} and @code{shear()} can
cause an @code{Ellipse} to become non-elliptical.  
If this is the case, this function returns @code{INVALID_REAL}. 

If the @code{Ellipse} is still elliptical, @code{axis_h} is
recalculated and returned.  In the non-@code{const} version,
@code{axis_h} is also reset to the new value.
@end deftypefn 


@deftypefn {@code{const} virtual function} {signed short} location (Point @var{p}) 
@c
Returns a value @math{l} indicating the location of the @code{Point} argument
@math{p} with respect to the @code{Ellipse}.

Let @math{e} stand for the @code{Ellipse}.
The return values are as follows:


@table @asis
@item 0 
@math{p} lies on the perimeter of @math{e}.

@item 1
@math{p} lies in the plane of @math{e}, within its perimeter.

@item -1
@math{p} lies in the plane of @math{e}, outside its perimeter.

@item -2 
@math{p} and @math{e} do not lie in the same plane.

@item -3 
@math{e} is not elliptical, possibly due to having been transformed.
@end table

@example
Ellipse e(origin, 3, 5, 45, 15, 3);
e.shift(2, 1, 1);
Point A = e.get_point(7);
cout << e.location(A);
@print{} 0
Point B = center.mediate(e.get_point(2));
cout << e.location(B);
@print{} 1
Point C = center.mediate(e.get_point(2), 1.5);
cout << e.location(C);
@print{} -1
Point D = A;
D.shift(-2, 0, 4);
e.location(D);
@print{} WARNING! In Ellipse::location():
   Point doesn't lie in plane of Ellipse.
   Returning -2.
e.scale(1.5, 0, 1.5);
e.location(A);
@print{} WARNING! In Ellipse::do_transform(const Transform&):
   This transformation has made *this non-elliptical!

   ERROR! In Ellipse::location():
   Ellipse is non-elliptical. Returning -3.
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 10);}
\immediate\write\examples{Ellipse e(origin, 3, 5, 45, 15, 3);}
\immediate\write\examples{e.shift(2, 1, 1);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Point center = e.get_center();}
\immediate\write\examples{center.label("$e$", "");}
\immediate\write\examples{Point A = e.get_point(7);}
\immediate\write\examples{A.dotlabel("$A$", "lft"); }
\immediate\write\examples{Point B = center.mediate(e.get_point(2));}
\immediate\write\examples{B.dotlabel("$B$"); }
\immediate\write\examples{Point C = center.mediate(e.get_point(2), 1.5);}
\immediate\write\examples{C.dotlabel("$C$"); }
\immediate\write\examples{Point D = A;}
\immediate\write\examples{D.shift(-2, 0, 4);}
\immediate\write\examples{D.dotlabel("$D$"); }
\immediate\write\examples{e.scale(1.5, 0, 1.5);}
\immediate\write\examples{draw_axes(gray, 0, "d", "d", "lft");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.164.png"
alt="[Figure 164. Not displayed.]"
/>
<br>
<br>
Fig. 164.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 164 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} function} Point angle_point (real @var{angle})
Returns a point on the @code{Ellipse} given an angle.  
A @code{Point} @var{p} is set to the zeroth @code{Point} on the @code{Ellipse}
and rotated about the line from the center of the @code{Ellipse} in the
direction of the normal to the plane of the @code{Ellipse}.  
Then, the intersection of the ray from the center through
@var{p} and the perimeter of the @code{Ellipse} is returned.

@example
Ellipse e(origin, 6, 4);
Point P = e.angle_point(135);
current_picture.output(Projections::PARALLEL_X_Z);
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 6, 4);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Point center = e.get_center();}
\immediate\write\examples{center.label("$e$", "bot");}
\immediate\write\examples{Point e0 = e.get_point(0);}
\immediate\write\examples{e0.label(0, "rt");}
\immediate\write\examples{center.drawarrow(e0);}
\immediate\write\examples{Point P = e.angle_point(135);}
\immediate\write\examples{Point Q = e.angle_point(135/2.0);}
\immediate\write\examples{center.mediate(Q, .25).label("$@DBKS{theta} = 135^@DBKS{circ}$", "rt");}
\immediate\write\examples{center.drawarrow(P);}
\immediate\write\examples{P.label("$P$"); }
\immediate\write\examples{Point R(e.get_point(12));}
\immediate\write\examples{R.shift(0, 0, -.75);}
\immediate\write\examples{R.label("x-z plane");}
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.165.png"
alt="[Figure 165. Not displayed.]"
/>
<br>
<br>
Fig. 165.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 165 not displayed.]
@end ifinfo

@NEXTFIG{} demonstrates, that the rotation is unfortunately not always
in the direction one would prefer.  I don't have a solution to this
problem yet.

@example
Ellipse e(origin, 6, 4, 90);
Point P = e.angle_point(135);
Point Q = e.angle_point(-135);
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 6, 4, 90);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Point center = e.get_center();}
\immediate\write\examples{center.mediate(e.get_point(8), .25).label("$e$", "");}
\immediate\write\examples{Point e0 = e.get_point(0);}
\immediate\write\examples{e0.label(0, "rt");}
\immediate\write\examples{e.get_point(1).dotlabel(1);}
\immediate\write\examples{e.get_point(2).dotlabel(2);}
\immediate\write\examples{center.drawarrow(e0);}
\immediate\write\examples{Point P = e.angle_point(135);}
\immediate\write\examples{Point R = e.angle_point(135/2.0);}
\immediate\write\examples{center.mediate(R, .25).label("$@DBKS{theta} = 135^@DBKS{circ}$", "rt");}
\immediate\write\examples{center.drawarrow(P);}
\immediate\write\examples{P.label("$P$", "bot"); }
\immediate\write\examples{Point Q = e.angle_point(-135);}
\immediate\write\examples{R =  e.angle_point(-135/2.0);}
\immediate\write\examples{center.mediate(R, .25).label("$@DBKS{phi} = -135^@DBKS{circ}$", "rt");}
\immediate\write\examples{center.drawarrow(Q);}
\immediate\write\examples{Q.label("$Q$"); }
\immediate\write\examples{Point S(e.get_point(12));}
\immediate\write\examples{S.shift(0, -.75);}
\immediate\write\examples{S.label("x-y plane");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.166.png"
alt="[Figure 166. Not displayed.]"
/>
<br>
<br>
Fig. 166.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 166 not displayed.]
@end ifinfo

@end deftypefn 

@node Ellipse Intersections, Solving Ellipses, Returning Elements and Information for Ellipses, Ellipse Reference
@section Intersections

@deftypefn {@code{const} virtual function} bool_point_pair intersection_points ({const Point&} @var{p0}, {const Point&} @var{p1}) 
@deftypefnx {@code{const} virtual function} bool_point_pair intersection_points ({const Path&} @var{p}) 
@c
These functions return the intersection points of a line with an
@code{Ellipse}.  In the first version, the line is specified by the two
@code{Point} arguments. 
In the second version, @code{@var{p}.is_linear()} must return @code{true},
otherwise, @code{intersection_points()} issues an error message and 
returns @code{INVALID_BOOL_POINT_PAIR}.

If the line and the @code{Ellipse} are coplanar, there can be at most two
intersection points.  Otherwise, there can be at most one.

@example
Ellipse e(origin, 5, 7, 30, 30, 30);
e.shift(3, 0, 3);
Point p0 = e.get_center().mediate(e.get_point(3));
Point normal = e.get_normal();
Point A = normal;
A *= 2.5;
A.shift(p0);
Point B = normal;
B *= -2.5;
B.shift(p0);
bool_point_pair bpp = e.intersection_points(A, B);
bpp.first.pt.dotlabel("$i_0$", "rt"); 
Point C = e.get_point(15).mediate(e.get_point(11), 1.25);
Point D = e.get_point(11).mediate(e.get_point(15), 1.5);
Path q = C.draw(D);
bpp = e.intersection_points(q);
bpp.first.pt.dotlabel("$i_1$", "llft"); 
bpp.second.pt.dotlabel("$i_2$", "ulft"); 
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 10); }
\immediate\write\examples{Ellipse e(origin, 5, 7, 30, 30, 30);}
\immediate\write\examples{e.shift(3, 0, 3);}
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Point p0 = e.get_center().mediate(e.get_point(3));}
\immediate\write\examples{Point normal = e.get_normal();}
\immediate\write\examples{Point A = normal;}
\immediate\write\examples{A *= 2.5;}
\immediate\write\examples{A.shift(p0);}
\immediate\write\examples{Point B = normal;}
\immediate\write\examples{B *= -2.5;}
\immediate\write\examples{B.shift(p0);}
\immediate\write\examples{A.dotlabel("$A$"); }
\immediate\write\examples{B.dotlabel("$B$", "bot"); }
\immediate\write\examples{bool_point_pair bpp = e.intersection_points(A, B);}
\immediate\write\examples{bpp.first.pt.dotlabel("$i_0$", "rt"); }
\immediate\write\examples{A.draw(bpp.first.pt);}
\immediate\write\examples{bpp.first.pt.draw(B, black, "evenly");}
\immediate\write\examples{Point C = e.get_point(15).mediate(e.get_point(11), 1.25);}
\immediate\write\examples{C.dotlabel("$C$", "bot"); }
\immediate\write\examples{Point D = e.get_point(11).mediate(e.get_point(15), 1.5);}
\immediate\write\examples{D.dotlabel("$D$"); }
\immediate\write\examples{Path q = C.draw(D);}
\immediate\write\examples{bpp = e.intersection_points(q);}
\immediate\write\examples{bpp.first.pt.dotlabel("$i_1$", "llft"); }
\immediate\write\examples{bpp.second.pt.dotlabel("$i_2$", "ulft"); }
\immediate\write\examples{draw_axes(gray, 0, "d", "d", "lft");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.167.png"
alt="[Figure 167. Not displayed.]"
/>
<br>
<br>
Fig. 167.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 167 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} virtual function} bool_point_quadruple intersection_points (Ellipse @var{e}, [{const real} @var{step} = 3, [bool @var{verbose} = @code{false}]]) 
Returns the intersection points of two @code{Ellipses}.  Two @code{Ellipses}
can intersect at at most four points.  

Let @var{bpq} be the @code{bool_point_quadruple} returned by
@code{intersection_points()}.  If one or more intersection points are
found, the corresponding @code{Points} are stored in the
@code{pt} elements of the four @code{bool_points} belonging to
@var{bpq}, otherwise @code{INVALID_POINT}.  If a @code{Point} is found, the
@code{b} element of the @code{bool_point} will be @code{true}, otherwise
@code{false}.  

The @var{step} argument is used when the @code{Ellipses} are coplanar
and either have different centers or the vertical axis of one @code{Ellipse} is
colinear with the horizontal axis of the other (and vice versa).  In
these cases, the intersection points must be found by an iterative
routine.  A @code{Point} @math{p} travels around the perimeter of @code{*this},
and its location with respect to @var{e} is tested.  @var{step} is the
angle of rotation used for stepping around the perimeter of
@code{*this}.  The default value, 3, should be adequate, unless the
@code{Ellipses} differ greatly in size. 

If the @var{verbose} argument is @code{true},
@code{intersection_points()} will print information about the
intersection points to standard output.

In @NEXTFIG{}, the @code{Ellipses} @math{e} and @math{f} both lie in the x-z
plane, are centered at the origin, and intersect at four points.

@example
Ellipse e(origin, 5, 2);
Ellipse f(origin, 2, 5);
bool_point_quadruple bpq = e.intersection_points(f);
bpq.first.pt.dotlabel(1, "llft"); 
bpq.second.pt.dotlabel(2, "urt"); 
bpq.third.pt.dotlabel(3, "ulft"); 
bpq.fourth.pt.dotlabel(4, "lrt"); 
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 5, 2);}
\immediate\write\examples{Point pt_e(origin.mediate(e.get_point(0), .75));}
\immediate\write\examples{pt_e.shift(0, 0, .2);}
\immediate\write\examples{pt_e.label("$e$", "");}
\immediate\write\examples{Ellipse f(origin, 2, 5);}
\immediate\write\examples{Point pt_f(origin.mediate(f.get_point(4), .75));}
\immediate\write\examples{pt_f.shift(.2);}
\immediate\write\examples{pt_f.label("$f$", "");}
\immediate\write\examples{e.draw();}
\immediate\write\examples{f.draw();}
\immediate\write\examples{bool_point_quadruple bpq = e.intersection_points(f);}
\immediate\write\examples{bpq.first.pt.dotlabel(1, "llft"); }
\immediate\write\examples{bpq.second.pt.dotlabel(2, "urt"); }
\immediate\write\examples{bpq.third.pt.dotlabel(3, "ulft"); }
\immediate\write\examples{bpq.fourth.pt.dotlabel(4, "lrt"); }
\immediate\write\examples{draw_axes(gray, 3.5, "d", "", "rt");}
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.168.png"
alt="[Figure 168. Not displayed.]"
/>
<br>
<br>
Fig. 168.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 168 not displayed.]
@end ifinfo

In @NEXTFIG{}, @math{e} and @math{f} are coplanar, but don't lie in a major plane,
have different centers, and only intersect at two points.

@example
Ellipse e(origin, 4, 2);
Ellipse f(origin, 2, 5);
f.shift(0, 0, 1);
f.rotate(0, 15);
f.shift(1, 0, 1);
e *= f.shift(-.25, 1, -1);
e *= f.rotate(10, -12.5, 3);
bool_point_quadruple bpq = e.intersection_points(f, true);
bpq.first.pt.dotlabel(1, "urt"); 
bpq.second.pt.dotlabel(2, "ulft"); 
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 15);}
\immediate\write\examples{Ellipse e(origin, 4, 2);}
\immediate\write\examples{Ellipse f(origin, 2, 5);}
\immediate\write\examples{f.shift(0, 0, 1);}
\immediate\write\examples{f.rotate(0, 15);}
\immediate\write\examples{f.shift(1, 0, 1);}
\immediate\write\examples{e *= f.shift(-.25, 1, -1);}
\immediate\write\examples{e *= f.rotate(10, -12.5, 3);}
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{f.get_center().mediate(f.get_point(4)).label("$f$", ""); }
\immediate\write\examples{e.draw();}
\immediate\write\examples{f.draw();}
\immediate\write\examples{bool_point_quadruple bpq = e.intersection_points(f, true);}
\immediate\write\examples{bpq.first.pt.dotlabel(1, "rt"); }
\immediate\write\examples{bpq.second.pt.dotlabel(2, "ulft"); }
\immediate\write\examples{draw_axes(gray, 0, "d", "d", "urt");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.169.png"
alt="[Figure 169. Not displayed.]"
/>
<br>
<br>
Fig. 169.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 169 not displayed.]
@end ifinfo

If the planes of the @code{Ellipses} are parallel, there are, of course,
no intersection points.  If the @code{Ellipses} are non-coplanar, and
their planes are not parallel to each other,
@code{intersection_points()} first finds the line of intersection of the
planes of the @code{Ellipses}.  It then returns the @code{Points} of
intersection of this line with the @code{Ellipses}, if they exist.  If
the @var{verbose} argument is @code{true}, information about the
@code{Points} is printed to standard output.

In @NEXTFIG{}, the two @code{Ellipses} lie in skew planes.  The plane
of @math{f} intersects with @math{e} at the @code{Points} labelled ``1'' and ``2'',
while the plane of @math{e} intersects with @math{f} at the @code{Points} labelled
``3'' and ``4''.

@example
Ellipse e(origin, 5, 3);
Ellipse f(origin, 2, 5);
f.rotate(0, 0, 30);
f.rotate(0, 10);
f.rotate(45);
f.shift(1.5, 1);
bool_point_quadruple bpq = e.intersection_points(f, true);
bpq.first.pt.dotlabel(1); 
bpq.second.pt.dotlabel(2); 
bpq.third.pt.dotlabel(3, "rt"); 
bpq.fourth.pt.dotlabel(4, "urt"); 
@print{} First point lies on the perimeter of *this.
   First point lies inside e.
   Second point lies on the perimeter of *this.
   Second point lies outside e.
   Third point lies outside *this.
   Third point lies on the perimeter of e.
   Fourth point lies inside *this.
   Fourth point lies on the perimeter of e.
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 10);}
\immediate\write\examples{Ellipse e(origin, 5, 3);}
\immediate\write\examples{Ellipse f(origin, 2, 5);}
\immediate\write\examples{f.rotate(0, 0, 30);}
\immediate\write\examples{f.rotate(0, 10);}
\immediate\write\examples{f.rotate(45);}
\immediate\write\examples{f.shift(1.5, 1);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{f.draw();}
\immediate\write\examples{bool_point_quadruple bpq = e.intersection_points(f, true);}
\immediate\write\examples{bpq.first.pt.dotlabel(1); }
\immediate\write\examples{bpq.second.pt.dotlabel(2); }
\immediate\write\examples{bpq.third.pt.dotlabel(3, "rt"); }
\immediate\write\examples{bpq.fourth.pt.dotlabel(4, "urt"); }
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{f.get_center().label("$f$", "");}
\immediate\write\examples{bpq.second.pt.draw(bpq.third.pt, black, "evenly");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.170.png"
alt="[Figure 170. Not displayed.]"
/>
<br>
<br>
Fig. 170.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 170 not displayed.]
@end ifinfo

In @NEXTFIG{}, the two @code{Ellipses} lie in skew planes.  The plane of
@math{f} intersects with @math{e} at the @code{Points} labelled ``1'' and ``2''.
The plane of @math{e} does not intersect with @math{f}, so @code{bpq.third.pt}
and @code{bpq.fourth.pt} are @code{INVALID_POINT}.

@example
Ellipse e(origin, 5, 3);
Ellipse f(origin, 2, 5, 45);
f.shift(0, 2.5, 3);
bool_point_quadruple bpq = e.intersection_points(f, true);
bpq.first.pt.dotlabel(1);
bpq.second.pt.dotlabel(2);
@print{} First point lies on the perimeter of *this.
   First point lies outside e.
   Second point lies on the perimeter of *this.
   Second point lies outside e.
   Third intersection point is INVALID_POINT.
   Fourth intersection point is INVALID_POINT.
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 10);}
\immediate\write\examples{Ellipse e(origin, 5, 3);}
\immediate\write\examples{Ellipse f(origin, 2, 5, 45);}
\immediate\write\examples{f.shift(0, 2.5, 3);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{f.draw();}
\immediate\write\examples{bool_point_quadruple bpq = e.intersection_points(f, true);}
\immediate\write\examples{bpq.first.pt.dotlabel(1); }
\immediate\write\examples{bpq.second.pt.dotlabel(2); }
\immediate\write\examples{bpq.first.pt.draw(bpq.second.pt, black, "evenly");}
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{f.get_center().label("$f$", "");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.171.png"
alt="[Figure 171. Not displayed.]"
/>
<br>
<br>
Fig. 171.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 171 not displayed.]
@end ifinfo

@end deftypefn 

@node Solving Ellipses, Rectangles for Ellipses, Ellipse Intersections, Ellipse Reference
@section Solving 

@deftypefn {@code{const} function} real_pair solve (char @var{axis_unknown}, real @var{known}) 
Returns two possible values for either the horizontal or vertical
coordinate.  This function assumes that the @code{Ellipse} lies in a major
plane with @code{center} at the origin.  Code that calls it must ensure
that these conditions are fulfilled.
@c !! TO DO: Add EXAMPLE!! 

@code{solve()} is called in
@code{Reg_Cl_Plane_Curve::intersection_points(Point, Point, Point)} and 
@code{Reg_Cl_Plane_Curve::location()}, and
resolves to this function, when these functions are called on an
@code{Ellipse}.  However, @code{Ellipse::location()} overloads
@code{Reg_Cl_Plane_Curve::location()}, so the latter won't normally be
called on an @code{Ellipse}.  
@c
@xref{Regular Closed Plane Curve Intersections,,
Regular Closed Plane Curve Reference; Intersections}, and 
@ref{Querying Regular Closed Plane Curves,,
Regular Closed Plane Curve Reference; Querying}.

@end deftypefn 

@deftypefn {@code{const} function} real_triple get_coefficients (real @var{Slope}, real @var{v_intercept}) 

Let @math{x} and @math{y} stand for the x and y-coordinates of a point on an
ellipse in the x-y plane, @math{a} for half of the horizontal axis
@c
@iftex 
@tex 
(@code{axis_h}$/2$), 
@end tex
@end iftex
@c
@ifnottex 
@math{(@code{axis_h} / 2)}, 
@end ifnottex 
@c
and @math{b} for half of the vertical axis
@c
@iftex 
@tex 
(@code{axis_v}$/2$). 
@end tex
@end iftex
@c
@ifnottex 
@math{(@code{axis_v} / 2)}. 
@end ifnottex 

Further, let @math{y = mx + i} be the equation of a line in
the x-y plane, where @math{m} is the slope and @math{i} the
y-intercept. 

This function returns the coefficients of the quadratic equation 
that results from replacing @math{y} with @math{mx + i}
in the equation for the ellipse   
@c
@iftex 
@tex 
$$x^2/a^2 + y^2/b^2 = 1$$ 
namely 
$$x^2/a^2 + (mx + i)^2/b^2 - 1 = 0$$ 
$$\equiv (b^2x + a^2m^2)x^2 + 2a^2imx 
+ (a^2i^2 - a^2b^2) = 0.$$
@end tex
@end iftex
@c
@ifnottex 

@display
@math{x^2/a^2 + y^2/b^2 = 1}@*
@end display
namely
@display 
@math{x^2/a^2 + (mx + i)^2/b^2 - 1 = 0}
@math{== (b^2x + a^2m^2)x^2 + 2a^2imx + (a^2i^2 - a^2b^2) = 0}.
@end display
@end ifnottex 
@c
The coefficients are returned in the @code{real_triple} in the order
one would expect: @code{r.first} is the coefficient of @math{x^2}, @code{r.second} of
@math{x} and @code{r.third} of the constant term 
@iftex 
@tex 
($x^0 \equiv 1 $).
@end tex
@end iftex
@c
@ifnottex 
@math{(x^0 == 1)}. 
@end ifnottex 

@code{get_coefficients()} is called in 
@code{Reg_Cl_Plane_Curve::intersection_points(Point, Point, Point)}, and 
resolves to this function, when the latter is called on an
@code{Ellipse}.  
@xref{Regular Closed Plane Curve Intersections,,
Regular Closed Plane Curve Reference; Intersections}.
@end deftypefn 

@node Rectangles for Ellipses,  , Solving Ellipses, Ellipse Reference
@section Rectangles

@deftypefn {@code{const} function} Rectangle out_rectangle (@code{void})
Returns the @code{Rectangle} that surrounds the @code{Ellipse}.

@example
Ellipse e(origin, 3, 4, 45, 30, 17);
e.shift(1, -1, 2);
Rectangle r = e.out_rectangle();
r.filldraw(black, gray);
e.unfilldraw(black);
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 3, 4, 45, 30, 17);}
\immediate\write\examples{e.shift(1, -1, 2);}
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{Rectangle r = e.out_rectangle();}
\immediate\write\examples{r.filldraw(black, gray);}
\immediate\write\examples{e.unfilldraw(black);}
\immediate\write\examples{r.get_point(2).mediate(r.get_point(3)).label("$r$");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.172.png"
alt="[Figure 172. Not displayed.]"
/>
<br>
<br>
Fig. 172.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 172 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} function} Rectangle in_rectangle (@code{void})
Returns the @code{Rectangle} enclosed within the @code{Ellipse}.

@example
Rectangle r = e.in_rectangle();
e.filldraw(black, gray);
r.unfilldraw(black);
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Ellipse e(origin, 3, 4, 45, 30, 17);}
\immediate\write\examples{e.shift(1, -1, 2);}
\immediate\write\examples{e.get_point(4).label("$e$");}
\immediate\write\examples{Rectangle r = e.in_rectangle();}
\immediate\write\examples{r.get_center().label("$r$", "");}
\immediate\write\examples{e.filldraw(black, gray);}
\immediate\write\examples{r.unfilldraw(black);}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.173.png"
alt="[Figure 173. Not displayed.]"
/>
<br>
<br>
Fig. 173.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 173 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} function} Rectangle draw_out_rectangle ([{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]])
Draws the @code{Rectangle} that surrounds the @code{Ellipse}.  The arguments
are like those of @code{Path::draw()}.   
The return value is the surrounding @code{Rectangle}.
@xref{Drawing and Filling Paths,, Path Reference; Drawing and Filling}.


@example
Ellipse e(origin, 2.5, 5, 10, 12, 15.5);
e.shift(-1, 1, 1);
e.draw_out_rectangle(black, "evenly", "pencircle scaled .3mm");
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 3, -10, 1, 2, 10, 10);}
\immediate\write\examples{Ellipse e(origin, 2.5, 5, 10, 12, 15.5);}
\immediate\write\examples{e.shift(-1, 1, 1);}
\immediate\write\examples{e.filldraw(black, gray);}
\immediate\write\examples{Rectangle r = e.draw_out_rectangle(black, "evenly", "pencircle scaled .3mm");}
\immediate\write\examples{e.get_center().label("$e$", "");}
\immediate\write\examples{r.get_point(0).mediate(r.get_point(1), .25).label("$r$");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.174.png"
alt="[Figure 174. Not displayed.]"
/>
<br>
<br>
Fig. 174.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 174 not displayed.]
@end ifinfo

@end deftypefn 

@deftypefn {@code{const} function} Rectangle draw_in_rectangle ([{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]])
Draws the @code{Rectangle} enclosed within the @code{Ellipse}.  The arguments 
are like those of @code{Path::draw()}. 
The return value is the enclosed @code{Rectangle}.
@xref{Drawing and Filling Paths, , Path Reference; Drawing and Filling}. 

@example
Ellipse e(origin, 3.5, 6, 10, 12, 15.5);
e.shift(-1, 1, 1);
e.draw_in_rectangle(black, "evenly", "pencircle scaled .3mm");
@end example
  
@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 3, -10, 1, 2, 10, 10);}
\immediate\write\examples{Ellipse e(origin, 3.5, 6, 10, 12, 15.5);}
\immediate\write\examples{e.shift(-1, 1, 1);}
\immediate\write\examples{e.draw();}
\immediate\write\examples{Rectangle r = e.draw_in_rectangle}
\immediate\write\examples{(black, "evenly", "pencircle scaled .3mm");} 
\immediate\write\examples{r.get_center().label("$r$", "");}
\immediate\write\examples{e.get_point(12).label("$e$");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX  
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.175.png"
alt="[Figure 175. Not displayed.]"
/>
<br>
<br>
Fig. 175.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 175 not displayed.]
@end ifinfo

@end deftypefn 

