CGAL 4.7  3D Periodic Triangulations

The periodic 3Dtriangulation class of CGAL is designed to represent the triangulations of a set of points in the threedimensional flat torus. The triangulation forms a partition of the space it is computed in. It is a simplicial complex, i.e. it contains all incident \( j\)simplices ( \( j<k\)) of any \( k\)simplex and two \( k\)simplices either do not intersect or share a common \( j\)face, \( j<k\). The occurring simplices of dimension up to three are called vertex, edge, facet, and cell, respectively.
The 3D Periodic Triangulation package computes triangulations in the space \( \mathbb T_c^3\), which is defined as follows: Let \( c\in\mathbb R\setminus\{0\}\) and \( G\) be the group \( (c\cdot\mathbb Z^3, +)\), where \( c\cdot\mathbb Z\) denotes the set containing all integer multiples of \( c\). The flat torus is the quotient space: \( \mathbb T_c^3:=\mathbb R^3/G\). The parameter \( c\) defines the period.
The elements of \( \mathbb T_c^3\) are the equivalence classes of sets of points in \( \mathbb R^3\). We call these points representatives of an element of \( \mathbb T_c^3\). The implementation works not directly on elements of \( \mathbb T_c^3\) but on some representatives in \( \mathbb R^3\). So there need to be distinguished representatives to work on. Given \( \alpha\), \( \beta\), and \( \gamma\), the cube \( [\alpha,\alpha+c)\times[\beta,\beta+c)\times[\gamma,\gamma+c)\) contains exactly one representative of each element in \( \mathbb T_c^3\). We call it original domain. From now on, when we talk about points, we generally mean representatives of elements of \( \mathbb T_c^3\) that lie inside the original domain. Note that any input point is required to be an element of the halfopen cube representing the original domain as defined above.
There are simplices containing points inside the original domain but also points outside it. The points outside the original domain are periodic copies of points inside the original domain. So, to specify a simplex we need points together with some additional information that determines the respective periodic copy of each point. The set of representatives of an element of \( \mathbb T_c^3\) is a cubic point grid. We address each representative by a threedimensional integer vector \( (o_x,o_y,o_z)\), called offset. It represents the number of periods a representative in the original domain must be translated in \( x\), \( y\), and \( z\)direction. The vector \( (0,0,0)\) corresponds to the representative in the original domain. To specify a \( k\)simplex we need \( k+1\) pointoffset pairs (cf. Figure 42.1).
A triangulation is a collection of vertices and cells that are linked together through incidence and adjacency relations. Each cell gives access to its four incident vertices, their corresponding offsets, and to its four adjacent cells. Each vertex gives access to one of its incident cells.
The four vertices of a cell are indexed with 0, 1, 2 and 3 in positive orientation. The orientation of a simplex in \( \mathbb T_c^3\) is defined as the orientation of the corresponding simplex in \( \mathbb R^3\) given by representatives determined by the respective offsets (see Figure 42.2).
As in the underlying combinatorial triangulation (see Chapter 3D Triangulation Data Structure), the neighbors of a cell are indexed with 0, 1, 2, 3 in such a way that the neighbor indexed by \( i\) is opposite to the vertex with the same index. Also edges ( \( 1\)faces) and facets ( \( 2\)faces) are not explicitly represented: a facet is given by a cell and an index (the facet i
of a cell c
is the facet of c
that is opposite to the vertex with index i
) and an edge is given by a cell and two indices (the edge (i,j)
of a cell c
is the edge whose endpoints are the vertices of c
with indices i
and j
). See Figure 41.1 of chapter 3D Triangulation Data Structure.
Some point sets do not admit a triangulation in \( \mathbb T_c^3\). In this case we use 27 periodic copies of the point set arranged in a cube of edge length \( 3c\). Any point set constructed in this way has a triangulation in \( \mathbb R^3/G'\) with \( G'=((3c\cdot\mathbb Z)^3,+)\) [1]. So we compute the triangulation in this space, which is a 27sheeted covering space of \( \mathbb T_c^3\) (see Figure 42.3).
The machinery that manages the copies is largely hidden from the user. However there are some effects that cannot be ignored. For example if the point set does not permit a triangulation in \( \mathbb T_c^3\) then the combinatorial iterators (Cell_iterator
, Facet_iterator
, Edge_iterator
, and Vertex_iterator
) return all simplices that are internally stored, which correspond to 27 periodic copies of each geometric primitive (Tetrahedron, Triangle, Segment, and Point). This is necessary to ensure consistency in the adjacency relations. In case it is desired to have only one periodic copy of each primitive, we provide geometric iterators. They return geometric primitives of the triangulation without relations between them. Another effect is that when the algorithm switches from the 27sheeted covering space to the 1sheeted covering space, the Vertex_handle
s and Cell_handle
s referencing deleted items become invalid.
In the data structure each vertex stores the input point it corresponds to. If we are computing in the 27sheeted covering space, each vertex stores the representative inside the original domain it corresponds to. So, the 27 vertices corresponding to the same element of \( \mathbb T_c^3\) all store the same representative in \( \mathbb R^3\), and not different periodic copies.
Validity
A periodic triangulation is said to be locally valid
iff
(a)(b) Its underlying combinatorial graph, the triangulation data structure, is locally valid
(see Section Representation of Chapter 3D Triangulation Data Structure)
(c) Any cell has its vertices ordered according to positive orientation. See Figure 42.2.
The class Periodic_3_Delaunay_triangulation_3
implements Delaunay triangulations of point sets in \( \mathbb T_c^3\).
Delaunay triangulations have the empty sphere property, that is, the circumscribing sphere of each cell does not contain any other vertex of the triangulation in its interior. These triangulations are uniquely defined except in degenerate cases where five points are cospherical. Note however that the CGAL implementation computes a unique triangulation even in these cases [2].
This implementation is fully dynamic: it supports both insertions of points and vertex removal.
The class Periodic_3_triangulation_hierarchy_3
is the adaptation of the hierarchical structure described in chapter 3D Triangulations to the periodic case.
We have chosen the prefix "Periodic_3" to emphasize that the triangulation is periodic in all three directions of space.
The two main classes Periodic_3_Delaunay_triangulation_3
and Periodic_3_triangulation_3
provide highlevel geometric functionality and are responsible for the geometric validity. Periodic_3_Delaunay_triangulation_3
contains all the functionality that is special to Delaunay triangulations, such as point insertion and vertex removal, the sideofsphere test, finding the conflicting region of a given point, dual functions etc. Periodic_3_triangulation_3
contains all the functionality that is common to triangulations in general, such as location of a point in the triangulation [3], access functions, geometric queries like the orientation test etc.
They are built as layers on top of a triangulation data structure, which stores their combinatorial structure. This separation between the geometry and the combinatorics is reflected in the software design by the fact that the triangulation classes take two template parameters:
Periodic_3DelaunayTriangulationTraits_3
and Periodic_3TriangulationTraits_3
can be used for this parameter. Periodic_3TriangulationDSCellBase_3
and Periodic_3TriangulationDSVertexBase_3
as template parameters. The first template parameter of the triangulation class Periodic_3_triangulation_3<Periodic_3TriangulationTraits_3, TriangulationDataStructure_3>
is the geometric traits class, described by the concept Periodic_3TriangulationTraits_3
. It is different to the TriangulationTraits_3 (see chapter 3D Triangulations) in that it implements all objects, predicates and constructions with using offsets.
The class Periodic_3_triangulation_traits_3<TriangulationTraits_3,Periodic_3Offset_3>
provides the required functionality. It expects two template parameters: A model of the concept TriangulationTraits_3
and a model of the concept Periodic_3Offset_3
.
The second parameter Periodic_3Offset_3
defaults to Periodic_3_offset_3
.
The first template parameter of the Delaunay triangulation class Periodic_3_Delaunay_triangulation_3<Periodic_3DelaunayTriangulationTraits_3, TriangulationDataStructure_3>
is the geometric traits class, described by the concept Periodic_3DelaunayTriangulationTraits_3
. It is different to the DelaunayTriangulationTraits_3 (see chapter 3D Triangulations) in that it implements all objects, predicates and constructions with using offsets.
The class Periodic_3_Delaunay_triangulation_traits_3<DelaunayTriangulationTraits_3,Periodic_3Offset_3>
provides the required functionality. It expects two template parameters: A model of the concept DelaunayTriangulationTraits_3
and a model of the concept Periodic_3Offset_3
.
The second parameter Periodic_3Offset_3
defaults to Periodic_3_offset_3
.
The kernels Cartesian
, Homogeneous
, Simple_cartesian
, Simple_homogeneous
and Filtered_kernel
can all be used as models for TriangulationTraits_3
and DelaunayTriangulationTraits_3
. Periodic_3_triangulation_traits_3
and Periodic_3_Delaunay_triangulation_traits_3
provide exact predicates and exact constructions if TriangulationTraits_3
and DelaunayTriangulationTraits_3
do. They provide exact predicates but not exact constructions if Filtered_kernel<CK>
with CK
an inexact kernel is used as their first template parameter. Using Exact_predicates_inexact_constructions_kernel
as Traits
provides fast and exact predicates and not exact constructions, using Exact_predicates_exact_constructions_kernel
provides fast and exact predicates and exact constructions. The latter is recommended if the dual constructions and constructions of points, segments, triangles, and tetrahedra are used.
The second template parameter of the main classes Periodic_3_triangulation_3
and Periodic_3_Delaunay_triangulation_3
is a triangulation data structure class. This class can be seen as a container for the cells and vertices maintaining incidence and adjacency relations (see Chapter 3D Triangulation Data Structure). A model of this triangulation data structure is Triangulation_data_structure_3
, and it is described by the TriangulationDataStructure_3
concept. This model is itself parameterized by a vertex base class and a cell base class, which gives the possibility to customize the vertices and cells used by the triangulation data structure, and hence by the geometric triangulation using it. To represent periodic triangulations the cell base and vertex base classes need to meet the concepts Periodic_3TriangulationDSCellBase_3
and Periodic_3TriangulationDSVertexBase_3
.
A default value for the triangulation data structure parameter is provided in all the triangulation classes, so it does not need to be specified by the user unless he wants to use a different triangulation data structure or a different vertex or cell base class.
Periodic_3_triangulation_3
uses the TriangulationDataStructure_3
in essentially the same way as Triangulation_3
. That is why the flexibility described in Software Design is applicable in exactly the same way. Also the classes Triangulation_vertex_base_with_info_3
and Triangulation_cell_base_with_info_3
can be reused directly, see also Example Adding a Color.
This example shows the incremental construction of a 3D Delaunay triangulation, the location of a point and how to perform elementary operations on indices in a cell. It uses the default parameter of the Periodic_3_Delaunay_triangulation_3
class for the triangulation data structure.
File Periodic_3_triangulation_3/simple_example.cpp
The following two examples show how the user can plug his own vertex base in a triangulation. Changing the cell base is similar.
If the user does not need to add a type in a vertex that depends on the TriangulationDataStructure_3
(e.g. a Vertex_handle
or Cell_handle
), then he can use the Triangulation_vertex_base_with_info_3
class to add his own information easily in the vertices. The example below shows how to add a Color
this way.
File Periodic_3_triangulation_3/colored_vertices.cpp
If the user needs to add a type in a vertex that depends on the TriangulationDataStructure_3
(e.g. a Vertex_handle
or Cell_handle
), then he has to derive his own vertex base class, as the following example shows.
File Periodic_3_triangulation_3/periodic_adding_handles.cpp
The user can check at any time whether a triangulation would be a simplicial complex in \( \mathbb T_c^3\) and force a conversion if so. However this should be done very carefully in order to be sure that the internal structure always remains a simplicial complex and thus a triangulation.
In this example we construct a triangulation that can be converted to the 1sheeted covering space. However, we can insert new points such that the point set does not have a Delaunay triangulation in the 1sheeted covering space anymore, so the triangulation is not extensible.
File Periodic_3_triangulation_3/covering.cpp
For large point sets there are two optimizations available. Firstly, there is spatial sorting that sorts the input points according to a Hilbert curve, see chapter Spatial Sorting. The second one inserts 36 appropriately chosen dummy points to avoid the use of a 27sheeted covering space in the beginning. The 36 dummy points are deleted in the end. If the point set turns out to not have a Delaunay triangulation in the 1sheeted covering space, the triangulation is converted to the 27sheeted covering space during the removal of the 36 dummy points. This might take even longer than computing the triangulation without using this optimization. In general, uniformly distributed random point sets of more than 1000 points have a Delaunay triangulation in the 1sheeted covering space.
It is recommended to run this example only when compiled in release mode because of the relatively large number of points.
File Periodic_3_triangulation_3/large_point_set.cpp
There might be applications that need the geometric primitives of a triangulation as an input but do not require a simplicial complex. For these cases we provide the geometric iterators that return only the geometric primitives fulfilling some properties. In the following example we use the Periodic_3_triangulation_3::Periodic_triangle_iterator
with the option UNIQUE_COVER_DOMAIN
. This means that only those triangles are returned that have a nonempty intersection with the original domain of the 1sheeted covering space, see Figure P3Triangulation3figgeom_iterators. The Periodic_3_triangulation_3::Periodic_triangle
is actually a threedimensional array of pointoffset pairs. We check for all three entries of the periodic triangle whether the offset is (0,0,0) using the method is_null
. If so, we convert the periodic triangle to a PK::Triangle_3
, which requires exact constructions to be exact.
File Periodic_3_triangulation_3/geometric_access.cpp
It is possible to use the class Periodic_3_Delaunay_triangulation_3
as underlying triangulation for computing alpha shapes. For an example see Section Example for Periodic Alpha Shapes of the chapter on 3D alpha shapes.
In 2006, Nico Kruithof started to work with Monique Teillaud on the 3D Periodic Triangulations package.
In 2007, Manuel Caroli continued work on the algorithms [1] and on the package with Monique Teillaud.
The package follows the design of the 3D Triangulations package (see Chapter 3D Triangulations).