mirror of https://github.com/CGAL/cgal
352 lines
12 KiB
TeX
352 lines
12 KiB
TeX
% +------------------------------------------------------------------------+
|
||
% | CGAL Reference Manual: generators.tex
|
||
% +------------------------------------------------------------------------+
|
||
% | Geometric object generators.
|
||
% |
|
||
% | 09.06.1997 Lutz Kettner
|
||
% |
|
||
|
||
% +------------------------------------------------------------------------+
|
||
|
||
|
||
\section{Introduction}
|
||
A variety of generators for geometric objects 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.
|
||
|
||
Two kinds of point generators are provided: first, random point
|
||
generators and second deterministic point generators. Most random
|
||
point generators and a few deterministic point generators are provided
|
||
as input iterators. The input iterators model an infinite sequence of
|
||
points. The function \ccc{CGAL::cpp0x::copy_n()} can be used to copy a
|
||
finite sequence; see Section~\ref{sectionCopyN}. The iterator adaptor
|
||
\ccc{Counting_iterator} can be used to create finite iterator
|
||
ranges; see Section~\ref{sectionCountingIterator}.
|
||
Other generators are provided as functions that write to output
|
||
iterators. Further functions add degeneracies or random perturbations.
|
||
|
||
\ccIndexSubitem[c]{generator}{2D point}
|
||
\ccIndexSubitem[c]{point, 2D}{generator}
|
||
In 2D, we provide input iterators to generate random points in a disc
|
||
(\ccc{Random_points_in_disc_2}),
|
||
in a square (\ccc{Random_points_in_square_2}),
|
||
on a circle (\ccc{Random_points_on_circle_2}),
|
||
on a segment (\ccc{Random_points_on_segment}),
|
||
and on a square (\ccc{Random_points_on_square_2}).
|
||
For generating grid points we provide three functions,
|
||
\ccc{points_on_segment_2},
|
||
\ccc{points_on_square_grid_2} that write to output iterators and
|
||
an input iterator \ccc{Points_on_segment_2}.
|
||
|
||
\ccIndexSubitem[c]{generator}{3D point}
|
||
\ccIndexSubitem[c]{point, 3D}{generator}
|
||
For 3D points, input iterators are provided for random points uniformly
|
||
distributed in a sphere (\ccc{Random_points_in_sphere_3})
|
||
or cube (\ccc{Random_points_in_cube_3}) or on the boundary of a sphere
|
||
(\ccc{Random_points_on_sphere_3}).
|
||
For generating 3D grid points, we provide the function
|
||
\ccc{points_on_cube_grid_3} that writes to
|
||
an output iterator.
|
||
|
||
\ccIndexSubitem[c]{generator}{dD point}
|
||
\ccIndexSubitem[c]{point, dD}{generator}
|
||
For higher dimensions, input iterators are provided for random points uniformly
|
||
distributed in a $d$-dimensional cube (\ccc{Random_points_in_cube_d})
|
||
or $d$-dimensional ball (\ccc{Random_points_in_ball_d}) or on the boundary of a
|
||
sphere (\ccc{Random_points_on_sphere_d}).
|
||
For generating grid points, we provide the function
|
||
\ccc{points_on_grid_d} that writes to
|
||
an output iterator.
|
||
|
||
|
||
We also provide two functions for generating more complex geometric objects.
|
||
The function \ccc{random_convex_set_2} computes a random convex planar
|
||
point set of a given size where the points are drawn from a specific
|
||
domain and \ccc{random_polygon_2} generates a random simple polygon from
|
||
points drawn from a specific domain.
|
||
|
||
\subsection{Random Perturbations}
|
||
\ccIndexMainItem{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.
|
||
For this the function \ccc{perturb_points_2} is provided.
|
||
|
||
\subsection{Adding Degeneracies}
|
||
\ccModifierCrossRefOff
|
||
\ccIndexSubitem{degeneracies}{adding to input}
|
||
\ccModifierCrossRefOn
|
||
|
||
For a given point set certain kinds of degeneracies can be produced
|
||
by adding new points. The \ccc{random_selection()} function is
|
||
useful for generating multiple copies of identical points.
|
||
The function \ccc{random_collinear_points_2()} adds collinearities to
|
||
a point set.
|
||
|
||
\subsection{Support Functions and Classes for Generators}
|
||
|
||
The function \ccc{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.
|
||
|
||
\section{Example Generating Degenerate Point Sets}
|
||
|
||
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\% are duplicates
|
||
points, and 10\% collinear points. A random shuffle removes the
|
||
construction order from the test set. See \ccTexHtml{%
|
||
Figure~\ref{figurePointGenerator}}{Figure <A HREF="#PointGenerators">☞</A>}
|
||
for the example output.
|
||
|
||
\ccIncludeExampleCode{Generator/random_degenerate_point_set.cpp}
|
||
|
||
\begin{ccTexOnly}
|
||
\begin{figure}
|
||
\noindent
|
||
\hspace*{0.025\textwidth}%
|
||
\begin{minipage}{0.45\textwidth}%
|
||
\includegraphics[width=\textwidth]{Generator/generators_prog1}
|
||
\caption{Output of example program for point generators.}
|
||
\label{figurePointGenerator}
|
||
\end{minipage}%
|
||
\hspace*{0.05\textwidth}%
|
||
\begin{minipage}{0.45\textwidth}%
|
||
\includegraphics[width=\textwidth]{Generator/generators_prog2}
|
||
\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 WIDTH=100%>
|
||
<TR ALIGN=CENTER>
|
||
<TD> <img src="./generators_prog1.png" alt="Point Generator Example Output"> </TD>
|
||
</TR>
|
||
<TR ALIGN=LEFT>
|
||
<TD> <B>Figure:</B> Output of example program for point generators. </TD>
|
||
</TR>
|
||
</TABLE>
|
||
\end{ccHtmlOnly}
|
||
|
||
\section{Example Generating Grid Points}
|
||
|
||
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">☞</A>}
|
||
for the example output.
|
||
|
||
\ccIncludeExampleCode{Generator/random_grid.cpp}
|
||
|
||
\begin{ccHtmlOnly}
|
||
<A NAME="IntegerPointGenerators">
|
||
<TABLE WIDTH=100%>
|
||
<TR ALIGN=CENTER>
|
||
<TD> <img src="./generators_prog2.png" alt="Integer Point Generator Example Output"> </TD>
|
||
</TR>
|
||
<TR ALIGN=LEFT>
|
||
<TD> <B>Figure:</B> Output of example program for point generators working
|
||
on integer points. </TD>
|
||
</TR>
|
||
</TABLE>
|
||
\end{ccHtmlOnly}%
|
||
|
||
|
||
|
||
% +------------------------------------------------------------------------+
|
||
%\newpage
|
||
\section{Examples Generating Segments\label{sec:segment_example}}
|
||
\lcTex{\ccIndexSubitemBegin[c]{generator}{segment}}
|
||
|
||
The following two examples illustrate the use of the generic functions
|
||
from Section~\ref{sectionGenericFunctions} like
|
||
\ccc{Join_input_iterator_2}%
|
||
\lcTex{\ccIndexGlobalFunction{Join_input_iterator_2}} to generate
|
||
composed objects from other
|
||
generators -- here two-dimensional segments from two point generators.
|
||
|
||
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">☞</A>} for the example
|
||
output.
|
||
|
||
\begin{ccTexOnly}
|
||
\begin{figure}
|
||
\noindent
|
||
\hspace*{0.025\textwidth}%
|
||
\begin{minipage}[t]{0.45\textwidth}%
|
||
\includegraphics[width=\textwidth]{Generator/Segment_generator_prog1}
|
||
\caption{Output of the first example program for the generic generator.}
|
||
\label{figureSegmentGenerator}
|
||
\end{minipage}%
|
||
\hspace*{0.05\textwidth}%
|
||
\begin{minipage}[t]{0.45\textwidth}%
|
||
\includegraphics[width=\textwidth]{Generator/Segment_generator_prog2}
|
||
\caption{Output of the second example program for the generic
|
||
generator without using intermediate storage.}
|
||
\label{figureSegmentGeneratorFan}
|
||
\end{minipage}%
|
||
\end{figure}
|
||
\end{ccTexOnly}
|
||
|
||
\ccIncludeExampleCode{Generator/random_segments1.cpp}
|
||
|
||
\begin{ccHtmlOnly}
|
||
<A NAME="SegmentGenerator">
|
||
<TABLE WIDTH=100%>
|
||
<TR ALIGN=CENTER>
|
||
<TD> <img src="./Segment_generator_prog1.png" alt="Segment Generator Example Output"> </TD>
|
||
</TR>
|
||
<TR ALIGN=LEFT>
|
||
<TD> <B>Figure:</B> Output of example program for the generic segment generator. </TD>
|
||
</TR>
|
||
</TABLE>
|
||
\end{ccHtmlOnly}
|
||
|
||
The second example generates a regular structure of 100 segments; see
|
||
\ccTexHtml{Figure~\ref{figureSegmentGeneratorFan}}{Figure <A
|
||
HREF="#SegmentGeneratorFan">☞</A>} for the example
|
||
output. It uses the \ccc{Points_on_segment_2}%
|
||
\lcTex{\ccIndexGlobalFunction{Points_on_segment_2}} iterator,
|
||
\ccc{Join_input_iterator_2}%
|
||
\lcTex{\ccIndexGlobalFunction{Join_input_iterator_2}}
|
||
and \ccc{Counting_iterator} %\lcTex{\ccIndexGlobalFunction{Counting_iterator}}
|
||
to avoid any intermediate storage of the generated objects until they are
|
||
used.
|
||
|
||
\ccIncludeExampleCode{Generator/random_segments2.cpp}
|
||
|
||
\begin{ccHtmlOnly}
|
||
<A NAME="SegmentGeneratorFan">
|
||
<TABLE WIDTH=100%>
|
||
<TR ALIGN=CENTER>
|
||
<TD> <img src="./Segment_generator_prog2.png" alt="Segment Generator Example Output 2"> </TD>
|
||
</TR>
|
||
<TR ALIGN=LEFT>
|
||
<TD> <B>Figure:</B>
|
||
Output of example program for the generic segment generator using
|
||
pre-computed point locations. </TD>
|
||
</TR>
|
||
</TABLE>
|
||
\end{ccHtmlOnly}
|
||
\lcTex{\ccIndexSubitemEnd[c]{generator}{segment}}
|
||
|
||
|
||
\section{Example Generating Point Sets in \texorpdfstring{$d$}{d} dimensions}
|
||
|
||
The following example generates points inside a cube in dimension 5
|
||
(examples for ball and sphere are available in the example directory) :
|
||
|
||
\ccIncludeExampleCode{Generator/cube_d.cpp}
|
||
|
||
The output of this example looks like:
|
||
\begin{verbatim}
|
||
Generating 10 random points in a cube in 5D, coordinates from -100 to 100
|
||
5 32.9521 26.0403 59.3979 -99.2553 15.5102
|
||
5 80.3731 30.809 7.32491 -90.2544 94.5635
|
||
5 -71.3412 -31.933 -98.0734 79.6493 66.6104
|
||
5 -78.5065 -58.2397 -33.9096 81.2196 57.2512
|
||
5 21.4093 26.7661 57.6083 23.4958 93.1047
|
||
5 10.5895 -21.8914 70.9726 36.756 -42.2667
|
||
5 23.9813 54.4519 -26.0894 -85.18 -21.0775
|
||
5 -48.7499 59.9873 6.22335 -4.16011 81.0727
|
||
5 -11.6615 5.53147 -32.6578 -79.9283 44.5679
|
||
5 53.0183 78.3228 -28.5665 83.3503 68.0482
|
||
\end{verbatim}
|
||
|
||
|
||
Next example generates grid points in dimension $dim=4$.
|
||
Since the required number of
|
||
points, 20 is between $2^{dim}$ and $3^{dim}$ the supporting grid has
|
||
$3\times 3\times 3\times 3$ points.
|
||
Since the size parameter is 5, the
|
||
coordinates are in $\{-5, 0, 5\}$, but since the number of points
|
||
verifies $20\leq 3^{dim-1}$, all
|
||
generated points have the same last coordinate $-5$.
|
||
|
||
\ccIncludeExampleCode{Generator/grid_d.cpp}
|
||
|
||
The output of previous example corresponds to the points of this
|
||
figure depicted in red or pink (pink points are ``inside'' the cube).
|
||
The output is:
|
||
\begin{verbatim}
|
||
Generating 20 grid points in 4D
|
||
4 -5 -5 -5 -5
|
||
4 0 -5 -5 -5
|
||
4 5 -5 -5 -5
|
||
4 -5 0 -5 -5
|
||
4 0 0 -5 -5
|
||
4 5 0 -5 -5
|
||
4 -5 5 -5 -5
|
||
4 0 5 -5 -5
|
||
4 5 5 -5 -5
|
||
4 -5 -5 0 -5
|
||
4 0 -5 0 -5
|
||
4 5 -5 0 -5
|
||
4 -5 0 0 -5
|
||
4 0 0 0 -5
|
||
4 5 0 0 -5
|
||
4 -5 5 0 -5
|
||
4 0 5 0 -5
|
||
4 5 5 0 -5
|
||
4 -5 -5 5 -5
|
||
4 0 -5 5 -5
|
||
\end{verbatim}
|
||
|
||
\begin{ccHtmlOnly}
|
||
<center>
|
||
<img border=0 src="./hypergrid.gif" align=middle>
|
||
</center>
|
||
\end{ccHtmlOnly}
|
||
\begin{ccTexOnly}
|
||
\begin{center}
|
||
\includegraphics[width=11.5cm]{Generator/hypergrid}
|
||
\end{center}
|
||
\end{ccTexOnly}
|
||
|
||
|
||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||
\section{Design and Implementation History}
|
||
|
||
Lutz Kettner coded generators in 2D and 3D
|
||
For points {\em in} and {\em on} sphere, points are generated in a cube up
|
||
to the moment the point is inside the sphere, then it is normalized to go on the
|
||
boundary if needed.
|
||
|
||
Sven Sch<63>nherr implemented the Random class.
|
||
|
||
Michael Hoffmann coded the random convex polygon,
|
||
|
||
Geert-Jan Giezeman and Susan Hert coded the random simple polygon.
|
||
|
||
Olivier Devillers coded generators in high dimensions.
|
||
For points {\em in ball} and {\em on sphere}, points are generated on a
|
||
sphere/ball boundary as a product of normal distributions, then it is
|
||
normalized.
|
||
If needed a random radius (with relevant distribution)
|
||
is used to put the point inside the ball.
|
||
|
||
% +--------------------------------------------------------+
|
||
% restore default column and paragraph layout
|
||
\ccParDims
|
||
\cgalColumnLayout
|
||
|
||
|
||
|
||
% +--------------------------------------------------------+
|
||
% restore default column and paragraph layout
|
||
\ccParDims
|
||
\beforecprogskip\parskip
|
||
\aftercprogskip0pt
|
||
|
||
|
||
% EOF
|