Merge pull request #4941 from afabri/Bounding_Volumes-doc_fixes-GF

Bounding Volumes:  Fix and improve the documentation
This commit is contained in:
Sebastien Loriot 2020-10-02 15:15:10 +02:00 committed by GitHub
commit 8199d88a6c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 238 additions and 131 deletions

View File

@ -9,37 +9,16 @@ namespace CGAL {
\authors Kaspar Fischer, Bernd Gärtner, Thomas Herrmann, Michael Hoffmann, and Sven Schönherr
\image html ball.png
\image latex ball.png
This chapter describes algorithms which for a given point set compute
the <i>best</i> circumscribing object from a specific
class. If the class consists of all spheres in \f$ d\f$-dimensional
Euclidean space and <i>best</i> is defined as having smallest radius,
then we obtain the smallest enclosing sphere problem already mentioned
above.
then we obtain the smallest enclosing sphere.
In the following example a smallest enclosing circle
(`Min_circle_2<Traits>`) is constructed from points
on a line and written to standard output. The example
shows that it is advisable to switch on random shuffling
in order to deal with a <i>bad</i> order of the input points.
\cgalExample{Min_circle_2/min_circle_2.cpp}
Other classes for which we provide solutions are ellipses
(`Min_ellipse_2<Traits>`), rectangles
(`min_rectangle_2()`), parallelograms
(`min_parallelogram_2()`) and strips (`min_strip_2()`)
in the plane, with appropriate optimality criteria. For arbitrary
dimensions we provide smallest enclosing spheres for points
(`Min_sphere_d<Traits>`) and spheres for spheres
(`Min_sphere_of_spheres_d<Traits>`), smallest enclosing
annuli (`Min_annulus_d<Traits>`), and approximate
minimum-volume enclosing ellipsoid with user-specified
approximation ratio (`Approximate_min_ellipsoid_d<Traits>`).
\image html annulus.png
\image latex annulus.png
\section SectBoundingIntroduction Introduction
Bounding volumes can be used to obtain simple approximations of
complicated objects. For example, consider the problem of deciding
@ -60,13 +39,74 @@ geometric properties of objects. For example, the smallest enclosing
annulus of a point set can be used to test whether a set of points is
approximately cospherical. Here, the width of the annulus (or its
area, or still another criterion that we use) is a good measure for
this property. The largest area triangle is for example used in
heuristics for matching archaeological aerial photographs. Largest
perimeter triangles are used in scoring cross country soaring flights,
where the goal is basically to fly as far as possible, but still
return to the departure airfield. To score simply based on the total
distance flown is not a good measure, since circling in thermals
allows to increase it easily.
this property.
\section SectBoundingSphere Bounding Spheres in dD
We provide the class `Min_sphere_of_spheres_d<Traits>` for arbitrary dimensions
to compute the smallest enclosing spheres for points as well as for spheres.
The dimension as well as the input type depend on the chosen traits class.
The following example is for 2D points
\cgalExample{Min_circle_2/min_circle_2.cpp}
The example for 2D circles as input looks rather similar.
\cgalExample{Min_sphere_of_spheres_d/min_sphere_of_spheres_d_2.cpp}
\subsection SectBoundingSphereHomogeneous Bounding Spheres for the Homogeneous Kernel
In the previous section we saw that we used `Min_sphere_of_spheres_d`
to compute the smallest circle for points. This package also provides
the classes `Min_circle_2` and `Min_sphere_d`, but they are slower,
and they should only be used in case of homogeneous coordinates which
are not supported by `Min_sphere_of_spheres_d`.
In the following example a smallest enclosing circle
(`Min_circle_2<Traits>`) is constructed from points
on a line and written to standard output. The example
shows that it is advisable to switch on random shuffling
in order to deal with a <i>bad</i> order of the input points.
\cgalExample{Min_circle_2/min_circle_homogeneous_2.cpp}
\section SectBoundingAnnulus Bounding Annulus in dD
We provide the class `Min_annulus_d<Traits>` for arbitrary dimensions
to compute the smalles enclosing annulus for a set of points.
In 2D the annulus consists of two concentric circles, in 3D of
two concentric spheres.
\image html annulus.png
\section SectBounding2D Various Bounding Areas in 2D
Other classes for which we provide solutions are ellipses
(`Min_ellipse_2<Traits>`), rectangles
(`min_rectangle_2()`), parallelograms
(`min_parallelogram_2()`) and strips (`min_strip_2()`)
in the plane, with appropriate optimality criteria.
\section SectBoundingEllipsoid Approximate Bounding Ellipsoid in dD
While this package provides an exact smallest 2D ellipse, it also
provides the class `Approximate_min_ellipsoid_d<Traits>` to compute
an approximate minimum-volume enclosing ellipsoid with user-specified
approximation ratio.
\section SectBoundingPcenter Rectangular P-Center
Bounding volumes also define geometric "center points" of objects.
For example, if two objects are to be matched (approximately), one
@ -81,8 +121,6 @@ planar point set with between two and four minimal boxes
three boxes; the center points are shown in red.
\image html pcenter.png
\image latex pcenter.png
*/
} /* namespace CGAL */

View File

@ -191,7 +191,7 @@ to iterate over the %Cartesian coordinates of the direction of a fixed
axis of the computed ellipsoid, see
`axis_direction_cartesian_begin()`.
*/
typedef unspecified_type Axis_direction_iterator;
typedef unspecified_type Axes_direction_coordinate_iterator;
/// @}

View File

@ -24,17 +24,17 @@ The underlying algorithm can cope with all kinds of input, e.g. \f$ P\f$ may be
empty or points may occur more than once. The algorithm computes a support
set \f$ S\f$ which remains fixed until the next set, insert, or clear operation.
\tparam Traits must be a model for `OptimisationDTraits`.
\tparam Traits must be a model for `MinSphereAnnulusDTraits`.
We provide the models `Optimisation_d_traits_2`,
`Optimisation_d_traits_3`, and `Optimisation_d_traits_d` using the
We provide the models `Min_sphere_annulus_d_traits_2`,
`Min_sphere_annulus_d_traits_3`, and `Min_sphere_annulus_d_traits_d` using the
two-, three-, and \f$ d\f$-dimensional \cgal kernel, respectively.
\sa `CGAL::Min_sphere_d<Traits>`
\sa `CGAL::Optimisation_d_traits_2<K,ET,NT>`
\sa `CGAL::Optimisation_d_traits_3<K,ET,NT>`
\sa `CGAL::Optimisation_d_traits_d<K,ET,NT>`
\sa `OptimisationDTraits`
\sa `CGAL::Min_sphere_annulus_d_traits_2<K,ET,NT>`
\sa `CGAL::Min_sphere_annulus_d_traits_3<K,ET,NT>`
\sa `CGAL::Min_sphere_annulus_d_traits_d<K,ET,NT>`
\sa `MinSphereAnnulusDTraits`
\cgalHeading{Implementation}

View File

@ -23,9 +23,9 @@ The underlying algorithm can cope with all kinds of input, e.g. \f$ P\f$ may be
empty or points may occur more than once. The algorithm computes a support
set \f$ S\f$ which remains fixed until the next insert or clear operation.
<B>Please note:</B> This class is (almost) obsolete. The class
\note This class is (almost) obsolete. The class
`CGAL::Min_sphere_of_spheres_d<Traits>` solves a more general problem
and is faster then `Min_circle_2` even if used only for points in two
and is faster than `Min_circle_2` even if used only for points in two
dimensions as input. Most importantly,
`CGAL::Min_sphere_of_spheres_d<Traits>` has
a specialized implementation for floating-point arithmetic which

View File

@ -22,9 +22,9 @@ The algorithm
computes a support set \f$ S\f$ which remains fixed until the next insert
or clear operation.
<B>Please note:</B> This class is (almost) obsolete. The class
\note This class is (almost) obsolete. The class
`CGAL::Min_sphere_of_spheres_d<Traits>` solves a more general problem
and is faster then `Min_sphere_d` even if used only for points
and is faster than `Min_sphere_d` even if used only for points
as input. Most importantly, `CGAL::Min_sphere_of_spheres_d<Traits>` has
a specialized implementation for floating-point arithmetic which
ensures correct results in a large number of cases (including
@ -38,17 +38,17 @@ divide.
\tparam Traits must be a model of the concept
`OptimisationDTraits` as its template argument.
`MinSphereAnnulusDTraits` as its template argument.
We provide the models `CGAL::Optimisation_d_traits_2`,
`CGAL::Optimisation_d_traits_3` and
`CGAL::Optimisation_d_traits_d`
We provide the models `CGAL::Min_sphere_annulus_d_traits_2`,
`CGAL::Min_sphere_annulus_d_traits_3` and
`CGAL::Min_sphere_annulus_d_traits_d`
for two-, three-, and \f$ d\f$-dimensional points respectively.
\sa `CGAL::Optimisation_d_traits_2<K,ET,NT>`
\sa `CGAL::Optimisation_d_traits_3<K,ET,NT>`
\sa `CGAL::Optimisation_d_traits_d<K,ET,NT>`
\sa `OptimisationDTraits`
\sa `CGAL::Min_sphere_annulus_d_traits_2<K,ET,NT>`
\sa `CGAL::Min_sphere_annulus_d_traits_3<K,ET,NT>`
\sa `CGAL::Min_sphere_annulus_d_traits_d<K,ET,NT>`
\sa `MinSphereAnnulusDTraits`
\sa `CGAL::Min_circle_2<Traits>`
\sa `CGAL::Min_sphere_of_spheres_d<Traits>`
\sa `CGAL::Min_annulus_d<Traits>`
@ -68,7 +68,7 @@ each take linear time.
\cgalHeading{Example}
\cgalExample{Min_sphere_d/min_sphere_d.cpp}
\cgalExample{Min_sphere_d/min_sphere_homogeneous_d.cpp}
*/
template< typename Traits >

View File

@ -50,7 +50,7 @@ minsphere can be described by the number \f$ t\f$, which is called the
sphere's <I>discriminant</I>, and by \f$ d+1\f$ pairs \f$ (a_i,b_i)\in\Q^2\f$
(one for the radius and \f$ d\f$ for the center coordinates).
<B>Note:</B> This class (almost) replaces
\note This class (almost) replaces
`CGAL::Min_sphere_d<Traits>`, which solves the less general
problem of finding the smallest enclosing ball of a set of
<I>points</I>. `Min_sphere_of_spheres_d` is faster than

View File

@ -3,6 +3,11 @@ namespace CGAL {
/*!
\ingroup PkgBoundingVolumesRef
computes a minimum area enclosing parallelogram of the point set
described by [`points_begin`, `points_end`), writes its
vertices (counterclockwise) to `o` and returns the past-the-end
iterator of this sequence.
The function computes a minimum area enclosing
parallelogram \f$ A(P)\f$ of a given convex point set \f$ P\f$. Note that
\f$ R(P)\f$ is not necessarily axis-parallel, and it is in general not
@ -11,10 +16,6 @@ parallelogram enclosing \f$ P\f$ - as a convex set - contains the convex
hull of \f$ P\f$. For general point sets one has to compute the convex hull
as a preprocessing step.
computes a minimum area enclosing parallelogram of the point set
described by [`points_begin`, `points_end`), writes its
vertices (counterclockwise) to `o` and returns the past-the-end
iterator of this sequence.
If the input range is empty, `o` remains unchanged.
If the input range consists of one element only, this point is written
@ -74,6 +75,11 @@ namespace CGAL {
/*!
\ingroup PkgBoundingVolumesRef
computes a minimum area enclosing rectangle of the point set described
by [`points_begin`, `points_end`), writes its vertices
(counterclockwise) to `o`, and returns the past-the-end iterator
of this sequence.
The function computes a minimum area enclosing rectangle
\f$ R(P)\f$ of a given convex point set \f$ P\f$. Note that \f$ R(P)\f$ is not
necessarily axis-parallel, and it is in general not unique. The focus
@ -81,10 +87,6 @@ on convex sets is no restriction, since any rectangle enclosing
\f$ P\f$ - as a convex set - contains the convex hull of \f$ P\f$. For general
point sets one has to compute the convex hull as a preprocessing step.
computes a minimum area enclosing rectangle of the point set described
by [`points_begin`, `points_end`), writes its vertices
(counterclockwise) to `o`, and returns the past-the-end iterator
of this sequence.
If the input range is empty, `o` remains unchanged.
@ -143,6 +145,10 @@ namespace CGAL {
/*!
\ingroup PkgBoundingVolumesRef
computes a minimum enclosing strip of the point set described by
[`points_begin`, `points_end`), writes its two bounding lines
to `o` and returns the past-the-end iterator of this sequence.
The function computes a minimum width enclosing strip
\f$ S(P)\f$ of a given convex point set \f$ P\f$. A strip is the closed region
bounded by two parallel lines in the plane. Note that \f$ S(P)\f$ is not
@ -151,10 +157,6 @@ parallelogram enclosing \f$ P\f$ - as a convex set - contains the convex
hull of \f$ P\f$. For general point sets one has to compute the convex hull
as a preprocessing step.
computes a minimum enclosing strip of the point set described by
[`points_begin`, `points_end`), writes its two bounding lines
to `o` and returns the past-the-end iterator of this sequence.
If the input range is empty or consists of one element only, `o`
remains unchanged.
@ -205,4 +207,3 @@ OutputIterator o,
Traits& t = Default_traits);
} /* namespace CGAL */

View File

@ -5,8 +5,8 @@
The concept `MinQuadrilateralTraits_2` defines types and operations
needed to compute minimum enclosing quadrilaterals of a planar point
set using the functions `min_rectangle_2`,
`min_parallelogram_2` and `min_strip_2`.
set using the functions `min_rectangle_2()`,
`min_parallelogram_2()` and `min_strip_2()`.
\cgalHasModel `CGAL::Min_quadrilateral_default_traits_2<K>`
@ -262,4 +262,3 @@ const ;
/// @}
}; /* end MinQuadrilateralTraits_2 */

View File

@ -10,6 +10,9 @@ following constants, types, predicates and operations.
\cgalHasModel `CGAL::Min_sphere_of_spheres_d_traits_3<K,FT,UseSqrt,Algorithm>`
\cgalHasModel `CGAL::Min_sphere_of_spheres_d_traits_d<K,FT,Dim,UseSqrt,Algorithm>`
\cgalHasModel `CGAL::Min_sphere_of_points_d_traits_2<K,FT,UseSqrt,Algorithm>`
\cgalHasModel `CGAL::Min_sphere_of_points_d_traits_3<K,FT,UseSqrt,Algorithm>`
\cgalHasModel `CGAL::Min_sphere_of_points_d_traits_d<K,FT,Dim,UseSqrt,Algorithm>`
*/
class MinSphereOfSpheresTraits {
@ -112,4 +115,3 @@ Cartesian_const_iterator center_cartesian_begin(const Sphere& s);
/// @}
}; /* end MinSphereOfSpheresTraits */

View File

@ -5,7 +5,7 @@
The concept `RectangularPCenterTraits_2` defines types and operations
needed to compute rectilinear \f$ p\f$-centers of a planar point set
using the function `CGAL::rectangular_p_center_2`.
using the function `CGAL::rectangular_p_center_2()`.
\cgalHasModel `CGAL::Rectangular_p_center_default_traits_2<K>`
@ -193,4 +193,3 @@ construct_iso_rectangle_2_above_right_point_2_object() const;
/// @}
}; /* end RectangularPCenterTraits_2 */

View File

@ -4,11 +4,13 @@
\example Min_annulus_d/min_annulus_d.cpp
\example Min_annulus_d/min_annulus_d_fast_exact.cpp
\example Min_circle_2/min_circle_2.cpp
\example Min_circle_2/min_circle_homogeneous_2.cpp
\example Min_ellipse_2/min_ellipse_2.cpp
\example Min_quadrilateral_2/minimum_enclosing_parallelogram_2.cpp
\example Min_quadrilateral_2/minimum_enclosing_rectangle_2.cpp
\example Min_quadrilateral_2/minimum_enclosing_strip_2.cpp
\example Min_sphere_d/min_sphere_d.cpp
\example Min_sphere_d/min_sphere_3.cpp
\example Min_sphere_d/min_sphere_homogeneous_3.cpp
\example Min_sphere_of_spheres_d/benchmark.cpp
\example Min_sphere_of_spheres_d/min_sphere_of_spheres_d_2.cpp
\example Min_sphere_of_spheres_d/min_sphere_of_spheres_d_3.cpp

View File

@ -1,13 +1,13 @@
#include <CGAL/Exact_predicates_exact_constructions_kernel.h>
#include <CGAL/Min_circle_2.h>
#include <CGAL/Min_circle_2_traits_2.h>
#include <CGAL/Simple_cartesian.h>
#include <CGAL/Min_sphere_of_spheres_d.h>
#include <CGAL/Min_sphere_of_points_d_traits_2.h>
#include <CGAL/Random.h>
#include <iostream>
// typedefs
typedef CGAL::Exact_predicates_exact_constructions_kernel K;
typedef CGAL::Min_circle_2_traits_2<K> Traits;
typedef CGAL::Min_circle_2<Traits> Min_circle;
typedef CGAL::Simple_cartesian<double> K;
typedef CGAL::Min_sphere_of_points_d_traits_2<K,double> Traits;
typedef CGAL::Min_sphere_of_spheres_d<Traits> Min_circle;
typedef K::Point_2 Point;
int
@ -15,16 +15,19 @@ main( int, char**)
{
const int n = 100;
Point P[n];
CGAL::Random r; // random number generator
for ( int i = 0; i < n; ++i)
P[ i] = Point( (i%2 == 0 ? i : -i), 0);
// (0,0), (-1,0), (2,0), (-3,0), ...
for ( int i = 0; i < n; ++i){
P[ i] = Point(r.get_double(), r.get_double());
}
Min_circle mc1( P, P+n, false); // very slow
Min_circle mc2( P, P+n, true); // fast
CGAL::set_pretty_mode( std::cout);
std::cout << mc2;
Min_circle mc( P, P+n);
Min_circle::Cartesian_const_iterator ccib = mc.center_cartesian_begin(), ccie = mc.center_cartesian_end();
std::cout << "center:";
for( ; ccib != ccie; ++ccib){
std::cout << " " << *ccib;
}
std::cout << std::endl << "radius: " << mc.radius() << std::endl;
return 0;
}

View File

@ -0,0 +1,33 @@
#include <CGAL/Exact_integer.h>
#include <CGAL/Simple_homogeneous.h>
#include <CGAL/Min_circle_2.h>
#include <CGAL/Min_circle_2_traits_2.h>
#include <iostream>
// typedefs
typedef CGAL::Exact_integer RT;
typedef CGAL::Simple_homogeneous<RT> K;
typedef CGAL::Min_circle_2_traits_2<K> Traits;
typedef CGAL::Min_circle_2<Traits> Min_circle;
typedef K::Point_2 Point;
int
main( int, char**)
{
const int n = 100;
Point P[n];
for ( int i = 0; i < n; ++i){
P[i] = Point( (i%2 == 0 ? i : -i), 0, 1);
// (0,0), (-1,0), (2,0), (-3,0), ...
}
Min_circle mc1( P, P+n, false); // very slow
Min_circle mc2( P, P+n, true); // fast
CGAL::set_pretty_mode( std::cout);
std::cout << mc2;
return 0;
}

View File

@ -0,0 +1,38 @@
#include <CGAL/Simple_cartesian.h>
#include <CGAL/Min_sphere_of_points_d_traits_3.h>
#include <CGAL/Min_sphere_of_spheres_d.h>
#include <CGAL/Random.h>
#include <iostream>
#include <cstdlib>
typedef CGAL::Simple_cartesian<double> K;
typedef CGAL::Min_sphere_of_points_d_traits_3<K,double> Traits;
typedef CGAL::Min_sphere_of_spheres_d<Traits> Min_sphere;
typedef K::Point_3 Point;
const int n = 10; // number of points
const int d = 3; // dimension of points
int main ()
{
Point P[n]; // n points
CGAL::Random r; // random number generator
for (int i=0; i<n; ++i) {
for (int j = 0; j < d; ++j) {
P[i] = Point(r.get_double(), r.get_double(), r.get_double()); // random point
}
}
Min_sphere ms(P, P+n); // smallest enclosing sphere
Min_sphere::Cartesian_const_iterator ccib = ms.center_cartesian_begin(), ccie = ms.center_cartesian_end();
std::cout << "center:";
for( ; ccib != ccie; ++ccib){
std::cout << " " << *ccib;
}
std::cout << std::endl << "radius: " << ms.radius() << std::endl;
return 0;
}

View File

@ -1,34 +0,0 @@
#include <CGAL/Cartesian_d.h>
#include <iostream>
#include <cstdlib>
#include <CGAL/Random.h>
#include <CGAL/Min_sphere_annulus_d_traits_d.h>
#include <CGAL/Min_sphere_d.h>
typedef CGAL::Cartesian_d<double> K;
typedef CGAL::Min_sphere_annulus_d_traits_d<K> Traits;
typedef CGAL::Min_sphere_d<Traits> Min_sphere;
typedef K::Point_d Point;
const int n = 10; // number of points
const int d = 5; // dimension of points
int main ()
{
Point P[n]; // n points
double coord[d]; // d coordinates
CGAL::Random r; // random number generator
for (int i=0; i<n; ++i) {
for (int j=0; j<d; ++j)
coord[j] = r.get_double();
P[i] = Point(d, coord, coord+d); // random point
}
Min_sphere ms (P, P+n); // smallest enclosing sphere
CGAL::set_pretty_mode (std::cout);
std::cout << ms; // output the sphere
return 0;
}

View File

@ -0,0 +1,32 @@
#include <CGAL/Exact_integer.h>
#include <CGAL/Homogeneous.h>
#include <CGAL/Random.h>
#include <CGAL/Min_sphere_annulus_d_traits_3.h>
#include <CGAL/Min_sphere_d.h>
#include <iostream>
#include <cstdlib>
typedef CGAL::Homogeneous<CGAL::Exact_integer> K;
typedef CGAL::Min_sphere_annulus_d_traits_3<K> Traits;
typedef CGAL::Min_sphere_d<Traits> Min_sphere;
typedef K::Point_3 Point;
int
main ()
{
const int n = 10; // number of points
Point P[n]; // n points
CGAL::Random r; // random number generator
for (int i=0; i<n; ++i) {
P[i] = Point(r.get_int(0, 1000),r.get_int(0, 1000), r.get_int(0, 1000), 1 );
}
Min_sphere ms (P, P+n); // smallest enclosing sphere
CGAL::set_pretty_mode (std::cout);
std::cout << ms; // output the sphere
return 0;
}

View File

@ -1,6 +1,4 @@
// Computes the minsphere of some random spheres.
// This example illustrates how to use CGAL::Point_2 and CGAL::
// Weighted_point with the Min_sphere_of_spheres_d package.
#include <CGAL/Cartesian.h>
#include <CGAL/Random.h>

View File

@ -1,6 +1,4 @@
// Computes the minsphere of some random spheres.
// This example illustrates how to use CGAL::Point_3 and CGAL::
// Weighted_point with the Min_sphere_of_spheres_d package.
#include <CGAL/Cartesian.h>
#include <CGAL/Random.h>

View File

@ -1,6 +1,4 @@
// Computes the minsphere of some random spheres.
// This example illustrates how to use CGAL::Point_d and CGAL::
// Weighted_point with the Min_sphere_of_spheres_d package.
#include <CGAL/Cartesian_d.h>
#include <CGAL/Random.h>