3Dtriangulation data structures are meant to maintain the combinatorial information for 3Dgeometric triangulations.
In CGAL, a triangulation data structure is a container of cells ($$3faces) and vertices ($$0faces). Each cell gives access to its four incident vertices and to its four adjacent cells. Each vertex gives direct access to one of its incident cells, which is sufficient to retrieve all the incident cells when needed.
The four vertices of a cell are indexed with 0, 1, 2 and 3. The neighbors of a cell are also 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 (see Figure 28.1).
Edges ($$1faces) and facets ($$2faces) 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 of 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 indices i and j of c).
As CGAL explicitly deals with all degenerate cases, a 3Dtriangulation data structure in CGAL can handle the cases when the dimension of the triangulation is lower than 3 (see Section 28.1).
Thus, a 3Dtriangulation data structure can store a triangulation of a topological sphere $$S^{d} of $$ ^{d+1}, for any $$d {1,0,1,2,3}.
The second template parameter of the basic triangulation class (see Chapter 27, ) Triangulation_3 is a triangulation data structure class. (See Chapter 28.)
To ensure all the flexibility of the class Triangulation_3, a model of a triangulation data structure must be templated by the base vertex and the base cell classes (see 28.1): TriangulationDataStructure_3<TriangulationVertexBase_3,TriangulationCellBase_3>. The optional functionalities related to geometry are compulsory for this use as a template parameter of Triangulation_3.
A class that satisfies the requirements for a triangulation data structure class must provide the following types and operations.
Vertices and cells are usually manipulated via handles, which support the two dereference operators operator* and operator>.
 

Requirements for Vertex and Cell are described in TriangulationDataStructure_3::Vertex and TriangulationDataStructure_3::Cell .
 
 (c,i,j) is the edge of cell c whose vertices indices are i and j. (See Section 28.1.)  
 
 (c,i) is the facet of c opposite to the vertex of index i. (See Section 28.1.) 
The following iterators allow one to visit all the vertices, edges, facets and cells of the triangulation data structure. They are all bidirectional, nonmutable iterators.
 
 
 

The following circulators allow us to visit all the cells and facets incident to a given edge. They are bidirectional and nonmutable.
 

Iterators and circulators are convertible to the corresponding handles, thus the user can pass them directly as arguments to the functions.
 
Default constructor.
 
 
Copy constructor. All vertices and cells are duplicated.


 Assignment operator. All vertices and cells are duplicated, and the former data structure of tds is deleted.  

 
tds1 is copied into tds. If $$v != Vertex_{h}andle(),
the vertex of tds corresponding to v is returned,
otherwise Vertex_handle() is returned.
 

 Swaps tds and tds1. There is no copy of cells and vertices, thus this method runs in constant time. This method should be preferred to tds=tds1 or tds(tds1) when tds1 is deleted after that.  

 Deletes all cells and vertices. tds is reset as a triangulation data structure constructed by the default constructor. 

 The dimension of the triangulated topological sphere. 

 The number of vertices. Note that the triangulation data structure has one more vertex than an associated geometric triangulation, if there is one, since the infinite vertex is a standard vertex and is thus also counted. 

 The number of cells. Returns 0 if tds.dimension()$$<3. 

 The number of facets. Returns 0 if tds.dimension()$$<2. 

 The number of edges. Returns 0 if tds.dimension()$$<1. 

 Tests whether v is a vertex of tds.  

 
Tests whether (c,i,j) is an edge of tds. Answers false when
dimension() $$<1 .
 

 
Tests whether (u,v) is an edge of tds. If the edge is found, it computes a cell c having this edge and the indices i and j of the vertices u and v, in this order.  

 
Tests whether (u,v) is an edge of tds.  

 
Tests whether (c,i) is a facet of tds. Answers false when
dimension() $$<2 .
 

 
Tests whether (u,v,w) is a facet of tds. If the facet is found, it computes a cell c having this facet and the indices i, j and k of the vertices u, v and w, in this order.  

 Tests whether c is a cell of tds. Answers false when dimension() $$<3 .  

 
Tests whether (u,v,w,t) is a cell of tds. If the cell c is found, it computes the indices i, j, k and l of the vertices u, v, w and t in c, in this order. 
There is a method has_vertex in the cell class. The analogous methods for facets are defined here.

 
If v is a vertex of f, then j is the index of
v in the cell f.first, and the method returns true.
 

 
Same for facet (c,i). Computes the index j of v in c.  

 

 
Same as the first two methods, but these two methods do not return the index of the vertex. 
The following three methods test whether two facets have the same vertices.

 

 

 
For these three methods:

Two kinds of flips exist for a threedimensional triangulation. They are reciprocal. To be flipped, an edge must be incident to three tetrahedra. During the flip, these three tetrahedra disappear and two tetrahedra appear. Figure 28.7(left) shows the edge that is flipped as bold dashed, and one of its three incident facets is shaded. On the right, the facet shared by the two new tetrahedra is shaded.
The following methods guarantee the validity of the resulting 3D combinatorial triangulation. Moreover the flip operations do not invalidate the vertex handles, and only invalidate the cell handles of the affected cells.
Flips for a 2d triangulation are not implemented yet




 
Before flipping, these methods check that edge e=(c,i,j) is flippable (which is quite expensive). They return false or true according to this test.  




 
Should be preferred to the previous methods when the edge is
known to be flippable.
 




 Before flipping, these methods check that facet f=(c,i) is flippable (which is quite expensive). They return false or true according to this test.  




 
Should be preferred to the previous methods when the facet is
known to be flippable.

The following modifier member functions guarantee the combinatorial validity of the resulting triangulation.

 
Creates a new vertex, inserts it in cell c and returns its handle.
The cell c is split into four new cells, each of these cells being
formed by the new vertex and a facet of c.
 


Creates a new vertex, inserts it in facet f and returns its handle.
In dimension 3, the two incident cells are split into 3 new cells;
in dimension 2, the facet is split into 3 facets.
 

 
Creates a new vertex, inserts it in facet i of c and returns its
handle.
 


Creates a new vertex, inserts it in edge e and returns its handle.
In dimension 3, all the
incident cells are split into 2 new cells; in dimension 2, the 2
incident facets are split into 2 new facets; in dimension 1, the edge is
split into 2 new edges.
 

 
Creates a new vertex, inserts it in edge $$(i,j) of c and returns its
handle.
 

 
Transforms a triangulation of the sphere $$S^{d} of $$ ^{d+1} into the
triangulation of the sphere $$S^{d+1} of $$ ^{d+2} by adding a new vertex
v:
v is linked to all the vertices to triangulate one of the two
halfspheres of dimension $$(d+1). Vertex star is used to
triangulate the second halfsphere (when there is an associated
geometric triangulation, star is in fact the vertex associated with
its infinite vertex).
See Figure 28.8. The numbering of the cells is such that, if f was a face of maximal dimension in the initial triangulation, then (f,v) (in this order) is the corresponding face in the new triangulation. This method can be used to insert the first two vertices in an empty triangulation. A handle to v is returned.

Figure 28.8: insert_increase_dimension (1dimensional case).
 

 
Creates a new vertex by starring a hole. It takes an iterator range
[cell_begin; cell_end[ of Cell_handles which specifies a set
of connected cells (resp. facets in dimension 2) describing a hole.
(begin, i) is a facet (resp. an edge) on the boundary of the hole,
that is, begin belongs to the set of cells (resp. facets) previously
described, and begin>neighbor(i) does not. Then this function deletes
all the cells (resp. facets) describing the hole, creates a new vertex
v, and for each facet (resp. edge) on the boundary of the hole, creates
a new cell (resp. facet) with v as vertex. v is returned.

advanced 


Changes the orientation of all cells of the triangulation data structure.
 

 
Adds a copy of the vertex v to the triangulation data structure.  

 
Creates a vertex which is a copy of the one pointed to by v and adds it to the triangulation data structure.  

 
Adds a copy of the cell c to the triangulation data structure.  

 Creates a cell which is a copy of the one pointed to by c and adds it to the triangulation data structure.  

 
Creates a cell and adds it into the triangulation data structure. Initializes the vertices of the cell, its neighbor handles being initialized with the default constructed handle.  

 
Creates a cell, initializes its vertices and neighbors, and adds it into the triangulation data structure.  

 
Removes the vertex from the triangulation data structure.
 


Removes the cell from the triangulation data structure.
 
 

 
Calls delete_vertex over an iterator range of value type Vertex_handle.  
 

 
Calls delete_cell over an iterator range of value type Cell_handle. 
advanced 

 Returns cells_end() when tds.dimension() $$<3. 




 Lowlevel access to the cells, does not return cells_end() when tds.dimension() $$<3. 




 Returns facets_end() when tds.dimension() $$<2. 




 Returns edges_end() when tds.dimension() $$<1. 










Starts at an arbitrary cell incident to e.
 

 
As above for edge (i,j) of c.  

 
Starts at cell start.
 

 
As above for edge (i,j) of c. 
The following circulators on facets are defined only in dimension 3, though facets are defined also in dimension 2: there are only two facets sharing an edge in dimension 2.


Starts at an arbitrary facet incident to e.
 

 
As above for edge (i,j) of c.  

 
Starts at facet start.
 

 
Starts at facet of index f in start.  

 
As above for edge (i,j) of c.  

 
As above for edge (i,j) of c and facet (start,f). 
 

 
Copies the Cell_handles of all cells (resp. facets in dimension 2)
incident to v to the output iterator cells.
If tds.dimension() $$<2, then do nothing.
Returns the resulting output iterator.
 
 

 
Copies the Facets incident to v to the output iterator
facets.
Returns the resulting output iterator.
 
 

 
Copies the Vertex_handles of all vertices incident to v to the
output iterator vertices. If tds.dimension() $$<2, then do
nothing. Returns the resulting output iterator.
 


Returns the degree of a vertex, that is, the number of incident vertices.


 
Returns the index of c in its $$i^{th} neighbor.
 

 
Returns the vertex of the $$i^{th} neighbor of c that is opposite to
c.
 

 Returns the same facet viewed from the other adjacent cell. 
advanced 

 
Checks the combinatorial validity of the triangulation by checking
the local validity of all its cells and vertices (see functions below).
(See Section 28.1.) Moreover, the Euler relation is
tested. When verbose is set to true, messages are printed to give a precise indication on the kind of invalidity encountered.  

 
Checks the local validity of the adjacency relations of the triangulation. It also calls the is_valid member function of the vertex. When verbose is set to true, messages are printed to give a precise indication on the kind of invalidity encountered.  

 
Checks the local validity of the adjacency relations of the triangulation. It also calls the is_valid member function of the cell. When verbose is set to true, messages are printed to give a precise indication on the kind of invalidity encountered. 
advanced 

 Reads a combinatorial triangulation from is and assigns it to tds 

 Writes tds into the stream os 
The information stored in the iostream is: the dimension, the number of vertices, the number of cells, the indices of the vertices of each cell, then the indices of the neighbors of each cell, where the index corresponds to the preceding list of cells. When dimension $$< 3, the same information is stored for faces of maximal dimension instead of cells.
CGAL::Triangulation_data_structure_3
TriangulationDataStructure_3::Vertex
TriangulationDataStructure_3::Cell