%% ==============================================================
%% Specification: Random Simple Polygons
%% --------------------------------------------------------------
%% author: Susan Hert
%% ==============================================================

\begin{ccRefFunction}{random_polygon_2}
\ccIndexMainItemBegin[c]{random simple polygon}
\ccIndexSubitemBegin[c]{generator}{simple polygon}

\ccDefinition

The function \ccRefName constructs a random simple polygon 
from points that are drawn from a specific domain.
Though each simple polygon defined on this set of 
points has a non-zero probability of being constructed, some polygons may 
have higher probabilities than others.  The overall distribution of the
generated polygons is not known since it depends on the generated points.

\ccInclude{CGAL/random_polygon_2.h}


\ccFunction{
template < class OutputIterator, class PointGenerator, class Traits > 
OutputIterator random_polygon_2( int n, OutputIterator result, 
                    const PointGenerator& pg, Traits t = Default_traits);
}
{
computes a random simple polygon by writing its vertices (oriented
counterclockwise) to \ccc{result}. The polygon generated will have a number
of vertices equal to the number of unique points in the first $n$ points
generated by \ccc{pg}. 
}

\ccRequirements
\begin{enumerate}
\item \ccc{Traits} is a model of the concept RandomPolygonTraits\_2
\item \ccc{PointGenerator::value_type} is equivalent to
      \ccc{Traits::Point_2} and \ccc{OutputIterator::value_type}.
\end{enumerate}

The default traits class \ccc{Default_traits} is the kernel in which
\ccc{Traits::Point_2} is defined.% 
\ccIndexTraitsClassDefault{random_polygon_2}

\ccSeeAlso 
\ccRefIdfierPage{CGAL::Random_points_in_disc_2<Point_2, Creator>} \\
\ccRefIdfierPage{CGAL::Random_points_in_square_2<Point_2, Creator>} \\

\ccImplementation 
The implementation is based on the method of eliminating self-intersections in
a polygon by using so-called ``2-opt'' moves.  Such a move eliminates an 
intersection between two edges by reversing the order of the vertices between 
the edges.  No more than $O(n^3)$ such moves are required to simplify a polygon
defined on $n$ points \cite{ls-utstp-82}.
Intersecting edges are detected using a simple sweep through the vertices
and then one intersection is chosen at random to eliminate after each sweep. 
The worse-case running time is therefore $O(n^4 \log n)$.
\ccIndexMainItemEnd[c]{random simple polygon}
\ccIndexSubitemEnd[c]{generator}{simple polygon}

\ccExample

The following program displays a random simple polygon with up to 100
vertices, where the vertex coordinates are drawn uniformly from the 
unit square centered at the origin.

\ccIncludeExampleCode{Generator/random_polygon.cpp}

\end{ccRefFunction}