mirror of https://github.com/CGAL/cgal
finished (modulo Default_traits)
This commit is contained in:
Andreas Fabri
parent
650dda74c3
commit
d6ad28c6bd
|
|
@ -4,9 +4,9 @@ namespace CGAL {
|
|||
\ingroup PkgConvexHull3Traits
|
||||
|
||||
The class `Convex_hull_traits_3` serves as a traits class for the function
|
||||
`CGAL::convex_hull_3`. This is the default traits class for this
|
||||
`convex_hull_3()`. This is the default traits class for this
|
||||
function when `R` is a kernel with exact predicates but inexact constructions
|
||||
(note below that the type `Plane_3` is a triple of `Point_3` and not `R::Plane_3`).
|
||||
(note that the type `Plane_3` is a triple of `Point_3` and not `R::Plane_3`).
|
||||
|
||||
\models ::ConvexHullTraits_3
|
||||
\models ::IsStronglyConvexTraits_3
|
||||
|
|
|
|||
|
|
@ -5,47 +5,34 @@ namespace CGAL {
|
|||
|
||||
\brief computes the convex hull of the set of points in the range
|
||||
[`first`, `last`). The polyhedron `P` is cleared, then
|
||||
the convex hull is stored in `P`
|
||||
and the plane equations of each face are not computed.
|
||||
the convex hull is stored in `P`.
|
||||
|
||||
\attention This function does not compute the plane equations of the faces of `P`.
|
||||
|
||||
\pre There are at least four points in the range
|
||||
[`first`, `last`) not all of which are collinear.
|
||||
|
||||
The function `::convex_hull_3` computes the convex hull of a given set of
|
||||
The function `::convex_hull_3()` computes the convex hull of a given set of
|
||||
three-dimensional points
|
||||
Two versions of this function
|
||||
are available. The first can be used when it is known that the result
|
||||
will be a polyhedron and the second when a degenerate hull
|
||||
may also be possible.
|
||||
|
||||
### Requirements ###
|
||||
|
||||
Both functions require the following:
|
||||
<OL>
|
||||
<LI>`InputIterator::value_type` is equivalent to `Traits::Point_3`.
|
||||
<LI>`Traits` is a model of the concept `ConvexHullTraits_3`
|
||||
c.
|
||||
\requires `InputIterator::value_type` is equivalent to `Traits::Point_3`.
|
||||
\requires `Traits` is a model of the concept `ConvexHullTraits_3`.
|
||||
For the purposes of checking the postcondition that the convex hull
|
||||
is valid, `Traits` should also be a model of the concept
|
||||
`IsStronglyConvexTraits_3`.
|
||||
</OL>
|
||||
\requires `Polyhedron_3` is a model of `ConvexHullPolyhedron_3`.
|
||||
|
||||
Both functions have an additional requirement for the polyhedron that is
|
||||
to be constructed. For the first version this is that:
|
||||
<UL>
|
||||
<LI>`Polyhedron_3` is a model of `ConvexHullPolyhedron_3`,
|
||||
</UL>
|
||||
and for the second, it is required that
|
||||
<UL>
|
||||
<LI>`Traits` defines a type `Polyhedron_3` that is a model of
|
||||
`ConvexHullPolyhedron_3`.
|
||||
</UL>
|
||||
|
||||
For both versions, if the kernel `R` of the points determined by `InputIterator::value_type`
|
||||
If the kernel `R` of the points determined by `InputIterator::value_type`
|
||||
is a kernel with exact predicates but inexact constructions
|
||||
(in practice we check `R::Has_filtered_predicates_tag` is `Tag_true` and `R::FT` is a floating point type),
|
||||
then the default traits class of `::convex_hull_3` is `Convex_hull_traits_3<R>`, and `R` otherwise.
|
||||
then the default traits class of `::convex_hull_3()` is `Convex_hull_traits_3<R>`, and `R` otherwise.
|
||||
|
||||
\sa `CGAL::convex_hull_incremental_3`
|
||||
\sa `CGAL::convex_hull_incremental_3()`
|
||||
|
||||
### Implementation ###
|
||||
|
||||
|
|
@ -57,7 +44,7 @@ Barnard <I>et al.</I> \cite bdh-qach-96.
|
|||
The following program computes the convex hull of a set of 250 random
|
||||
points chosen from a sphere of radius 100. It then determines if the resulting
|
||||
hull is a segment or a polyhedron. Notice that the traits class is not
|
||||
necessary in the call to `::convex_hull_3` but is used in the definition
|
||||
necessary in the call to `::convex_hull_3()` but is used in the definition
|
||||
of `Polyhedron_3`.
|
||||
|
||||
\cgalexample{Convex_hull_3/quickhull_3.cpp}
|
||||
|
|
@ -72,8 +59,23 @@ void convex_hull_3(InputIterator first, InputIterator last, Polyhedron_3& P, con
|
|||
|
||||
\brief computes the convex hull of the set of points in the range
|
||||
[`first`, `last`). The result, which may be a point, a segment,
|
||||
a triangle, or a polyhedron, is stored in `ch_object`. When
|
||||
the result is a polyhedron, the plane equations of each face are not computed.
|
||||
a triangle, or a polyhedron, is stored in `ch_object`.
|
||||
|
||||
\attention This function does not compute the plane equations of the faces of `P`
|
||||
in case the result is a polyhedron.
|
||||
|
||||
\requires `InputIterator::value_type` is equivalent to `Traits::Point_3`.
|
||||
\requires `Traits` is a model of the concept `ConvexHullTraits_3`.
|
||||
For the purposes of checking the postcondition that the convex hull
|
||||
is valid, `Traits` should also be a model of the concept
|
||||
`IsStronglyConvexTraits_3`.
|
||||
\requires `Traits` defines a type `Polyhedron_3` that is a model of
|
||||
`ConvexHullPolyhedron_3`.
|
||||
|
||||
If the kernel `R` of the points determined by `InputIterator::value_type`
|
||||
is a kernel with exact predicates but inexact constructions
|
||||
(in practice we check `R::Has_filtered_predicates_tag` is `Tag_true` and `R::FT` is a floating point type),
|
||||
then the default traits class of `::convex_hull_3()` is `Convex_hull_traits_3<R>`, and `R` otherwise.
|
||||
|
||||
*/
|
||||
|
||||
|
|
|
|||
|
|
@ -10,27 +10,22 @@ and assigns it to `P`. If `test_correctness` is set to
|
|||
used to determine the correctness of the resulting polyhedron.
|
||||
|
||||
|
||||
This function is provided for completeness and educational
|
||||
\attention This function is provided for completeness and educational
|
||||
purposes. When an efficient incremental implementation is needed,
|
||||
using `CGAL::Delaunay_triangulation_3` together with
|
||||
`CGAL::convex_hull_3_to_polyhedron_3` is highly recommended.
|
||||
|
||||
### Requirements ###
|
||||
|
||||
<OL>
|
||||
<LI>`Polyhedron` must provide a type `Polyhedron::Traits`
|
||||
\requires `Polyhedron` must provide a type `Polyhedron::Traits`
|
||||
that defines the following types
|
||||
<UL>
|
||||
<LI>`Polyhedron::Traits::R`, which is a model of
|
||||
- `Polyhedron::Traits::R`, which is a model of
|
||||
the representation class `R` required by
|
||||
`CGAL::Convex_hull_d_traits_3<R>`
|
||||
<LI>`Polyhedron::Traits::Point`
|
||||
</UL>
|
||||
<LI>`InputIterator::value_type` must be the same as
|
||||
`Polyhedron::Traits::Point`
|
||||
</OL>
|
||||
- `Polyhedron::Traits::Point`
|
||||
\requires `InputIterator::value_type` must be the same as
|
||||
`Polyhedron::Traits::Point`.
|
||||
|
||||
\sa `CGAL::convex_hull_3`
|
||||
|
||||
\sa `CGAL::convex_hull_3()`
|
||||
|
||||
### Implementation ###
|
||||
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
\ingroup PkgConvexHull3Concepts
|
||||
\cgalconcept
|
||||
|
||||
The requirements of the facet type of a polyhedron to be built by the
|
||||
function `CGAL::convex_hull_3`.
|
||||
Requirements of the facet type of a polyhedron built by the
|
||||
function `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel `CGAL::Polyhedron_3::Facet`
|
||||
|
||||
\sa `CGAL::Polyhedron_3<Traits>`
|
||||
\sa `CGAL::Polyhedron_3`
|
||||
\sa `ConvexHullPolyhedronVertex_3`
|
||||
\sa `ConvexHullPolyhedronHalfedge_3`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
\ingroup PkgConvexHull3Concepts
|
||||
\cgalconcept
|
||||
|
||||
The requirements of the halfedge type required for the polyhedron built
|
||||
by the function `CGAL::convex_hull_3`.
|
||||
Requirements of the halfedge type required for the polyhedron built
|
||||
by the function `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel CGAL::Polyhedron_3::Halfedge
|
||||
|
||||
\sa `CGAL::Polyhedron_3<Traits>`
|
||||
\sa `CGAL::Polyhedron_3`
|
||||
\sa `ConvexHullPolyhedronVertex_3`
|
||||
\sa `ConvexHullPolyhedronFacet_3`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
\ingroup PkgConvexHull3Concepts
|
||||
\cgalconcept
|
||||
|
||||
The requirements of the vertex type of the polyhedron to be built by the
|
||||
function `CGAL::convex_hull_3`.
|
||||
Requirements of the vertex type of the polyhedron built by the
|
||||
function `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel CGAL::Polyhedron_3::Vertex
|
||||
|
||||
\sa `CGAL::Polyhedron_3<Traits>`
|
||||
\sa `CGAL::Polyhedron_3`
|
||||
\sa `ConvexHullPolyhedronFacet_3`
|
||||
\sa `ConvexHullPolyhedronHalfedge_3`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
\ingroup PkgConvexHull3Concepts
|
||||
\cgalconcept
|
||||
|
||||
The requirements of the polyhedron type to be built by the
|
||||
function `CGAL::convex_hull_3`.
|
||||
Requirements of the polyhedron type built by the
|
||||
function `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel `CGAL::Polyhedron_3<Traits>`
|
||||
\hasModel `CGAL::Polyhedron_3`
|
||||
|
||||
*/
|
||||
class ConvexHullPolyhedron_3 {
|
||||
|
|
|
|||
|
|
@ -2,11 +2,10 @@
|
|||
\ingroup PkgConvexHull3Concepts
|
||||
\cgalconcept
|
||||
|
||||
Requirements of the traits class to be used with the function
|
||||
`CGAL::convex_hull_3`.
|
||||
Requirements of the traits class of the function `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel `CGAL::Convex_hull_traits_3<R>`
|
||||
\hasModel All kernels of CGAL
|
||||
\hasModel `CGAL::Convex_hull_traits_3`
|
||||
\hasModel All models of `Kernel`
|
||||
|
||||
*/
|
||||
class ConvexHullTraits_3 {
|
||||
|
|
@ -59,43 +58,42 @@ typedef Hidden_type Construct_segment_3;
|
|||
Function object type that provides
|
||||
`Triangle_3 operator()(Point_3 p, Point_3 q, Point_3 r)`, which
|
||||
constructs and returns the triangle with vertices `p`, `q`, and
|
||||
`r`
|
||||
`r`.
|
||||
*/
|
||||
typedef Hidden_type Construct_triangle_3;
|
||||
|
||||
/*!
|
||||
Function object type that provides
|
||||
`Vector_3 operator()(Point_3 p, Point_3 q)`, which constructs and
|
||||
returns the vector `q`-`p`
|
||||
returns the vector `q`-`p`.
|
||||
*/
|
||||
typedef Hidden_type Construct_vector_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Point_3 p, Point_3 q)`, which determines
|
||||
if points `p` and `q` are equal or not
|
||||
if points `p` and `q` are equal.
|
||||
*/
|
||||
typedef Hidden_type Equal_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Point_3 p, Point_3 q, Point_3 r)`, which determines
|
||||
if points `p`, `q` and `r` are collinear or not
|
||||
if points `p`, `q` and `r` are collinear.
|
||||
*/
|
||||
typedef Hidden_type Collinear_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Point_3 p, Point_3 q, Point_3 r, Point_3 s)`, which
|
||||
determines if points `p`, `q`, `r`, and `s` are coplanar
|
||||
or not
|
||||
determines if points `p`, `q`, `r`, and `s` are coplanar.
|
||||
*/
|
||||
typedef Hidden_type Coplanar_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Plane_3 h, Point_3 q)`, which determines of the point
|
||||
`q` is on the positive side of the halfspace `h`
|
||||
`bool operator()(Plane_3 h, Point_3 q)`, which determines if the point
|
||||
`q` is on the positive side of the halfspace `h`.
|
||||
*/
|
||||
typedef Hidden_type Has_on_positive_side_3;
|
||||
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@
|
|||
\cgalconcept
|
||||
|
||||
Requirements of the traits class used by the function
|
||||
`CGAL::is_strongly_convex_3`, which is used for postcondition checking
|
||||
by `CGAL::convex_hull_3`.
|
||||
`CGAL::is_strongly_convex_3()`, which is used for postcondition checking
|
||||
by `CGAL::convex_hull_3()`.
|
||||
|
||||
\hasModel `CGAL::Convex_hull_traits_3<R>`
|
||||
\hasModel All kernels of CGAL
|
||||
\hasModel All models of `Kernel`
|
||||
|
||||
\sa `ConvexHullTraits_3`
|
||||
\sa `CGAL::is_strongly_convex_3`
|
||||
|
|
@ -43,7 +43,7 @@ typedef Hidden_type Triangle_3;
|
|||
/*!
|
||||
Function object type that provides
|
||||
`Ray_3 operator()(Point_3 p, Point_3 q)`, which constructs and returns
|
||||
the ray based at point `p` and passing though `q`
|
||||
the ray based at point `p` and passing though `q`.
|
||||
*/
|
||||
typedef Hidden_type Construct_ray_3;
|
||||
|
||||
|
|
@ -51,37 +51,35 @@ typedef Hidden_type Construct_ray_3;
|
|||
Function object type that provides
|
||||
`Triangle_3 operator()(Point_3 p, Point_3 q, Point_3 r)`, which
|
||||
constructs and returns the triangle with vertices `p`, `q`, and
|
||||
`r`
|
||||
`r`.
|
||||
*/
|
||||
typedef Hidden_type Construct_triangle_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Point_3 p, Point_3 q, Point_3 r, Point_3 s)`, which
|
||||
determines if points `p`, `q`, `r`, and `s` are coplanar
|
||||
or not
|
||||
determines if points `p`, `q`, `r`, and `s` are coplanar.
|
||||
*/
|
||||
typedef Hidden_type Coplanar_3;
|
||||
|
||||
/*!
|
||||
Function object type that provides
|
||||
`CGAL::Object operator()(Triangle_3 t, Ray_3 r)`, which
|
||||
returns `true` iff `t` and
|
||||
`r` intersect.
|
||||
returns `true` iff `t` and `r` intersect.
|
||||
*/
|
||||
typedef Hidden_type Do_intersect_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`bool operator()(Plane_3 h, Point_3 q)`, which determines of the point
|
||||
`q` is on the positive side of the halfspace `h`
|
||||
`q` is on the positive side of the halfspace `h`.
|
||||
*/
|
||||
typedef Hidden_type Has_on_positive_side_3;
|
||||
|
||||
/*!
|
||||
Predicate object type that provides
|
||||
`Oriented_side operator()(Plane_3 p, Point_3 q)`, which determines
|
||||
the position of point `q` relative to plane `p`
|
||||
the position of point `q` relative to plane `p`.
|
||||
*/
|
||||
typedef Hidden_type Oriented_side_3;
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ triangulation to get a fully dynamic computation.
|
|||
# Static Convex Hull Construction # {#secconvex_hull_3}
|
||||
|
||||
The function
|
||||
`::convex_hull_3` provides an
|
||||
`::convex_hull_3()` provides an
|
||||
implementation of the quickhull algorithm \cite bdh-qach-96 for three
|
||||
dimensionsquickhull, 3D. There are two versions of this
|
||||
function available, one that can be used when it is known that the output
|
||||
|
|
@ -48,7 +48,7 @@ computing the hull.
|
|||
|
||||
## Traits Class ##
|
||||
|
||||
The function `::convex_hull_3` is parameterized by a traits class,
|
||||
The function `::convex_hull_3()` is parameterized by a traits class,
|
||||
which specifies the types and geometric primitives to be used in the
|
||||
computation. If input points from a kernel with exact predicates
|
||||
and non-exact constructions are used, and a certified result is expected,
|
||||
|
|
@ -58,11 +58,11 @@ account.
|
|||
|
||||
## Convexity Checking ##
|
||||
|
||||
The function `::is_strongly_convex_3`
|
||||
The function `::is_strongly_convex_3()`
|
||||
implements the algorithm of Mehlhorn <I>et al.</I> \cite mnssssu-cgpvg-96
|
||||
to determine if the vertices of a given polytope constitute a strongly convex
|
||||
point set or not. This function is used in postcondition testing for
|
||||
`::convex_hull_3`.
|
||||
`::convex_hull_3()`.
|
||||
|
||||
## Example ##
|
||||
|
||||
|
|
@ -70,15 +70,15 @@ The following program computes the convex hull of a set of 250 random
|
|||
points chosen from a sphere of radius 100. We assume that the points are
|
||||
not all identical and not all collinear, thus we directly use a polyhedron
|
||||
as output. Note the usage of the functor `Plane_from_facet` together with
|
||||
`std::transform` to compute the equations of the plane of each facet
|
||||
`std::transform()` to compute the equations of the plane of each facet
|
||||
of the convex hull.
|
||||
|
||||
\cgalexample{Convex_hull_3/quickhull_3.cpp}
|
||||
|
||||
# Incremental Convex Hull Construction # {#Convex_hull_3Incremental}
|
||||
|
||||
The function `::convex_hull_incremental_3` provides an
|
||||
interface similar to `::convex_hull_3` for the \f$ d\f$-dimensional
|
||||
The function `::convex_hull_incremental_3()` provides an
|
||||
interface similar to `::convex_hull_3()` for the `d`-dimensional
|
||||
incremental construction algorithm \cite cms-frric-93
|
||||
implemented by the class `Convex_hull_d<R>` that is specialized
|
||||
to three dimensions. This function accepts an iterator range over a set of
|
||||
|
|
@ -94,7 +94,7 @@ of the general d-dimension). The incremental version is provided for
|
|||
completeness and educational purposes. You should use the dynamic
|
||||
version when you need an efficient incremental convex hull algorithm.
|
||||
|
||||
To use the full functionality available with the \f$ d\f$-dimensional class
|
||||
To use the full functionality available with the `d`-dimensional class
|
||||
`Convex_hull_d<R>` in three dimensions (<I>e.g.</I>, the ability
|
||||
to insert new points and to query if a point lies in the convex hull or not),
|
||||
you can instantiate the class `Convex_hull_d<K>` with the adapter
|
||||
|
|
@ -127,10 +127,10 @@ not all of them are vertices of the hull.
|
|||
# Performance # {#Convex_hull_3Performance}
|
||||
|
||||
In the following, we compare the running times of the three approaches to compute 3D convex hulls.
|
||||
For the static version (using `::convex_hull_3`) and the dynamic version
|
||||
(using `Delaunay_triangulation_3` and `::convex_hull_3_to_polyhedron_3`), the kernel
|
||||
For the static version (using `::convex_hull_3()`) and the dynamic version
|
||||
(using `Delaunay_triangulation_3` and `::convex_hull_3_to_polyhedron_3()`), the kernel
|
||||
used was `Exact_predicates_inexact_constructions_kernel`. For the incremental version
|
||||
(using `::convex_hull_incremental_3`), the kernel used was `Exact_predicates_exact_constructions_kernel`.
|
||||
(using `::convex_hull_incremental_3()`), the kernel used was `Exact_predicates_exact_constructions_kernel`.
|
||||
|
||||
To compute the convex hull of a million of random points in a unit ball the static approach needed 1.63s, while
|
||||
the dynamic and incremental approaches needed 9.50s and 11.54s respectively.
|
||||
|
|
|
|||
|
|
@ -14,13 +14,14 @@
|
|||
|
||||
/*!
|
||||
\addtogroup PkgConvexHull3
|
||||
\todo check generated documentation
|
||||
\todo fix or keep the `Default_traits`
|
||||
|
||||
\PkgDescriptionBegin{3D Convex Hulls,PkgConvexHull3Summary}
|
||||
\PkgPicture{Convex_hull_3/fig/bunny.png}
|
||||
\PkgAuthors{Susan Hert and Stefan Schirra}
|
||||
\PkgDesc{This package provides functions for computing convex hulls in three dimensions as well as functions for checking if sets of points are strongly convex or not. One can compute the convex hull of a set of points in three dimensions in one of three ways: using a static algorithm, using an incremental construction algorithm, or using a triangulation to get a fully dynamic computation.}
|
||||
\PkgSince{1.1}
|
||||
\PkgDependsOn{All algorithms produce as output a \ref PkgPolyhedronSummary. The dynamic algorithms depend on \ref PkgTriangulation3Summary.}
|
||||
\PkgDependsOn{All algorithms produce as output a \ref PkgPolyhedronSummary "Polyhedron". The dynamic algorithms depend on \ref PkgTriangulation3Summary.} "3D Triangulations".
|
||||
\PkgBib{cgal:hs-ch3}
|
||||
\PkgLicense{\ref licensesGPL "GPL"}
|
||||
\PkgDemo{See Polyhedral Surface,polyhedron_3.zip}
|
||||
|
|
|
|||
Loading…
Reference in New Issue