User Manual

Authors

Susan Hert and Stefan Schirra

Figure 13.1 The convex hull of a model made of 192135 points.

Introduction

A subset \( S \subseteq \mathbb{R}^3\) is convex if for any two points \( p\) and \( q\) in the set the line segment with endpoints \( p\) and \( q\) is contained in \( S\). The convex hull of a set \( S\) is the smallest convex set containing \( S\). The convex hull of a set of points \( P \in \mathbb{R}^3\) is a convex polytope with vertices in \( P\). A point in \( P\) is an extreme point (with respect to \( P\)) if it is a vertex of the convex hull of \( P\). A set of points is said to be strongly convex if it consists of only extreme points.

This chapter describes the functions provided in CGAL for producing convex hulls in three dimensions as well as functions for checking if sets of points are strongly convex are not. One can compute the convex hull of a set of points in three dimensions in two ways in CGAL: using a static algorithm or using a triangulation to get a fully dynamic computation.

Static Convex Hull Construction

The function convex_hull_3() provides an implementation of the quickhull algorithm [1] for three dimensionsquickhull, 3D. There are two versions of this function available, one that can be used when it is known that the output will be a polyhedron (i.e., there are more than three points and they are not all collinear) and one that handles all degenerate cases and returns an Object, which may be a point, a segment, a triangle, or a polyhedron. Both versions accept a range of input iterators defining the set of points whose convex hull is to be computed and a traits class defining the geometric types and predicates used in computing the hull.

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, the traits Convex_hull_traits_3<R> should be used (R being the input kernel). Note that the default traits class takes this into account.

Convexity Checking

The function is_strongly_convex_3() implements the algorithm of Mehlhorn et al. [3] 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().

Halfspace Intersection

The functions halfspace_intersection_3() and halfspace_intersection_with_constructions_3() uses the convex hull algorithm and the duality to compute the intersection of a list of halfspaces. The first version does not explicitly computes the dual points: the traits class handles this issue. The second one constructs these points and hence is less robust but the computation is faster.

In order to compute, the intersection an interior point is needed. It could be either given by the user or computed using linear programming. Notice that the second approach is slower due to the resolution of a linear program.

The following program computes the intersection of halfspaces defined by tangent planes to a sphere:

File Convex_hull_3/halfspace_intersection_3.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Convex_hull_3/dual/halfspace_intersection_3.h>
#include <CGAL/point_generators_3.h>

#include <list>

typedef CGAL::Exact_predicates_inexact_constructions_kernel   K;
typedef K::Plane_3                                            Plane;
typedef K::Point_3                                            Point;
typedef CGAL::Polyhedron_3<K>                                 Polyhedron_3;

// compute the tangent plane of a point
template <typename K>
typename K::Plane_3 tangent_plane (typename K::Point_3 const& p) {
    typename K::Vector_3 v(p.x(), p.y(), p.z());
    v = v / sqrt(v.squared_length());
    typename K::Plane_3 plane(v.x(), v.y(), v.z(), -(p - CGAL::ORIGIN) * v);

    return plane;
}

int main (void) {
    // number of generated planes
    int N = 200;

    // generates random planes on a sphere
    std::list<Plane> planes;
    CGAL::Random_points_on_sphere_3<Point> g;
    for (int i = 0; i < N; i++) {
        planes.push_back(tangent_plane<K>(*g++));
    }

    // define polyhedron to hold the intersection
    Polyhedron_3 P;

    // compute the intersection
    // if a point inside the intersection is unknown, pass boost::none
    // to automatically found one using linear programming
    CGAL::halfspace_intersection_3(planes.begin(),
                                   planes.end(),
                                   P,
                                   Point(0, 0, 0));

    return 0;
}

Example

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 of the convex hull.

File Convex_hull_3/quickhull_3.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/point_generators_3.h>
#include <CGAL/algorithm.h>
#include <CGAL/Polyhedron_3.h>
#include <CGAL/convex_hull_3.h>
#include <vector>


typedef CGAL::Exact_predicates_inexact_constructions_kernel  K;
typedef CGAL::Polyhedron_3<K>                     Polyhedron_3;
typedef K::Segment_3                              Segment_3;

// define point creator
typedef K::Point_3                                Point_3;
typedef CGAL::Creator_uniform_3<double, Point_3>  PointCreator;

//a functor computing the plane containing a triangular facet
struct Plane_from_facet {
  Polyhedron_3::Plane_3 operator()(Polyhedron_3::Facet& f) {
      Polyhedron_3::Halfedge_handle h = f.halfedge();
      return Polyhedron_3::Plane_3( h->vertex()->point(),
                                    h->next()->vertex()->point(),
                                    h->opposite()->vertex()->point());
  }
};


int main()
{
  CGAL::Random_points_in_sphere_3<Point_3, PointCreator> gen(100.0);

  // generate 250 points randomly on a sphere of radius 100.0
  // and copy them to a vector
  std::vector<Point_3> points;
  CGAL::cpp11::copy_n( gen, 250, std::back_inserter(points) );

  // define polyhedron to hold convex hull
  Polyhedron_3 poly;
  
  // compute convex hull of non-collinear points
  CGAL::convex_hull_3(points.begin(), points.end(), poly);

  std::cout << "The convex hull contains " << poly.size_of_vertices() << " vertices" << std::endl;
  
  // assign a plane equation to each polyhedron facet using functor Plane_from_facet
  std::transform( poly.facets_begin(), poly.facets_end(), poly.planes_begin(),Plane_from_facet());


  return 0;
}

Dynamic Convex Hull Construction

Fully dynamic maintenance of a convex hull can be achieved by using the class Delaunay_triangulation_3. This class supports insertion and removal of points (i.e., vertices of the triangulation) and the convex hull edges are simply the finite edges of infinite faces. The following example illustrates the dynamic construction of a convex hull. First, random points from a sphere of a certain radius are generated and are inserted into a triangulation. Then the number of points of the convex hull are obtained by counting the number of triangulation vertices incident to the infinite vertex. Some of the points are removed and then the number of points remaining on the hull are determined. Notice that the vertices incident to the infinite vertex of the triangulation are on the convex hull but it may be that not all of them are vertices of the hull.

Example

File Convex_hull_3/dynamic_hull_3.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/point_generators_3.h>
#include <CGAL/Delaunay_triangulation_3.h>
#include <CGAL/Polyhedron_3.h>
#include <CGAL/convex_hull_3_to_polyhedron_3.h>
#include <CGAL/algorithm.h>

#include <list>

typedef CGAL::Exact_predicates_inexact_constructions_kernel      K;
typedef K::Point_3                                              Point_3;
typedef CGAL::Delaunay_triangulation_3<K>                       Delaunay;
typedef Delaunay::Vertex_handle                                 Vertex_handle;
typedef CGAL::Polyhedron_3<K>                                   Polyhedron_3;

int main()
{
  CGAL::Random_points_in_sphere_3<Point_3> gen(100.0);
  std::list<Point_3>   points;

  // generate 250 points randomly on a sphere of radius 100.0
  // and insert them into the triangulation
  CGAL::cpp11::copy_n(gen, 250, std::back_inserter(points) );
  Delaunay T;
  T.insert(points.begin(), points.end());

  std::list<Vertex_handle>  vertices;
  T.incident_vertices(T.infinite_vertex(), std::back_inserter(vertices));
  std::cout << "This convex hull of the 250 points has "
            << vertices.size() << " points on it." << std::endl;

  // remove 25 of the input points
  std::list<Vertex_handle>::iterator v_set_it = vertices.begin();
  for (int i = 0; i < 25; i++)
  {
     T.remove(*v_set_it);
     v_set_it++;
  }

  //copy the convex hull of points into a polyhedron and use it
  //to get the number of points on the convex hull
  Polyhedron_3 chull;
  CGAL::convex_hull_3_to_polyhedron_3(T,chull);
  
  std::cout << "After removal of 25 points, there are "
            << chull.size_of_vertices() << " points on the convex hull." << std::endl;
  

  
  return 0;
}

Performance

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 used was Exact_predicates_inexact_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 approach needed 9.50s. To compute the convex hull of the model of Figure 13.1 featuring 192135 points, the static approach needed 0.18s, while the dynamic approach needed 1.90s.

The measurements have been performed using CGAL 3.9, using the Gnu C++ compiler version 4.3.5, under Linux (Debian distribution), with the compilation options -O3 -DCGAL_NDEBUG. The computer used was equipped with a 64bit Intel Xeon 2.27GHz processor and 12GB of RAM.