songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

\warning, ###Requires, i.e., whitespace

This commit is contained in:
Andreas Fabri 2012-08-20 14:15:10 +00:00
parent 37cb57b6bc
commit 115c25c207
5 changed files with 73 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Generator/doc/Generator/CGAL/Random.h
View File

@ -106,7 +106,8 @@ double upper = 1.0);
returns a random `IntType` from the interval returns a random `IntType` from the interval
\f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type \f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type
as `int`, `std::ptrdiff_t`, `std::size_t`,etc. <B>Warning: In contrast to `get_int` this function may return `upper`. </B> as `int`, `std::ptrdiff_t`, `std::size_t`,etc.
\warning In contrast to `get_int` this function may return `upper`.
*/ */
template <typename IntType> IntType uniform_smallint( IntType lower=0, IntType upper=9); template <typename IntType> IntType uniform_smallint( IntType lower=0, IntType upper=9);
@ -114,7 +115,8 @@ template <typename IntType> IntType uniform_smallint( IntType lower=0, IntType u
returns a random `IntType` from the interval returns a random `IntType` from the interval
\f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type \f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type
as `int`, `std::ptrdiff_t`, `std::size_t`,etc. <B>Warning: In contrast to `get_int` this function may return `upper`. </B> as `int`, `std::ptrdiff_t`, `std::size_t`,etc.
\warning In contrast to `get_int` this function may return `upper`.
*/ */
template <typename IntType> IntType uniform_int( IntType lower=0, IntType upper=9); template <typename IntType> IntType uniform_int( IntType lower=0, IntType upper=9);

100
Generator/doc/Generator/CGAL/point_generators_2.h
View File

@ -11,25 +11,21 @@ are needed from `rnd` for each point.
The function `perturb_points_2` perturbs each point in a given range of points by The function `perturb_points_2` perturbs each point in a given range of points by
a random amount. a random amount.
Requirements ###Requires ###
-------------- - `Creator` must be a function object accepting two
`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point
`(x,y)` of type `P`.
Predefined implementations for these creators like the default are
described in Section \ref sectionCreatorFunctionObjects.
<UL> - The `value_type` of the `ForwardIterator` must be assignable
<LI>`Creator` must be a function object accepting two to `P`.
`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point - `P` is equal to the `value_type` of the
`(x,y)` of type `P`. `ForwardIterator` when using the default initializer.
- The expressions `to_double((*first).x())` and
`to_double((*first).y())` must result in the respective
coordinate values.
Predefined implementations for these creators like the default are
described in Section \ref sectionCreatorFunctionObjects .
<LI>The `value_type` of the `ForwardIterator` must be assignable
to `P`.
<LI>`P` is equal to the `value_type` of the
`ForwardIterator` when using the default initializer.
<LI>The expressions `to_double((*first).x())` and
`to_double((*first).y())` must result in the respective
coordinate values.
</UL>
\sa `CGAL::points_on_segment_2` \sa `CGAL::points_on_segment_2`
\sa `CGAL::points_on_square_grid_2` \sa `CGAL::points_on_square_grid_2`
@ -51,7 +47,7 @@ namespace CGAL {
\ingroup PkgGenerators \ingroup PkgGenerators
creates \f$ n\f$ points equally spaced on the segment from \f$ p\f$ to \f$ q\f$, creates \f$ n\f$ points equally spaced on the segment from \f$ p\f$ to \f$ q\f$,
i.e. \f$ \forall i: 0 \le i < n: o[i] := \frac{n-i-1}{n-1}\, p + i.e.\ \f$ \forall i: 0 \le i < n: o[i] := \frac{n-i-1}{n-1}\, p +
\frac{i}{n-1}\, q\f$. Returns the value of \f$ o\f$ after inserting \frac{i}{n-1}\, q\f$. Returns the value of \f$ o\f$ after inserting
the \f$ n\f$ points. the \f$ n\f$ points.
@ -81,20 +77,19 @@ the \f$ n\f$ points.
The function `points_on_square_grid_2` generates a given number of points on a square The function `points_on_square_grid_2` generates a given number of points on a square
grid whose size is determined by the number of points to be generated. grid whose size is determined by the number of points to be generated.
Requirements
--------------
<UL> ###Requires###
<LI>`Creator` must be a function object accepting two
`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point - `Creator` must be a function object accepting two
`(x,y)` of type `P`. Predefined implementations for these `double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point
creators like the default can be found in `(x,y)` of type `P`. Predefined implementations for these
Section \ref sectionCreatorFunctionObjects . creators like the default can be found in
<LI>The `OutputIterator` must accept values of type `P`. If the Section \ref sectionCreatorFunctionObjects.
`OutputIterator` has a `value_type` the default - The `OutputIterator` must accept values of type `P`. If the
initializer of the `creator` can be used. `P` is set to `OutputIterator` has a `value_type` the default
the `value_type` in this case. initializer of the `creator` can be used. `P` is set to
</UL> the `value_type` in this case.
\sa `CGAL::perturb_points_2` \sa `CGAL::perturb_points_2`
\sa `CGAL::points_on_segment_2` \sa `CGAL::points_on_segment_2`
@ -123,22 +118,19 @@ in the range \f$ [first,last)\f$.
Three random numbers are needed from `rnd` for each point. Three random numbers are needed from `rnd` for each point.
Returns the value of `first2` after inserting the \f$ n\f$ points. Returns the value of `first2` after inserting the \f$ n\f$ points.
Requirements ###Requires ###
--------------
<UL> - `Creator` must be a function object accepting two
<LI>`Creator` must be a function object accepting two `double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point
`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point `(x,y)` of type `P`. Predefined implementations for these
`(x,y)` of type `P`. Predefined implementations for these creators like the default can be found in
creators like the default can be found in Section \ref sectionCreatorFunctionObjects.
Section \ref sectionCreatorFunctionObjects . - The `value_type` of the `RandomAccessIterator` must be
<LI>The `value_type` of the `RandomAccessIterator` must be assignable to `P`. `P` is equal to the `value_type` of the
assignable to `P`. `P` is equal to the `value_type` of the `RandomAccessIterator` when using the default initializer.
`RandomAccessIterator` when using the default initializer. - The expressions `to_double((*first).x())` and
<LI>The expressions `to_double((*first).x())` and `to_double((*first).y())` must result in the respective
`to_double((*first).y())` must result in the respective coordinate values.
coordinate values.
</UL>
\sa `CGAL::perturb_points_2` \sa `CGAL::perturb_points_2`
\sa `CGAL::points_on_segment_2` \sa `CGAL::points_on_segment_2`
@ -218,7 +210,7 @@ typedef const Point_2& reference;
/*! /*!
\f$ g\f$ is an input iterator creating points of type `Point_2` uniformly \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly
distributed in the open disc with radius \f$ r\f$, distributed in the open disc with radius \f$ r\f$,
i.e. \f$ |*g| < r\f$ . Two random numbers are needed from i.e.\ \f$ |*g| < r\f$. Two random numbers are needed from
`rnd` for each point. `rnd` for each point.
*/ */
@ -292,8 +284,8 @@ typedef const Point_2& reference;
/*! /*!
\f$ g\f$ is an input iterator creating points of type `Point_2` uniformly \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly
distributed in the half-open square with side length \f$ 2 a\f$, centered distributed in the half-open square with side length \f$ 2 a\f$, centered
at the origin, i.e. \f$ \forall p = *g: -a \le p.x() < a\f$ and at the origin, i.e.\ \f$ \forall p = *g: -a \le p.x() < a\f$ and
\f$ -a \le p.y() < a\f$ . \f$ -a \le p.y() < a\f$.
Two random numbers are needed from `rnd` for each point. Two random numbers are needed from `rnd` for each point.
*/ */
@ -371,7 +363,7 @@ typedef const Point_2& reference;
/*! /*!
\f$ g\f$ is an input iterator creating points of type `Point_2` uniformly \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly
distributed on the circle with radius \f$ r\f$, distributed on the circle with radius \f$ r\f$,
i.e. \f$ |*g| == r\f$ . A single random number is needed from i.e.\ \f$ |*g| == r\f$. A single random number is needed from
`rnd` for each point. `rnd` for each point.
*/ */
@ -445,7 +437,7 @@ typedef const Point_2& reference;
/*! /*!
\f$ g\f$ is an input iterator creating points of type `Point_2` uniformly \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly
distributed on the segment from \f$ p\f$ to \f$ q\f$ (excluding \f$ q\f$), distributed on the segment from \f$ p\f$ to \f$ q\f$ (excluding \f$ q\f$),
i.e. \f$ *g == (1-\lambda)\, p + \lambda q\f$ where \f$ 0 \le\lambda< 1\f$ . i.e.\ \f$ *g == (1-\lambda)\, p + \lambda q\f$ where \f$ 0 \le\lambda< 1\f$.
A single random number is needed from `rnd` for each point. A single random number is needed from `rnd` for each point.
\require The expressions `to_double(p.x())` and `to_double(p.y())` must result in the respective `double` representation of the coordinates of \f$ p\f$, and similarly for \f$ q\f$. \require The expressions `to_double(p.x())` and `to_double(p.y())` must result in the respective `double` representation of the coordinates of \f$ p\f$, and similarly for \f$ q\f$.
*/ */
@ -519,9 +511,9 @@ typedef const Point_2& reference;
/*! /*!
\f$ g\f$ is an input iterator creating points of type `Point_2` uniformly \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly
distributed on the boundary of the square with side length \f$ 2 a\f$, distributed on the boundary of the square with side length \f$ 2 a\f$,
centered at the origin, i.e. \f$ \forall p = *g:\f$ one centered at the origin, i.e.\ \f$ \forall p = *g:\f$ one
coordinate is either \f$ a\f$ or \f$ -a\f$ and for the coordinate is either \f$ a\f$ or \f$ -a\f$ and for the
other coordinate \f$ c\f$ holds \f$ -a \le c < a\f$ . other coordinate \f$ c\f$ holds \f$ -a \le c < a\f$.
A single random number is needed from `rnd` for each point. A single random number is needed from `rnd` for each point.
*/ */
@ -612,7 +604,7 @@ std::size_t n, std::size_t i = 0);
/*! /*!
returns the range in which the point returns the range in which the point
coordinates lie, i.e. \f$ \forall x: |x| \leq\f$ `range()` and coordinates lie, i.e.\ \f$ \forall x: |x| \leq\f$ `range()` and
\f$ \forall y: |y| \leq\f$`range()` \f$ \forall y: |y| \leq\f$`range()`
*/ */
double range(); double range();

27
Generator/doc/Generator/CGAL/point_generators_3.h
View File

@ -11,24 +11,21 @@ inserting the \f$ n\f$ points.
The function `points_on_cube_grid_3` generates a given number of points on a cubic The function `points_on_cube_grid_3` generates a given number of points on a cubic
grid whose size is determined by the number of points to be generated. grid whose size is determined by the number of points to be generated.
Requirements ###Requires###
-------------- - `Creator` must be a function object accepting three
`double` values \f$ x\f$, \f$ y\f$, and \f$ z\f$ and returning an initialized
point `(x,y,z)` of type `P`. Predefined implementations for
these creators like the default can be found in
Section \ref sectionCreatorFunctionObjects .
- The `OutputIterator` must accept values of type `P`. If the
`OutputIterator` has a `value_type` the default
initializer of the `creator` can be used. `P` is set to
the `value_type` in this case.
<UL>
<LI>`Creator` must be a function object accepting three
`double` values \f$ x\f$, \f$ y\f$, and \f$ z\f$ and returning an initialized
point `(x,y,z)` of type `P`. Predefined implementations for
these creators like the default can be found in
Section \ref sectionCreatorFunctionObjects .
<LI>The `OutputIterator` must accept values of type `P`. If the
`OutputIterator` has a `value_type` the default
initializer of the `creator` can be used. `P` is set to
the `value_type` in this case.
</UL>
`CGAL::points_on_square_grid_2` \sa `CGAL::points_on_square_grid_2`
`CGAL::random_selection` \sa `CGAL::random_selection`
*/ */
template <class OutputIterator, Creator creator> template <class OutputIterator, Creator creator>

2
Generator/doc/Generator/Concepts/PointGenerator.h
View File

@ -36,7 +36,7 @@ typedef Hidden_type value_type;
/// @{ /// @{
/*! /*!
return an absolute bound for returns an absolute bound for
the coordinates of all generated points. the coordinates of all generated points.
*/ */
double range() const; double range() const;

20
Generator/doc/Generator/Generator.txt
View File

@ -31,8 +31,8 @@ on a circle (`Random_points_on_circle_2`),
on a segment (`Random_points_on_segment`), on a segment (`Random_points_on_segment`),
and on a square (`Random_points_on_square_2`). and on a square (`Random_points_on_square_2`).
For generating grid points we provide three functions, For generating grid points we provide three functions,
`points_on_segment_2()`, `::points_on_segment_2()`,
`points_on_square_grid_2()` that write to output iterators and `::points_on_square_grid_2()` that write to output iterators and
an input iterator `Points_on_segment_2`. an input iterator `Points_on_segment_2`.
For 3D points, input iterators are provided for random points uniformly For 3D points, input iterators are provided for random points uniformly
@ -48,34 +48,34 @@ distributed in a \f$ d\f$-dimensional cube (`Random_points_in_cube_d`)
or \f$ d\f$-dimensional ball (`Random_points_in_ball_d`) or on the boundary of a or \f$ d\f$-dimensional ball (`Random_points_in_ball_d`) or on the boundary of a
sphere (`Random_points_on_sphere_d`). sphere (`Random_points_on_sphere_d`).
For generating grid points, we provide the function For generating grid points, we provide the function
`points_on_grid_d()` that writes to `::points_on_grid_d()` that writes to
an output iterator. an output iterator.
We also provide two functions for generating more complex geometric objects. We also provide two functions for generating more complex geometric objects.
The function `random_convex_set_2()` computes a random convex planar The function `::random_convex_set_2()` computes a random convex planar
point set of a given size where the points are drawn from a specific point set of a given size where the points are drawn from a specific
domain and `random_polygon_2()` generates a random simple polygon from domain and `::random_polygon_2()` generates a random simple polygon from
points drawn from a specific domain. points drawn from a specific domain.
## Random Perturbations ## ## %Random Perturbations ##
Degenerate input sets like grid points can be randomly perturbed by a Degenerate input sets like grid points can be randomly perturbed by a
small amount to produce <I>quasi</I>-degenerate test sets. This small amount to produce <I>quasi</I>-degenerate test sets. This
challenges numerical stability of algorithms using inexact arithmetic and challenges numerical stability of algorithms using inexact arithmetic and
exact predicates to compute the sign of expressions slightly off from zero. exact predicates to compute the sign of expressions slightly off from zero.
For this the function `perturb_points_2()` is provided. For this the function `::perturb_points_2()` is provided.
## Adding Degeneracies ## ## Adding Degeneracies ##
For a given point set certain kinds of degeneracies can be produced For a given point set certain kinds of degeneracies can be produced
by adding new points. The `random_selection()` function is by adding new points. The `::random_selection()` function is
useful for generating multiple copies of identical points. useful for generating multiple copies of identical points.
The function `random_collinear_points_2()` adds collinearities to The function `::random_collinear_points_2()` adds collinearities to
a point set. a point set.
## Support Functions and Classes for Generators ## ## Support Functions and Classes for Generators ##
The function `random_selection()` chooses \f$ n\f$ items at random from a random The function `::random_selection()` chooses \f$ n\f$ items at random from a random
access iterator range which is useful to produce degenerate input data access iterator range which is useful to produce degenerate input data
sets with multiple entries of identical items. sets with multiple entries of identical items.