diff --git a/Packages/Generator/doc_tex/Generator/Segment_generator_prog1.C b/Packages/Generator/doc_tex/Generator/Segment_generator_prog1.C index 08e754c658e..4a4b54817a9 100644 --- a/Packages/Generator/doc_tex/Generator/Segment_generator_prog1.C +++ b/Packages/Generator/doc_tex/Generator/Segment_generator_prog1.C @@ -10,13 +10,15 @@ #include #include #include -#include +#include +#include #include #include /* only for visualization used */ -typedef CGAL_Cartesian R; -typedef CGAL_Point_2 Point; -typedef CGAL_Segment_2 Segment; +typedef CGAL_Cartesian R; +typedef CGAL_Point_2 Point; +typedef CGAL_Creator_uniform_2 Pt_creator; +typedef CGAL_Segment_2 Segment; int main() { @@ -25,15 +27,17 @@ int main() segs.reserve(200); /* Prepare point generator for the horizontal segment, length 200. */ - typedef CGAL_Random_points_on_segment_2 P1; + typedef CGAL_Random_points_on_segment_2 P1; P1 p1( Point(-100,0), Point(100,0)); /* Prepare point generator for random points on circle, radius 250. */ - typedef CGAL_Random_points_on_circle_2 P2; + typedef CGAL_Random_points_on_circle_2 P2; P2 p2( 250); /* Create 200 segments. */ - CGAL_Segment_generator g( p1, p2); + typedef CGAL_Creator_uniform_2< Point, Segment> Seg_creator; + typedef CGAL_Join_input_iterator_2< P1, P2, Seg_creator> Seg_iterator; + Seg_iterator g( p1, p2); CGAL_copy_n( g, 200, back_inserter( segs)); /* Visualize segments. Can be omitted, see example programs */ diff --git a/Packages/Generator/doc_tex/Generator/Segment_generator_prog2.C b/Packages/Generator/doc_tex/Generator/Segment_generator_prog2.C index 9c185370dbc..80c1b709052 100644 --- a/Packages/Generator/doc_tex/Generator/Segment_generator_prog2.C +++ b/Packages/Generator/doc_tex/Generator/Segment_generator_prog2.C @@ -1,65 +1,55 @@ /* Segment_generator_prog2.C */ /* ------------------------------- */ -/* CGAL example program for the generic segment generator */ -/* using precomputed point locations. */ +/* CGAL example program generating a regular segment pattern. */ #include -#include -#include #include #include #include #include #include -#include -#include -#include /* only for visualization used */ +#include +#include +#include +#include +#include + +typedef CGAL_Cartesian R; +typedef CGAL_Point_2 Point; +typedef CGAL_Segment_2 Segment; +typedef CGAL_Points_on_segment_2 PG; +typedef CGAL_Creator_uniform_2< Point, Segment> Creator; +typedef CGAL_Join_input_iterator_2< PG, PG, Creator> Segm_iterator; +typedef CGAL_Counting_iterator Count_iterator; -typedef CGAL_Cartesian R; -typedef CGAL_Point_2 Point; -typedef CGAL_Segment_2 Segment; int main() { - /* Prepare two point vectors for the precomputed points. */ - vector p1, p2; - p1.reserve(100); - p2.reserve(100); - - /* Create points for a horizontal like fan. */ - CGAL_points_on_segment_2( Point(-250, -50), Point(-250, 50), - 50, back_inserter( p1)); - CGAL_points_on_segment_2( Point( 250,-250), Point( 250,250), - 50, back_inserter( p2)); - - /* Create points for a vertical like fan. */ - CGAL_points_on_segment_2( Point( -50,-250), Point( 50,-250), - 50, back_inserter( p1)); - CGAL_points_on_segment_2( Point(-250, 250), Point( 250, 250), - 50, back_inserter( p2)); - - /* Create test segment set. Prepare a vector for 100 segments. */ - vector segs; - segs.reserve(100); - - /* Create both fans at once from the precomputed points. */ - typedef vector::iterator I; - I i1 = p1.begin(); - I i2 = p2.begin(); - CGAL_Segment_generator g( i1, i2); - CGAL_copy_n( g, 100, back_inserter( segs)); - - /* Visualize segments. Can be omitted, see example programs */ - /* in the CGAL source code distribution. */ + /* Open window. */ CGAL_Window_stream W(512, 512); W.init(-256.0, 255.0, -256.0); W << CGAL_BLACK; - for( vector::iterator i = segs.begin(); i != segs.end(); i++) - W << *i; + + /* A horizontal like fan. */ + PG p1( Point(-250, -50), Point(-250, 50),50); /* Point generator. */ + PG p2( Point( 250,-250), Point( 250,250),50); + Segm_iterator t1( p1, p2); /* Segment generator. */ + Count_iterator t1_begin( t1); /* Finite range. */ + Count_iterator t1_end( 50); + copy( t1_begin, t1_end, + CGAL_Ostream_iterator(W)); + + /* A vertical like fan. */ + PG p3( Point( -50,-250), Point( 50,-250),50); + PG p4( Point(-250, 250), Point( 250, 250),50); + Segm_iterator t2( p3, p4); + Count_iterator t2_begin( t2); + Count_iterator t2_end( 50); + copy( t2_begin, t2_end, + CGAL_Ostream_iterator(W)); /* Wait for mouse click in window. */ Point p; W >> p; - return 0; } diff --git a/Packages/Generator/doc_tex/Generator/generators.tex b/Packages/Generator/doc_tex/Generator/generators.tex index a9ec85abc8a..cc30bb448aa 100644 --- a/Packages/Generator/doc_tex/Generator/generators.tex +++ b/Packages/Generator/doc_tex/Generator/generators.tex @@ -26,10 +26,15 @@ 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). +generators. The second section provides useful generic functions +related to random numbers like \ccc{CGAL_random_selection()}. The +third section documents generators for two-dimensional point sets, the +fourth section for three-dimensional point sets. The fifth section +presents examples using functions from +Section~\ref{sectionGenericFunctions} to generate composed objects +like segments. Note that the \stl\ algorithm \ccc{random_shuffle} is +useful in this context to achieve random permutations for otherwise +regular generators (e.g.~points on a grid or segment). % +------------------------------------------------------------------------+ @@ -40,28 +45,14 @@ permutations (e.g.~for points on a grid). \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 - 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} +\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. + \ccInclude{CGAL/random_selection.h} \ccFunction{template }\footnote{% + For compilers not supporting these kind of default arguments, both + template arguments must be provided when using these generators.}. +The \ccc{Creator} must be a function object accepting two \ccc{double} +values $x$ and $y$ and returning an initialized point \ccc{(x,y)} of type +\ccc{P}. Predifined implementations for these creators like the +default can be found in Section~\ref{sectionCreatorFunctionObjects}. +They simply assume an appropriate constructor for type \ccc{P}. + +All generators know a range within which the coordinates of the +generated points will lie. \ccInclude{CGAL/point_generators_2.h} +\ccTypes + +The generators comply to the requirements of input iterators which +includes local type declarations including \ccc{value_type} which +denotes \ccc{P} here. + \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} and -\ccc{CGAL_Cartesian}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_in_disc_2} \ccCreationVariable{g} \ccConstructor{CGAL_Random_points_in_disc_2( double r, CGAL_Random& rnd = CGAL_random);}{% @@ -134,12 +133,11 @@ Section~\ref{sectionCopyN}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_circle_2} \ccCreationVariable{g} \ccConstructor{CGAL_Random_points_on_circle_2( double r, CGAL_Random& rnd = CGAL_random);}{% @@ -147,76 +145,116 @@ Section~\ref{sectionCopyN}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_in_square_2} \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}$~. + distributed in the half-open square with side length $2 a$, centered + at the origin, i.e.~$\forall p = \ccc{*g}: -a \le p.x() < a$ and + $-a \le p.y() < a$~. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_square_2} \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$, + distributed on the boundary of the square with side length $2 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}$~. + coordinate is either $a$ or $-a$ and for the + other coordinate $c$ holds $-a \le c < a$~. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_segment_2} \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$, + distributed on the segment from $p$ to $q$ (excluding $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 + \ccPrecond 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} +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Points_on_segment_2

} +\ccCreationVariable{g} +\ccConstructor{CGAL_Points_on_segment_2( const P& p, const P& q, + size_t n, size_t i = 0);}{% + $g$ is an input iterator creating points of type \ccc{P} equally + spaced on the segment from $p$ to $q$. $n$ points are placed on the + segment including $p$ and $q$. The iterator denoted the point $i$ + where $p$ has the index 0 and $q$ the index $n$. + \ccPrecond 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$.} + + +\ccOperations +\ccThree{double}{g.source();}{} + +\ccMethod{double range();}{returns the range in which the point + coordinates lie, i.e.~$\forall x: |x| \leq $\ccc{range()} and + $\forall y: |y| \leq $\ccc{range()}.} + +The generators \ccc{CGAL_Random_points_on_segment_2} and +\ccc{CGAL_Points_on_segment_2} have to additional methods. + +\ccMethod{const P& source();}{returns the source point of the segment.} +\ccGlue +\ccMethod{const P& target();}{returns the target point of the segment.} + +\end{ccClassTemplate} + + +% +------------------------------------------------------------------------+ +\subsection{Point Generators as Functions} + \ccHeading{Grid Points} \ccThree{OutputIterator}{rand}{} -Grid points are produced by generating functions writing to an output -iterator. +Grid points are generated by functions writing to an output iterator. -\ccFunction{template +\def\ccLongParamLayout{\ccTrue} +\ccFunction{template OutputIterator CGAL_points_on_square_grid_2( double a, size_t n, OutputIterator o, - const P*);} + const P*, Creator creator = + CGAL_Creator_uniform_2);} { 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}.} + $[-a,a]\times [-a,a]$. Returns the value of $o$ after inserting + the $n$ points. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The + \ccc{OutputIterator} must accept values of type \ccc{P}. If the + \ccc{OutputIterator} has a \ccc{value_type} the default + initializer of the \ccc{creator} can be used. \ccc{P} is set to + the \ccc{value_type} in this case.} +\def\ccLongParamLayout{\ccFalse} + \ccFunction{template 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$, +{ creates $n$ points equally 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.} @@ -230,13 +268,20 @@ exact predicates to compute the sign of expressions slightly off from zero. \ccFunction{template void CGAL_perturb_points_2( ForwardIterator first, ForwardIterator last, - double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random);} + double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random, + Creator creator = CGAL_Creator_uniform_2);} { 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. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The \ccc{value_type} of the + \ccc{ForwardIterator} must be assignable to \ccc{P}. + \ccc{P} is equal to the \ccc{value_type} of the + \ccc{ForwardIterator} when using the default initializer. The expressions \ccc{CGAL_to_double((*first).x())} and \ccc{CGAL_to_double((*first).y())} must result in the respective coordinate values. @@ -252,23 +297,33 @@ Section~\ref{sectionRandomSelection}. The a point set. +\def\ccLongParamLayout{\ccTrue} \ccFunction{template OutputIterator CGAL_random_collinear_points_2( RandomAccessIterator first, RandomAccessIterator last, - size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random);} + size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random, + Creator creator = CGAL_Creator_uniform_2);} { 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 + points, writes it to \ccc{first2}, and 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. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The \ccc{value_type} of the + \ccc{RandomAccessIterator} must be assignable to \ccc{P}. + \ccc{P} is equal to the \ccc{value_type} of the + \ccc{RandomAccessIterator} when using the default initializer. The expressions \ccc{CGAL_to_double((*first).x())} and \ccc{CGAL_to_double((*first).y())} must result in the respective coordinate values. } +\def\ccLongParamLayout{\ccFalse} + \ccExample @@ -343,47 +398,96 @@ for the example output. % +------------------------------------------------------------------------+ \newpage -\section{2D Segment Generators} +\section{3D Point 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. +One kind of point generators is currently provided: Random point +generators implemented as input iterators. The input iterators model +an infinite sequence of points. The function \ccc{CGAL_copy_n()} could +be used to copy a finite sequence, see Section~\ref{sectionCopyN}. The +iterator adaptor \ccc{CGAL_Counting_iterator} can be used to create +finite iterator ranges, see Section~\ref{sectionCountingIterator}. % +------------------------------------------------------------------------+ -\begin{ccClassTemplate}{CGAL_Segment_generator} -\ccCreationVariable{g} -\subsection{A Generic Segment Generator from Two Points} +\subsection{Point Generators as Input Iterators} \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}. +Input iterators are provided for random points uniformly distributed +in a three-dimensional volume (sphere or cube) or a two-dimensional +surface (boundary of a sphere). -\ccInclude{CGAL/Segment_generator.h} +All iterators are parameterized with the point type \ccc{P} and a second +template argument \ccc{Creator} which defaults to +\ccc{CGAL_Creator_uniform_3}\footnote{% + For compilers not supporting these kind of default arguments, both + template arguments must be provided when using these generators.}. +The \ccc{Creator} must be a function object accepting three +\ccc{double} values $x$, $y$ and $z$ and returning an initialized +point \ccc{(x,y,z)} of type \ccc{P}. Predifined implementations for +these creators like the default can be found in +Section~\ref{sectionCreatorFunctionObjects}. They simply assume an +appropriate constructor for type \ccc{P}. + +All generators know a range within which the coordinates of the +generated points will lie. + +\ccInclude{CGAL/point_generators_3.h} + +\ccTypes + +The generators comply to the requirements of input iterators which +includes local type declarations including \ccc{value_type} which +denotes \ccc{P} here. \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 +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_in_sphere_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_in_sphere_3( double r, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed in the open sphere with radius $r$, + i.e.~$|\ccc{*g}| < r$~. +} +\end{ccClassTemplate} -$g$ satisfies the requirements of an input iterator. Each call to the -\ccc{operator*} returns a new segment. +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_on_sphere_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_on_sphere_3( double r, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed on the boundary of a sphere with radius $r$, + i.e.~$|\ccc{*g}| == r$~. Two random numbers are needed from + \ccc{rnd} for each point. +} +\end{ccClassTemplate} -\ccExample +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_in_cube_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_in_cube_3( double a, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed in the half-open cube with side length $2 a$, centered + at the origin, i.e.~$\forall p = \ccc{*g}: -a \le p.x(),p.y(),p.z() < a$~. + Three random numbers are needed from \ccc{rnd} for each point. +} +\end{ccClassTemplate} + + + +% +------------------------------------------------------------------------+ +\newpage +\section{Examples Generating Segments} + +The following two examples illustrate the use of the generic functions +from Section~\ref{sectionGenericFunctions} like +\ccc{CGAL_Join_input_iterator} 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 @@ -397,16 +501,16 @@ output. \begin{figure} \noindent \hspace*{0.025\textwidth}% - \begin{minipage}{0.45\textwidth}% + \begin{minipage}[t]{0.45\textwidth}% \epsfig{figure=Segment_generator_prog1.ps,width=\textwidth} - \caption{Output of example program for the generic segment generator.} + \caption{Output of the first example program for the generic generator.} \label{figureSegmentGenerator} \end{minipage}% \hspace*{0.05\textwidth}% - \begin{minipage}{0.45\textwidth}% + \begin{minipage}[t]{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.} + \caption{Output of the second example program for the generic + generator without using intermediate storage.} \label{figureSegmentGeneratorFan} \end{minipage}% \end{figure} @@ -427,12 +531,14 @@ output. \end{ccHtmlOnly} -The second example uses precomputed point vectors to generate a -regular structure of 100 segments, see +The second example generates a regular structure of 100 segments, see \ccTexHtml{Figure~\ref{figureSegmentGeneratorFan}}{Figure reference arrow} for the example -output. +output. It uses the \ccc{CGAL_Points_on_segment_2} iterator, +\ccc{CGAL_Join_input_iterator_2} and \ccc{CGAL_Counting_iterator} to +avoid any intermediate storage of the generated objects until they are +used, in this example copied to a windowstream. \cprogfile{Segment_generator_prog2.C} @@ -450,8 +556,6 @@ output. \end{ccHtmlOnly} -\end{ccClassTemplate} - % +--------------------------------------------------------+ \beforecprogskip\parskip \aftercprogskip0pt diff --git a/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog1.C b/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog1.C index 08e754c658e..4a4b54817a9 100644 --- a/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog1.C +++ b/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog1.C @@ -10,13 +10,15 @@ #include #include #include -#include +#include +#include #include #include /* only for visualization used */ -typedef CGAL_Cartesian R; -typedef CGAL_Point_2 Point; -typedef CGAL_Segment_2 Segment; +typedef CGAL_Cartesian R; +typedef CGAL_Point_2 Point; +typedef CGAL_Creator_uniform_2 Pt_creator; +typedef CGAL_Segment_2 Segment; int main() { @@ -25,15 +27,17 @@ int main() segs.reserve(200); /* Prepare point generator for the horizontal segment, length 200. */ - typedef CGAL_Random_points_on_segment_2 P1; + typedef CGAL_Random_points_on_segment_2 P1; P1 p1( Point(-100,0), Point(100,0)); /* Prepare point generator for random points on circle, radius 250. */ - typedef CGAL_Random_points_on_circle_2 P2; + typedef CGAL_Random_points_on_circle_2 P2; P2 p2( 250); /* Create 200 segments. */ - CGAL_Segment_generator g( p1, p2); + typedef CGAL_Creator_uniform_2< Point, Segment> Seg_creator; + typedef CGAL_Join_input_iterator_2< P1, P2, Seg_creator> Seg_iterator; + Seg_iterator g( p1, p2); CGAL_copy_n( g, 200, back_inserter( segs)); /* Visualize segments. Can be omitted, see example programs */ diff --git a/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog2.C b/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog2.C index 9c185370dbc..80c1b709052 100644 --- a/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog2.C +++ b/Packages/Generator/doc_tex/support/Generator/Segment_generator_prog2.C @@ -1,65 +1,55 @@ /* Segment_generator_prog2.C */ /* ------------------------------- */ -/* CGAL example program for the generic segment generator */ -/* using precomputed point locations. */ +/* CGAL example program generating a regular segment pattern. */ #include -#include -#include #include #include #include #include #include -#include -#include -#include /* only for visualization used */ +#include +#include +#include +#include +#include + +typedef CGAL_Cartesian R; +typedef CGAL_Point_2 Point; +typedef CGAL_Segment_2 Segment; +typedef CGAL_Points_on_segment_2 PG; +typedef CGAL_Creator_uniform_2< Point, Segment> Creator; +typedef CGAL_Join_input_iterator_2< PG, PG, Creator> Segm_iterator; +typedef CGAL_Counting_iterator Count_iterator; -typedef CGAL_Cartesian R; -typedef CGAL_Point_2 Point; -typedef CGAL_Segment_2 Segment; int main() { - /* Prepare two point vectors for the precomputed points. */ - vector p1, p2; - p1.reserve(100); - p2.reserve(100); - - /* Create points for a horizontal like fan. */ - CGAL_points_on_segment_2( Point(-250, -50), Point(-250, 50), - 50, back_inserter( p1)); - CGAL_points_on_segment_2( Point( 250,-250), Point( 250,250), - 50, back_inserter( p2)); - - /* Create points for a vertical like fan. */ - CGAL_points_on_segment_2( Point( -50,-250), Point( 50,-250), - 50, back_inserter( p1)); - CGAL_points_on_segment_2( Point(-250, 250), Point( 250, 250), - 50, back_inserter( p2)); - - /* Create test segment set. Prepare a vector for 100 segments. */ - vector segs; - segs.reserve(100); - - /* Create both fans at once from the precomputed points. */ - typedef vector::iterator I; - I i1 = p1.begin(); - I i2 = p2.begin(); - CGAL_Segment_generator g( i1, i2); - CGAL_copy_n( g, 100, back_inserter( segs)); - - /* Visualize segments. Can be omitted, see example programs */ - /* in the CGAL source code distribution. */ + /* Open window. */ CGAL_Window_stream W(512, 512); W.init(-256.0, 255.0, -256.0); W << CGAL_BLACK; - for( vector::iterator i = segs.begin(); i != segs.end(); i++) - W << *i; + + /* A horizontal like fan. */ + PG p1( Point(-250, -50), Point(-250, 50),50); /* Point generator. */ + PG p2( Point( 250,-250), Point( 250,250),50); + Segm_iterator t1( p1, p2); /* Segment generator. */ + Count_iterator t1_begin( t1); /* Finite range. */ + Count_iterator t1_end( 50); + copy( t1_begin, t1_end, + CGAL_Ostream_iterator(W)); + + /* A vertical like fan. */ + PG p3( Point( -50,-250), Point( 50,-250),50); + PG p4( Point(-250, 250), Point( 250, 250),50); + Segm_iterator t2( p3, p4); + Count_iterator t2_begin( t2); + Count_iterator t2_end( 50); + copy( t2_begin, t2_end, + CGAL_Ostream_iterator(W)); /* Wait for mouse click in window. */ Point p; W >> p; - return 0; } diff --git a/Packages/Generator/doc_tex/support/Generator/generators.tex b/Packages/Generator/doc_tex/support/Generator/generators.tex index a9ec85abc8a..cc30bb448aa 100644 --- a/Packages/Generator/doc_tex/support/Generator/generators.tex +++ b/Packages/Generator/doc_tex/support/Generator/generators.tex @@ -26,10 +26,15 @@ 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). +generators. The second section provides useful generic functions +related to random numbers like \ccc{CGAL_random_selection()}. The +third section documents generators for two-dimensional point sets, the +fourth section for three-dimensional point sets. The fifth section +presents examples using functions from +Section~\ref{sectionGenericFunctions} to generate composed objects +like segments. Note that the \stl\ algorithm \ccc{random_shuffle} is +useful in this context to achieve random permutations for otherwise +regular generators (e.g.~points on a grid or segment). % +------------------------------------------------------------------------+ @@ -40,28 +45,14 @@ permutations (e.g.~for points on a grid). \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 - 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} +\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. + \ccInclude{CGAL/random_selection.h} \ccFunction{template }\footnote{% + For compilers not supporting these kind of default arguments, both + template arguments must be provided when using these generators.}. +The \ccc{Creator} must be a function object accepting two \ccc{double} +values $x$ and $y$ and returning an initialized point \ccc{(x,y)} of type +\ccc{P}. Predifined implementations for these creators like the +default can be found in Section~\ref{sectionCreatorFunctionObjects}. +They simply assume an appropriate constructor for type \ccc{P}. + +All generators know a range within which the coordinates of the +generated points will lie. \ccInclude{CGAL/point_generators_2.h} +\ccTypes + +The generators comply to the requirements of input iterators which +includes local type declarations including \ccc{value_type} which +denotes \ccc{P} here. + \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} and -\ccc{CGAL_Cartesian}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_in_disc_2} \ccCreationVariable{g} \ccConstructor{CGAL_Random_points_in_disc_2( double r, CGAL_Random& rnd = CGAL_random);}{% @@ -134,12 +133,11 @@ Section~\ref{sectionCopyN}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_circle_2} \ccCreationVariable{g} \ccConstructor{CGAL_Random_points_on_circle_2( double r, CGAL_Random& rnd = CGAL_random);}{% @@ -147,76 +145,116 @@ Section~\ref{sectionCopyN}. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_in_square_2} \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}$~. + distributed in the half-open square with side length $2 a$, centered + at the origin, i.e.~$\forall p = \ccc{*g}: -a \le p.x() < a$ and + $-a \le p.y() < a$~. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_square_2} \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$, + distributed on the boundary of the square with side length $2 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}$~. + coordinate is either $a$ or $-a$ and for the + other coordinate $c$ holds $-a \le c < a$~. 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

} +\begin{ccClassTemplate}{CGAL_Random_points_on_segment_2} \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$, + distributed on the segment from $p$ to $q$ (excluding $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 + \ccPrecond 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} +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Points_on_segment_2

} +\ccCreationVariable{g} +\ccConstructor{CGAL_Points_on_segment_2( const P& p, const P& q, + size_t n, size_t i = 0);}{% + $g$ is an input iterator creating points of type \ccc{P} equally + spaced on the segment from $p$ to $q$. $n$ points are placed on the + segment including $p$ and $q$. The iterator denoted the point $i$ + where $p$ has the index 0 and $q$ the index $n$. + \ccPrecond 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$.} + + +\ccOperations +\ccThree{double}{g.source();}{} + +\ccMethod{double range();}{returns the range in which the point + coordinates lie, i.e.~$\forall x: |x| \leq $\ccc{range()} and + $\forall y: |y| \leq $\ccc{range()}.} + +The generators \ccc{CGAL_Random_points_on_segment_2} and +\ccc{CGAL_Points_on_segment_2} have to additional methods. + +\ccMethod{const P& source();}{returns the source point of the segment.} +\ccGlue +\ccMethod{const P& target();}{returns the target point of the segment.} + +\end{ccClassTemplate} + + +% +------------------------------------------------------------------------+ +\subsection{Point Generators as Functions} + \ccHeading{Grid Points} \ccThree{OutputIterator}{rand}{} -Grid points are produced by generating functions writing to an output -iterator. +Grid points are generated by functions writing to an output iterator. -\ccFunction{template +\def\ccLongParamLayout{\ccTrue} +\ccFunction{template OutputIterator CGAL_points_on_square_grid_2( double a, size_t n, OutputIterator o, - const P*);} + const P*, Creator creator = + CGAL_Creator_uniform_2);} { 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}.} + $[-a,a]\times [-a,a]$. Returns the value of $o$ after inserting + the $n$ points. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The + \ccc{OutputIterator} must accept values of type \ccc{P}. If the + \ccc{OutputIterator} has a \ccc{value_type} the default + initializer of the \ccc{creator} can be used. \ccc{P} is set to + the \ccc{value_type} in this case.} +\def\ccLongParamLayout{\ccFalse} + \ccFunction{template 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$, +{ creates $n$ points equally 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.} @@ -230,13 +268,20 @@ exact predicates to compute the sign of expressions slightly off from zero. \ccFunction{template void CGAL_perturb_points_2( ForwardIterator first, ForwardIterator last, - double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random);} + double xeps, double yeps = xeps, CGAL_Random& rnd = CGAL_random, + Creator creator = CGAL_Creator_uniform_2);} { 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. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The \ccc{value_type} of the + \ccc{ForwardIterator} must be assignable to \ccc{P}. + \ccc{P} is equal to the \ccc{value_type} of the + \ccc{ForwardIterator} when using the default initializer. The expressions \ccc{CGAL_to_double((*first).x())} and \ccc{CGAL_to_double((*first).y())} must result in the respective coordinate values. @@ -252,23 +297,33 @@ Section~\ref{sectionRandomSelection}. The a point set. +\def\ccLongParamLayout{\ccTrue} \ccFunction{template OutputIterator CGAL_random_collinear_points_2( RandomAccessIterator first, RandomAccessIterator last, - size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random);} + size_t n, OutputIterator first2, CGAL_Random& rnd = CGAL_random, + Creator creator = CGAL_Creator_uniform_2);} { 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 + points, writes it to \ccc{first2}, and 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. + \ccPrecond \ccc{Creator} must be a function object accepting two + \ccc{double} values $x$ and $y$ and returning an initialized point + \ccc{(x,y)} of type \ccc{P}. Predifined implementations for these + creators like the default can be found in + Section~\ref{sectionCreatorFunctionObjects}. The \ccc{value_type} of the + \ccc{RandomAccessIterator} must be assignable to \ccc{P}. + \ccc{P} is equal to the \ccc{value_type} of the + \ccc{RandomAccessIterator} when using the default initializer. The expressions \ccc{CGAL_to_double((*first).x())} and \ccc{CGAL_to_double((*first).y())} must result in the respective coordinate values. } +\def\ccLongParamLayout{\ccFalse} + \ccExample @@ -343,47 +398,96 @@ for the example output. % +------------------------------------------------------------------------+ \newpage -\section{2D Segment Generators} +\section{3D Point 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. +One kind of point generators is currently provided: Random point +generators implemented as input iterators. The input iterators model +an infinite sequence of points. The function \ccc{CGAL_copy_n()} could +be used to copy a finite sequence, see Section~\ref{sectionCopyN}. The +iterator adaptor \ccc{CGAL_Counting_iterator} can be used to create +finite iterator ranges, see Section~\ref{sectionCountingIterator}. % +------------------------------------------------------------------------+ -\begin{ccClassTemplate}{CGAL_Segment_generator} -\ccCreationVariable{g} -\subsection{A Generic Segment Generator from Two Points} +\subsection{Point Generators as Input Iterators} \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}. +Input iterators are provided for random points uniformly distributed +in a three-dimensional volume (sphere or cube) or a two-dimensional +surface (boundary of a sphere). -\ccInclude{CGAL/Segment_generator.h} +All iterators are parameterized with the point type \ccc{P} and a second +template argument \ccc{Creator} which defaults to +\ccc{CGAL_Creator_uniform_3}\footnote{% + For compilers not supporting these kind of default arguments, both + template arguments must be provided when using these generators.}. +The \ccc{Creator} must be a function object accepting three +\ccc{double} values $x$, $y$ and $z$ and returning an initialized +point \ccc{(x,y,z)} of type \ccc{P}. Predifined implementations for +these creators like the default can be found in +Section~\ref{sectionCreatorFunctionObjects}. They simply assume an +appropriate constructor for type \ccc{P}. + +All generators know a range within which the coordinates of the +generated points will lie. + +\ccInclude{CGAL/point_generators_3.h} + +\ccTypes + +The generators comply to the requirements of input iterators which +includes local type declarations including \ccc{value_type} which +denotes \ccc{P} here. \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 +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_in_sphere_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_in_sphere_3( double r, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed in the open sphere with radius $r$, + i.e.~$|\ccc{*g}| < r$~. +} +\end{ccClassTemplate} -$g$ satisfies the requirements of an input iterator. Each call to the -\ccc{operator*} returns a new segment. +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_on_sphere_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_on_sphere_3( double r, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed on the boundary of a sphere with radius $r$, + i.e.~$|\ccc{*g}| == r$~. Two random numbers are needed from + \ccc{rnd} for each point. +} +\end{ccClassTemplate} -\ccExample +\ccHtmlNoClassFile +\begin{ccClassTemplate}{CGAL_Random_points_in_cube_3} +\ccCreationVariable{g} +\ccConstructor{CGAL_Random_points_in_cube_3( double a, CGAL_Random& rnd = + CGAL_random);}{% + $g$ is an input iterator creating points of type \ccc{P} uniformly + distributed in the half-open cube with side length $2 a$, centered + at the origin, i.e.~$\forall p = \ccc{*g}: -a \le p.x(),p.y(),p.z() < a$~. + Three random numbers are needed from \ccc{rnd} for each point. +} +\end{ccClassTemplate} + + + +% +------------------------------------------------------------------------+ +\newpage +\section{Examples Generating Segments} + +The following two examples illustrate the use of the generic functions +from Section~\ref{sectionGenericFunctions} like +\ccc{CGAL_Join_input_iterator} 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 @@ -397,16 +501,16 @@ output. \begin{figure} \noindent \hspace*{0.025\textwidth}% - \begin{minipage}{0.45\textwidth}% + \begin{minipage}[t]{0.45\textwidth}% \epsfig{figure=Segment_generator_prog1.ps,width=\textwidth} - \caption{Output of example program for the generic segment generator.} + \caption{Output of the first example program for the generic generator.} \label{figureSegmentGenerator} \end{minipage}% \hspace*{0.05\textwidth}% - \begin{minipage}{0.45\textwidth}% + \begin{minipage}[t]{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.} + \caption{Output of the second example program for the generic + generator without using intermediate storage.} \label{figureSegmentGeneratorFan} \end{minipage}% \end{figure} @@ -427,12 +531,14 @@ output. \end{ccHtmlOnly} -The second example uses precomputed point vectors to generate a -regular structure of 100 segments, see +The second example generates a regular structure of 100 segments, see \ccTexHtml{Figure~\ref{figureSegmentGeneratorFan}}{Figure reference arrow} for the example -output. +output. It uses the \ccc{CGAL_Points_on_segment_2} iterator, +\ccc{CGAL_Join_input_iterator_2} and \ccc{CGAL_Counting_iterator} to +avoid any intermediate storage of the generated objects until they are +used, in this example copied to a windowstream. \cprogfile{Segment_generator_prog2.C} @@ -450,8 +556,6 @@ output. \end{ccHtmlOnly} -\end{ccClassTemplate} - % +--------------------------------------------------------+ \beforecprogskip\parskip \aftercprogskip0pt