CGAL 4.13 - 2D Alpha Shapes
User Manual

Assume we are given a set $$S$$ of points in 2D or 3D and we would like to have something like "the shape formed by these points". This is quite a vague notion and there are probably many possible interpretations, the $$\alpha$$-shape being one of them. Alpha shapes can be used for shape reconstruction from a dense unorganized set of data points. Indeed, an $$\alpha$$-shape is demarcated by a frontier, which is a linear approximation of the original shape [1].

As mentioned in Edelsbrunner's and Mücke's paper [2], one can intuitively think of an $$\alpha$$-shape as the following. Imagine a huge mass of ice-cream making up the space $$\mathbb{R}^3$$ and containing the points as "hard" chocolate pieces. Using one of these sphere-formed ice-cream spoons, we carve out all parts of the ice-cream block we can reach without bumping into chocolate pieces, thereby even carving out holes in the inside (e.g. parts not reachable by simply moving the spoon from the outside). We will eventually end up with a (not necessarily convex) object bounded by caps, arcs and points. If we now straighten all "round" faces to triangles and line segments, we have an intuitive description of what is called the $$\alpha$$-shape of $$S$$. The drawing above provides an example of this process in 2D (where our ice-cream spoon is simply a circle).

Alpha shapes depend on a parameter $$\alpha$$ after which they are named. In the ice-cream analogy above, $$\alpha$$ is the squared radius of the carving spoon. A very small value will allow us to eat up all of the ice-cream except the chocolate points themselves. Thus we already see that the $$\alpha$$-shape degenerates to the point-set $$S$$ for $$\alpha \rightarrow 0$$. On the other hand, a huge value of $$\alpha$$ will prevent us even from moving the spoon between two points since it is too large. So we will never spoon up the ice-cream lying in the inside of the convex hull of $$S$$. Hence, the alpha shape becomes the convex hull of $$S$$ as $$\alpha \rightarrow \infty$$.

CGAL offers 2D and 3D alpha shapes. The GUDHI library offers a dD Alpha complex.

# Definitions

We distinguish two versions of alpha shapes. Basic alpha shapes are based on the Delaunay triangulation. Weighted alpha shapes are based on its generalization, the regular triangulation (cf. Section Regular Triangulations), replacing the euclidean distance by the power to weighted points.

There is a close connection between alpha shapes and the underlying triangulations. More precisely, the $$\alpha$$-complex of $$S$$ is a subcomplex of this triangulation of $$S$$, containing the $$\alpha$$-exposed $$k$$-simplices, $$0 \leq k \leq d$$. A simplex is said to be $$\alpha$$-exposed, if there is an open disk (resp. ball) of radius $$\sqrt{\alpha}$$ through the vertices of the simplex that does not contain any other point of $$S$$, for the metric used in the computation of the underlying triangulation. The corresponding $$\alpha$$-shape is defined as the underlying interior space of the $$\alpha$$-complex (see [2]).

In general, an $$\alpha$$-complex is a non-connected and non-pure polytope, meaning that one $$k$$-simplex, with $$0 \leq k \leq d-1$$, is not necessarily adjacent to a $$(k+1)$$-simplex.

The $$\alpha$$-shapes of $$S$$ form a discrete family, even though they are defined for all real numbers $$\alpha$$ with $$0 \leq \alpha \leq \infty$$. Thus, we can represent the entire family of $$\alpha$$-shapes of $$S$$ by the underlying triangulation of $$S$$. In this representation each $$k$$-simplex of the underlying triangulation is associated with an interval that specifies for which values of $$\alpha$$ the $$k$$-simplex belongs to the $$\alpha$$-shape. Relying on this fact, the family of $$\alpha$$-shapes can be computed efficiently and relatively easily. Furthermore, we can select an appropriate $$\alpha$$-shape from a finite number of different $$\alpha$$-shapes and corresponding $$\alpha$$-values.

# Functionality

The class Alpha_shape_2<Dt> represents the family of $$\alpha$$-shapes of points in a plane for all positive $$\alpha$$. It maintains the underlying triangulation Dt which represents connectivity and order among squared radius of its faces. Each $$k$$-dimensional face of the Dt is associated with an interval that specifies for which values of $$\alpha$$ the face belongs to the $$\alpha$$-shape. There are links between the intervals and the $$k$$-dimensional faces of the triangulation.

The class Alpha_shape_2<Dt> provides functions to set and get the current $$\alpha$$-value, as well as an iterator that enumerates the $$\alpha$$-values where the $$\alpha$$-shape changes.

It provides iterators to enumerate the vertices and edges that are in the $$\alpha$$-shape, and functions that allow to classify vertices, edges and faces with respect to the $$\alpha$$-shape. They can be in the interior of a face that belongs or does not belong to the $$\alpha$$-shape. They can be singular/regular, that is be on the boundary of the $$\alpha$$-shape, but not incident/incident to a triangle of the $$\alpha$$-complex.

Finally, it provides a function to determine the $$\alpha$$-value such that the $$\alpha$$-shape satisfies the following two properties, or at least the second one if there is no such $$\alpha$$ that both are satisfied:

1. the number of components equals a number of your choice, and
2. all data points are either on the boundary or in the interior of the regularized version of the $$\alpha$$-shape (no singular edges).

The current implementation is static, that is after its construction points cannot be inserted or removed.

# Concepts and Models

We currently do not specify concepts for the underlying triangulation type. Models that work for a basic alpha shape are the classes Delaunay_triangulation_2, Periodic_2_Delaunay_triangulation_2, and Triangulation_hierarchy_2 templated with a Delaunay triangulation. A model that works for a weighted alpha shape is the class Regular_triangulation_2.

## Alpha Shapes

The triangulation needs a geometric traits class as argument. The requirements of this class are described in the concepts AlphaShapeTraits_2 in the non-weighted case and WeightedAlphaShapeTraits_2 in the weighted case. All CGAL kernels are models of both concepts.

The triangulation data structure of the triangulation has to be a model of the concept TriangulationDataStructure_2, and it must be parameterized with vertex and face classes which are models of the concepts AlphaShapeVertex_2 and AlphaShapeFace_2. The classes Alpha_shape_vertex_base_2<Gt, Vb> and Alpha_shape_face_base_2<Gt, Fb> are models of these concepts and can be used for all type of alpha shapes, provided that the template parameters Vb and Fb are appropriately chosen, as we shall see in the following section.

## Triangulation data structure

Additional requirements are put when using weighted or periodic triangulations as underlying triangulation:

• When using a weighted triangulation (Regular_triangulation_2), the vertex and face classes must respectively be models to both AlphaShapeVertex_2 and RegularTriangulationVertexBase_2, and to both AlphaShapeFace_2 and RegularTriangulationFaceBase_2 (see example: Example for Weighted Alpha Shapes).
• When using a periodic triangulation (Periodic_2_Delaunay_triangulation_2), the vertex and face classes must respectively be models to both AlphaShapeVertex_2 and Periodic_2TriangulationVertexBase_2, and to both AlphaShapeFace_2 and Periodic_2TriangulationFaceBase_2 (see example: Example for Periodic Alpha Shapes).

# Examples

## Example for Basic Alpha Shapes

The basic alpha shape requires a Delaunay triangulation as underlying triangulation Dt. The Delaunay triangulation class is parameterized with a geometric and a triangulation data structure traits.

For the geometric traits class we can use a CGAL kernel.

For the triangulation data structure traits, we have to choose the vertex and face classes needed for alpha shapes, namely Alpha_shape_vertex_base_2<Gt, Vb> and Alpha_shape_face_base_2<Gt,Fb>. The parameter Vb and Fb must be filled by classes that are models of the TriangulationVertexBase_2 and TriangulationFaceBase_2 concepts. The classes Triangulation_vertex_base_2<Gt> and Triangulation_face_base_2<Gt> fit these requirements.

The example below illustrates how to construct a basic alpha shape. Note that Triangulation_vertex_base_2<Gt> and Triangulation_face_base_2<Gt> are the default parameters for Vb and Fb in the classes Alpha_shape_vertex_base_2<Gt, Vb> and Alpha_shape_face_base_2<Gt,Fb>. They are thus omitted in the code below.
File Alpha_shapes_2/ex_alpha_shapes_2.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Alpha_shape_2.h>
#include <CGAL/Alpha_shape_vertex_base_2.h>
#include <CGAL/Alpha_shape_face_base_2.h>
#include <CGAL/Delaunay_triangulation_2.h>
#include <CGAL/algorithm.h>
#include <CGAL/assertions.h>
#include <fstream>
#include <iostream>
#include <list>
#include <vector>
typedef K::FT FT;
typedef K::Point_2 Point;
typedef K::Segment_2 Segment;
typedef CGAL::Triangulation_data_structure_2<Vb,Fb> Tds;
typedef CGAL::Delaunay_triangulation_2<K,Tds> Triangulation_2;
typedef Alpha_shape_2::Alpha_shape_edges_iterator Alpha_shape_edges_iterator;
template <class OutputIterator>
void alpha_edges( const Alpha_shape_2& A, OutputIterator out)
{
Alpha_shape_edges_iterator it = A.alpha_shape_edges_begin(),
end = A.alpha_shape_edges_end();
for( ; it!=end; ++it)
*out++ = A.segment(*it);
}
template <class OutputIterator>
bool file_input(OutputIterator out)
{
std::ifstream is("./data/fin", std::ios::in);
if(is.fail())
{
std::cerr << "unable to open file for input" << std::endl;
return false;
}
int n;
is >> n;
std::cout << "Reading " << n << " points from file" << std::endl;
CGAL::cpp11::copy_n(std::istream_iterator<Point>(is), n, out);
return true;
}
// Reads a list of points and returns a list of segments
// corresponding to the Alpha shape.
int main()
{
std::list<Point> points;
if(! file_input(std::back_inserter(points)))
return -1;
Alpha_shape_2 A(points.begin(), points.end(),
FT(10000),
std::vector<Segment> segments;
alpha_edges(A, std::back_inserter(segments));
std::cout << "Alpha Shape computed" << std::endl;
std::cout << segments.size() << " alpha shape edges" << std::endl;
std::cout << "Optimal alpha: " << *A.find_optimal_alpha(1)<<std::endl;
return 0;
}

## Example for Weighted Alpha Shapes

A weighted alpha shape requires a regular triangulation as underlying triangulation Dt. Here again, we can use the vertex and face Alpha_shape_vertex_base_2<Gt, Vb> and Alpha_shape_face_base_2<Gt,Fb>, but for weighted alpha shapes, Vb and Fb must be models of the concepts RegularTriangulationVertexBase_2 and RegularTriangulationFaceBase_2. The classes Regular_triangulation_vertex_base_2<Gt> Regular_triangulation_face_base_2<Gt> fit these requirements.

Note that there is no special weighted alpha shape class.

The example below illustrates how to construct a weighted alpha shape.
File Alpha_shapes_2/ex_weighted_alpha_shapes_2.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Alpha_shape_2.h>
#include <CGAL/Alpha_shape_face_base_2.h>
#include <CGAL/Alpha_shape_vertex_base_2.h>
#include <CGAL/Regular_triangulation_2.h>
#include <fstream>
#include <iostream>
#include <list>
#include <vector>
typedef K::FT FT;
typedef K::Weighted_point_2 Weighted_point;
typedef K::Segment_2 Segment;
typedef CGAL::Triangulation_data_structure_2<Vb,Fb> Tds;
typedef CGAL::Regular_triangulation_2<K,Tds> Triangulation_2;
typedef Alpha_shape_2::Alpha_shape_edges_iterator Alpha_shape_edges_iterator;
template <class OutputIterator>
void alpha_edges(const Alpha_shape_2& A, OutputIterator out)
{
Alpha_shape_edges_iterator it = A.alpha_shape_edges_begin(),
end = A.alpha_shape_edges_end();
for( ; it!=end; ++it)
*out++ = A.segment(*it);
}
bool file_input(std::list<Weighted_point>& L)
{
std::ifstream is("./data/fin_weighted", std::ios::in);
if(is.fail())
{
std::cerr << "unable to open file for input" << std::endl;
return false;
}
int n;
is >> n;
std::cout << "Reading " << n << " points" << std::endl;
for( ; n>0; n--)
{
Weighted_point wp;
is >> wp;
L.push_back(wp);
}
return true;
}
// Reads a list of points and returns a list of segments corresponding to
// the weighted Alpha Shape.
int main()
{
std::list<Weighted_point> wpoints;
if(!file_input(wpoints))
return -1;
Alpha_shape_2 A(wpoints.begin(), wpoints.end(),
FT(10000),
std::vector<Segment> segments;
alpha_edges(A, std::back_inserter(segments));
std::cout << "Alpha Shape computed" << std::endl;
std::cout << segments.size() << " alpha shape edges" << std::endl;
std::cout << "Optimal alpha: " << *A.find_optimal_alpha(1)<<std::endl;
return 0;
}

## Example for Periodic Alpha Shapes

The following example shows how to use a periodic Delaunay triangulation as underlying triangulation for the alpha shape computation.

In order to define the original domain and to benefit from the built-in heuristic optimizations of the periodic triangulation computation, it is recommended to first construct the triangulation and then construct the alpha shape from it. The alpha shape constructor that takes a point range can be used as well but in this case the original domain cannot be specified and the default unit cube will be chosen and no optimizations will be used.

It is also recommended to switch the triangulation to 1-sheeted covering if possible. Note that a periodic triangulation in 9-sheeted covering space is degenerate. In this case, an exact constructions kernel needs to be used to compute the alpha shapes. Otherwise the results will suffer from round-off problems.

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Periodic_2_Delaunay_triangulation_traits_2.h>
#include <CGAL/Periodic_2_Delaunay_triangulation_2.h>
#include <CGAL/Alpha_shape_2.h>
#include <CGAL/Alpha_shape_face_base_2.h>
#include <CGAL/Alpha_shape_vertex_base_2.h>
#include <fstream>
#include <iostream>
// Traits
// Vertex type
// Cell type
typedef CGAL::Triangulation_data_structure_2<AsVb, AsCb> Tds;
typedef CGAL::Alpha_shape_2<P2DT2> Alpha_shape_2;
typedef Gt::Point_2 Point;
typedef Gt::Segment_2 Segment;
typedef Alpha_shape_2::Alpha_shape_edges_iterator Alpha_shape_edges_iterator;
template <class OutputIterator>
void alpha_edges( const Alpha_shape_2& A, OutputIterator out)
{
Alpha_shape_edges_iterator it = A.alpha_shape_edges_begin(),
end = A.alpha_shape_edges_end();
for( ; it!=end; ++it)
*out++ = A.segment(*it);
}
template <class OutputIterator>
bool file_input(OutputIterator out)
{
std::ifstream is("./data/fin", std::ios::in);
if(is.fail())
{
std::cerr << "unable to open file for input" << std::endl;
return false;
}
int n;
is >> n;
std::cout << "Reading " << n << " points from file" << std::endl;
CGAL::cpp11::copy_n(std::istream_iterator<Point>(is), n, out);
return true;
}
int main()
{
std::list<Point> points;
if(! file_input(std::back_inserter(points)))
return -1;
// Define the periodic square
P2DT2 pdt(Gt::Iso_rectangle_2(-10,-10, 700,700));
// Heuristic for inserting large point sets (if pts is reasonably large)
pdt.insert(points.begin(), points.end(), true);
// As pdt won't be modified anymore switch to 1-sheeted cover if possible
if(pdt.is_triangulation_in_1_sheet())
pdt.convert_to_1_sheeted_covering();
std::cout << "Periodic Delaunay computed." << std::endl;
// compute alpha shape
Alpha_shape_2 as(pdt);
std::cout << "Alpha shape computed in REGULARIZED mode by default." << std::endl;
// find optimal alpha values
Alpha_shape_2::NT alpha_solid = as.find_alpha_solid();
Alpha_shape_2::Alpha_iterator opt = as.find_optimal_alpha(1);
std::cout << "Smallest alpha value to get a solid through data points is " << alpha_solid << std::endl;
std::cout << "Optimal alpha value to get one connected component is " << *opt << std::endl;
as.set_alpha(*opt);
assert(as.number_of_solid_components() == 1);
as.set_alpha(10000);
std::vector<Segment> segments;
alpha_edges(as, std::back_inserter(segments));
std::cout << segments.size() << " alpha shape edges" << std::endl;
return 0;
}