mirror of https://github.com/CGAL/cgal
288 lines
11 KiB
Plaintext
288 lines
11 KiB
Plaintext
|
|
namespace CGAL {
|
|
/*!
|
|
|
|
\mainpage User Manual
|
|
\anchor Chapter_Geometric_Object_Generators
|
|
\anchor chapterGenerators
|
|
\cgalAutoToc
|
|
\authors Pedro M. M. de Castro, Olivier Devillers, Susan Hert, Michael Hoffmann, Lutz Kettner, Sven Schönherr, Alexandru Tifrea, and Maxime Gimeno
|
|
|
|
\section GeneratorIntroduction 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 `CGAL::copy_n()` can be used to copy a
|
|
finite sequence. The iterator adaptor
|
|
`Counting_iterator` can be used to create finite iterator
|
|
ranges.
|
|
Other generators are provided as functions that write to output
|
|
iterators. Further functions add degeneracies or random perturbations.
|
|
|
|
In 2D, we provide input iterators to generate random points in a disc
|
|
(`Random_points_in_disc_2`),
|
|
in a square (`Random_points_in_square_2`),
|
|
on a circle (`Random_points_on_circle_2`),
|
|
on a segment (`Random_points_on_segment`),
|
|
in a square (`Random_points_on_square_2`),
|
|
in a triangle (`Random_points_in_triangle_2`),
|
|
in a range of triangles (`Random_points_in_triangles_2`),
|
|
and in a triangle mesh (`Random_points_in_triangle_mesh_2`).
|
|
For generating grid points we provide three functions,
|
|
`points_on_segment_2()`,
|
|
`points_on_square_grid_2()` that write to output iterators and
|
|
an input iterator `Points_on_segment_2`.
|
|
|
|
For 3D points, input iterators are provided for random points uniformly
|
|
distributed in a sphere (`Random_points_in_sphere_3`), in a triangle (`Random_points_in_triangle_3`),
|
|
in a range of triangles (`Random_points_in_triangles_3`),
|
|
in a tetrahedron (`Random_points_in_tetrahedron_3`), in a cube (`Random_points_in_cube_3`), on the boundary of a sphere
|
|
(`Random_points_on_sphere_3`), in a triangle mesh (`Random_points_in_triangle_mesh_3`),
|
|
in a tetrahedron mesh (`Random_points_in_tetrahedral_mesh_3`), and on the boundary
|
|
of a tetrahedron mesh (`Random_points_in_tetrahedral_mesh_boundary_3`).
|
|
For generating 3D grid points, we provide the function
|
|
`points_on_cube_grid_3()` that writes to
|
|
an output iterator.
|
|
|
|
For higher dimensions, input iterators are provided for random points uniformly
|
|
distributed in a `d`-dimensional cube (`Random_points_in_cube_d`)
|
|
or `d`-dimensional ball (`Random_points_in_ball_d`) or on the boundary of a
|
|
sphere (`Random_points_on_sphere_d`).
|
|
For generating grid points, we provide the function
|
|
`points_on_cube_grid_d()` that writes to
|
|
an output iterator.
|
|
|
|
We also provide two functions for generating more complex geometric objects.
|
|
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
|
|
domain and `random_polygon_2()` generates a random simple polygon from
|
|
points drawn from a specific domain. The function `random_convex_hull_in_disc_2()` computes a random polygon as a convex hull from uniformly generated random points in a disc.
|
|
|
|
\subsection GeneratorRandomPerturbations Random Perturbations
|
|
|
|
Degenerate input sets like grid points can be randomly perturbed by a
|
|
small amount to produce <I>quasi</I>-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 `perturb_points_2()` is provided.
|
|
|
|
\subsection GeneratorAddingDegeneracies Adding Degeneracies
|
|
|
|
For a given point set certain kinds of degeneracies can be produced
|
|
by adding new points. The `random_selection()` function is
|
|
useful for generating multiple copies of identical points.
|
|
The function `random_collinear_points_2()` adds collinearities to
|
|
a point set.
|
|
|
|
\subsection GeneratorSupportFunctionsandClassesforGenerators Support Functions and Classes for Generators
|
|
|
|
The function `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.
|
|
|
|
The class `Combination_enumerator<CombinationElement>` is used to enumerate
|
|
all fixed-size combinations (subsets) of a range of elements. It is useful
|
|
in the context of high-dimensional triangulations, e.g., for enumerating the
|
|
faces of a simplex.
|
|
|
|
\section GeneratorExample_1 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 \cgalFigureRef{figurePointGenerator}
|
|
for the example output.
|
|
|
|
\cgalExample{Generator/random_degenerate_point_set.cpp}
|
|
|
|
\cgalFigureBegin{figurePointGenerator,generators_prog1.png}
|
|
Output of example program for point generators.
|
|
\cgalFigureEnd
|
|
|
|
\section GeneratorExampleGridPoints Example Generating Grid Points
|
|
|
|
The second example demonstrates the point generators with integer
|
|
points. Floating point arithmetic is sufficient to produce
|
|
regular integer grids. See \cgalFigureRef{figureIntegerPointGenerator}
|
|
for the example output.
|
|
|
|
\cgalExample{Generator/random_grid.cpp}
|
|
|
|
\cgalFigureBegin{figureIntegerPointGenerator,generators_prog2.png}
|
|
Output of example program for point generators working
|
|
\cgalFigureEnd
|
|
|
|
\section GeneratorExample_mesh Example Generating Random Point Sets On a Triangle Mesh
|
|
The following example demonstrates the use of the random point generator
|
|
on a triangle mesh. We want to generate 100 points uniformly chosen on a `Polyhedron_3`.
|
|
See \cgalFigureRef{figureMeshPointGenerator}
|
|
\cgalExample{Generator/random_points_on_triangle_mesh_3.cpp}
|
|
|
|
|
|
\cgalFigureBegin{figureMeshPointGenerator,generator_mesh_3.png}
|
|
Output of example program for point generator on a triangle mesh
|
|
\cgalFigureEnd
|
|
|
|
\section secsegment_example Examples Generating Segments
|
|
|
|
The following two examples illustrate the use of the generic functions
|
|
from Section \ref STLAlgos like
|
|
`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 \cgalFigureRef{figureSegmentGenerator} for the example output.
|
|
|
|
\cgalExample{Generator/random_segments1.cpp}
|
|
|
|
\cgalFigureBegin{figureSegmentGenerator,Segment_generator_prog1.png}
|
|
Output of example program for the generic segment generator.
|
|
\cgalFigureEnd
|
|
|
|
The second example generates a regular structure of 100 segments; see
|
|
\cgalFigureRef{figureSegmentGeneratorFan} for the example output. It uses
|
|
the `Points_on_segment_2` iterator, `Join_input_iterator_2` and
|
|
`Counting_iterator` to avoid any intermediate storage of the generated
|
|
objects until they are used.
|
|
|
|
\cgalExample{Generator/random_segments2.cpp}
|
|
|
|
\cgalFigureBegin{figureSegmentGeneratorFan,Segment_generator_prog2.png}
|
|
Output of example program for the generic segment generator using pre-computed point locations.
|
|
\cgalFigureEnd
|
|
|
|
\section GeneratorExample_2 Example Generating Point Sets in d Dimensions
|
|
|
|
The following example generates points inside a cube in dimension 5
|
|
(examples for ball and sphere are available in the example directory) :
|
|
|
|
\cgalExample{Generator/cube_d.cpp}
|
|
|
|
The output of this example looks like:
|
|
\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
|
|
\endverbatim
|
|
|
|
Next example generates grid points in dimension `d=4`.
|
|
Since the required number of
|
|
points, 20 is between \f$ 2^d\f$ and \f$ 3^d\f$ the supporting grid has
|
|
\f$ 3\times 3\times 3\times 3\f$ points.
|
|
Since the size parameter is 5, the
|
|
coordinates are in \f$ \{-5, 0, 5\}\f$, but since the number of points
|
|
verifies \f$ 20\leq 3^{d-1}\f$, all
|
|
generated points have the same last coordinate \f$ -5\f$.
|
|
|
|
\cgalExample{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:
|
|
|
|
\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
|
|
\endverbatim
|
|
|
|
\image html hypergrid.png
|
|
\image latex hypergrid.png
|
|
|
|
\section GeneratorExGenCombi Example Generating Combinations
|
|
|
|
\subsection GeneratorFromRangeInt From a Range of Integers
|
|
|
|
The following example enumerates and outputs all subsets of 3 elements from the
|
|
range \f$ [10, 15]\f$. Accordingly, it outputs \f$ \frac{6!}{3! 3!}=20\f$
|
|
triples.
|
|
|
|
|
|
\cgalExample{Generator/combination_enumerator.cpp}
|
|
|
|
The output of this example is:
|
|
\verbatim
|
|
Taking 3 distinct integers in the range [10, 15]: {10 11 12} {10 11 13} {10 11 14}
|
|
{10 11 15} {10 12 13} {10 12 14} {10 12 15} {10 13 14} {10 13 15} {10 14 15}
|
|
{11 12 13} {11 12 14} {11 12 15} {11 13 14} {11 13 15} {11 14 15} {12 13 14}
|
|
{12 13 15} {12 14 15} {13 14 15}
|
|
Enumerated 20 combinations.
|
|
\endverbatim
|
|
|
|
\subsection GeneratorFromArrayStr From an Array of Strings
|
|
The following example generates all pairs of names from a set of names stored
|
|
in an array of strings.
|
|
|
|
\cgalExample{Generator/name_pairs.cpp}
|
|
|
|
\section GeneratorDesign Design and Implementation History
|
|
|
|
Lutz Kettner coded generators in 2D and 3D
|
|
For points <I>in</I> and <I>on</I> 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ö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 <I>in ball</I> and <I>on sphere</I>, 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.
|
|
|
|
|
|
Remy Thomasse coded the random convex hull in a disc.
|
|
|
|
During Google Summer of Code 2013, Pedro M. M. de Castro and Alexandru Tifrea coded generators for points in
|
|
triangle (2D and 3D) and in tetrahedra (3D). Basically, in order to generate
|
|
a random point in a \f$N\f$-simplex (a triangle for \f$N = 2\f$, and tetrahedron
|
|
for \f$N = 3\f$), we generate numbers \f$a_1,a_2,\ldots,a_N\f$ identically and independently
|
|
uniformly distributed in \f$(0,1)\f$, we sort them, we let \f$a_0 = 0\f$ and \f$a_{N+1} = 1\f$,
|
|
and then \f$a_{i+1}-a_i\f$, for \f$i = 1,\ldots,N\f$ becomes its
|
|
barycentric coordinates with respect to the simplex.
|
|
|
|
Maxime Gimemo introduced the random generators on 2D and 3D triangle meshes.
|
|
|
|
*/
|
|
} /* namespace CGAL */
|
|
|