mirror of https://github.com/CGAL/cgal
Initial revision
This commit is contained in:
Lutz Kettner
parent
af69ad7b6c
commit
6bad692d74
|
|
@ -0,0 +1,389 @@
|
|||
% +------------------------------------------------------------------------+
|
||||
% | 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 geomeric object generators are 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{2D Point Generators}
|
||||
|
||||
\ccDefinition
|
||||
|
||||
Point generators are provided for random points equally 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 before. 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_ncopy()} could be used.
|
||||
|
||||
\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}.}
|
||||
\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}.}
|
||||
\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
|
||||
around 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}.}
|
||||
\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 around 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}.}
|
||||
\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} == \lambda p + (1-\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}.
|
||||
The expressions \ccc{CGAL_to_double(p.x())} and
|
||||
\ccc{CGAL_to_double(p.y())} must be legal and similar for $q$.}
|
||||
\end{ccClassTemplate}
|
||||
|
||||
\ccFunction{template <class InputIterator, class OutputIterator>
|
||||
OutputIterator CGAL_ncopy( InputIterator first, size_t n,
|
||||
OutputIterator first2);}
|
||||
{copies the first $n$ elements from \ccc{first} to \ccc{first2}.}
|
||||
|
||||
\ccHeading{Grid Points}
|
||||
|
||||
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 either numerical stability of algorithms using inexact
|
||||
arithmetic or exact predicates to compute the sign of expressions
|
||||
slightly off from zero.
|
||||
|
||||
\ccFunction{template <class ForwardIterator>
|
||||
void CGAL_perturbe_points_2( ForwardIterator first, ForwardIterator last,
|
||||
double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random);}
|
||||
{ perturbes 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 around 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}.
|
||||
The expression \ccc{CGAL_to_double((*first).x())} and
|
||||
\ccc{CGAL_to_double((*begin).y())} must be legal.
|
||||
}
|
||||
|
||||
\ccHeading{Adding Degeneracies}
|
||||
|
||||
For a given point set certain kinds of degeneracies can be produced
|
||||
adding new points.
|
||||
|
||||
\ccFunction{template <class RandomAccessIterator, class OutputIterator>
|
||||
OutputIterator CGAL_random_selection( RandomAccessIterator first,
|
||||
RandomAccessIterator last,
|
||||
size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random);}
|
||||
{ choose a random point from the range $[\ccc{first},\ccc{last})$ and
|
||||
write it to \ccc{first2}, each point from the range with equal
|
||||
probability. Repeat this $n$ times, thus writing $n$ points to
|
||||
\ccc{first2}.
|
||||
A single random number is needed from \ccc{rnd} for each point.
|
||||
Returns the value of \ccc{first2} after inserting the $n$ points.
|
||||
}
|
||||
|
||||
\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);}
|
||||
{ choose two random points from the range $[\ccc{first},\ccc{last})$,
|
||||
create a random third point on the segment connecting this two
|
||||
points, and write it to \ccc{first2}. Repeat 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}.
|
||||
The expression \ccc{CGAL_to_double((*first).x())} and
|
||||
\ccc{CGAL_to_double((*first).y())} must be legal.
|
||||
}
|
||||
|
||||
\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 demostrates 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. This is a design example how further generators could
|
||||
look like -- for segments and for other higher level objects.
|
||||
|
||||
The generic segment generator \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_ncopy()} could be used.
|
||||
|
||||
\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 with regular spacing from a horizontal segment of length 200,
|
||||
and the other endpoint is chosen ramdomly 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}%
|
||||
\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}
|
||||
|
||||
\end{ccClassTemplate}
|
||||
|
||||
% +--------------------------------------------------------+
|
||||
\beforecprogskip\parskip
|
||||
\aftercprogskip0pt
|
||||
|
||||
% EOF
|
||||
|
|
@ -0,0 +1,389 @@
|
|||
% +------------------------------------------------------------------------+
|
||||
% | 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 geomeric object generators are 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{2D Point Generators}
|
||||
|
||||
\ccDefinition
|
||||
|
||||
Point generators are provided for random points equally 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 before. 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_ncopy()} could be used.
|
||||
|
||||
\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}.}
|
||||
\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}.}
|
||||
\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
|
||||
around 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}.}
|
||||
\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 around 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}.}
|
||||
\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} == \lambda p + (1-\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}.
|
||||
The expressions \ccc{CGAL_to_double(p.x())} and
|
||||
\ccc{CGAL_to_double(p.y())} must be legal and similar for $q$.}
|
||||
\end{ccClassTemplate}
|
||||
|
||||
\ccFunction{template <class InputIterator, class OutputIterator>
|
||||
OutputIterator CGAL_ncopy( InputIterator first, size_t n,
|
||||
OutputIterator first2);}
|
||||
{copies the first $n$ elements from \ccc{first} to \ccc{first2}.}
|
||||
|
||||
\ccHeading{Grid Points}
|
||||
|
||||
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 either numerical stability of algorithms using inexact
|
||||
arithmetic or exact predicates to compute the sign of expressions
|
||||
slightly off from zero.
|
||||
|
||||
\ccFunction{template <class ForwardIterator>
|
||||
void CGAL_perturbe_points_2( ForwardIterator first, ForwardIterator last,
|
||||
double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random);}
|
||||
{ perturbes 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 around 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}.
|
||||
The expression \ccc{CGAL_to_double((*first).x())} and
|
||||
\ccc{CGAL_to_double((*begin).y())} must be legal.
|
||||
}
|
||||
|
||||
\ccHeading{Adding Degeneracies}
|
||||
|
||||
For a given point set certain kinds of degeneracies can be produced
|
||||
adding new points.
|
||||
|
||||
\ccFunction{template <class RandomAccessIterator, class OutputIterator>
|
||||
OutputIterator CGAL_random_selection( RandomAccessIterator first,
|
||||
RandomAccessIterator last,
|
||||
size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random);}
|
||||
{ choose a random point from the range $[\ccc{first},\ccc{last})$ and
|
||||
write it to \ccc{first2}, each point from the range with equal
|
||||
probability. Repeat this $n$ times, thus writing $n$ points to
|
||||
\ccc{first2}.
|
||||
A single random number is needed from \ccc{rnd} for each point.
|
||||
Returns the value of \ccc{first2} after inserting the $n$ points.
|
||||
}
|
||||
|
||||
\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);}
|
||||
{ choose two random points from the range $[\ccc{first},\ccc{last})$,
|
||||
create a random third point on the segment connecting this two
|
||||
points, and write it to \ccc{first2}. Repeat 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}.
|
||||
The expression \ccc{CGAL_to_double((*first).x())} and
|
||||
\ccc{CGAL_to_double((*first).y())} must be legal.
|
||||
}
|
||||
|
||||
\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 demostrates 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. This is a design example how further generators could
|
||||
look like -- for segments and for other higher level objects.
|
||||
|
||||
The generic segment generator \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_ncopy()} could be used.
|
||||
|
||||
\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 with regular spacing from a horizontal segment of length 200,
|
||||
and the other endpoint is chosen ramdomly 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}%
|
||||
\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}
|
||||
|
||||
\end{ccClassTemplate}
|
||||
|
||||
% +--------------------------------------------------------+
|
||||
\beforecprogskip\parskip
|
||||
\aftercprogskip0pt
|
||||
|
||||
% EOF
|
||||
Loading…
Reference in New Issue