CGAL::Periodic_3_triangulation_3<PT,TDS>

Definition

The class Periodic_triangulation_3 represents a 3-dimensional triangulation of a point set in c3.

#include <CGAL/Periodic_3_triangulation_3.h>

Parameters

The first template argument PT must be a model of the Periodic_3DelaunayTriangulationTraits_3 concept.

The second template argument TDS must be a model of the TriangulationDataStructure_3 concept with some additional functionality in cells and vertices. Its default value is Triangulation_data_structure_3<Triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<>>,Triangulation_cell_base_3<PT,Periodic_3_triangulation_ds_cell_base_3<>>>.

Types

The class Triangulation_3 defines the following types:

typedef PT Geometric_traits;
typedef TDS Triangulation_data_structure;

typedef Geometric_traits::Periodic_3_offset_3
Offset;
typedef Geometric_traits::Iso_cuboid_3
Iso_cuboid; A type representing an axis-aligned cuboid. It must be a model of PT::Iso_cuboid_3. Used to represent the original domain.
typedef array<int,3> Covering_sheets; Integer triple to store the number of sheets in each direction of space.

typedef Geometric_traits::Point_3 Point;
typedef Geometric_traits::Segment_3
Segment;
typedef Geometric_traits::Triangle_3
Triangle;
typedef Geometric_traits::Tetrahedron_3
Tetrahedron;

typedef std::pair< Point, Offset >
Periodic_point;
typedef array< Periodic_point, 2> Periodic_segment;
typedef array< Periodic_point, 3> Periodic_triangle;
typedef array< Periodic_point, 4> Periodic_tetrahedron;

Only vertices (0-faces) and cells (3-faces) are stored. Edges (1-faces) and facets (2-faces) are not explicitly represented and thus there are no corresponding classes (see Section 37.2).

typedef Triangulation_data_structure::Vertex
Vertex;
typedef Triangulation_data_structure::Cell
Cell;
typedef Triangulation_data_structure::Edge
Edge;
typedef Triangulation_data_structure::Facet
Facet;

The vertices and faces of the triangulations are accessed through handles, iterators and circulators. A handle is a type which supports the two dereference operators operator* and operator->. The Handle concept is documented in the support library. Iterators and circulators are bidirectional and non-mutable. The edges and facets of the triangulation can also be visited through iterators and circulators which are bidirectional and non-mutable.

Iterators and circulators are convertible to the corresponding handles, thus the user can pass them directly as arguments to the functions.

typedef Triangulation_data_structure::Vertex_handle
Vertex_handle; handle to a vertex
typedef Triangulation_data_structure::Cell_handle
Cell_handle; handle to a cell

typedef Triangulation_data_structure::size_type
size_type; Size type (an unsigned integral type)
typedef Triangulation_data_structure::difference_type
difference_type; Difference type (a signed integral type)

typedef Triangulation_data_structure::Cell_iterator
Cell_iterator; iterator over cells
typedef Triangulation_data_structure::Facet_iterator
Facet_iterator; iterator over facets
typedef Triangulation_data_structure::Edge_iterator
Edge_iterator; iterator over edges
typedef Triangulation_data_structure::Vertex_iterator
Vertex_iterator; iterator over vertices

typedef Triangulation_data_structure::Cell_circulator
Cell_circulator; circulator over all cells incident to a given edge
typedef Triangulation_data_structure::Facet_circulator
Facet_circulator; circulator over all facets incident to a given edge

Geometric iterators:

Periodic_3_triangulation_3<PT,TDS>::Periodic_tetrahedron_iterator
iterator over the tetrahedra corresponding to cells of the triangulation.

Periodic_3_triangulation_3<PT,TDS>::Periodic_triangle_iterator
iterator over the triangles corresponding to facets of the triangulation.

Periodic_3_triangulation_3<PT,TDS>::Periodic_segment_iterator
iterator over the segments corresponding to edges of the triangulation.

Periodic_3_triangulation_3<PT,TDS>::Periodic_point_iterator
iterator over the points corresponding to vertices of the triangulation.

Enums:

The triangulation class also defines the following enum types:

To specify which case occurs when locating a point in the triangulation.

enum Locate_type { VERTEX=0, EDGE, FACET, CELL, EMPTY};

To specify the behavior of geometric iterators.

enum Iterator_type { STORED=0, UNIQUE, STORED_COVER_DOMAIN, UNIQUE_COVER_DOMAIN};

Creation

Periodic_3_triangulation_3<PT,TDS> t ( Iso_cuboid domain = Iso_cuboid(0,0,0,1,1,1), Geometric_traits traits = Geometric_traits());
Introduces an empty triangulation t with domain as original domain.
Precondition: domain is a cube.


Periodic_3_triangulation_3<PT,TDS> t ( Periodic_3_triangulation_3 tr);
Copy constructor. All vertices and faces are duplicated.

Assignment

Periodic_3_triangulation_3 & t = Periodic_3_triangulation_3 tr
The triangulation tr is duplicated, and modifying the copy after the duplication does not modify the original. The previous triangulation held by t is deleted.

void t.swap ( Periodic_3_triangulation_3 & tr)
The triangulations tr and t are swapped. t.swap(tr) should be preferred to t = tr or to t(tr) if tr is deleted after that. Indeed, there is no copy of cells and vertices, thus this method runs in constant time.

void t.clear () Deletes all vertices and all cells of t.

template < class PT, class TDS1, class TDS2 >
bool Periodic_3_triangulation_3<PT, TDS1> t1 == Periodic_3_triangulation_3<PT, TDS2> t2
Equality operator. Returns true iff there exist a bijection between the vertices of t1 and those of t2 and a bijection between the cells of t1 and those of t2, which preserve the geometry of the triangulation, that is, the points of each corresponding pair of vertices are equal, and the tetrahedra corresponding to each pair of cells are equal (up to a permutation of their vertices).
template < class PT, class TDS1, class TDS2 >
bool Periodic_3_triangulation_3<PT, TDS1> t1 != Periodic_3_triangulation_3<PT, TDS2> t2
The opposite of operator==.

Access Functions

Geometric_traits t.geom_traits () Returns a const reference to the geometric traits object.
Triangulation_data_structure t.tds () Returns a const reference to the triangulation data structure.

Non const access

The responsibility of keeping a valid triangulation belongs to the user when using advanced operations allowing a direct manipulation of the tds. This method is mainly a help for users implementing their own triangulation algorithms.

Triangulation_data_structure & t.tds () Returns a reference to the triangulation data structure.

Iso_cuboid t.domain () Returns the original domain.

Covering_sheets t.number_of_sheets () Returns the number of sheets of the covering the triangulation is currently computed in.

Non-constant-time queries and conversions

bool t.is_extensible_triangulation_in_1_sheet_h1 ()
The current triangulation remains a triangulation in 1-sheeted covering even after adding points if this method returns true. This test relies on a heuristic, i.e. if it answers false nothing is known. This test runs in constant-time when not computing in 1-sheeted covering space. (This test uses the length of the longest edge in the triangulation as a criterion [CT09].)

bool t.is_extensible_triangulation_in_1_sheet_h2 ()
The same as is_extensible_triangulation_in_1_sheet_h1() but with a more precise heuristic, i.e. it might answer true in cases in which is_extensible_triangulation_in_1_sheet_h1() would not. However, it is much less time efficient when not computing in 1-sheeted covering space. (This test uses the diameter of the largest empty ball in the input point set as a criterion [CT09].)
bool t.is_triangulation_in_1_sheet () Returns true if the current triangulation would still be a triangulation in 1-sheeted covering, returns false otherwise.

It is not recommended to interfere with the built-in covering management. Especially a premature conversion to a 1-sheeted covering might lead to problems when modifying the triangulation later.

void t.convert_to_1_sheeted_covering ()
Converts the current triangulation into the same periodic triangulation in 1-sheeted covering.
void t.convert_to_27_sheeted_covering ()
Converts the current triangulation into the same periodic triangulation in 27-sheeted covering.

size_type t.number_of_vertices () Returns the number of vertices. Counts all vertices that are representatives of the same point in c3 as one vertex.
size_type t.number_of_cells () Returns the number of cells. Counts all cells that are representatives of the same tetrahedron in c3 as one cell.

size_type t.number_of_stored_vertices () Returns the number of vertices in the data structure. This is the same as the number of sheets times number_of_vertices().
size_type t.number_of_stored_cells () Returns the number of cells in the data structure. This is the same as the number of sheets times number_of_cells().

Non-constant-time access functions

size_type t.number_of_edges () Returns the number of edges. Counts all edges that are representatives of the same segment in c3 as one edge.
size_type t.number_of_facets () Returns the number of facets. Counts all facets that are representatives of the same triangle in c3 as one facet.

size_type t.number_of_stored_edges () Returns the number of edges in the data structure. This is the same as the number of sheets times number_of_edges().
size_type t.number_of_stored_facets () Returns the number of facets in the data structure. This is the same as the number of sheets times number_of_facets().

Geometric access functions

Periodic_point t.periodic_point ( const Vertex_handle v)
Returns the periodic point given by vertex v.
Periodic_point t.periodic_point ( const Cell_handle c, int i)
Returns the periodic point given by the i-th vertex of cell c.
Precondition: i {0,1,2,3}
Periodic_segment t.periodic_segment ( const Cell_handle c, int i, int j)
Returns the periodic segment formed by the two point-offset pairs corresponding to the two vertices of edge (c,i,j).
Precondition: i,j {0,1,2,3}, i j
Periodic_segment t.periodic_segment ( Edge e) Same as the previous method for edge e.
Periodic_triangle t.periodic_triangle ( const Cell_handle c, int i)
Returns the periodic triangle formed by the three point-offset pairs corresponding to the three vertices of facet (c,i). The triangle is oriented so that its normal points to the inside of cell c.
Precondition: i {0,1,2,3}
Periodic_triangle t.periodic_triangle ( Facet f) Same as the previous method for facet f.
Periodic_tetrahedron t.periodic_tetrahedron ( const Cell_handle c)
Returns the periodic tetrahedron formed by the four point-offset pairs corresponding to the four vertices of c.

Note: the following functions require exact constructions in the traits to be exact.

Point t.point ( Periodic_point p) Converts the Periodic_point s to a Point.
Segment t.segment ( Periodic_segment s) Converts the Periodic_segment s to a Segment.
Triangle t.triangle ( Periodic_triangle t)
Converts the Periodic_triangle t to a Triangle.
Tetrahedron t.tetrahedron ( Periodic_tetrahedron t)
Converts the Periodic_tetrahedron t to a Tetrahedron.

Queries

bool t.is_vertex ( Point p, Vertex_handle & v)
Tests whether p is a vertex of t by locating p in the triangulation. If p is found, the associated vertex v is given.
bool t.is_vertex ( Vertex_handle v) Tests whether v is a vertex of t.

bool t.is_edge ( Vertex_handle u, Vertex_handle v, Cell_handle & c, int & i, int & j)
Tests whether (u,v) is an edge of t. If the edge is found, it gives a cell c having this edge and the indices i and j of the vertices u and v in c, in this order.
Precondition: u and v are vertices of t.
bool
t.is_edge ( Vertex_handle u,
Offset offu,
Vertex_handle v,
Offset offv,
Cell_handle & c,
int & i,
int & j)
Tests whether ((u,offu),(v,offu)) is an edge of t. If the edge is found, it gives a cell c having this edge and the indices i and j of the vertices u and v in c, in this order.
Precondition: u and v are vertices of t.

bool
t.is_facet ( Vertex_handle u,
Vertex_handle v,
Vertex_handle w,
Cell_handle & c,
int & i,
int & j,
int & k)
Tests whether (u,v,w) is a facet of t. 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 c, in this order.
Precondition: u, v and w are vertices of t.
bool
t.is_facet ( Vertex_handle u,
Offset offu,
Vertex_handle v,
Offset offv,
Vertex_handle w,
Offset offw,
Cell_handle & c,
int & i,
int & j,
int & k)
Tests whether ((u,offu),(v,offv),(w,offw)) is a facet of t. 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 c, in this order.
Precondition: u, v and w are vertices of t.

bool t.is_cell ( Cell_handle c) Tests whether c is a cell of t.
bool
t.is_cell ( Vertex_handle u,
Vertex_handle v,
Vertex_handle w,
Vertex_handle x,
Cell_handle & c,
int & i,
int & j,
int & k,
int & l)
Tests whether (u,v,w,x) is a cell of t. If the cell c is found, the method computes the indices i, j, k and l of the vertices u, v, w and x in c, in this order.
Precondition: u, v, w and x are vertices of t.
bool t.is_cell ( Vertex_handle u, Vertex_handle v, Vertex_handle w, Vertex_handle x, Cell_handle & c)
Tests whether (u,v,w,x) is a cell of t and computes this cell c.
Precondition: u, v, w and x are vertices of t.
bool
t.is_cell ( Vertex_handle u,
Offset offu,
Vertex_handle v,
Offset offv,
Vertex_handle w,
Offset offw,
Vertex_handle x,
Offset offx,
Cell_handle & c,
int & i,
int & j,
int & k,
int & l)
Tests whether ((u,offu),(v,offv),(w,offv),(x,offx)) is a cell of t. If the cell c is found, the method computes the indices i, j, k and l of the vertices u, v, w and x in c, in this order.
Precondition: u, v, w and x are vertices of t.
bool
t.is_cell ( Vertex_handle u,
Offset offu,
Vertex_handle v,
Offset offv,
Vertex_handle w,
Offset offw,
Vertex_handle x,
Offset offx,
Cell_handle & c)
Tests whether ((u,offu),(v,offv),(w,offv),(x,offx)) is a cell of t and computes this cell c.
Precondition: u, v, w and x are vertices of t.

There is a method has_vertex in the cell class. The analogous methods for facets are defined here.

bool t.has_vertex ( Facet f, Vertex_handle v, int & j)
If v is a vertex of f, then j is the index of v in the cell f.first, and the method returns true.
bool t.has_vertex ( Cell_handle c, int i, Vertex_handle v, int & j)
Same for facet (c,i). Computes the index j of v in c.
bool t.has_vertex ( Facet f, Vertex_handle v)
bool t.has_vertex ( Cell_handle c, int i, Vertex_handle v)
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.

bool t.are_equal ( Cell_handle c, int i, Cell_handle n, int j)
bool t.are_equal ( Facet f, Facet g)
bool t.are_equal ( Facet f, Cell_handle n, int j)

Point location

The class Periodic_3_triangulation_3<PT,TDS> provides three functions to locate a given point with respect to a triangulation. It provides also functions to test if a given point is inside a face or not. Note that the class Periodic_3_Delaunay_triangulation_3 also provides a nearest_vertex() function.

Cell_handle t.locate ( Point query, Cell_handle start = Cell_handle())
Returns the cell that contains the query in its interior. If query lies on a facet, an edge or on a vertex, one of the cells having query on its boundary is returned.
The optional argument start is used as a starting place for the search.
Precondition: query lies in the original domain domain.

Cell_handle t.locate ( Point query, Locate_type & lt, int & li, int & lj, Cell_handle start = Cell_handle())
The k-face that contains query in its interior is returned, by means of the cell returned together with lt, which is set to the locate type of the query (VERTEX, EDGE, FACET, CELL) and two indices li and lj that specify the k-face of the cell containing query.
If the k-face is a cell, li and lj have no meaning; if it is a facet (resp. vertex), li gives the index of the facet (resp. vertex) and lj has no meaning; if it is an edge, li and lj give the indices of its vertices.
If there is no vertex in the triangulation yet, lt is set to EMPTY and locate returns the default constructed handle.
The optional argument start is used as a starting place for the search.
Precondition: query lies in the original domain domain.

Bounded_side t.side_of_cell ( Point p, Cell_handle c, Locate_type & lt, int & li, int & lj)
Returns a value indicating on which side of the oriented boundary of c the point p lies. More precisely, it returns:
- ON_BOUNDED_SIDE if p is inside the cell.
- ON_BOUNDARY if p on the boundary of the cell. Then lt together with li and lj give the precise location on the boundary. (See the descriptions of the locate methods.)
- ON_UNBOUNDED_SIDE if p lies outside the cell.
Precondition: query lies in the original domain domain.

Traversal of the Triangulation

The periodic triangulation class provides several iterators and circulators that allow one to traverse it.

Cell, Face, Edge and Vertex Iterators

The following iterators allow the user to visit cells, facets, edges and vertices of the stored triangulation, i.e. in case of computing in multiply sheeted covering space all stored periodic copies of each item are returned. These iterators are non-mutable, bidirectional and their value types are respectively Cell, Facet, Edge and Vertex. They are all invalidated by any change in the triangulation.

Vertex_iterator t.vertices_begin () Starts at an arbitrary vertex. Iterates over all vertices. Returns vertices_end() if t.number_of_vertices() =0.
Vertex_iterator t.vertices_end () Past-the-end iterator

Edge_iterator t.edges_begin () Starts at an arbitrary edge. Iterates over all edges. Returns edges_end() if t.number_of_vertices() =0.
Edge_iterator t.edges_end () Past-the-end iterator

Facet_iterator t.facets_begin () Starts at an arbitrary facet. Iterates over all facets. Returns facets_end() if t.number_of_vertices() =0.
Facet_iterator t.facets_end () Past-the-end iterator

Cell_iterator t.cells_begin () Starts at an arbitrary cell. Iterates over all cells. Returns cells_end() if t.number_of_vertices() =0.
Cell_iterator t.cells_end () Past-the-end iterator

Geometric iterators

The following iterators allow the user to obtain geometric primitives corresponding to cells, facets, edges, and vertices of the triangulation. These iterators are non-mutable, bidirectional and their value types are respectively Periodic_point, Periodic_segment, Periodic_triangle, and Periodic_tetrahedron. They are all invalidated by any change in the triangulation. If the periodic triangulation is not computed in 1-sheeted covering these iterators can be used to retain only the geometric primitives in the original domain. This can be controlled using the enum Iterator_type, see .

STORED STORED_COVER_DOMAIN UNIQUE UNIQUE_COVER_DOMAIN
Figure 37.4:  The four different modes of the geometric iterators: STORED, STORED_COVER_DOMAIN, UNIQUE, UNIQUE_COVER_DOMAIN. Note that in case of computing in 1-sheeted covering STORED and UNIQUE give the same result.

Periodic_point_iterator t.periodic_points_begin ( Iterator_type it = AS_STORED)
Iterates over the points of the triangulation. Its behavior is defined by the Iterator_type it as described on .
Periodic_point_iterator t.periodic_points_end ( Iterator_type it = AS_STORED)
Past-the-end iterator. Note that to match another Periodic_point_iterator both must have the same Iterator_type it.

Periodic_segment_iterator t.periodic_segments_begin ( Iterator_type it = AS_STORED)
Iterates over the segments of the triangulation. Its behavior is defined by the Iterator_type it as described on .
Periodic_segment_iterator t.periodic_segments_end ( Iterator_type it = AS_STORED)
Past-the-end iterator. Note that to match another Periodic_segment_iterator both must have the same Iterator_type it.

Periodic_triangle_iterator t.periodic_triangles_begin ( Iterator_type it = AS_STORED)
Iterates over the triangles of the triangulation. Its behavior is defined by the Iterator_type it as described on .
Periodic_triangle_iterator t.periodic_triangles_end ( Iterator_type it = AS_STORED)
Past-the-end iterator. Note that to match another Periodic_triangle_iterator both must have the same Iterator_type it.

Periodic_tetrahedron_iterator t.periodic_tetrahedra_begin ( Iterator_type it = AS_STORED)
Iterates over the tetrahedra of the triangulation. Its behavior is defined by the Iterator_type it as described on .
Periodic_tetrahedron_iterator t.periodic_tetrahedra_end ( Iterator_type it = AS_STORED)
Past-the-end iterator. Note that to match another Periodic_tetrahedron_iterator both must have the same Iterator_type it.

Cell and Facet Circulators

The following circulators respectively visit all cells or all facets incident to a given edge. They are non-mutable and bidirectional. They are invalidated by any modification of one of the cells traversed.

Cell_circulator t.incident_cells ( Edge e) Starts at an arbitrary cell incident to e.
Cell_circulator t.incident_cells ( Cell_handle c, int i, int j)
As above for edge (i,j) of c.
Cell_circulator t.incident_cells ( Edge e, Cell_handle start)
Starts at cell start.
Precondition: start is incident to e.
Cell_circulator t.incident_cells ( Cell_handle c, int i, int j, Cell_handle start)
As above for edge (i,j) of c.

Facet_circulator t.incident_facets ( Edge e) Starts at an arbitrary facet incident to e.
Facet_circulator t.incident_facets ( Cell_handle c, int i, int j)
As above for edge (i,j) of c.
Facet_circulator t.incident_facets ( Edge e, Facet start)
Starts at facet start.
Precondition: start is incident to e.
Facet_circulator t.incident_facets ( Edge e, Cell_handle start, int f)
Starts at facet of index f in start.
Facet_circulator t.incident_facets ( Cell_handle c, int i, int j, Facet start)
As above for edge (i,j) of c.
Facet_circulator t.incident_facets ( Cell_handle c, int i, int j, Cell_handle start, int f)
As above for edge (i,j) of c and facet (start,f).

Traversal of the incident cells and facets, and the adjacent vertices of a given vertex

template <class OutputIterator>
OutputIterator t.incident_cells ( Vertex_handle v, OutputIterator cells)
Copies the Cell_handles of all cells incident to v to the output iterator cells. Returns the resulting output iterator.
Precondition: v Vertex_handle(), t.is_vertex(v).

template <class OutputIterator>
OutputIterator t.incident_facets ( Vertex_handle v, OutputIterator facets)
Copies the Facets incident to v to the output iterator facets. Returns the resulting output iterator.
Precondition: v Vertex_handle(), t.is_vertex(v).

template <class OutputIterator>
OutputIterator t.incident_edges ( Vertex_handle v, OutputIterator edges)
Copies the Edges incident to v to the output iterator edges. Returns the resulting output iterator.
Precondition: v Vertex_handle(), t.is_vertex(v).

template <class OutputIterator>
OutputIterator t.adjacent_vertices ( Vertex_handle v, OutputIterator vertices)
Copies the Vertex_handles of all vertices adjacent to v to the output iterator vertices. Returns the resulting output iterator.
Precondition: v Vertex_handle(), t.is_vertex(v).

size_type t.degree ( Vertex_handle v) Returns the degree of a vertex, that is, the number of adjacent vertices.
Precondition: v Vertex_handle(), t.is_vertex(v).

Traversal between adjacent cells

int t.mirror_index ( Cell_handle c, int i)
Returns the index of c in its ith neighbor.
Precondition: i {0, 1, 2, 3}.
Vertex_handle t.mirror_vertex ( Cell_handle c, int i)
Returns the vertex of the ith neighbor of c that is opposite to c.
Precondition: i {0, 1, 2, 3}.
Facet t.mirror_facet ( Facet f) Returns the same facet viewed from the other adjacent cell.

Checking

The responsibility of keeping a valid triangulation belongs to the user when using advanced operations allowing a direct manipulation of cells and vertices. We provide the user with the following methods to help debugging.

bool t.is_valid ( bool verbose = false)
Checks the combinatorial validity of the triangulation. Checks also the validity of its geometric embedding (see Section 37.2).
When verbose is set to true, messages describing the first invalidity encountered are printed.

bool t.is_valid ( Cell_handle c, bool verbose = false)
Checks the combinatorial validity of the cell by calling the is_valid method of the Triangulation_data_structure cell class. Also checks the geometric validity of c, if c is finite. (See Section 37.2.)
When verbose is set to true, messages are printed to give a precise indication of the kind of invalidity encountered.

I/O

istream& istream& is >> Periodic_3_triangulation_3 &t
Reads a triangulation from is and stores it in t.
Precondition: is has the below described format.

ostream& ostream& os << Periodic_3_triangulation_3 t
Writes the triangulation t into os.

The information in the iostream is: the number of sheets of the covering as in number_of_sheets(), the number of vertices, the non-combinatorial information about vertices (point resp. point-offset pairs, etc.), the number of cells, the indices of the vertices of each cell, plus the non-combinatorial information about each cell, then the indices of the neighbors of each cell, where the index corresponds to the preceding list of cells. Then the offsets corresponding to the vertices of the cells are written, the indices again correspond to the list of cells. Finally some optional information contained in the cell can be written.

See Also

Periodic_3_Delaunay_triangulation_3