mirror of https://github.com/CGAL/cgal
460 lines
18 KiB
TeX
460 lines
18 KiB
TeX
% +------------------------------------------------------------------------+
|
|
% | CEBaP Reference Manual: generators.tex
|
|
% +------------------------------------------------------------------------+
|
|
% | Random sources and geometric object generators.
|
|
% |
|
|
% | 09.06.1997 Lutz Kettner
|
|
% |
|
|
\RCSdef{\generatorsRev}{$Revision$}
|
|
\RCSdefDate{\generatorsDate}{$Date$}
|
|
% +------------------------------------------------------------------------+
|
|
|
|
\beforecprogskip\medskipamount
|
|
\aftercprogskip\medskipamount
|
|
\ccParDims
|
|
|
|
\chapter{Random Sources and Geometric Object Generators}
|
|
\label{chapterGenerators}
|
|
\ccChapterSubTitle{\generatorsRev. \ \generatorsDate}\\
|
|
\ccChapterAuthor{Lutz Kettner}\\
|
|
\ccChapterAuthor{Sven Sch\"onherr}
|
|
|
|
|
|
A variety of generators for random numbers and geometric objects is
|
|
provided in \cgal. They are useful as synthetic test data sets,
|
|
e.g.~for testing algorithms on degenerate object sets and for
|
|
performance analysis.
|
|
|
|
The first section describes the random number source used for random
|
|
generators. The second section documents generators for point sets,
|
|
the third section for segments. Note that the \stl\ algorithm
|
|
\ccc{random_shuffle} is useful in this context to achieve random
|
|
permutations (e.g.~for points on a grid).
|
|
|
|
|
|
% +------------------------------------------------------------------------+
|
|
\input{Random}
|
|
|
|
% +------------------------------------------------------------------------+
|
|
%\newpage
|
|
\section{Support Functions for Generators}
|
|
\ccThree{OutputIterator}{rand}{}
|
|
|
|
Two support functions are provided. \ccc{CGAL_copy_n()} copies $n$
|
|
items from an input iterator to an output iterator which is useful for
|
|
possibly infinite sequences of random geometric objects\footnote{%
|
|
The STL release June 13, 1997, from SGI has a new function \ccc{copy_n} which is equivalent with \ccc{CGAL_copy_n}.}.
|
|
\ccc{CGAL_random_selection} chooses $n$ items at random from a random
|
|
access iterator range which is useful to produce degenerate input data
|
|
sets with multiple entries of identical items.
|
|
|
|
\subsection{{\it CGAL\_copy\_n()}}
|
|
\label{sectionCopyN}
|
|
|
|
\ccInclude{CGAL/copy_n.h}
|
|
|
|
\ccFunction{template <class InputIterator, class Size, class OutputIterator>
|
|
OutputIterator CGAL_copy_n( InputIterator first, Size n,
|
|
OutputIterator result);}
|
|
{copies the first $n$ items from \ccc{first} to \ccc{result}.
|
|
Returns the value of \ccc{result} after inserting the $n$ items.}
|
|
|
|
\subsection{{\it CGAL\_random\_selection()}}
|
|
\label{sectionRandomSelection}
|
|
|
|
\ccInclude{CGAL/random_selection.h}
|
|
|
|
\ccFunction{template <class RandomAccessIterator, class Size,
|
|
class OutputIterator, class Random>
|
|
OutputIterator CGAL_random_selection( RandomAccessIterator first,
|
|
RandomAccessIterator last,
|
|
Size n, OutputIterator result, Random& rnd = CGAL_random);}
|
|
{ choose a random item from the range $[\ccc{first},\ccc{last})$ and
|
|
write it to \ccc{result}, each item from the range with equal
|
|
probability. Repeat this $n$ times, thus writing $n$ items to
|
|
\ccc{result}.
|
|
A single random number is needed from \ccc{rnd} for each item.
|
|
Returns the value of \ccc{result} after inserting the $n$ items.
|
|
\ccPrecond \ccc{Random} is a random number generator type as provided
|
|
by the STL or by \ccc{CGAL_Random}.
|
|
}
|
|
|
|
|
|
|
|
% +------------------------------------------------------------------------+
|
|
\newpage
|
|
\section{2D Point Generators}
|
|
|
|
\ccDefinition
|
|
|
|
Point generators are provided for random points uniformly distributed
|
|
over a two-dimensional domain (square or disc) or a one-dimensional
|
|
domain (boundary of a square, circle, or segment). Other point
|
|
generators create two-dimensional grids or equally spaced points on a
|
|
segment. A perturbation function adds random noise to a given set of
|
|
points. Several functions add degeneracies: the duplication of randomly
|
|
chosen points and the construction of a collinear point between two randomly
|
|
chosen points from a set of points.
|
|
|
|
|
|
\ccInclude{CGAL/point_generators_2.h}
|
|
|
|
\ccCreation
|
|
|
|
The random point generators build two-dimensional points from a pair
|
|
of \ccc{double}'s. Depending on the point representation and
|
|
arithmetic, a different building process is necessary. It is
|
|
encapsulated in the global function \ccc{CGAL_build_point()}.
|
|
Implementations exist for \ccc{CGAL_Cartesian<double>} and
|
|
\ccc{CGAL_Cartesian<float>}. They are automatically included if the
|
|
representation type \ccc{CGAL_Cartesian} has been included beforehand.
|
|
For other representations and arithmetic types the function can be
|
|
overloaded.
|
|
|
|
\ccThree{void}{random}{}
|
|
\ccFunction{void CGAL_build_point( double x, double y, Point&
|
|
p);}{builds a point $(x,y)$ in $p$. \ccc{Point} is the point type in
|
|
question.}
|
|
|
|
\ccHeading{Random Points}
|
|
|
|
The random point generators are implemented as classes that satisfies
|
|
the requirements for input iterators. They represent the possibly
|
|
infinite sequence of randomly generated points. Each call to the
|
|
\ccc{operator*} returns a new point. To create a finite sequence in a
|
|
container, the function \ccc{CGAL_copy_n()} could be used, see
|
|
Section~\ref{sectionCopyN}.
|
|
|
|
\ccHtmlNoClassFile
|
|
\begin{ccClassTemplate}{CGAL_Random_points_in_disc_2<P>}
|
|
\ccCreationVariable{g}
|
|
\ccConstructor{CGAL_Random_points_in_disc_2( double r, CGAL_Random& rnd =
|
|
CGAL_random);}{%
|
|
$g$ is an input iterator creating points of type \ccc{P} uniformly
|
|
distributed in the open disc with radius $r$,
|
|
i.e.~$|\ccc{*g}| < r$~. Two random numbers are needed from
|
|
\ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type
|
|
\ccc{P} exists.}
|
|
\end{ccClassTemplate}
|
|
|
|
\ccHtmlNoClassFile
|
|
\begin{ccClassTemplate}{CGAL_Random_points_on_circle_2<P>}
|
|
\ccCreationVariable{g}
|
|
\ccConstructor{CGAL_Random_points_on_circle_2( double r, CGAL_Random& rnd =
|
|
CGAL_random);}{%
|
|
$g$ is an input iterator creating points of type \ccc{P} uniformly
|
|
distributed on the circle with radius $r$,
|
|
i.e.~$|\ccc{*g}| == r$~. A single random number is needed from
|
|
\ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type
|
|
\ccc{P} exists.}
|
|
\end{ccClassTemplate}
|
|
|
|
\ccHtmlNoClassFile
|
|
\begin{ccClassTemplate}{CGAL_Random_points_in_square_2<P>}
|
|
\ccCreationVariable{g}
|
|
\ccConstructor{CGAL_Random_points_in_square_2( double a, CGAL_Random& rnd =
|
|
CGAL_random);}{%
|
|
$g$ is an input iterator creating points of type \ccc{P} uniformly
|
|
distributed in the half-open square with side length $a$, centered
|
|
at the origin, i.e.~$\forall p = \ccc{*g}: -\frac{a}{2} \le
|
|
p.x() < \frac{a}{2}$ and $-\frac{a}{2} \le p.y() < \frac{a}{2}$~.
|
|
Two random numbers are needed from \ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type
|
|
\ccc{P} exists.}
|
|
\end{ccClassTemplate}
|
|
|
|
\ccHtmlNoClassFile
|
|
\begin{ccClassTemplate}{CGAL_Random_points_on_square_2<P>}
|
|
\ccCreationVariable{g}
|
|
\ccConstructor{CGAL_Random_points_on_square_2( double a, CGAL_Random& rnd =
|
|
CGAL_random);}{%
|
|
$g$ is an input iterator creating points of type \ccc{P} uniformly
|
|
distributed on the boundary of the square with side length $a$,
|
|
centered at the origin, i.e.~$\forall p = \ccc{*g}:$ one
|
|
coordinate is either $\frac{a}{2}$ or $-\frac{a}{2}$ and for the
|
|
other coordinate $c$ holds $-\frac{a}{2} \le c < \frac{a}{2}$~.
|
|
A single random number is needed from \ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type
|
|
\ccc{P} exists.}
|
|
\end{ccClassTemplate}
|
|
|
|
\ccHtmlNoClassFile
|
|
\begin{ccClassTemplate}{CGAL_Random_points_on_segment_2<P>}
|
|
\ccCreationVariable{g}
|
|
\ccConstructor{CGAL_Random_points_on_segment_2( const P& p, const P& q,
|
|
CGAL_Random& rnd = CGAL_random);}{%
|
|
$g$ is an input iterator creating points of type \ccc{P} uniformly
|
|
distributed on the segment from $p$ to $q$ except $q$,
|
|
i.e.~$\ccc{*g} == (1-\lambda)\, p + \lambda q$ where $0 \le \lambda < 1$~.
|
|
A single random number is needed from \ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type \ccc{P}
|
|
exists. The expressions \ccc{CGAL_to_double(p.x())} and
|
|
\ccc{CGAL_to_double(p.y())} must result in the respective
|
|
\ccc{double} representation of the coordinates and similar for $q$.}
|
|
\end{ccClassTemplate}
|
|
|
|
\ccHeading{Grid Points}
|
|
\ccThree{OutputIterator}{rand}{}
|
|
|
|
Grid points are produced by generating functions writing to an output
|
|
iterator.
|
|
|
|
\ccFunction{template <class OutputIterator>
|
|
OutputIterator
|
|
CGAL_points_on_square_grid_2( double a, size_t n, OutputIterator o,
|
|
const P*);}
|
|
{ creates the $n$ first points on the regular $\lceil\sqrt{n}\,\rceil
|
|
\times \lceil \sqrt{n}\,\rceil$ grid within the square
|
|
$[-\frac{a}{2},\frac{a}{2}]\times [-\frac{a}{2},\frac{a}{2}]$.
|
|
Returns the value of $o$ after inserting the $n$ points.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the point type
|
|
$P$ and $P$ must be assignable to the value type of
|
|
\ccc{OutputIterator}.}
|
|
|
|
\ccFunction{template <class P, class OutputIterator>
|
|
OutputIterator CGAL_points_on_segment_2( const P& p, const P& q, size_t n,
|
|
OutputIterator o);}
|
|
{ creates $n$ points regular spaced on the segment from $p$ to $q$,
|
|
i.e.~$\forall i: 0 \le i < n: o[i] := \frac{n-i-1}{n-1}\, p +
|
|
\frac{i}{n-1}\, q$. Returns the value of $o$ after inserting
|
|
the $n$ points.}
|
|
|
|
\ccHeading{Random Perturbations}
|
|
|
|
Degenerate input sets like grid points can be randomly perturbed by a
|
|
small amount to produce {\em quasi}-degenerate test sets. This
|
|
challenges numerical stability of algorithms using inexact arithmetic and
|
|
exact predicates to compute the sign of expressions slightly off from zero.
|
|
|
|
\ccFunction{template <class ForwardIterator>
|
|
void CGAL_perturb_points_2( ForwardIterator first, ForwardIterator last,
|
|
double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random);}
|
|
{ perturbs the points in the range $[\ccc{first},\ccc{last})$ by
|
|
replacing each point with a random point from the rectangle
|
|
\ccc{xeps} $\times$ \ccc{yeps} centered at the original point.
|
|
Two random numbers are needed from \ccc{rnd} for each point.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the value type of
|
|
the \ccc{ForwardIterator} exists.
|
|
The expressions \ccc{CGAL_to_double((*first).x())} and
|
|
\ccc{CGAL_to_double((*first).y())} must result in the respective
|
|
coordinate values.
|
|
}
|
|
|
|
\ccHeading{Adding Degeneracies}
|
|
|
|
For a given point set certain kinds of degeneracies can be produced
|
|
adding new points. The \ccc{CGAL_random_selection()} function is
|
|
useful to generate multiple entries of identical points, see
|
|
Section~\ref{sectionRandomSelection}. The
|
|
\ccc{CGAL_random_collinear_points_2()} function adds collinearities to
|
|
a point set.
|
|
|
|
|
|
\ccFunction{template <class RandomAccessIterator, class OutputIterator>
|
|
OutputIterator CGAL_random_collinear_points_2( RandomAccessIterator first,
|
|
RandomAccessIterator last,
|
|
size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random);}
|
|
{ randomly chooses two points from the range $[\ccc{first},\ccc{last})$,
|
|
creates a random third point on the segment connecting this two
|
|
points, and writes it to \ccc{first2}. Repeats this $n$ times, thus
|
|
writing $n$ points to \ccc{first2} that are collinear with points
|
|
in the range $[\ccc{first},\ccc{last})$.
|
|
Three random numbers are needed from \ccc{rnd} for each point.
|
|
Returns the value of \ccc{first2} after inserting the $n$ points.
|
|
\ccPrecond a function \ccc{CGAL_build_point()} for the value type of
|
|
the \ccc{ForwardIterator} exists.
|
|
The expressions \ccc{CGAL_to_double((*first).x())} and
|
|
\ccc{CGAL_to_double((*first).y())} must result in the respective
|
|
coordinate values.
|
|
}
|
|
|
|
\ccExample
|
|
|
|
We want to generate a test set of 1000 points, where 60\% are chosen
|
|
randomly in a small disc, 20\% are from a larger grid, 10\% duplicates
|
|
are added, and 10\% collinearities added. A random shuffle removes the
|
|
construction order from the test set. See \ccTexHtml{%
|
|
Figure~\ref{figurePointGenerator}}{Figure <A HREF="#PointGenerators">
|
|
<IMG SRC="cc_ref_up_arrow.gif" ALT="reference arrow" WIDTH="10"
|
|
HEIGHT="10"></A>} for the example output.
|
|
|
|
\cprogfile{generators_prog1.C}
|
|
|
|
\begin{ccTexOnly}
|
|
\begin{figure}
|
|
\noindent
|
|
\hspace*{0.025\textwidth}%
|
|
\begin{minipage}{0.45\textwidth}%
|
|
\epsfig{figure=generators_prog1.ps,width=\textwidth}
|
|
\caption{Output of example program for point generators.}
|
|
\label{figurePointGenerator}
|
|
\end{minipage}%
|
|
\hspace*{0.05\textwidth}%
|
|
\begin{minipage}{0.45\textwidth}%
|
|
\epsfig{figure=generators_prog2.ps,width=\textwidth}%
|
|
\caption{Output of example program for point generators working
|
|
on integer points.}
|
|
\label{figureIntegerPointGenerator}
|
|
\end{minipage}%
|
|
\end{figure}
|
|
\end{ccTexOnly}
|
|
|
|
\begin{ccHtmlOnly}
|
|
<A NAME="PointGenerators">
|
|
<TABLE><TR><TD ALIGN=LEFT VALIGN=TOP WIDTH=60%>
|
|
<A HREF="./generators_prog1.gif">Figure:</A>
|
|
Output of example program for point generators.
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=5% NOWRAP>
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=35% NOWRAP>
|
|
<A HREF="./generators_prog1.gif">
|
|
<img src="./generators_prog1_small.gif"
|
|
alt="Point Generator Example Output"></A>
|
|
</TD></TR></TABLE>
|
|
\end{ccHtmlOnly}
|
|
|
|
|
|
The second example demonstrates the point generators with integer
|
|
points. Arithmetic with \ccc{double}'s is sufficient to produce
|
|
regular integer grids. See \ccTexHtml{%
|
|
Figure~\ref{figureIntegerPointGenerator}}{Figure
|
|
<A HREF="#IntegerPointGenerators">
|
|
<IMG SRC="cc_ref_up_arrow.gif" ALT="reference arrow" WIDTH="10"
|
|
HEIGHT="10"></A>}
|
|
for the example output.
|
|
|
|
\cprogfile{generators_prog2.C}
|
|
|
|
\begin{ccHtmlOnly}
|
|
<A NAME="IntegerPointGenerators">
|
|
<TABLE><TR><TD ALIGN=LEFT VALIGN=TOP WIDTH=60%>
|
|
<A HREF="./generators_prog2.gif">Figure:</A>
|
|
Output of example program for point generators working
|
|
on integer points.
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=5% NOWRAP>
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=35% NOWRAP>
|
|
<A HREF="./generators_prog2.gif">
|
|
<img src="./generators_prog2_small.gif"
|
|
alt="Integer Point Generator Example Output"></A>
|
|
</TD></TR></TABLE>
|
|
\end{ccHtmlOnly}
|
|
|
|
|
|
% +------------------------------------------------------------------------+
|
|
\newpage
|
|
\section{2D Segment Generators}
|
|
|
|
The following generic segment generator uses two point generators to
|
|
create a segment from two endpoints. This is a design example how
|
|
further generators could look like -- for segments and for other
|
|
higher level objects.
|
|
|
|
|
|
% +------------------------------------------------------------------------+
|
|
\begin{ccClassTemplate}{CGAL_Segment_generator<S,P1,P2>}
|
|
\ccCreationVariable{g}
|
|
\subsection{A Generic Segment Generator from Two Points}
|
|
|
|
\ccDefinition
|
|
|
|
The generic segment generator \ccClassTemplateName\ uses two point
|
|
generators \ccc{P1} and \ccc{P2} to create a segment of type $S$ from
|
|
two endpoints. \ccClassTemplateName\ satisfies the requirements for
|
|
an input iterator. It represents the possibly infinite sequence of
|
|
generated segments. Each call to the \ccc{operator*} returns a new
|
|
segment. To create a finite sequence in a container, the function
|
|
\ccc{CGAL_copy_n()} could be used, see Section~\ref{sectionCopyN}.
|
|
|
|
\ccInclude{CGAL/Segment_generator_2.h}
|
|
|
|
\ccCreation
|
|
|
|
\ccConstructor{CGAL_Segment_generator( P1& p1, P2& p2);}{%
|
|
$g$ is an input iterator creating segments of type \ccc{S} from two
|
|
input points, one chosen from \ccc{p1}, the other chosen from
|
|
\ccc{p2}. \ccc{p1} and \ccc{p2} are allowed be be same point
|
|
generator.\ccPrecond $S$ must provide a constructor with two
|
|
arguments, such that the value type of \ccc{P1} and the
|
|
value type of \ccc{P2} can be used to construct a segment.}
|
|
|
|
\ccOperations
|
|
|
|
$g$ satisfies the requirements of an input iterator. Each call to the
|
|
\ccc{operator*} returns a new segment.
|
|
|
|
\ccExample
|
|
|
|
We want to generate a test set of 200 segments, where one endpoint is
|
|
chosen randomly from a horizontal segment of length 200, and the other
|
|
endpoint is chosen randomly from a circle of radius 250. See
|
|
\ccTexHtml{Figure~\ref{figureSegmentGenerator}}{Figure <A
|
|
HREF="#SegmentGenerator"> <IMG SRC="cc_ref_up_arrow.gif"
|
|
ALT="reference arrow" WIDTH="10" HEIGHT="10"></A>} for the example
|
|
output.
|
|
|
|
\begin{ccTexOnly}
|
|
\begin{figure}
|
|
\noindent
|
|
\hspace*{0.025\textwidth}%
|
|
\begin{minipage}{0.45\textwidth}%
|
|
\epsfig{figure=Segment_generator_prog1.ps,width=\textwidth}
|
|
\caption{Output of example program for the generic segment generator.}
|
|
\label{figureSegmentGenerator}
|
|
\end{minipage}%
|
|
\hspace*{0.05\textwidth}%
|
|
\begin{minipage}{0.45\textwidth}%
|
|
\epsfig{figure=Segment_generator_prog2.ps,width=\textwidth}
|
|
\caption{Output of example program for the generic segment
|
|
generator using precomputed point locations.}
|
|
\label{figureSegmentGeneratorFan}
|
|
\end{minipage}%
|
|
\end{figure}
|
|
\end{ccTexOnly}
|
|
|
|
\cprogfile{Segment_generator_prog1.C}
|
|
|
|
\begin{ccHtmlOnly}
|
|
<A NAME="SegmentGenerator">
|
|
<TABLE><TR><TD ALIGN=LEFT VALIGN=TOP WIDTH=60%>
|
|
<A HREF="./Segment_generator_prog1.gif">Figure:</A>
|
|
Output of example program for the generic segment generator.
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=5% NOWRAP>
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=35% NOWRAP>
|
|
<A HREF="./Segment_generator_prog1.gif">
|
|
<img src="./Segment_generator_prog1_small.gif"
|
|
alt="Segment Generator Example Output"></A>
|
|
</TD></TR></TABLE>
|
|
\end{ccHtmlOnly}
|
|
|
|
The second example uses precomputed point vectors to generate a
|
|
regular structure of 100 segments, see
|
|
\ccTexHtml{Figure~\ref{figureSegmentGeneratorFan}}{Figure <A
|
|
HREF="#SegmentGeneratorFan"> <IMG SRC="cc_ref_up_arrow.gif"
|
|
ALT="reference arrow" WIDTH="10" HEIGHT="10"></A>} for the example
|
|
output.
|
|
|
|
\cprogfile{Segment_generator_prog2.C}
|
|
|
|
\begin{ccHtmlOnly}
|
|
<A NAME="SegmentGeneratorFan">
|
|
<TABLE><TR><TD ALIGN=LEFT VALIGN=TOP WIDTH=60%>
|
|
<A HREF="./Segment_generator_prog2.gif">Figure:</A>
|
|
Output of example program for the generic segment generator using
|
|
precomputed point locations.
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=5% NOWRAP>
|
|
</TD><TD ALIGN=LEFT VALIGN=TOP WIDTH=35% NOWRAP>
|
|
<A HREF="./Segment_generator_prog2.gif">
|
|
<img src="./Segment_generator_prog2_small.gif"
|
|
alt="Segment Generator Example Output 2"></A>
|
|
</TD></TR></TABLE>
|
|
\end{ccHtmlOnly}
|
|
|
|
\end{ccClassTemplate}
|
|
|
|
% +--------------------------------------------------------+
|
|
\beforecprogskip\parskip
|
|
\aftercprogskip0pt
|
|
|
|
% EOF
|