diff --git a/Convex_hull_3/doc/Convex_hull_3/CGAL/Convex_hull_traits_3.h b/Convex_hull_3/doc/Convex_hull_3/CGAL/Convex_hull_traits_3.h index 079689ad919..2009e5808df 100644 --- a/Convex_hull_3/doc/Convex_hull_3/CGAL/Convex_hull_traits_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/CGAL/Convex_hull_traits_3.h @@ -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 diff --git a/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_3.h b/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_3.h index 797893e6dc5..6037e156bb2 100644 --- a/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_3.h @@ -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: -
    -
  1. `InputIterator::value_type` is equivalent to `Traits::Point_3`. -
  2. `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`. -
+\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: - -and for the second, it is required that - -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`, and `R` otherwise. +then the default traits class of `::convex_hull_3()` is `Convex_hull_traits_3`, and `R` otherwise. -\sa `CGAL::convex_hull_incremental_3` +\sa `CGAL::convex_hull_incremental_3()` ### Implementation ### @@ -57,7 +44,7 @@ Barnard et al. \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`, and `R` otherwise. */ diff --git a/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_incremental_3.h b/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_incremental_3.h index 67d4e236952..e9680123bd5 100644 --- a/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_incremental_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/CGAL/convex_hull_incremental_3.h @@ -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 ### - -
    -
  1. `Polyhedron` must provide a type `Polyhedron::Traits` +\requires `Polyhedron` must provide a type `Polyhedron::Traits` that defines the following types -
      -
    • `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` -
    • `Polyhedron::Traits::Point` -
    -
  2. `InputIterator::value_type` must be the same as -`Polyhedron::Traits::Point` -
+- `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 ### diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronFacet_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronFacet_3.h index d991b0714ae..0b7e9aa4b83 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronFacet_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronFacet_3.h @@ -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` +\sa `CGAL::Polyhedron_3` \sa `ConvexHullPolyhedronVertex_3` \sa `ConvexHullPolyhedronHalfedge_3` diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronHalfedge_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronHalfedge_3.h index 7dc899cbc58..708d0c68df1 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronHalfedge_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronHalfedge_3.h @@ -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` +\sa `CGAL::Polyhedron_3` \sa `ConvexHullPolyhedronVertex_3` \sa `ConvexHullPolyhedronFacet_3` diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronVertex_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronVertex_3.h index 5c94d20c253..8d2388df68c 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronVertex_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedronVertex_3.h @@ -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` +\sa `CGAL::Polyhedron_3` \sa `ConvexHullPolyhedronFacet_3` \sa `ConvexHullPolyhedronHalfedge_3` diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedron_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedron_3.h index 82b3fe47ac5..9b723a38342 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedron_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullPolyhedron_3.h @@ -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` +\hasModel `CGAL::Polyhedron_3` */ class ConvexHullPolyhedron_3 { diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullTraits_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullTraits_3.h index cfceab889f7..ac8639a5aa6 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullTraits_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullTraits_3.h @@ -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` -\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; diff --git a/Convex_hull_3/doc/Convex_hull_3/Concepts/IsStronglyConvexTraits_3.h b/Convex_hull_3/doc/Convex_hull_3/Concepts/IsStronglyConvexTraits_3.h index 967c4ae83cb..6b0d59848fa 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Concepts/IsStronglyConvexTraits_3.h +++ b/Convex_hull_3/doc/Convex_hull_3/Concepts/IsStronglyConvexTraits_3.h @@ -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` -\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; diff --git a/Convex_hull_3/doc/Convex_hull_3/Convex_hull_3.txt b/Convex_hull_3/doc/Convex_hull_3/Convex_hull_3.txt index 09cf9764e6d..e14798ed7e5 100644 --- a/Convex_hull_3/doc/Convex_hull_3/Convex_hull_3.txt +++ b/Convex_hull_3/doc/Convex_hull_3/Convex_hull_3.txt @@ -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 et al. \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` 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` in three dimensions (e.g., 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` 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. diff --git a/Convex_hull_3/doc/Convex_hull_3/PackageDescription.txt b/Convex_hull_3/doc/Convex_hull_3/PackageDescription.txt index 89bdddb27a8..ad9a346ada0 100644 --- a/Convex_hull_3/doc/Convex_hull_3/PackageDescription.txt +++ b/Convex_hull_3/doc/Convex_hull_3/PackageDescription.txt @@ -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}