diff --git a/.gitattributes b/.gitattributes index df6dbef4a5a..6a22c295602 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1644,6 +1644,8 @@ Packages/Triangulation_2/doc_tex/TDS_2/Flip.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/TDS_2/Three.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/TDS_2/flip.ltex -text Packages/Triangulation_2/doc_tex/TDS_2/insert.ltex -text +Packages/Triangulation_2/doc_tex/TDS_2/rep_bis.gif -text svneol=unset#unset +Packages/Triangulation_2/doc_tex/TDS_2/threelevels2.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/TDS_2_ref/Flip.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/TDS_2_ref/Three.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/Triangulation_2/Embedding.ipe -text @@ -1722,6 +1724,8 @@ Packages/Triangulation_2/doc_tex/basic/TDS_2/Flip.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/basic/TDS_2/Three.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/basic/TDS_2/flip.ltex -text Packages/Triangulation_2/doc_tex/basic/TDS_2/insert.ltex -text +Packages/Triangulation_2/doc_tex/basic/TDS_2/rep_bis.gif -text svneol=unset#unset +Packages/Triangulation_2/doc_tex/basic/TDS_2/threelevels2.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/basic/TDS_2_ref/Flip.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/basic/TDS_2_ref/Three.gif -text svneol=unset#unset Packages/Triangulation_2/doc_tex/basic/Triangulation_2/Embedding.ipe -text diff --git a/Packages/Triangulation_2/changes.txt b/Packages/Triangulation_2/changes.txt index be4d23e7e0d..0a0b8db7141 100644 --- a/Packages/Triangulation_2/changes.txt +++ b/Packages/Triangulation_2/changes.txt @@ -1,6 +1,10 @@ Package triangulation: provides triangulations Delaunay triangulations, constrained and regular triangulations with tests and examples. +ver 8.07 +- updated and changed the examples +- changed the doc + ver 8.06 (05/08/03) - fixed Triangulation:: to Ctr:: in Constraint_delaunay_triangulation_2.h - fixed get_conflicts and get_boundary_of_conflicts for SGI CC diff --git a/Packages/Triangulation_2/doc_tex/TDS_2/rep_bis.gif b/Packages/Triangulation_2/doc_tex/TDS_2/rep_bis.gif new file mode 100644 index 00000000000..371a49b4d17 Binary files /dev/null and b/Packages/Triangulation_2/doc_tex/TDS_2/rep_bis.gif differ diff --git a/Packages/Triangulation_2/doc_tex/TDS_2/tds_user.tex b/Packages/Triangulation_2/doc_tex/TDS_2/tds_user.tex index e42fb753dfc..57cd7eb54ae 100644 --- a/Packages/Triangulation_2/doc_tex/TDS_2/tds_user.tex +++ b/Packages/Triangulation_2/doc_tex/TDS_2/tds_user.tex @@ -4,35 +4,105 @@ \label{Chapter_2D_Triangulation_Data_structure} \minitoc -The second template parameter of a 2D triangulation class -has to be instanciated with a model -of \ccc{TriangulationDataStructure_2}. -Section~\ref{2D_TDS_Concept} describes the concept -of \ccc{TriangulationDataStructure_2}. -Section~\ref{2D_TDS_default} describes the -class \ccc{CGAL::Triangulation_data_structure_2} -which is the default model provided for this concept. -To ensure to the triangulation classes all the flexibility -described in Chapter~\ref{user_chapter_2D_Triangulations} -the default model derives its \ccc{Vertex} and \ccc{Face} types -from the two template parameters \ccc{Vb} and \ccc{Fb} -which have to be models for the base vertex and face -classes. -Section~\ref{2D_TDS_Base_Classes} described the base -vertex and face classes of a triangulation. -At last, section~\ref{2D_TDS_Example} shows -how the user can plug in the triangulation -data structure his own vertex or face base class. -\section{The Concept} +\section{Definition} + +A triangulation data structure is a data structure designed +to handle the representation of a two dimensional +triangulation. The concept of triangulation data structure +was primarily designed to serve as a data structure +for \cgal\ 2D triangulation classes which are triangulations +embedded in a plane. +However it appears that the concept is more general +and can be used for any orientable triangulated surface +without boundary, whatever may be the dimensionality +of the space the trianguation is embedded in. + + +\subsection{A data structure based on faces and vertices} + +The representation of \cgal\ 2D triangulations is based on faces and vertices, +Edges are only implicitely +represented trough the adjacency relations betwen two +faces. + +The triangulation data structure can be seen +as a container for faces and vertices +maintaining incidence and adjacency relations +among them. + +Each triangular face gives access to its three incident vertices +and to its three adjacent faces. +Each vertex gives access to one of its incident faces +and through that face to the circular list of its incident faces. + +The three vertices of a face are indexed with 0, 1 and 2. +The neighbor of a face are also +indexed with 0,1,2 in such a way that the neighbor indexed by \ccc{i} +is opposite to the vertex with the same index. + +Each edge has two implicit representations : the edge +of a face \ccc{f} which is opposed to the vertex indexed \ccc{i}, +can be represented as well as an edge of the \ccc{neighbor(i)} of +\ccc{f}. See Figure~\ref{2D_Triangulation_Fig_neighbors1}. + + \begin{figure} +\begin{ccTexOnly} + \begin{center} + \includegraphics[width=6cm]{rep_bis.eps} + \end{center} +\end{ccTexOnly} + \caption{Vertices and neighbors. The function \ccc{ccw(i)} +and \ccc{cw(i)} compute respectively $i+1$ and $i-1$ modulo 3. + \label{2D_TDS_Fig_neighbors1}} + \begin{ccHtmlOnly} +
+Neighbors +
+\end{ccHtmlOnly} +\end{figure} + + + +This kind or representation of simplicial complexes extends in any +dimension. More precisely, in dimension $d$, the data structure +will explicitely represents cells (i. e. faces of maximal dimension) +and vertices (i. e. faces of dimension 0). +All faces of dimension between $1$ and $d-1$ +will have an implicit representation. +The 2D triangulation data structure can represent simplicial complexes +of dimension 2, 1 or 0. + +\subsection{The set of faces and vertices} + The set of faces maintained by a 2D triangulation +data structure is such that each edge +is incident to two faces. In other words, +the set of maintained faces +is topologically +equivalent to a two-dimensional triangulated sphere. + +This rules extends to lower dimensional triangulation data structure +arising in degenerate cases or when the triangulations +have less than three vertices. +A one dimensional triangulation structure maintains a set of vertices + and edges which forms a ring +topologically equivalent to a $1$-sphere. + +A zero dimensional triangulation data structure +only includes two adjacent vertices +that is +topologically equivalent to a $0$-sphere. + + +\section{The Concept of Triangulation Data Structure} \label{2D_TDS_Concept} A model of \ccc{TriangulationDataStructure_2} can be seen has a container for the faces and vertices of the triangulation. This class is also responsible for the combinatorial integrity of the triangulation. This means that -the triangulation data strutcure +the triangulation data structure maintains proper incidence and adjacency relations among the vertices and faces of a triangulation while combinatorial modifications @@ -73,13 +143,14 @@ of the triangulation. The triangulation data structure provides member functions to perform the following combinatorial transformation of the triangulation:\\ -flip of two adjacent faces, \\ -addition of a new vertex splitting a given face,\\ -addition of a new vertex splitting a given edge,\\ -addition of a new vertex raising by one the dimension of a degenerate -lower dimensional triangulation, \\ -removal of a vertex incident to three faces, \\ -removal of a vertex lowering the dimension of the triangulation.\\ +-- flip of two adjacent faces, \\ +-- addition of a new vertex splitting a given face +see Figure~\ref{2D_TDS_Fig_insertion},\\ +-- addition of a new vertex splitting a given edge,\\ +-- addition of a new vertex raising by one the dimension of a degenerate +-- lower dimensional triangulation, \\ +-- removal of a vertex incident to three faces, \\ +-- removal of a vertex lowering the dimension of the triangulation.\\ %\begin{figure} @@ -88,7 +159,7 @@ removal of a vertex lowering the dimension of the triangulation.\\ %\input{flip.ltex} %\end{center} %\end{ccTexOnly} -%\caption{Flip. \label{I1_fig_flip_bis}} +%\caption{Flip. \label{{2D_Triangulation_fig_flip_bis}} %\begin{ccHtmlOnly} %
@@ -103,9 +174,9 @@ removal of a vertex lowering the dimension of the triangulation.\\ \begin{ccTexOnly} %\begin{center} \IpeScale{70} \Ipe{Three.ipe} \end{center} \begin{center} \input{insert.ltex} \end{center} -\caption{Insertion} \end{ccTexOnly} - +\caption{Insertion of a new vertex, splitting a face} + \label{2D_TDS_Fig_insertion} \begin{ccHtmlOnly}
Insertion @@ -120,77 +191,186 @@ removal of a vertex lowering the dimension of the triangulation.\\ \cgal\ provides the class \ccc{CGAL::Triangulation_data_structure_2} as a default triangulation data structure. -The two template parameters \ccc{Vb} and \ccc{Fb} -have to be respectively models of the concept -\ccc{TriangulationVertexBase_2} and -\ccc{TriangulationFaceBase_2} which describe the requirements for the -base vertex and face classes of a triangulation. + + +\subsection{Flexibility} +In oder to provide flexibility, the default triangulation data +structure is templated by two parameters +which stands respectively for a vertex base class and a face base +class. +The concept +\ccc{TriangulationDSVertexBase_2} and +\ccc{TriangulationDSFaceBase_2} describe the requirements for the +base vertex and face classes of a triangulation data structure. The triangulation data structure derives from thoses base classes the -vertex and face classes of the triangulations. +vertex and face classes from thoses base classes. This design allows the user to plug in the triangulation data structure his own base classes tuned for his application. +\subsection{The cyclic dependancy of template parameters} + Since adjacency and incidence relation are stored in vertices and +faces, +the vertex and face base classes have to know the types +of handles on faces and vertices provided by the triangulation data +structure. +Therefore , vertex and base classes need to be templated +by the triangulation data structure. Because the triangulation +data structure +is itself templated by the vertex and base classes this induces +a cyclic dependancy. +See figure~\ref{2D_TDS_Fig_three_levels_2}. + +\begin{figure} +\begin{ccTexOnly} +\begin{center} +\includegraphics[width=13cm]{threelevels2.eps} +\end{center} +\end{ccTexOnly} +\caption{The cyclic dependency in triangulations software design. +\label{2D_TDS_Fig_three_levels_2}} +\begin{ccHtmlOnly} +
+
+Three_levels +
+\end{ccHtmlOnly} +\end{figure} + + +\subsection{The rebind mecanism} + +The solution proposed by \cgal\ to resolve this cyclic dependency +is based on a rebind mecanism similar to the mecanism used in the +standard allocator class std::allocator. +The vertex and face base classes plugged in the instantiation of a +triangulation data structure are themselves instantiated with a +fake data structure. The triangulation data structure +will then rebind these classes, plugging itself +at the place of the fake data structure, before using them +to derive the vertex and face classes. The rebinding is performed +through a nested template class \ccc{Rebind_TDS} in the vertex and +face base class, which provide the rebound class +as a type called \ccc{Other}. + +Here is how it works schematically. First, here is the rebinding +taking place in the triangulation data stucture. +\begin{ccExampleCode} +template < class Vb, class Fb > +class Triangulation_data_structure +{ + typedef Triangulation_data_structure Self; + + // Rebind the vertex and cell base to the actual TDS (Self). + typedef typename Vb::template Rebind_TDS::Other VertexBase; + typedef typename Fb::template Rebind_TDS::Other FaceBase; + + // ... further internal machinery leads to the final public types: +public: + typedef ... Vertex; + typedef ... Face; + typedef ... Vertex_handle; + typedef ... Face_handle; +}; +\end{ccExampleCode} + +Then, here is the vertex base class with its nested + \ccc{Rebind_TDS} template class and its template parameter +set by default to an an internal type faking a triangulation data +structure. +\begin{ccExampleCode} +template < class TDS = an internal type faking a triangulation data +structure > +class Vertex_base +{ +public: + template < class TDS2 > + struct Rebind_TDS { + typedef Vertex_base Other; + }; +... +}; +\end{ccExampleCode} +Imagine an analog \ccc{Face_base} class. +The triangulation data structure is then instantiate as follows~: +\begin{ccExampleCode} +typedef Triangulation_data_structure< Vertex_base<>, Face_base<> > TDS; +\end{ccExampleCode} + + +\subsection{Making use of the flexibility} + +There is several possibilities to make use +of the flexibility offered by +the triangulation data structure. +\begin{itemize} +\item{} First, when the user needs to have, +in vertices and faces, additionnal informations +which do not depend on types defined by the +triangulated data structure, predefined classes +\ccc{Triangulation_vertex_base_with_info} +and \ccc{Triangulation_face_base_with_info} can be plugged in. +Those classes have a template parameter \ccc{Info} to be instantiated +by a user defined type. They +store a data member of this type and gives acces to it. +\item{} Second, the user can derive +his own base classes from the default base +classes : +\ccc{Triangulation_ds_vertex_base_2}, and +\ccc{Triangulation_ds_cell_base_2} +are the default base classes to be plugged in a triangulation +data structure used alone. +Triangulation classes requires a data strucure in which +other base classes have been plugged it. The default base classes +for most of the triangulation classes are +\ccc{Triangulation_vertex_base_2}, and \ccc{Triangulation_face_base_2} +are the default base classes to be used when the triangulation data +structure is plugged in a triangulation class. + +When derivation is used, the rebind mecanism is slightly +more involved, because it is necessary to rebind the base class +itself. However the user will be able to use in his classes +references to types provided by the triangulation data structure. +For example, +\begin{ccExampleCode} +template < class Gt, class Vb = CGAL::Triangulation_vertex_base_2 > +class My_vertex_base + : public Vb +{ +public : + template < typename TDS2 > + struct Rebind_TDS { + typedef typename Vb::template Rebind_TDS::Other Vb2; + typedef My_vertex_base Other; + }; + + typedef typename Vb::Triangulation_data_structure Tds; + typedef typename Tds::Vertex_handle Vertex_handle; + ...... +}; +\end{ccExampleCode} + +\item{} At last the user can write his own base classes. +If the triangulation data structure is used alone, +the requirements for the base classes are described by the concepts +\ccc{TriangulationDSVertexBase_2} +and \ccc{TriangulationDSFaceBase_2}\lcTex{, + documented \ccRefPage{TriangulationDSVertexBase_2} and +\ccRefPage{TriangulationDSFaceBase_2}}. +If the triangulation data structure is plugged into a triangulation +class, +the concepts for the vertex and base classes depends on the +triangulation class. The most basic concepts, valid for +basic and Delaunay triangulations are \ccc{TriangulationVertexBase_2} +and \ccc{TriangulationFaceBase_2}\lcTex{, documented +\ccRefPage{TriangulationVertexBase_2} +and \ccRefPage{TriangulationFaceBase_2}}. +\end{itemize} + + See section~\ref{Section_2D_Triangulations_Flexibility} +for examples of using the triangulation data structure flexibility. -\section{The Base Vertex and Face Classes } -\label{2D_TDS_Base_Classes} - -\subsection*{The concepts} -The concepts \ccc{TriangulationVertexBase_2} and -\ccc{TriangulationFaceBase_2} described the requirements -for the base vertex and face classes of a two-dimensional -triangulation. - -At the bottom layer, -a vertex is required to provide access to the embedding point -and to one of its incident face -through a \ccc{void *} pointer. - -At the bottom layer, a -face provides access to its three vertices and to its three -neighboring faces through \ccc{void *} pointers. -The vertices and neighbors are indexed 0,1 and 2 in counterclockwise -order around the face. The neighbor indexed \ccc{i} - lies opposite to vertex with the same index. - - - -\subsection*{The Default Models} -\cgal\ provides the models -\ccc{Triangulation_face_base_2} and -\ccc{Triangulation_vertex_base_2} for -respectively -the \ccc{TriangulationVertexBase_2} and the -\ccc{TriangulationFaceBase_2} concepts. -Both of them are templated by a geometric traits class. -Using for this traits class, the geometric traits class used for the triangulation class -is strongly recommended. -It ensures that the point type defined by \ccc{Triangulation_vertex_base_2} -is the same as the point type defined the geometric traits class of -the triangulation. - -These default base classes can be used directly or can serve as a base to derive -other base classes with some additional attribute (a color for example) -tuned for a specific application. - - -\section{Example : Using one's own Base Face} -\label {2D_TDS_Example} - -The following example derives a new base face class from the default -one and adds a color to the faces of the triangulation. -The face of the triangulation data structure -and the face of the triangulation will inherit the new data member -and its functionality. -Any kind of additional functionality can thus be added to faces or vertices of a triangulation -as long as this functionality does not involve additional pointers to vertices or faces -(because the base classes use only void* pointer and have no knowledge -of the vertex or face types.). - -\ccExample -\ccIncludeExampleCode{Triangulation_2/colored_face.C} - diff --git a/Packages/Triangulation_2/doc_tex/TDS_2/threelevels2.gif b/Packages/Triangulation_2/doc_tex/TDS_2/threelevels2.gif new file mode 100644 index 00000000000..36e4b2b8fba Binary files /dev/null and b/Packages/Triangulation_2/doc_tex/TDS_2/threelevels2.gif differ diff --git a/Packages/Triangulation_2/doc_tex/Triangulation_2/triangulation_user.tex b/Packages/Triangulation_2/doc_tex/Triangulation_2/triangulation_user.tex index cb4ce4bf4a3..eaed9de856e 100644 --- a/Packages/Triangulation_2/doc_tex/Triangulation_2/triangulation_user.tex +++ b/Packages/Triangulation_2/doc_tex/Triangulation_2/triangulation_user.tex @@ -23,9 +23,9 @@ of \cgal. Section~\ref{Section_2D_Triangulations_Definitions} recalls the main definitions about triangulations. Sections~\ref{Section_2D_Triangulations_Representation} discusses -the way two-dimensional triangulations are represented in \cgal\. +the way two-dimensional triangulations are represented in \cgal\ . Section~\ref{Section_2D_Triangulations_Software_Design} presents -and the overall software +the overall software design of the 2D triangulations package. The next sections present the different two dimensional triangulations classes available in \cgal\ : @@ -40,26 +40,28 @@ and constrained Delaunay triangulations (Section~\ref{Section_2D_Triangulations_Constrained_Delaunay}). Section~\ref{Section_2D_Triangulations_Constrained_Plus} describes a class which implements a constrained or -constrained Delaunay triangulation together with -a hierarchiacal data structure on the constraints. +constrained Delaunay triangulation with +an additionnal data structure +to describe how the constraints are refined +by the edges of the triangulations. Section~\ref{Section_2D_Triangulations_Hierarchy} describes a hierarchical data structure for fast point location queries. At last, Section~\ref{Section_2D_Triangulations_Flexibility} -explain how to benefit from the flexibility +explains how the user can benefit from the flexibility of \cgal\ triangulations using customized classes for faces and vertices. \section{Definitions} \label{Section_2D_Triangulations_Definitions} -A two dimensional triangulation can be simply described as a set $T$ +A two dimensional triangulation can be roughly described as a set $T$ of triangular facets such that~:\\ - two facets either are disjoint or share a lower dimensional face (edge or vertex).\\ - the set of facets in $T$ is connected for the adjacency relation. \\ -- the domain $U_T$ of the triangulation which is the union -of facets in $T$ has no singularity. +- the domain $U_T$ which is the union +of facets in $T$ has no singularity. More precisely, a triangulation can be described @@ -101,25 +103,25 @@ that all pairs of incident facets have consistent orientations. The data stucture underlying \cgal\ triangulations allows to represent the combinatorics of any orientable two dimensional triangulations -without boundaries. However, taking care -of the geometric embedding, -the two dimensional triangulations of \cgal\ are mainly -designed to represent planar triangulations. +without boundaries. +On top of this data structure, the 2D triangulations classes +take care of the geometric embedding of the triangulation +and are designed to handle planar triangulations. The plane of the tiangulation may be embedded in a higher dimensional space. -The triangulation \cgal\ are complete -meaning that their domain always covers the +The triangulations of \cgal\ are complete triangulations +which means that their domain is the convex hull of their vertices. -Because any planar two dimensional triangulation +Because any planar triangulation can be completed, this is not a real restriction. For instance, a triangulation of a polygonal region can be -constructed as a subset of a constrained triangulation -where the edges bounding the region have been input as +constructed and represented as a subset of a constrained triangulation +in which the region boundary edges have been input as constrained edges (see Section~\ref{Section_2D_Triangulations_Constrained}, \ref{Section_2D_Triangulations_Constrained_Delaunay} and -\ref{Section_2D_Triangulations_Constrained_Plus}.) +\ref{Section_2D_Triangulations_Constrained_Plus}). Strictly speaking, the term {\em face} should be used to design a face of any dimension, @@ -132,42 +134,43 @@ of a two dimensional triangulation. \section{Representation} \label{Section_2D_Triangulations_Representation} -\subsubsection{The set of represented faces} +\subsubsection{The set of faces} -A triangulation of \cgal\ can be viewed as a planar partition +A 2D triangulation of \cgal\ can be viewed as a planar partition whose bounded faces are triangular and cover -the convex hull of the set ${ A}$ of vertices. +the convex hull of the set of vertices. The single unbounded face of this partition -is the complementary of the convex hull of ${ A}$. +is the complementary of the convex hull. In many applications, such as Kirkpatrick's hierarchy or incremental Delaunay construction, it is convenient to deal with only triangular faces. Therefore, a fictitious vertex, called the \ccc{infinite vertex} -is added to the triangulation and the triangulation -includes additionnal \ccc{infinite edges} and \ccc{infinite faces}. +is added to the triangulation as well as +\ccc{infinite edges} and \ccc{infinite faces} incident to it.. Each infinite edge -is incident to the infinite vertex and a vertex of the convex hull. +is incident to the infinite vertex and to a vertex of the convex hull. Each infinite face is incident to the infinite vertex and to a convex hull edge. - In that way, each edge of the triangulation + +Therefore, each edge of the triangulation is incident to exactly two faces -and the set of faces (of a triangulation is topologically +and the set of faces of a triangulation is topologically equivalent to a two-dimensional sphere. -This is also true -in special cases of triangulations with lower dimensions -arising either in degenerate cases or when the triangulations +This extends to lower dimensional triangulations +arising in degenerate cases or when the triangulations as less than three vertices. -With the infinite vertex and edges, a one dimensional -is a one ring of edges and vertices -topologically equivalent to a $1$-sphere -and a zero dimensional triangulation whose domain is reduced to a -single point is formed with two vertices that is -topologically equivalent to a $0$-sphere +Including the infinite faces, +a one dimensional triangulation +is a ring of edges and vertices +topologically equivalent to a $1$-sphere. +A zero dimensional triangulation, whosedomain is reduced to a +single point, is represented by two vertices that is +topologically equivalent to a $0$-sphere. Note that the \ccc{infinite vertex} has no significant coordinates and that no geometric predicate can be applied on it -or on an infinite face. +nor on an infinite face. \begin{figure} \begin{ccTexOnly} @@ -175,8 +178,8 @@ or on an infinite face. \includegraphics{infinite.eps} \end{center} \end{ccTexOnly} -\caption{The infinite vertex. -\label{I1_Fig_infinite_vertex}} +\caption{Infinite vertex and infinite faces +\label{2D_Triangulation_Fig_infinite_vertex}} \begin{ccHtmlOnly}
Vertices at @@ -189,7 +192,7 @@ infinity \subsubsection{ A representation based on faces and vertices} -Because a triangulation is merely a set of +Because a triangulation is a set of triangular faces with constant-size complexity, triangulations are not implemented as a layer on top of a planar map. @@ -199,25 +202,23 @@ rather than on edges. Such a representation saves storage space and results in faster algorithms~ \cite{bdty-tcgal-00}. -Thus the basic elements of the representation are vertices and faces. +The basic elements of the representation are vertices and faces. Each triangular face gives access to its three incident vertices and to its three adjacent faces. Each vertex gives access to one of its incident faces and through that face to the circular list of its incident faces. -The edges are not explicitly represented, they are only represented -through the adjacency relations of two faces. The three vertices of a face are indexed with 0, 1 and 2 in counterclockwise order. The neighbor of a face are also indexed with 0,1,2 in such a way that the neighbor indexed by \ccc{i} is opposite to the vertex with the same index. -The edges are only implicitly represented -through the adjacency relations between their two incident -faces. Each edge has two implicit representations : the edge +The edges are not explicitly represented, they are only implicitely +represented through the adjacency relations of two faces. +Each edge has two implicit representations : the edge of a face \ccc{f} which is opposed to the vertex indexed \ccc{i}, can be represented as well as an edge of the \ccc{neighbor(i)} of -\ccc{f}. See Figure~\ref{I1_Fig_neighbors1}. +\ccc{f}. See Figure~\ref{2D_Triangulation_Fig_neighbors1}. \begin{figure} \begin{ccTexOnly} @@ -225,8 +226,9 @@ can be represented as well as an edge of the \ccc{neighbor(i)} of \includegraphics[width=6cm]{rep_bis.eps} \end{center} \end{ccTexOnly} - \caption{Vertices and neighbors. - \label{I1_Fig_neighbors1}} + \caption{Vertices and neighbors. The function \ccc{ccw(i)} +and \ccc{cw(i)} compute respectively $i+1$ and $i-1$ modulo 3. + \label{2D_Triangulation_Fig_neighbors1}} \begin{ccHtmlOnly}
Neighbors @@ -241,11 +243,10 @@ can be represented as well as an edge of the \ccc{neighbor(i)} of The triangulations classes of \cgal\ provide high-level geometric functionalities such as location of a point in the triangulation~\cite{dpt-wt-02}, insertion -or removal of a point and take care of the geometric validity -of the triangulation. +or removal of a point. They are build as a layer on top of a data structure called the triangulation data structure. -The triangulation data structure can be can be thought +The triangulation data structure can be thought of as a container for the faces and vertices of the triangulation. This data structure also takes care of all the combinatorial aspects of the triangulation. @@ -256,10 +257,10 @@ is reflected in the software design by the fact that the triangulation classes have two template parameters : \begin{itemize} -\item {} the first parameter is to be instanciated by a +\item {} the first parameter stands for a \textbf{geometric traits} class providing the geometric primitives (points, segments and triangles) -forming the triangulation and the elementary +of the triangulation and the elementary operations (predicate or constructions) on those objects. \item {} the second parameter stands for a @@ -267,19 +268,23 @@ operations (predicate or constructions) on those objects. of triangulation data structure is described in Section~\ref{2D_TDS_Concept} of Chapter~\ref{user_chapter_2D_Triangulation_Data_Structure}. -The triangulation data structure defines the classes -used to represent the vertices and faces of the triangulation. -\cgal provide a default triangulation data structure. -To ensure some flexibility, the default triangulation data structure -is templated by two base classes, the vertex base class and the -face base class, from which the vertex and face classes are respectively -derived. +The triangulation data structure defines the types +used to represent the faces and vertices of the triangulation, +as well as additionnal types (handles, iterators and circulators) +to access and visit the faces and vertices. + +\cgal\ provides the class \ccc{Triangulation_data_structure_2} +as a default model of triangulation data structure. +The class \ccc{Triangulation_data_structure_2} +has two template parameters standing for +a vertex base class and a face base class from which the vertex and +face classes are respectively derived. +\cgal\ defines concepts +for these template parameters +and provide default models for these concepts. The vertex and base classes are templated by the geometric traits which allows them to have some knowledge of the geometric primitives of the triangulation. -\cgal defines concepts -for these template parameters -and provide default models for these concepts. Those default vertex and face base classes can be replaced by user customized base classes in order, for example, to deal @@ -288,19 +293,11 @@ of a triangulation. See section~\ref{Section_2D_Triangulations_Flexibility} for more details on the way to make use of this flexibility. \end{itemize} -The Figure~\ref{I1_Fig_three_levels} summarizes the design of the -triangulation package, showing the the three layers +The Figure~\ref{2D_Triangulation_Fig_three_levels} summarizes the design of the +triangulation package, showing the three layers (base classes, triangulation data structure and triangulation) forming this design. -The top triangulation level, responsible for the geometric -embedding of the triangulation comes in different flavors -according to the kind of triangulation represented: -basic, Delaunay, regular, constrained or constrained Delaunay. -Each variant correspond to a different triangulation class -which is described in subsequents -sections. - \begin{figure} \begin{ccTexOnly} \begin{center} @@ -308,7 +305,7 @@ sections. \end{center} \end{ccTexOnly} \caption{The triangulations software design. -\label{I1_Fig_three_levels}} +\label{2D_Triangulation_Fig_three_levels}} \begin{ccHtmlOnly}

@@ -317,8 +314,45 @@ sections. \end{ccHtmlOnly} \end{figure} +The top triangulation level, responsible for the geometric +embedding of the triangulation comes in different flavors +according to the different kind of triangulations: +basic, Delaunay, regular, constrained or constrained Delaunay. +Each kind of triangulations correspond to a different +class. +Figure~\ref{2D_Triangulation_Fig_derivation_tree} summarizes the derivation dependancies +of \cgal\ 2D triangulations classes. +Any 2D triangulation class is parametrized by +a geometric traits and a triangulation data structure. +While a unique concept \ccc{TriangulationDataStructure_2} +describes the triangulation data structure requirements +for any triangulation classes, +the concept of geometric traits actually depends +on the triangulation class. +In general, the requirements for the vertex and face base classes +are described by the basic concepts \ccc{TriangulationVertexBase_2} +and \ccc{TriangulationFaceBase_2}. However, some triangulation +classes requires base classes implementing +refinements +of the basic concepts. +\begin{figure} +\begin{ccTexOnly} +\begin{center} +\includegraphics[width=13cm]{derivation_tree.eps} +\end{center} +\end{ccTexOnly} +\caption{The derivation tree of 2D triangulations.} +\label{2D_Triangulation_Fig_derivation_tree} +\begin{ccHtmlOnly} +
+
+ +
+\end{ccHtmlOnly} +\end{figure} + \section{Basic Triangulations} \label{Section_2D_Triangulations_Basic} @@ -326,41 +360,35 @@ sections. \label{Subsection_2D_Triangulations_Basic_Description} The class \ccc{Triangulation_2} -serves as a base class for all -planar embedded two-dimensional triangulations -in \cgal. -This class expects a model of -of the concept \ccc{TriangulationTraits_2} -as first template argument and a model of the concept -\ccc{TriangulationDataStructure_2} -as second argument. - -The concept -\ccc{TriangulationDataStructure_2} and some models for this concept are -described in chapter~\ref{Chapter_2D_Triangulation_Data_structure}. -The -vertex and face base class used to instanciate the template parameter -of the triangulation data strucure -of a basic triangulation -have to be respectively models for the concepts -\ccc{TriangulationVertexBase_2} and \ccc{TriangulationFaceBase_2}. -\cgal\ provides default models for these concepts -and a default instantiation for the second parameter -of the class \ccc{Triangulation_2}. +serves as a base class for the other +2D triangulations classes +and + implements the user +interface to a triangulation. -The class \ccc{Triangulation_2} implements the user -interface to the triangulation. - +\begin{ccTexOnly} The vertices and faces of the triangulations are accessed through -\ccc{handles}\footnote{ A handle is a type which supports the two -dereference operators \ccc{operator*} and \ccc{operator->}.}, +\ccc{handles} +\footnote{A handle is a type which supports the two +dereference operators \ccc{operator*} and \ccc{operator->}.}, +\ccc{iterators} and \ccc{circulators} +\footnote{A circulator is a type devoted to visit circular sequences.}. +\end{ccTexOnly} + \begin{ccHtmlOnly} +The vertices and faces of the triangulations are accessed through +\ccc{handles}, \ccc{iterators} and \ccc{circulators}. +(A handle is a type which supports the two +dereference operators \ccc{operator*} and \ccc{operator->}, +a circulator is a type devoted to visit circular sequences.) + \end{ccHtmlOnly} Handles are used whenever the accessed element -is not part of a sequence, -iterators and circulators are used -to visit parts of the triangulation. +is not part of a sequence. +iterators and circulators are used +to visit all or parts of the triangulation. + The iterators and circulators are all bidirectional and non mutable. The circulators and iterators are assignable to the @@ -383,8 +411,9 @@ Circulators step through infinite features as well as through finite ones. The triangulation class offers -some iterators to visit all the (finite or infinite) -faces, edges or vertices and also iterators to visit all the finite +some iterators to visit all the +faces, edges or vertices and also iterators to visit +selectively the finite faces, edges or vertices. @@ -413,7 +442,7 @@ The triangulation can be modified by several functions~: insertion of a point, removal of a vertex, flipping of an edge. The flipping of an edge is possible when the union of the two incident faces -forms a convex body (see Figure~\ref{I1_fig_flip_bis}). +forms a convex body (see Figure~\ref{2D_Triangulation_fig_flip_bis}). \begin{figure} \begin{ccTexOnly} @@ -421,8 +450,7 @@ forms a convex body (see Figure~\ref{I1_fig_flip_bis}). \input{flip.ltex} \end{center} \end{ccTexOnly} -\caption{Flip. \label{I1_fig_flip_bis}} - +\caption{Flip. \label{2D_Triangulation_fig_flip_bis}} \begin{ccHtmlOnly}
Flip @@ -474,31 +502,32 @@ building up the triangulation together with the geometric predicates on those objects. The required predicates are: \\ - comparison of the \ccc{x} or \ccc{y} coordinates of two points.\\ -- orientation tests providing \ccc{CGAL_orientation} - corresponding to the order type of three given point. +- the orientation test which computes + the order type of three given point. The concept \ccc{TriangulationTraits_2} describes the requirements for the -geometric traits class of a triangulation -\lcTex{see page (\ccRefPage{TriangulationTraits_2}) of the reference manual}. +geometric traits class of a triangulation. The \cgal\ kernel classes are models for this concept. -The \cgal\ library also provides tighter models +The \cgal\ library also provides dedicated models of \ccc{TriangulationTraits_2} using the kernel geometric objects and predicates. -These classes are themselves templated with a \cgal\ kernel. +These classes are themselves templated with a \cgal\ kernel +and extract the required types and predicates from the kernel. The traits class \ccc{Triangulation_euclidean_traits_2} is designed to deal with ordinary two dimensional points. The class \ccc{Triangulation_euclidean_traits_xy_3} is a geometric traits class to build the triangulation of a terrain. Such a triangulation is a two-dimensional -triangulation embedded the three-dimensional space. +triangulation embedded in three dimensional space. The data points are three-dimensional points. The triangulation is build according to the projections of those points on the $xy$ plane and then lifted up to the original three-dimensional data points. -This is the usual case when dealing with GIS terrains. +This is especially usefull +to deal with GIS terrains. Instead of really projecting the three-dimensional points and maintaining a mapping between each point and its projection (which costs space and is error prone), @@ -516,9 +545,9 @@ respectively. \label{Subsection_2D_Triangulations_Basic_Example} The following program creates a triangulation of 2D points -using the kernel model class \ccc{CGAL::Cartesian} -as geometric traits and the default triangulation data structure -template parameter. +using the default kernel +\ccc{Exact_predicate_inexact_constructions_kernel} +as geometric traits and the default triangulation data structure. The input points are read from a file and inserted in the triangulation. Finally points on the convex hull are written to {\tt cout}. @@ -532,39 +561,18 @@ Finally points on the convex hull are written to {\tt cout}. \label{Subsection_2D_Triangulations_Delaunay_Description} The class \ccc{Delaunay_triangulation_2} is designed to represent the Delaunay triangulation of a set of data points in the plane. -A Delaunay triangulation of a set of points +A Delaunay triangulation fulfills the following {\em empty circle property} (also called {\em Delaunay property}): the circumscribing -circle of any facets of the triangulation +circle of any facet of the triangulation contains no data point in its interior. For a point set with no subset of four cocircular points -the Delaunay triangulation is unique, it is the dual -of the Voronoi diagram of the points. - - -A Delaunay triangulation is a special triangulation of a set of points. -So it is natural to derive -the class \ccc{Delaunay_triangulation_2} -from the basic class \ccc{Triangulation_2}. -Like its base class, the Delaunay triangulation class is parametrized -by two template -parameters, the geometric traits \ccc{Traits} -and the triangulation data structure\ccc{Tds}. -Just like the triangulation data structure -of a basic triangulation, -the triangulation data strucure of a Delaunay triangulation -has to be a model of the concept \ccc{TriangulationDataStructure_2}. -In contrast, because the -concept of Delaunay triangulation relies on the notions of -distance and -empty circles, -the geometric traits has to be a model of the concept -\ccc{DelaunayTriangulationTraits_2} -which refines the concept \ccc{TriangulationTraits_2}. - - +the Delaunay triangulation is unique, it is dual +to the Voronoi diagram of the set of points. +The class \ccc{Delaunay_triangulation_2} derives +from the class \ccc{Triangulation_2}. The class \ccc{Delaunay_triangulation_2} inherits the types defined by the @@ -574,8 +582,8 @@ are defined to represent the dual Voronoi diagram. The class \ccc{Delaunay_triangulation_2} -overwrite the member functions that insert a new point -in the triangulation or +overwrites the member functions that insert a new point +in the triangulation or remove a vertex from it to maintain the Delaunay property. It also has a member function (\ccc{Vertex_handle @@ -589,15 +597,15 @@ The geometric traits has to be a model of the concept \ccc{DelaunayTriangulationTraits_2} which refines the concept \ccc{TriangulationTraits_2}. In particular this concept provides -the \ccc{in_circle(p,q,r,s)} predicate -which decides the position of the point $s$ (interior, exterior -or on the boundary) with respect to the circle +the \ccc{side_of_oriented_circle} predicate +which, given four points \ccc{p,q,r,s} + decides the position of the point $s$ with respect to the circle passing through $p$, $q$ and $r$. -The \ccc{in_circle(p,q,r,s)} +The \ccc{side_of_oriented_circle} predicate actually defines the Delaunay triangulation. Changing this predicate -allows to build Delaunay triangulations for different metrics -such that $L_1$ or $L_{\infty}$ or any metric defined by a +allows to build variant of Delaunay triangulations for different metrics +such that $L_1$ or $L_{\infty}$ metric or any metric defined by a convex object. However, the user of an exotic metric must be careful that the constructed triangulation has to be a triangulation of the convex hull @@ -610,19 +618,14 @@ The \cgal\ kernel classes and the class \ccc{Triangulation_euclidean_traits_2} are models of the concept \ccc{DelaunayTriangulationTraits_2} for the euclidean metric. -\cgal\ also provides traits classes to deal with terrains, -that are two dimensional triangulated surfaces -embedded in the three dimensional space that have project on -a two dimensional Delaunay triangulation. Namely, the traits classes +The traits class for terrains, \ccc{Triangulation_euclidean_traits_xy_3},\\ \ccc{Triangulation_euclidean_traits_yz_3}, and\\ \ccc{Triangulation_euclidean_traits_zx_3} \\ -are to be used to build a a triangulated surface -projecting on the Delaunay triangulation of respectively -the \ccc{xy}, \ccc{yz} or \ccc{zx} projections of its vertices:\\ -The requirements for the duality functions and nearest vertex -queries are not yet satisfied by -these last three classes. +are also models of \ccc{DelaunayTriangulationTraits_2} +excapt that they do not fulfills +the requirements for the duality functions and nearest vertex +queries. \ccHeading{Implementation} The insertion of a new point in the Delaunay triangulation @@ -634,7 +637,7 @@ if the new vertex has degree \ccTexHtml{$d$}{d} in the updated Delaunay triangulation. For points distributed uniformly at random, each insertion takes time \ccTexHtml{$O(1)$}{O(1)} on -average, once the point has benn located in the triangulation. +average, once the point has been located in the triangulation. Removal calls the removal in the triangulation and then retriangulates the hole created in such a way that the Delaunay criterion is @@ -760,13 +763,40 @@ ${ P'}= \{ (p_i,p_i ^2 - w_i ), i = 1, \ldots , n \}$. The class \ccc{Regular_triangulation_2} is designed to maintain the regular triangulation of a set of $2d$ weighted points. -The template parameters \ccc{Traits} and \ccc{Tds} stand respectively - for a geometric traits class and a triangulation data structure class. -The triangulation data structure has to be a model of the concept -\ccc{TriangulationDataStructure_2}. -The geometric traits class must provide a weighted point type -and a power test on these weighted points -and the concept for this parameter, called +It derives from the class \ccc{Triangulation_2}. +The functions \ccc{insert} and +\ccc{remove} are overwritten to handle weighted points +and maintain the regular +property. +The vertices of the regular triangulation +of a set of weighted points ${PW}$ correspond only to a subset +of ${PW}$. +Some of the input +weigthed points have no cell in the dual power diagrams +and therefore do not correspond to a vertex of the regular +triangulation. +Such a point is called a hidden point. +Because hidden points can reappear later on as vertices +when some other point is removed, +they have to be stored somewhere. +The regular triangulation store those points in special vertices, called +hidden vertices. +A hidden point can reappear as vertex of the triangulation +only when the two dimensional face that hides it +is removed from the triangulation. To deal with this feature, +each face of a regular triangulation stores a list of hidden vertices. +The points in those vertices +are reinserted in the triangulation when the face +is removed. + +Regular triangulation have member functions to construct +the vertices and edges of the dual power diagrams. + +\subsubsection{The geometric traits} +The geometric traits of a regular triangulation +must provide a weighted point type +and a power test on these weighted points. +The concept \ccc{RegularTriangulationTraits_2}, is a refinement of the concept \ccc{TriangulationTraits_2}. \cgal\ provides @@ -781,42 +811,14 @@ and uses a \ccc{Weighted_point} type derived from the type \ccc{Point_2} of \ccc{Triangulation_euclidean_traits_2}. - -The class \ccc{Regular_triangulation_2} -derives from the class \ccc{Triangulation_2}. -The functions \ccc{insert} and -\ccc{remove} are overwritten to maintain the regular -property. -The vertices of the regular triangulation -of a set of weighted points ${ PW}$ form only a subset -of the set of center points of ${ PW}$. -Some of the input -weigthed points have no cell in the dual power diagrams -and therefore do not correspond to a vertex of the regular -triangulation. -Such a point is called a hidden point. -Because hidden points can reappear later on the removal -of some other points as a vertex of the triangulation -they have to be store somewhere. -The regular triangulation store those points in special vertices, called -hidden vertices. -A hidden point can reappear as vertex of the triangulation -only when the two dimensional face that hides it -is removed from the triangulation. To detect these events -each face of a regular triangulation stores a list of hidden vertices. - -Regular triangulation have member functions to construct -the vertices and edges of the dual power diagrams. - - \subsubsection{The Vertex type and Face Type of a Regular Triangulation} The base vertex type of a regular triangulation -includes a boolean to mark the hidden or not state of the vertex. +includes a boolean to mark the hidden state of the vertex. Therefore CGAL defines the concept \ccc{RegularTriangulationVertexBase_2} which refine the concept \ccc{TriangulationVertexBase_2} -and provides a default model \ccc{Regular_triangulation_vertex_base_2} +and provides a default model for this concept. The base face type of a regular triangulation @@ -826,14 +828,15 @@ of the concept \ccc{RegularTriangulationFaceBase_2}. \cgal\ provides the templated class \ccc{Regular_triangulation_face_base_2} as a default base class for faces of regular triangulations. -This class derives from \ccc{Triangulation_face_base_2}. + \subsection{Example : a Regular Triangulation} \label{Subsection_2D_Triangulations_Regular_Example} The following code creates a regular triangulation -of a set of weighted points. +of a set of weighted points and ouput the number +of vertices and the number of hidden vertices. \ccIncludeExampleCode{Triangulation_2/regular.C} @@ -852,12 +855,15 @@ The endpoints of constrained edges are of course vertices of the triangulation. However the triangulation may include include other vertices as well. There are three versions of constrained triangulations. +\begin{itemize} +\item In the basic version, the constrained triangulation does not handle intersecting constraints, and the set of input constraints is required to be a set of segments that do not intersect except possibly at their endpoints. Any number of constrained edges are allowed to share the same endpoint. Vertical constrained edges or constrained edges with null length are allowed. +\item The two other versions support intersecting input constraints. In those versions, input constraints are allowed to be intersecting, overlapping or partially @@ -867,10 +873,14 @@ is the proper intersection points of two constraints. A single constraint intersecting other constraints will then appear as several edges in the triangulation. The two versions dealing with intersecting constraints differ -in the way intersecting constraints are dealt with. One of them is +in the way intersecting constraints are dealt with. +\begin{itemize} +\item + One of them is designed to be robust when predicates are evaluated exactly but constructions (i. e. intersection computations) are approximative. +\item The other one is designed to be used with exact arithmetic (meaning exact evaluation of predicates and exact computation of intersections.) @@ -878,7 +888,11 @@ This last version finds its full efficiency when used in conjunction with a constraint hierarchy data structure (which allows one to avoid the cascading of intersection computations) as provided in the class -\ccc{Constrained_triangulation_plus_2}. See section~\ref{Section_2D_Triangulations_Constrained_Plus}. +\ccc{Constrained_triangulation_plus_2}. See +section~\ref{Section_2D_Triangulations_Constrained_Plus}. +\end{itemize} +\end{itemize} + \begin{ccTexOnly} \begin{center} \IpeScale{100} \Ipe{constraints.ipe} \end{center} @@ -893,20 +907,6 @@ constraints and its constrained triangulation"> A constrained triangulation is represented in the CGAL library as an object of the class \ccc{Constrained_triangulation_2}. -The template parameter \ccc{Traits} -stands for a geometric traits class. It has to be a model -of the concept \ccc{TriangulationTraits_2}. -When intersections of input constraints are supported, -the geometric traits class has to be a model -of the concept \ccc{ConstrainedTriangulationTraits_2} -which refines the concept \ccc{TriangulationTraits_2} -providing additional function object types -to compute the intersection of two segments. - -The template parameter \ccc{Tds} -stands for -a triangulation data structure class that has to be a model -of the concept \ccc{TriangulationDataStructure_2}. The third parameter \ccc{Itag} is the intersection tag which serves to choose how intersecting constraints are dealt with. This parameter has to be instantiated @@ -933,22 +933,25 @@ information about constrained edges. The class also allows inline insertion of a new constraint, given by its two endpoints or the removal of a constraint. +\subsubsection{The Geometric Traits} +The geometric traits of a constraint triangulation + has to be a model +of the concept \ccc{TriangulationTraits_2}. +When intersections of input constraints are supported, +the geometric traits class has to be a model +of the concept \ccc{ConstrainedTriangulationTraits_2} +which refines the concept \ccc{TriangulationTraits_2} +providing additional function object types +to compute the intersection of two segments. + \subsubsection{The Base Face of a Constrained Triangulation} The information about constrained edges is stored in the -faces of the triangulation. Thus the nested \ccc{Face} -type of a constrained triangulation offers -additonnal functionalities to deal with this information. -To achieve this, the base face of a Constrained Triangulation +faces of the triangulation. The base face of a Constrained Triangulation has to be a model for the concept \ccc{ConstrainedFaceBase_2} which refines the concept \ccc{TriangulationFaceBase_2}. The concept \ccc{ConstrainedFaceBase_2} -requires a member function -(\ccc{bool is_constrained(int i)}) - providing the status -(constrained ou unconstrained) of the edges -and also a member function -(\ccc{void set_constraint(int i, bool b)}) to set this status. - +requires member functions + the get and set the constrained status of the edges. \cgal\ provides a default base face class for constrained triangulations. This class, named @@ -975,7 +978,7 @@ and adds three booleans to store the status of its edges. the constraining edges are the green edges, a constrained triangulation is shown on the left, the constrained Delaunay triangulation with two examples of circumcircles is shown on the right.} -\label{I1_Fig_constrained} +\label{2D_Triangulation_Fig_constrained} \begin{ccHtmlOnly}
Constrained triangulation @@ -1024,21 +1027,6 @@ The \cgal\ class is designed to represent constrained Delaunay triangulations. -The class is templated by a geometric traits class \ccc{Traits} -and a triangulation data structure \ccc{Tds} and an intersection tag -\ccc{Itag}. -The triangulation data structure has to be a model of the concept -\ccc{TriangulationDataStructure_2}. - The geometric traits -of a constrained Delaunay triangulation is required -to provide the \ccc{side_of_oriented_circle} test as the geometric traits -of a Delaunay triangulation and has to a model of the concept -\ccc{DelaunayTriangulationTraits_2}. When intersecting input -constraints -are supported the geometric traits is further required -to provide function objects to compute constraints intersections. -Then the geometric traits has to be at the same time a model -of the concept \ccc{ConstrainedTriangulationTraits_2}. As in the case of constraints triangulation, the third parameter \ccc{Itag} is the intersection tag and serves to choose how intersecting constraints @@ -1054,13 +1042,6 @@ Therefore the class \ccc{Constrained_Delaunay_triangulation_2} derives from the class \ccc{Constrained_triangulation_2}. -Also, information about the status (constrained or not) -of the edges of the triangulation has to be stored -in the face class - and the base face class -of a constrained Delaunay triangulation has to be a model -of \ccc{ConstrainedFaceBase_2}. - The constrained Delaunay triangulation has member functions to override the @@ -1070,10 +1051,38 @@ to restore the constrained empty circle property. +\subsubsection{The Geometric Traits} + The geometric traits +of a constrained Delaunay triangulation is required +to provide the \ccc{side_of_oriented_circle} predicate as the geometric traits +of a Delaunay triangulation and has to a model of the concept +\ccc{DelaunayTriangulationTraits_2}. When intersecting input +constraints +are supported the geometric traits is further required +to provide function objects to compute constraints intersections. +Then the geometric traits has to be at the same time a model +of the concept \ccc{ConstrainedTriangulationTraits_2}. + + + +\subsubsection{The face base class} +Information about the status (constrained or not) +of the edges of the triangulation has to be stored +in the face class + and the base face class +of a constrained Delaunay triangulation has to be a model +of \ccc{ConstrainedFaceBase_2}. + + + + \subsection{Example : a constrained Delaunay triangulation} \label{Subsection_2D_Triangulations_Constrained_Delaunay_Example} -The following code inputs constraining edges from a file -and build a constrained Delaunay triangulation. +The following code inserts a set of intersecting constraint segments +into a triangulation +and counts the number of constrained edges of the +resulting triangulation. + \ccIncludeExampleCode{Triangulation_2/constrained.C} @@ -1095,10 +1104,8 @@ the base class constructs a triangulation of the arrangement of the constraints, introducing new vertices at each proper intersection points and refining the input constraints into subconstraints -which appear as edges (more precisely constrained edges) of the -triangulation. In this context, the constraint hierarchy -keeps track of the input constraints and of their refinement -in the triangulation. This data structure maintains for each +which appear as edges (more precisely as constrained edges) of the +triangulation. The data structure maintains for each input constraint the sequence of intersection vertices added on this constraint. The constraint hierarchy also allows the user to retrieve the set @@ -1115,7 +1122,7 @@ intersection points. \subsection{Example : Building a triangulated arrangement of segments} -The following code iinserts a set of intersecting constraint segments +The following code inserts a set of intersecting constraint segments into a triangulation and counts the number of constrained edges of the resulting triangulation. @@ -1123,24 +1130,7 @@ resulting triangulation. \ccIncludeExampleCode{Triangulation_2/constrained_plus.C} -Figure~\ref{I1_Fig_derivation_tree} summarize the derivation dependancies -of \cgal\ 2D triandulations. -\begin{figure} -\begin{ccTexOnly} -\begin{center} -\includegraphics[width=13cm]{derivation_tree.eps} -\end{center} -\end{ccTexOnly} -\caption{The derivation tree of 2D triangulations.} -\label{I1_Fig_derivation_tree} -\begin{ccHtmlOnly} -
-
- -
-\end{ccHtmlOnly} -\end{figure} \section{The Triangulation Hierarchy} @@ -1215,8 +1205,8 @@ of a Delaunay triangulation. The program output the number of vertices at the different levels of the hierarchy. \ccIncludeExampleCode{Triangulation_2/hierarchy.C} -the following program shows how to use -a triangulation hierachy in conjonction with a Constrained +The following program shows how to use +a triangulation hierachy in conjonction with a constrained triangulation plus. \ccIncludeExampleCode{Triangulation_2/constrained_hierarchy_plus.C} @@ -1224,31 +1214,32 @@ triangulation plus. \label{Section_2D_Triangulations_Flexibility} -To be able to fulfills various different kind of needs, a hihgly +To be able to adapt to various needs, a highly flexible design has been selected for 2D triangulations. We have already seen that -the main triangulation classes are has two -parameter : a geometric traits class +the triangulation classes have two +parameters : a geometric traits class and a triangulation data structure class which the user can instantiate with his own customized classes. -The most usefull flexibility comes from the fact -that the triangulation data structure has two template +The most usefull flexibility however comes from the fact +that the triangulation data structure itself has two template parameters to be instantiated by base classes for the vertices and faces of the triangulation. The vertex and face classes of the triangulation are derived -from those base classes +from those base classes. Thus, using his own customized classes to instantiate these -parameters. +parameters, the user can easily build up a triangulation with additionnal +informations or functionalities in the vertices and faces. {\bf A cyclic dependancy} -Thus the triangulation data structure is templated by the -vertex and face base classes. However since incidence and adjacency -relations are stored in vertices anf faces, the base classes have to +To insure flexibility, the triangulation data structure is templated by the +vertex and face base classes. Also since incidence and adjacency +relations are stored in vertices and faces, the base classes have to know the types of handles on vertices and faces provided by the triangulation data structure. Thus the vertex and base classes have to be thenselves parameterized by the triangulation data -structure, hence the cyclic dependancy. +structure, and there is a cyclic dependancy on template parameter. \begin{figure} \begin{ccTexOnly} @@ -1257,7 +1248,7 @@ structure, hence the cyclic dependancy. \end{center} \end{ccTexOnly} \caption{The cyclic dependency in triangulations software design. -\label{I1_Fig_three_levels_2}} +\label{2D_Triangulation_Fig_three_levels_2}} \begin{ccHtmlOnly}

@@ -1266,18 +1257,20 @@ structure, hence the cyclic dependancy. \end{ccHtmlOnly} \end{figure} -Previously, this cyclic dependency was avoided by simply -using only void* pointers in interface of base classes -and later converting these void* to appropriate handles at the +Previously, this cyclic dependency was avoided by +using only \ccc{void*} pointers in the interface of base classes. +These \ccc{void*} were converted to appropriate types at the triangulation data structure levels. This solution had some drawbacks -~: mainly it prevented the user to add in the vertices or faces of the +~: mainly the user could not add in the vertices or faces of the triangulation a functionality related to types defined by -the triangulation data structure (face, vertex or handles) -(except through the use of void* pointers). -The new solution to resolve this dependancy +the triangulation data structure, for instance a handle to a vertex, +and he was lead to use himself +\ccc{void*} pointers). +The new solution to resolve the template dependancy is based on a rebind mecanism similar to the mecanism used in the standard allocator class std::allocator. The rebind mecanism -is described in Section~\ref{} of Chapter~\ref{}. +is described in Section~\ref{2D_TDS_default} +of Chapter~\ref{Chapter_2D_Triangulation_Data_Structure}. For now, we will just notice that the design requires the existence in the vertex and face base classes @@ -1287,19 +1280,20 @@ the rebinding mecanism. The two following examples aim to show how the user -can still put in use the flexibility offered by the +can put in use the flexibility offered by the base classes parameters. {\bf Adding colors} -The first example correspond to a case where the user wishes to add in +The first example corresponds to a case where the user wishes to add in the vertices or faces of the triangulation an additional information that do not depend on types provided by the triangulation data structure. -In that case he (or she) can make use of the predefined classes +In that case, predefined classes \ccc{Triangulation_vertex_base_with_info_2} or \ccc{Triangulation_face_base_with_info_2} -whose parameter \ccc{Info} to be instantiated by the type of the -added information. +can be used. Those classes have +a template parameter \ccc{Info} devoted to +handle additionnal information. The following examples shows how to add a \ccc{CGAL::Color} in the triangulation faces. @@ -1307,9 +1301,9 @@ The following examples shows how to add a \ccIncludeExampleCode{Triangulation_2/colored_face.C} {\bf Adding handles} -The second examples show how the user can still +The second examples shows how the user can still derive and plug in his own vertex base -or face base when he would like to have in vertices or faces +or face base when he would like to have additionnal functionalities depending on types provided by the triangulation data structure. diff --git a/Packages/Triangulation_2/doc_tex/basic/Makefile b/Packages/Triangulation_2/doc_tex/basic/Makefile index b0e8fecd492..9d3313eed4e 100644 --- a/Packages/Triangulation_2/doc_tex/basic/Makefile +++ b/Packages/Triangulation_2/doc_tex/basic/Makefile @@ -1,5 +1,5 @@ -LATEX_CONV_INPUTS=.:../../examples:Triangulation_2:TDS_2: -TEXINPUTS=.:/0/prisme_util/latex:/u/abeille/0/prisme/yvinec/tex/inputs:Triangulation_2:TDS_2:../../examples: +LATEX_CONV_INPUTS=.:../../examples:Triangulation_2:TDS_2:Triangulation_2_ref:TDS2_ref: +TEXINPUTS=.:/0/prisme_util/latex:/u/abeille/0/prisme/yvinec/tex/inputs:Triangulation_2:TDS_2:../../examples:Triangulation_2_ref:TD2_ref: doc: latex wrapper; @@ -16,9 +16,13 @@ Doc_html : mkdir -p ../../doc_html/basic/TDS_2_ref cc_manual_to_html -o ../../doc_html/basic/Triangulation_2 \ Triangulation_2/main.tex + cp Triangulation_2/*.gif ../../doc_html/basic/Triangulation_2 cc_manual_to_html -o ../../doc_html/basic/Triangulation_2_ref \ - Triangulation_2_ref/main.tex + Triangulation_2_ref/main.tex + cp Triangulation_2_ref/*.gif ../../doc_html/basic/Triangulation_2_ref cc_manual_to_html -o ../../doc_html/basic/TDS_2 \ TDS_2/main.tex + cp TDS_2/*.gif ../../doc_html/basic/TDS_2 cc_manual_to_html -o ../../doc_html/basic/TDS_2_ref \ TDS_2_ref/main.tex + cp TDS_2_ref/*.gif ../../doc_html/basic/TDS_2_ref diff --git a/Packages/Triangulation_2/doc_tex/basic/TDS_2/rep_bis.gif b/Packages/Triangulation_2/doc_tex/basic/TDS_2/rep_bis.gif new file mode 100644 index 00000000000..371a49b4d17 Binary files /dev/null and b/Packages/Triangulation_2/doc_tex/basic/TDS_2/rep_bis.gif differ diff --git a/Packages/Triangulation_2/doc_tex/basic/TDS_2/tds_user.tex b/Packages/Triangulation_2/doc_tex/basic/TDS_2/tds_user.tex index e42fb753dfc..57cd7eb54ae 100644 --- a/Packages/Triangulation_2/doc_tex/basic/TDS_2/tds_user.tex +++ b/Packages/Triangulation_2/doc_tex/basic/TDS_2/tds_user.tex @@ -4,35 +4,105 @@ \label{Chapter_2D_Triangulation_Data_structure} \minitoc -The second template parameter of a 2D triangulation class -has to be instanciated with a model -of \ccc{TriangulationDataStructure_2}. -Section~\ref{2D_TDS_Concept} describes the concept -of \ccc{TriangulationDataStructure_2}. -Section~\ref{2D_TDS_default} describes the -class \ccc{CGAL::Triangulation_data_structure_2} -which is the default model provided for this concept. -To ensure to the triangulation classes all the flexibility -described in Chapter~\ref{user_chapter_2D_Triangulations} -the default model derives its \ccc{Vertex} and \ccc{Face} types -from the two template parameters \ccc{Vb} and \ccc{Fb} -which have to be models for the base vertex and face -classes. -Section~\ref{2D_TDS_Base_Classes} described the base -vertex and face classes of a triangulation. -At last, section~\ref{2D_TDS_Example} shows -how the user can plug in the triangulation -data structure his own vertex or face base class. -\section{The Concept} +\section{Definition} + +A triangulation data structure is a data structure designed +to handle the representation of a two dimensional +triangulation. The concept of triangulation data structure +was primarily designed to serve as a data structure +for \cgal\ 2D triangulation classes which are triangulations +embedded in a plane. +However it appears that the concept is more general +and can be used for any orientable triangulated surface +without boundary, whatever may be the dimensionality +of the space the trianguation is embedded in. + + +\subsection{A data structure based on faces and vertices} + +The representation of \cgal\ 2D triangulations is based on faces and vertices, +Edges are only implicitely +represented trough the adjacency relations betwen two +faces. + +The triangulation data structure can be seen +as a container for faces and vertices +maintaining incidence and adjacency relations +among them. + +Each triangular face gives access to its three incident vertices +and to its three adjacent faces. +Each vertex gives access to one of its incident faces +and through that face to the circular list of its incident faces. + +The three vertices of a face are indexed with 0, 1 and 2. +The neighbor of a face are also +indexed with 0,1,2 in such a way that the neighbor indexed by \ccc{i} +is opposite to the vertex with the same index. + +Each edge has two implicit representations : the edge +of a face \ccc{f} which is opposed to the vertex indexed \ccc{i}, +can be represented as well as an edge of the \ccc{neighbor(i)} of +\ccc{f}. See Figure~\ref{2D_Triangulation_Fig_neighbors1}. + + \begin{figure} +\begin{ccTexOnly} + \begin{center} + \includegraphics[width=6cm]{rep_bis.eps} + \end{center} +\end{ccTexOnly} + \caption{Vertices and neighbors. The function \ccc{ccw(i)} +and \ccc{cw(i)} compute respectively $i+1$ and $i-1$ modulo 3. + \label{2D_TDS_Fig_neighbors1}} + \begin{ccHtmlOnly} +
+Neighbors +
+\end{ccHtmlOnly} +\end{figure} + + + +This kind or representation of simplicial complexes extends in any +dimension. More precisely, in dimension $d$, the data structure +will explicitely represents cells (i. e. faces of maximal dimension) +and vertices (i. e. faces of dimension 0). +All faces of dimension between $1$ and $d-1$ +will have an implicit representation. +The 2D triangulation data structure can represent simplicial complexes +of dimension 2, 1 or 0. + +\subsection{The set of faces and vertices} + The set of faces maintained by a 2D triangulation +data structure is such that each edge +is incident to two faces. In other words, +the set of maintained faces +is topologically +equivalent to a two-dimensional triangulated sphere. + +This rules extends to lower dimensional triangulation data structure +arising in degenerate cases or when the triangulations +have less than three vertices. +A one dimensional triangulation structure maintains a set of vertices + and edges which forms a ring +topologically equivalent to a $1$-sphere. + +A zero dimensional triangulation data structure +only includes two adjacent vertices +that is +topologically equivalent to a $0$-sphere. + + +\section{The Concept of Triangulation Data Structure} \label{2D_TDS_Concept} A model of \ccc{TriangulationDataStructure_2} can be seen has a container for the faces and vertices of the triangulation. This class is also responsible for the combinatorial integrity of the triangulation. This means that -the triangulation data strutcure +the triangulation data structure maintains proper incidence and adjacency relations among the vertices and faces of a triangulation while combinatorial modifications @@ -73,13 +143,14 @@ of the triangulation. The triangulation data structure provides member functions to perform the following combinatorial transformation of the triangulation:\\ -flip of two adjacent faces, \\ -addition of a new vertex splitting a given face,\\ -addition of a new vertex splitting a given edge,\\ -addition of a new vertex raising by one the dimension of a degenerate -lower dimensional triangulation, \\ -removal of a vertex incident to three faces, \\ -removal of a vertex lowering the dimension of the triangulation.\\ +-- flip of two adjacent faces, \\ +-- addition of a new vertex splitting a given face +see Figure~\ref{2D_TDS_Fig_insertion},\\ +-- addition of a new vertex splitting a given edge,\\ +-- addition of a new vertex raising by one the dimension of a degenerate +-- lower dimensional triangulation, \\ +-- removal of a vertex incident to three faces, \\ +-- removal of a vertex lowering the dimension of the triangulation.\\ %\begin{figure} @@ -88,7 +159,7 @@ removal of a vertex lowering the dimension of the triangulation.\\ %\input{flip.ltex} %\end{center} %\end{ccTexOnly} -%\caption{Flip. \label{I1_fig_flip_bis}} +%\caption{Flip. \label{{2D_Triangulation_fig_flip_bis}} %\begin{ccHtmlOnly} %
@@ -103,9 +174,9 @@ removal of a vertex lowering the dimension of the triangulation.\\ \begin{ccTexOnly} %\begin{center} \IpeScale{70} \Ipe{Three.ipe} \end{center} \begin{center} \input{insert.ltex} \end{center} -\caption{Insertion} \end{ccTexOnly} - +\caption{Insertion of a new vertex, splitting a face} + \label{2D_TDS_Fig_insertion} \begin{ccHtmlOnly}
Insertion @@ -120,77 +191,186 @@ removal of a vertex lowering the dimension of the triangulation.\\ \cgal\ provides the class \ccc{CGAL::Triangulation_data_structure_2} as a default triangulation data structure. -The two template parameters \ccc{Vb} and \ccc{Fb} -have to be respectively models of the concept -\ccc{TriangulationVertexBase_2} and -\ccc{TriangulationFaceBase_2} which describe the requirements for the -base vertex and face classes of a triangulation. + + +\subsection{Flexibility} +In oder to provide flexibility, the default triangulation data +structure is templated by two parameters +which stands respectively for a vertex base class and a face base +class. +The concept +\ccc{TriangulationDSVertexBase_2} and +\ccc{TriangulationDSFaceBase_2} describe the requirements for the +base vertex and face classes of a triangulation data structure. The triangulation data structure derives from thoses base classes the -vertex and face classes of the triangulations. +vertex and face classes from thoses base classes. This design allows the user to plug in the triangulation data structure his own base classes tuned for his application. +\subsection{The cyclic dependancy of template parameters} + Since adjacency and incidence relation are stored in vertices and +faces, +the vertex and face base classes have to know the types +of handles on faces and vertices provided by the triangulation data +structure. +Therefore , vertex and base classes need to be templated +by the triangulation data structure. Because the triangulation +data structure +is itself templated by the vertex and base classes this induces +a cyclic dependancy. +See figure~\ref{2D_TDS_Fig_three_levels_2}. + +\begin{figure} +\begin{ccTexOnly} +\begin{center} +\includegraphics[width=13cm]{threelevels2.eps} +\end{center} +\end{ccTexOnly} +\caption{The cyclic dependency in triangulations software design. +\label{2D_TDS_Fig_three_levels_2}} +\begin{ccHtmlOnly} +
+
+Three_levels +
+\end{ccHtmlOnly} +\end{figure} + + +\subsection{The rebind mecanism} + +The solution proposed by \cgal\ to resolve this cyclic dependency +is based on a rebind mecanism similar to the mecanism used in the +standard allocator class std::allocator. +The vertex and face base classes plugged in the instantiation of a +triangulation data structure are themselves instantiated with a +fake data structure. The triangulation data structure +will then rebind these classes, plugging itself +at the place of the fake data structure, before using them +to derive the vertex and face classes. The rebinding is performed +through a nested template class \ccc{Rebind_TDS} in the vertex and +face base class, which provide the rebound class +as a type called \ccc{Other}. + +Here is how it works schematically. First, here is the rebinding +taking place in the triangulation data stucture. +\begin{ccExampleCode} +template < class Vb, class Fb > +class Triangulation_data_structure +{ + typedef Triangulation_data_structure Self; + + // Rebind the vertex and cell base to the actual TDS (Self). + typedef typename Vb::template Rebind_TDS::Other VertexBase; + typedef typename Fb::template Rebind_TDS::Other FaceBase; + + // ... further internal machinery leads to the final public types: +public: + typedef ... Vertex; + typedef ... Face; + typedef ... Vertex_handle; + typedef ... Face_handle; +}; +\end{ccExampleCode} + +Then, here is the vertex base class with its nested + \ccc{Rebind_TDS} template class and its template parameter +set by default to an an internal type faking a triangulation data +structure. +\begin{ccExampleCode} +template < class TDS = an internal type faking a triangulation data +structure > +class Vertex_base +{ +public: + template < class TDS2 > + struct Rebind_TDS { + typedef Vertex_base Other; + }; +... +}; +\end{ccExampleCode} +Imagine an analog \ccc{Face_base} class. +The triangulation data structure is then instantiate as follows~: +\begin{ccExampleCode} +typedef Triangulation_data_structure< Vertex_base<>, Face_base<> > TDS; +\end{ccExampleCode} + + +\subsection{Making use of the flexibility} + +There is several possibilities to make use +of the flexibility offered by +the triangulation data structure. +\begin{itemize} +\item{} First, when the user needs to have, +in vertices and faces, additionnal informations +which do not depend on types defined by the +triangulated data structure, predefined classes +\ccc{Triangulation_vertex_base_with_info} +and \ccc{Triangulation_face_base_with_info} can be plugged in. +Those classes have a template parameter \ccc{Info} to be instantiated +by a user defined type. They +store a data member of this type and gives acces to it. +\item{} Second, the user can derive +his own base classes from the default base +classes : +\ccc{Triangulation_ds_vertex_base_2}, and +\ccc{Triangulation_ds_cell_base_2} +are the default base classes to be plugged in a triangulation +data structure used alone. +Triangulation classes requires a data strucure in which +other base classes have been plugged it. The default base classes +for most of the triangulation classes are +\ccc{Triangulation_vertex_base_2}, and \ccc{Triangulation_face_base_2} +are the default base classes to be used when the triangulation data +structure is plugged in a triangulation class. + +When derivation is used, the rebind mecanism is slightly +more involved, because it is necessary to rebind the base class +itself. However the user will be able to use in his classes +references to types provided by the triangulation data structure. +For example, +\begin{ccExampleCode} +template < class Gt, class Vb = CGAL::Triangulation_vertex_base_2 > +class My_vertex_base + : public Vb +{ +public : + template < typename TDS2 > + struct Rebind_TDS { + typedef typename Vb::template Rebind_TDS::Other Vb2; + typedef My_vertex_base Other; + }; + + typedef typename Vb::Triangulation_data_structure Tds; + typedef typename Tds::Vertex_handle Vertex_handle; + ...... +}; +\end{ccExampleCode} + +\item{} At last the user can write his own base classes. +If the triangulation data structure is used alone, +the requirements for the base classes are described by the concepts +\ccc{TriangulationDSVertexBase_2} +and \ccc{TriangulationDSFaceBase_2}\lcTex{, + documented \ccRefPage{TriangulationDSVertexBase_2} and +\ccRefPage{TriangulationDSFaceBase_2}}. +If the triangulation data structure is plugged into a triangulation +class, +the concepts for the vertex and base classes depends on the +triangulation class. The most basic concepts, valid for +basic and Delaunay triangulations are \ccc{TriangulationVertexBase_2} +and \ccc{TriangulationFaceBase_2}\lcTex{, documented +\ccRefPage{TriangulationVertexBase_2} +and \ccRefPage{TriangulationFaceBase_2}}. +\end{itemize} + + See section~\ref{Section_2D_Triangulations_Flexibility} +for examples of using the triangulation data structure flexibility. -\section{The Base Vertex and Face Classes } -\label{2D_TDS_Base_Classes} - -\subsection*{The concepts} -The concepts \ccc{TriangulationVertexBase_2} and -\ccc{TriangulationFaceBase_2} described the requirements -for the base vertex and face classes of a two-dimensional -triangulation. - -At the bottom layer, -a vertex is required to provide access to the embedding point -and to one of its incident face -through a \ccc{void *} pointer. - -At the bottom layer, a -face provides access to its three vertices and to its three -neighboring faces through \ccc{void *} pointers. -The vertices and neighbors are indexed 0,1 and 2 in counterclockwise -order around the face. The neighbor indexed \ccc{i} - lies opposite to vertex with the same index. - - - -\subsection*{The Default Models} -\cgal\ provides the models -\ccc{Triangulation_face_base_2} and -\ccc{Triangulation_vertex_base_2} for -respectively -the \ccc{TriangulationVertexBase_2} and the -\ccc{TriangulationFaceBase_2} concepts. -Both of them are templated by a geometric traits class. -Using for this traits class, the geometric traits class used for the triangulation class -is strongly recommended. -It ensures that the point type defined by \ccc{Triangulation_vertex_base_2} -is the same as the point type defined the geometric traits class of -the triangulation. - -These default base classes can be used directly or can serve as a base to derive -other base classes with some additional attribute (a color for example) -tuned for a specific application. - - -\section{Example : Using one's own Base Face} -\label {2D_TDS_Example} - -The following example derives a new base face class from the default -one and adds a color to the faces of the triangulation. -The face of the triangulation data structure -and the face of the triangulation will inherit the new data member -and its functionality. -Any kind of additional functionality can thus be added to faces or vertices of a triangulation -as long as this functionality does not involve additional pointers to vertices or faces -(because the base classes use only void* pointer and have no knowledge -of the vertex or face types.). - -\ccExample -\ccIncludeExampleCode{Triangulation_2/colored_face.C} - diff --git a/Packages/Triangulation_2/doc_tex/basic/TDS_2/threelevels2.gif b/Packages/Triangulation_2/doc_tex/basic/TDS_2/threelevels2.gif new file mode 100644 index 00000000000..36e4b2b8fba Binary files /dev/null and b/Packages/Triangulation_2/doc_tex/basic/TDS_2/threelevels2.gif differ diff --git a/Packages/Triangulation_2/doc_tex/basic/Triangulation_2/triangulation_user.tex b/Packages/Triangulation_2/doc_tex/basic/Triangulation_2/triangulation_user.tex index cb4ce4bf4a3..eaed9de856e 100644 --- a/Packages/Triangulation_2/doc_tex/basic/Triangulation_2/triangulation_user.tex +++ b/Packages/Triangulation_2/doc_tex/basic/Triangulation_2/triangulation_user.tex @@ -23,9 +23,9 @@ of \cgal. Section~\ref{Section_2D_Triangulations_Definitions} recalls the main definitions about triangulations. Sections~\ref{Section_2D_Triangulations_Representation} discusses -the way two-dimensional triangulations are represented in \cgal\. +the way two-dimensional triangulations are represented in \cgal\ . Section~\ref{Section_2D_Triangulations_Software_Design} presents -and the overall software +the overall software design of the 2D triangulations package. The next sections present the different two dimensional triangulations classes available in \cgal\ : @@ -40,26 +40,28 @@ and constrained Delaunay triangulations (Section~\ref{Section_2D_Triangulations_Constrained_Delaunay}). Section~\ref{Section_2D_Triangulations_Constrained_Plus} describes a class which implements a constrained or -constrained Delaunay triangulation together with -a hierarchiacal data structure on the constraints. +constrained Delaunay triangulation with +an additionnal data structure +to describe how the constraints are refined +by the edges of the triangulations. Section~\ref{Section_2D_Triangulations_Hierarchy} describes a hierarchical data structure for fast point location queries. At last, Section~\ref{Section_2D_Triangulations_Flexibility} -explain how to benefit from the flexibility +explains how the user can benefit from the flexibility of \cgal\ triangulations using customized classes for faces and vertices. \section{Definitions} \label{Section_2D_Triangulations_Definitions} -A two dimensional triangulation can be simply described as a set $T$ +A two dimensional triangulation can be roughly described as a set $T$ of triangular facets such that~:\\ - two facets either are disjoint or share a lower dimensional face (edge or vertex).\\ - the set of facets in $T$ is connected for the adjacency relation. \\ -- the domain $U_T$ of the triangulation which is the union -of facets in $T$ has no singularity. +- the domain $U_T$ which is the union +of facets in $T$ has no singularity. More precisely, a triangulation can be described @@ -101,25 +103,25 @@ that all pairs of incident facets have consistent orientations. The data stucture underlying \cgal\ triangulations allows to represent the combinatorics of any orientable two dimensional triangulations -without boundaries. However, taking care -of the geometric embedding, -the two dimensional triangulations of \cgal\ are mainly -designed to represent planar triangulations. +without boundaries. +On top of this data structure, the 2D triangulations classes +take care of the geometric embedding of the triangulation +and are designed to handle planar triangulations. The plane of the tiangulation may be embedded in a higher dimensional space. -The triangulation \cgal\ are complete -meaning that their domain always covers the +The triangulations of \cgal\ are complete triangulations +which means that their domain is the convex hull of their vertices. -Because any planar two dimensional triangulation +Because any planar triangulation can be completed, this is not a real restriction. For instance, a triangulation of a polygonal region can be -constructed as a subset of a constrained triangulation -where the edges bounding the region have been input as +constructed and represented as a subset of a constrained triangulation +in which the region boundary edges have been input as constrained edges (see Section~\ref{Section_2D_Triangulations_Constrained}, \ref{Section_2D_Triangulations_Constrained_Delaunay} and -\ref{Section_2D_Triangulations_Constrained_Plus}.) +\ref{Section_2D_Triangulations_Constrained_Plus}). Strictly speaking, the term {\em face} should be used to design a face of any dimension, @@ -132,42 +134,43 @@ of a two dimensional triangulation. \section{Representation} \label{Section_2D_Triangulations_Representation} -\subsubsection{The set of represented faces} +\subsubsection{The set of faces} -A triangulation of \cgal\ can be viewed as a planar partition +A 2D triangulation of \cgal\ can be viewed as a planar partition whose bounded faces are triangular and cover -the convex hull of the set ${ A}$ of vertices. +the convex hull of the set of vertices. The single unbounded face of this partition -is the complementary of the convex hull of ${ A}$. +is the complementary of the convex hull. In many applications, such as Kirkpatrick's hierarchy or incremental Delaunay construction, it is convenient to deal with only triangular faces. Therefore, a fictitious vertex, called the \ccc{infinite vertex} -is added to the triangulation and the triangulation -includes additionnal \ccc{infinite edges} and \ccc{infinite faces}. +is added to the triangulation as well as +\ccc{infinite edges} and \ccc{infinite faces} incident to it.. Each infinite edge -is incident to the infinite vertex and a vertex of the convex hull. +is incident to the infinite vertex and to a vertex of the convex hull. Each infinite face is incident to the infinite vertex and to a convex hull edge. - In that way, each edge of the triangulation + +Therefore, each edge of the triangulation is incident to exactly two faces -and the set of faces (of a triangulation is topologically +and the set of faces of a triangulation is topologically equivalent to a two-dimensional sphere. -This is also true -in special cases of triangulations with lower dimensions -arising either in degenerate cases or when the triangulations +This extends to lower dimensional triangulations +arising in degenerate cases or when the triangulations as less than three vertices. -With the infinite vertex and edges, a one dimensional -is a one ring of edges and vertices -topologically equivalent to a $1$-sphere -and a zero dimensional triangulation whose domain is reduced to a -single point is formed with two vertices that is -topologically equivalent to a $0$-sphere +Including the infinite faces, +a one dimensional triangulation +is a ring of edges and vertices +topologically equivalent to a $1$-sphere. +A zero dimensional triangulation, whosedomain is reduced to a +single point, is represented by two vertices that is +topologically equivalent to a $0$-sphere. Note that the \ccc{infinite vertex} has no significant coordinates and that no geometric predicate can be applied on it -or on an infinite face. +nor on an infinite face. \begin{figure} \begin{ccTexOnly} @@ -175,8 +178,8 @@ or on an infinite face. \includegraphics{infinite.eps} \end{center} \end{ccTexOnly} -\caption{The infinite vertex. -\label{I1_Fig_infinite_vertex}} +\caption{Infinite vertex and infinite faces +\label{2D_Triangulation_Fig_infinite_vertex}} \begin{ccHtmlOnly}
Vertices at @@ -189,7 +192,7 @@ infinity \subsubsection{ A representation based on faces and vertices} -Because a triangulation is merely a set of +Because a triangulation is a set of triangular faces with constant-size complexity, triangulations are not implemented as a layer on top of a planar map. @@ -199,25 +202,23 @@ rather than on edges. Such a representation saves storage space and results in faster algorithms~ \cite{bdty-tcgal-00}. -Thus the basic elements of the representation are vertices and faces. +The basic elements of the representation are vertices and faces. Each triangular face gives access to its three incident vertices and to its three adjacent faces. Each vertex gives access to one of its incident faces and through that face to the circular list of its incident faces. -The edges are not explicitly represented, they are only represented -through the adjacency relations of two faces. The three vertices of a face are indexed with 0, 1 and 2 in counterclockwise order. The neighbor of a face are also indexed with 0,1,2 in such a way that the neighbor indexed by \ccc{i} is opposite to the vertex with the same index. -The edges are only implicitly represented -through the adjacency relations between their two incident -faces. Each edge has two implicit representations : the edge +The edges are not explicitly represented, they are only implicitely +represented through the adjacency relations of two faces. +Each edge has two implicit representations : the edge of a face \ccc{f} which is opposed to the vertex indexed \ccc{i}, can be represented as well as an edge of the \ccc{neighbor(i)} of -\ccc{f}. See Figure~\ref{I1_Fig_neighbors1}. +\ccc{f}. See Figure~\ref{2D_Triangulation_Fig_neighbors1}. \begin{figure} \begin{ccTexOnly} @@ -225,8 +226,9 @@ can be represented as well as an edge of the \ccc{neighbor(i)} of \includegraphics[width=6cm]{rep_bis.eps} \end{center} \end{ccTexOnly} - \caption{Vertices and neighbors. - \label{I1_Fig_neighbors1}} + \caption{Vertices and neighbors. The function \ccc{ccw(i)} +and \ccc{cw(i)} compute respectively $i+1$ and $i-1$ modulo 3. + \label{2D_Triangulation_Fig_neighbors1}} \begin{ccHtmlOnly}
Neighbors @@ -241,11 +243,10 @@ can be represented as well as an edge of the \ccc{neighbor(i)} of The triangulations classes of \cgal\ provide high-level geometric functionalities such as location of a point in the triangulation~\cite{dpt-wt-02}, insertion -or removal of a point and take care of the geometric validity -of the triangulation. +or removal of a point. They are build as a layer on top of a data structure called the triangulation data structure. -The triangulation data structure can be can be thought +The triangulation data structure can be thought of as a container for the faces and vertices of the triangulation. This data structure also takes care of all the combinatorial aspects of the triangulation. @@ -256,10 +257,10 @@ is reflected in the software design by the fact that the triangulation classes have two template parameters : \begin{itemize} -\item {} the first parameter is to be instanciated by a +\item {} the first parameter stands for a \textbf{geometric traits} class providing the geometric primitives (points, segments and triangles) -forming the triangulation and the elementary +of the triangulation and the elementary operations (predicate or constructions) on those objects. \item {} the second parameter stands for a @@ -267,19 +268,23 @@ operations (predicate or constructions) on those objects. of triangulation data structure is described in Section~\ref{2D_TDS_Concept} of Chapter~\ref{user_chapter_2D_Triangulation_Data_Structure}. -The triangulation data structure defines the classes -used to represent the vertices and faces of the triangulation. -\cgal provide a default triangulation data structure. -To ensure some flexibility, the default triangulation data structure -is templated by two base classes, the vertex base class and the -face base class, from which the vertex and face classes are respectively -derived. +The triangulation data structure defines the types +used to represent the faces and vertices of the triangulation, +as well as additionnal types (handles, iterators and circulators) +to access and visit the faces and vertices. + +\cgal\ provides the class \ccc{Triangulation_data_structure_2} +as a default model of triangulation data structure. +The class \ccc{Triangulation_data_structure_2} +has two template parameters standing for +a vertex base class and a face base class from which the vertex and +face classes are respectively derived. +\cgal\ defines concepts +for these template parameters +and provide default models for these concepts. The vertex and base classes are templated by the geometric traits which allows them to have some knowledge of the geometric primitives of the triangulation. -\cgal defines concepts -for these template parameters -and provide default models for these concepts. Those default vertex and face base classes can be replaced by user customized base classes in order, for example, to deal @@ -288,19 +293,11 @@ of a triangulation. See section~\ref{Section_2D_Triangulations_Flexibility} for more details on the way to make use of this flexibility. \end{itemize} -The Figure~\ref{I1_Fig_three_levels} summarizes the design of the -triangulation package, showing the the three layers +The Figure~\ref{2D_Triangulation_Fig_three_levels} summarizes the design of the +triangulation package, showing the three layers (base classes, triangulation data structure and triangulation) forming this design. -The top triangulation level, responsible for the geometric -embedding of the triangulation comes in different flavors -according to the kind of triangulation represented: -basic, Delaunay, regular, constrained or constrained Delaunay. -Each variant correspond to a different triangulation class -which is described in subsequents -sections. - \begin{figure} \begin{ccTexOnly} \begin{center} @@ -308,7 +305,7 @@ sections. \end{center} \end{ccTexOnly} \caption{The triangulations software design. -\label{I1_Fig_three_levels}} +\label{2D_Triangulation_Fig_three_levels}} \begin{ccHtmlOnly}

@@ -317,8 +314,45 @@ sections. \end{ccHtmlOnly} \end{figure} +The top triangulation level, responsible for the geometric +embedding of the triangulation comes in different flavors +according to the different kind of triangulations: +basic, Delaunay, regular, constrained or constrained Delaunay. +Each kind of triangulations correspond to a different +class. +Figure~\ref{2D_Triangulation_Fig_derivation_tree} summarizes the derivation dependancies +of \cgal\ 2D triangulations classes. +Any 2D triangulation class is parametrized by +a geometric traits and a triangulation data structure. +While a unique concept \ccc{TriangulationDataStructure_2} +describes the triangulation data structure requirements +for any triangulation classes, +the concept of geometric traits actually depends +on the triangulation class. +In general, the requirements for the vertex and face base classes +are described by the basic concepts \ccc{TriangulationVertexBase_2} +and \ccc{TriangulationFaceBase_2}. However, some triangulation +classes requires base classes implementing +refinements +of the basic concepts. +\begin{figure} +\begin{ccTexOnly} +\begin{center} +\includegraphics[width=13cm]{derivation_tree.eps} +\end{center} +\end{ccTexOnly} +\caption{The derivation tree of 2D triangulations.} +\label{2D_Triangulation_Fig_derivation_tree} +\begin{ccHtmlOnly} +
+
+ +
+\end{ccHtmlOnly} +\end{figure} + \section{Basic Triangulations} \label{Section_2D_Triangulations_Basic} @@ -326,41 +360,35 @@ sections. \label{Subsection_2D_Triangulations_Basic_Description} The class \ccc{Triangulation_2} -serves as a base class for all -planar embedded two-dimensional triangulations -in \cgal. -This class expects a model of -of the concept \ccc{TriangulationTraits_2} -as first template argument and a model of the concept -\ccc{TriangulationDataStructure_2} -as second argument. - -The concept -\ccc{TriangulationDataStructure_2} and some models for this concept are -described in chapter~\ref{Chapter_2D_Triangulation_Data_structure}. -The -vertex and face base class used to instanciate the template parameter -of the triangulation data strucure -of a basic triangulation -have to be respectively models for the concepts -\ccc{TriangulationVertexBase_2} and \ccc{TriangulationFaceBase_2}. -\cgal\ provides default models for these concepts -and a default instantiation for the second parameter -of the class \ccc{Triangulation_2}. +serves as a base class for the other +2D triangulations classes +and + implements the user +interface to a triangulation. -The class \ccc{Triangulation_2} implements the user -interface to the triangulation. - +\begin{ccTexOnly} The vertices and faces of the triangulations are accessed through -\ccc{handles}\footnote{ A handle is a type which supports the two -dereference operators \ccc{operator*} and \ccc{operator->}.}, +\ccc{handles} +\footnote{A handle is a type which supports the two +dereference operators \ccc{operator*} and \ccc{operator->}.}, +\ccc{iterators} and \ccc{circulators} +\footnote{A circulator is a type devoted to visit circular sequences.}. +\end{ccTexOnly} + \begin{ccHtmlOnly} +The vertices and faces of the triangulations are accessed through +\ccc{handles}, \ccc{iterators} and \ccc{circulators}. +(A handle is a type which supports the two +dereference operators \ccc{operator*} and \ccc{operator->}, +a circulator is a type devoted to visit circular sequences.) + \end{ccHtmlOnly} Handles are used whenever the accessed element -is not part of a sequence, -iterators and circulators are used -to visit parts of the triangulation. +is not part of a sequence. +iterators and circulators are used +to visit all or parts of the triangulation. + The iterators and circulators are all bidirectional and non mutable. The circulators and iterators are assignable to the @@ -383,8 +411,9 @@ Circulators step through infinite features as well as through finite ones. The triangulation class offers -some iterators to visit all the (finite or infinite) -faces, edges or vertices and also iterators to visit all the finite +some iterators to visit all the +faces, edges or vertices and also iterators to visit +selectively the finite faces, edges or vertices. @@ -413,7 +442,7 @@ The triangulation can be modified by several functions~: insertion of a point, removal of a vertex, flipping of an edge. The flipping of an edge is possible when the union of the two incident faces -forms a convex body (see Figure~\ref{I1_fig_flip_bis}). +forms a convex body (see Figure~\ref{2D_Triangulation_fig_flip_bis}). \begin{figure} \begin{ccTexOnly} @@ -421,8 +450,7 @@ forms a convex body (see Figure~\ref{I1_fig_flip_bis}). \input{flip.ltex} \end{center} \end{ccTexOnly} -\caption{Flip. \label{I1_fig_flip_bis}} - +\caption{Flip. \label{2D_Triangulation_fig_flip_bis}} \begin{ccHtmlOnly}
Flip @@ -474,31 +502,32 @@ building up the triangulation together with the geometric predicates on those objects. The required predicates are: \\ - comparison of the \ccc{x} or \ccc{y} coordinates of two points.\\ -- orientation tests providing \ccc{CGAL_orientation} - corresponding to the order type of three given point. +- the orientation test which computes + the order type of three given point. The concept \ccc{TriangulationTraits_2} describes the requirements for the -geometric traits class of a triangulation -\lcTex{see page (\ccRefPage{TriangulationTraits_2}) of the reference manual}. +geometric traits class of a triangulation. The \cgal\ kernel classes are models for this concept. -The \cgal\ library also provides tighter models +The \cgal\ library also provides dedicated models of \ccc{TriangulationTraits_2} using the kernel geometric objects and predicates. -These classes are themselves templated with a \cgal\ kernel. +These classes are themselves templated with a \cgal\ kernel +and extract the required types and predicates from the kernel. The traits class \ccc{Triangulation_euclidean_traits_2} is designed to deal with ordinary two dimensional points. The class \ccc{Triangulation_euclidean_traits_xy_3} is a geometric traits class to build the triangulation of a terrain. Such a triangulation is a two-dimensional -triangulation embedded the three-dimensional space. +triangulation embedded in three dimensional space. The data points are three-dimensional points. The triangulation is build according to the projections of those points on the $xy$ plane and then lifted up to the original three-dimensional data points. -This is the usual case when dealing with GIS terrains. +This is especially usefull +to deal with GIS terrains. Instead of really projecting the three-dimensional points and maintaining a mapping between each point and its projection (which costs space and is error prone), @@ -516,9 +545,9 @@ respectively. \label{Subsection_2D_Triangulations_Basic_Example} The following program creates a triangulation of 2D points -using the kernel model class \ccc{CGAL::Cartesian} -as geometric traits and the default triangulation data structure -template parameter. +using the default kernel +\ccc{Exact_predicate_inexact_constructions_kernel} +as geometric traits and the default triangulation data structure. The input points are read from a file and inserted in the triangulation. Finally points on the convex hull are written to {\tt cout}. @@ -532,39 +561,18 @@ Finally points on the convex hull are written to {\tt cout}. \label{Subsection_2D_Triangulations_Delaunay_Description} The class \ccc{Delaunay_triangulation_2} is designed to represent the Delaunay triangulation of a set of data points in the plane. -A Delaunay triangulation of a set of points +A Delaunay triangulation fulfills the following {\em empty circle property} (also called {\em Delaunay property}): the circumscribing -circle of any facets of the triangulation +circle of any facet of the triangulation contains no data point in its interior. For a point set with no subset of four cocircular points -the Delaunay triangulation is unique, it is the dual -of the Voronoi diagram of the points. - - -A Delaunay triangulation is a special triangulation of a set of points. -So it is natural to derive -the class \ccc{Delaunay_triangulation_2} -from the basic class \ccc{Triangulation_2}. -Like its base class, the Delaunay triangulation class is parametrized -by two template -parameters, the geometric traits \ccc{Traits} -and the triangulation data structure\ccc{Tds}. -Just like the triangulation data structure -of a basic triangulation, -the triangulation data strucure of a Delaunay triangulation -has to be a model of the concept \ccc{TriangulationDataStructure_2}. -In contrast, because the -concept of Delaunay triangulation relies on the notions of -distance and -empty circles, -the geometric traits has to be a model of the concept -\ccc{DelaunayTriangulationTraits_2} -which refines the concept \ccc{TriangulationTraits_2}. - - +the Delaunay triangulation is unique, it is dual +to the Voronoi diagram of the set of points. +The class \ccc{Delaunay_triangulation_2} derives +from the class \ccc{Triangulation_2}. The class \ccc{Delaunay_triangulation_2} inherits the types defined by the @@ -574,8 +582,8 @@ are defined to represent the dual Voronoi diagram. The class \ccc{Delaunay_triangulation_2} -overwrite the member functions that insert a new point -in the triangulation or +overwrites the member functions that insert a new point +in the triangulation or remove a vertex from it to maintain the Delaunay property. It also has a member function (\ccc{Vertex_handle @@ -589,15 +597,15 @@ The geometric traits has to be a model of the concept \ccc{DelaunayTriangulationTraits_2} which refines the concept \ccc{TriangulationTraits_2}. In particular this concept provides -the \ccc{in_circle(p,q,r,s)} predicate -which decides the position of the point $s$ (interior, exterior -or on the boundary) with respect to the circle +the \ccc{side_of_oriented_circle} predicate +which, given four points \ccc{p,q,r,s} + decides the position of the point $s$ with respect to the circle passing through $p$, $q$ and $r$. -The \ccc{in_circle(p,q,r,s)} +The \ccc{side_of_oriented_circle} predicate actually defines the Delaunay triangulation. Changing this predicate -allows to build Delaunay triangulations for different metrics -such that $L_1$ or $L_{\infty}$ or any metric defined by a +allows to build variant of Delaunay triangulations for different metrics +such that $L_1$ or $L_{\infty}$ metric or any metric defined by a convex object. However, the user of an exotic metric must be careful that the constructed triangulation has to be a triangulation of the convex hull @@ -610,19 +618,14 @@ The \cgal\ kernel classes and the class \ccc{Triangulation_euclidean_traits_2} are models of the concept \ccc{DelaunayTriangulationTraits_2} for the euclidean metric. -\cgal\ also provides traits classes to deal with terrains, -that are two dimensional triangulated surfaces -embedded in the three dimensional space that have project on -a two dimensional Delaunay triangulation. Namely, the traits classes +The traits class for terrains, \ccc{Triangulation_euclidean_traits_xy_3},\\ \ccc{Triangulation_euclidean_traits_yz_3}, and\\ \ccc{Triangulation_euclidean_traits_zx_3} \\ -are to be used to build a a triangulated surface -projecting on the Delaunay triangulation of respectively -the \ccc{xy}, \ccc{yz} or \ccc{zx} projections of its vertices:\\ -The requirements for the duality functions and nearest vertex -queries are not yet satisfied by -these last three classes. +are also models of \ccc{DelaunayTriangulationTraits_2} +excapt that they do not fulfills +the requirements for the duality functions and nearest vertex +queries. \ccHeading{Implementation} The insertion of a new point in the Delaunay triangulation @@ -634,7 +637,7 @@ if the new vertex has degree \ccTexHtml{$d$}{d} in the updated Delaunay triangulation. For points distributed uniformly at random, each insertion takes time \ccTexHtml{$O(1)$}{O(1)} on -average, once the point has benn located in the triangulation. +average, once the point has been located in the triangulation. Removal calls the removal in the triangulation and then retriangulates the hole created in such a way that the Delaunay criterion is @@ -760,13 +763,40 @@ ${ P'}= \{ (p_i,p_i ^2 - w_i ), i = 1, \ldots , n \}$. The class \ccc{Regular_triangulation_2} is designed to maintain the regular triangulation of a set of $2d$ weighted points. -The template parameters \ccc{Traits} and \ccc{Tds} stand respectively - for a geometric traits class and a triangulation data structure class. -The triangulation data structure has to be a model of the concept -\ccc{TriangulationDataStructure_2}. -The geometric traits class must provide a weighted point type -and a power test on these weighted points -and the concept for this parameter, called +It derives from the class \ccc{Triangulation_2}. +The functions \ccc{insert} and +\ccc{remove} are overwritten to handle weighted points +and maintain the regular +property. +The vertices of the regular triangulation +of a set of weighted points ${PW}$ correspond only to a subset +of ${PW}$. +Some of the input +weigthed points have no cell in the dual power diagrams +and therefore do not correspond to a vertex of the regular +triangulation. +Such a point is called a hidden point. +Because hidden points can reappear later on as vertices +when some other point is removed, +they have to be stored somewhere. +The regular triangulation store those points in special vertices, called +hidden vertices. +A hidden point can reappear as vertex of the triangulation +only when the two dimensional face that hides it +is removed from the triangulation. To deal with this feature, +each face of a regular triangulation stores a list of hidden vertices. +The points in those vertices +are reinserted in the triangulation when the face +is removed. + +Regular triangulation have member functions to construct +the vertices and edges of the dual power diagrams. + +\subsubsection{The geometric traits} +The geometric traits of a regular triangulation +must provide a weighted point type +and a power test on these weighted points. +The concept \ccc{RegularTriangulationTraits_2}, is a refinement of the concept \ccc{TriangulationTraits_2}. \cgal\ provides @@ -781,42 +811,14 @@ and uses a \ccc{Weighted_point} type derived from the type \ccc{Point_2} of \ccc{Triangulation_euclidean_traits_2}. - -The class \ccc{Regular_triangulation_2} -derives from the class \ccc{Triangulation_2}. -The functions \ccc{insert} and -\ccc{remove} are overwritten to maintain the regular -property. -The vertices of the regular triangulation -of a set of weighted points ${ PW}$ form only a subset -of the set of center points of ${ PW}$. -Some of the input -weigthed points have no cell in the dual power diagrams -and therefore do not correspond to a vertex of the regular -triangulation. -Such a point is called a hidden point. -Because hidden points can reappear later on the removal -of some other points as a vertex of the triangulation -they have to be store somewhere. -The regular triangulation store those points in special vertices, called -hidden vertices. -A hidden point can reappear as vertex of the triangulation -only when the two dimensional face that hides it -is removed from the triangulation. To detect these events -each face of a regular triangulation stores a list of hidden vertices. - -Regular triangulation have member functions to construct -the vertices and edges of the dual power diagrams. - - \subsubsection{The Vertex type and Face Type of a Regular Triangulation} The base vertex type of a regular triangulation -includes a boolean to mark the hidden or not state of the vertex. +includes a boolean to mark the hidden state of the vertex. Therefore CGAL defines the concept \ccc{RegularTriangulationVertexBase_2} which refine the concept \ccc{TriangulationVertexBase_2} -and provides a default model \ccc{Regular_triangulation_vertex_base_2} +and provides a default model for this concept. The base face type of a regular triangulation @@ -826,14 +828,15 @@ of the concept \ccc{RegularTriangulationFaceBase_2}. \cgal\ provides the templated class \ccc{Regular_triangulation_face_base_2} as a default base class for faces of regular triangulations. -This class derives from \ccc{Triangulation_face_base_2}. + \subsection{Example : a Regular Triangulation} \label{Subsection_2D_Triangulations_Regular_Example} The following code creates a regular triangulation -of a set of weighted points. +of a set of weighted points and ouput the number +of vertices and the number of hidden vertices. \ccIncludeExampleCode{Triangulation_2/regular.C} @@ -852,12 +855,15 @@ The endpoints of constrained edges are of course vertices of the triangulation. However the triangulation may include include other vertices as well. There are three versions of constrained triangulations. +\begin{itemize} +\item In the basic version, the constrained triangulation does not handle intersecting constraints, and the set of input constraints is required to be a set of segments that do not intersect except possibly at their endpoints. Any number of constrained edges are allowed to share the same endpoint. Vertical constrained edges or constrained edges with null length are allowed. +\item The two other versions support intersecting input constraints. In those versions, input constraints are allowed to be intersecting, overlapping or partially @@ -867,10 +873,14 @@ is the proper intersection points of two constraints. A single constraint intersecting other constraints will then appear as several edges in the triangulation. The two versions dealing with intersecting constraints differ -in the way intersecting constraints are dealt with. One of them is +in the way intersecting constraints are dealt with. +\begin{itemize} +\item + One of them is designed to be robust when predicates are evaluated exactly but constructions (i. e. intersection computations) are approximative. +\item The other one is designed to be used with exact arithmetic (meaning exact evaluation of predicates and exact computation of intersections.) @@ -878,7 +888,11 @@ This last version finds its full efficiency when used in conjunction with a constraint hierarchy data structure (which allows one to avoid the cascading of intersection computations) as provided in the class -\ccc{Constrained_triangulation_plus_2}. See section~\ref{Section_2D_Triangulations_Constrained_Plus}. +\ccc{Constrained_triangulation_plus_2}. See +section~\ref{Section_2D_Triangulations_Constrained_Plus}. +\end{itemize} +\end{itemize} + \begin{ccTexOnly} \begin{center} \IpeScale{100} \Ipe{constraints.ipe} \end{center} @@ -893,20 +907,6 @@ constraints and its constrained triangulation"> A constrained triangulation is represented in the CGAL library as an object of the class \ccc{Constrained_triangulation_2}. -The template parameter \ccc{Traits} -stands for a geometric traits class. It has to be a model -of the concept \ccc{TriangulationTraits_2}. -When intersections of input constraints are supported, -the geometric traits class has to be a model -of the concept \ccc{ConstrainedTriangulationTraits_2} -which refines the concept \ccc{TriangulationTraits_2} -providing additional function object types -to compute the intersection of two segments. - -The template parameter \ccc{Tds} -stands for -a triangulation data structure class that has to be a model -of the concept \ccc{TriangulationDataStructure_2}. The third parameter \ccc{Itag} is the intersection tag which serves to choose how intersecting constraints are dealt with. This parameter has to be instantiated @@ -933,22 +933,25 @@ information about constrained edges. The class also allows inline insertion of a new constraint, given by its two endpoints or the removal of a constraint. +\subsubsection{The Geometric Traits} +The geometric traits of a constraint triangulation + has to be a model +of the concept \ccc{TriangulationTraits_2}. +When intersections of input constraints are supported, +the geometric traits class has to be a model +of the concept \ccc{ConstrainedTriangulationTraits_2} +which refines the concept \ccc{TriangulationTraits_2} +providing additional function object types +to compute the intersection of two segments. + \subsubsection{The Base Face of a Constrained Triangulation} The information about constrained edges is stored in the -faces of the triangulation. Thus the nested \ccc{Face} -type of a constrained triangulation offers -additonnal functionalities to deal with this information. -To achieve this, the base face of a Constrained Triangulation +faces of the triangulation. The base face of a Constrained Triangulation has to be a model for the concept \ccc{ConstrainedFaceBase_2} which refines the concept \ccc{TriangulationFaceBase_2}. The concept \ccc{ConstrainedFaceBase_2} -requires a member function -(\ccc{bool is_constrained(int i)}) - providing the status -(constrained ou unconstrained) of the edges -and also a member function -(\ccc{void set_constraint(int i, bool b)}) to set this status. - +requires member functions + the get and set the constrained status of the edges. \cgal\ provides a default base face class for constrained triangulations. This class, named @@ -975,7 +978,7 @@ and adds three booleans to store the status of its edges. the constraining edges are the green edges, a constrained triangulation is shown on the left, the constrained Delaunay triangulation with two examples of circumcircles is shown on the right.} -\label{I1_Fig_constrained} +\label{2D_Triangulation_Fig_constrained} \begin{ccHtmlOnly}
Constrained triangulation @@ -1024,21 +1027,6 @@ The \cgal\ class is designed to represent constrained Delaunay triangulations. -The class is templated by a geometric traits class \ccc{Traits} -and a triangulation data structure \ccc{Tds} and an intersection tag -\ccc{Itag}. -The triangulation data structure has to be a model of the concept -\ccc{TriangulationDataStructure_2}. - The geometric traits -of a constrained Delaunay triangulation is required -to provide the \ccc{side_of_oriented_circle} test as the geometric traits -of a Delaunay triangulation and has to a model of the concept -\ccc{DelaunayTriangulationTraits_2}. When intersecting input -constraints -are supported the geometric traits is further required -to provide function objects to compute constraints intersections. -Then the geometric traits has to be at the same time a model -of the concept \ccc{ConstrainedTriangulationTraits_2}. As in the case of constraints triangulation, the third parameter \ccc{Itag} is the intersection tag and serves to choose how intersecting constraints @@ -1054,13 +1042,6 @@ Therefore the class \ccc{Constrained_Delaunay_triangulation_2} derives from the class \ccc{Constrained_triangulation_2}. -Also, information about the status (constrained or not) -of the edges of the triangulation has to be stored -in the face class - and the base face class -of a constrained Delaunay triangulation has to be a model -of \ccc{ConstrainedFaceBase_2}. - The constrained Delaunay triangulation has member functions to override the @@ -1070,10 +1051,38 @@ to restore the constrained empty circle property. +\subsubsection{The Geometric Traits} + The geometric traits +of a constrained Delaunay triangulation is required +to provide the \ccc{side_of_oriented_circle} predicate as the geometric traits +of a Delaunay triangulation and has to a model of the concept +\ccc{DelaunayTriangulationTraits_2}. When intersecting input +constraints +are supported the geometric traits is further required +to provide function objects to compute constraints intersections. +Then the geometric traits has to be at the same time a model +of the concept \ccc{ConstrainedTriangulationTraits_2}. + + + +\subsubsection{The face base class} +Information about the status (constrained or not) +of the edges of the triangulation has to be stored +in the face class + and the base face class +of a constrained Delaunay triangulation has to be a model +of \ccc{ConstrainedFaceBase_2}. + + + + \subsection{Example : a constrained Delaunay triangulation} \label{Subsection_2D_Triangulations_Constrained_Delaunay_Example} -The following code inputs constraining edges from a file -and build a constrained Delaunay triangulation. +The following code inserts a set of intersecting constraint segments +into a triangulation +and counts the number of constrained edges of the +resulting triangulation. + \ccIncludeExampleCode{Triangulation_2/constrained.C} @@ -1095,10 +1104,8 @@ the base class constructs a triangulation of the arrangement of the constraints, introducing new vertices at each proper intersection points and refining the input constraints into subconstraints -which appear as edges (more precisely constrained edges) of the -triangulation. In this context, the constraint hierarchy -keeps track of the input constraints and of their refinement -in the triangulation. This data structure maintains for each +which appear as edges (more precisely as constrained edges) of the +triangulation. The data structure maintains for each input constraint the sequence of intersection vertices added on this constraint. The constraint hierarchy also allows the user to retrieve the set @@ -1115,7 +1122,7 @@ intersection points. \subsection{Example : Building a triangulated arrangement of segments} -The following code iinserts a set of intersecting constraint segments +The following code inserts a set of intersecting constraint segments into a triangulation and counts the number of constrained edges of the resulting triangulation. @@ -1123,24 +1130,7 @@ resulting triangulation. \ccIncludeExampleCode{Triangulation_2/constrained_plus.C} -Figure~\ref{I1_Fig_derivation_tree} summarize the derivation dependancies -of \cgal\ 2D triandulations. -\begin{figure} -\begin{ccTexOnly} -\begin{center} -\includegraphics[width=13cm]{derivation_tree.eps} -\end{center} -\end{ccTexOnly} -\caption{The derivation tree of 2D triangulations.} -\label{I1_Fig_derivation_tree} -\begin{ccHtmlOnly} -
-
- -
-\end{ccHtmlOnly} -\end{figure} \section{The Triangulation Hierarchy} @@ -1215,8 +1205,8 @@ of a Delaunay triangulation. The program output the number of vertices at the different levels of the hierarchy. \ccIncludeExampleCode{Triangulation_2/hierarchy.C} -the following program shows how to use -a triangulation hierachy in conjonction with a Constrained +The following program shows how to use +a triangulation hierachy in conjonction with a constrained triangulation plus. \ccIncludeExampleCode{Triangulation_2/constrained_hierarchy_plus.C} @@ -1224,31 +1214,32 @@ triangulation plus. \label{Section_2D_Triangulations_Flexibility} -To be able to fulfills various different kind of needs, a hihgly +To be able to adapt to various needs, a highly flexible design has been selected for 2D triangulations. We have already seen that -the main triangulation classes are has two -parameter : a geometric traits class +the triangulation classes have two +parameters : a geometric traits class and a triangulation data structure class which the user can instantiate with his own customized classes. -The most usefull flexibility comes from the fact -that the triangulation data structure has two template +The most usefull flexibility however comes from the fact +that the triangulation data structure itself has two template parameters to be instantiated by base classes for the vertices and faces of the triangulation. The vertex and face classes of the triangulation are derived -from those base classes +from those base classes. Thus, using his own customized classes to instantiate these -parameters. +parameters, the user can easily build up a triangulation with additionnal +informations or functionalities in the vertices and faces. {\bf A cyclic dependancy} -Thus the triangulation data structure is templated by the -vertex and face base classes. However since incidence and adjacency -relations are stored in vertices anf faces, the base classes have to +To insure flexibility, the triangulation data structure is templated by the +vertex and face base classes. Also since incidence and adjacency +relations are stored in vertices and faces, the base classes have to know the types of handles on vertices and faces provided by the triangulation data structure. Thus the vertex and base classes have to be thenselves parameterized by the triangulation data -structure, hence the cyclic dependancy. +structure, and there is a cyclic dependancy on template parameter. \begin{figure} \begin{ccTexOnly} @@ -1257,7 +1248,7 @@ structure, hence the cyclic dependancy. \end{center} \end{ccTexOnly} \caption{The cyclic dependency in triangulations software design. -\label{I1_Fig_three_levels_2}} +\label{2D_Triangulation_Fig_three_levels_2}} \begin{ccHtmlOnly}

@@ -1266,18 +1257,20 @@ structure, hence the cyclic dependancy. \end{ccHtmlOnly} \end{figure} -Previously, this cyclic dependency was avoided by simply -using only void* pointers in interface of base classes -and later converting these void* to appropriate handles at the +Previously, this cyclic dependency was avoided by +using only \ccc{void*} pointers in the interface of base classes. +These \ccc{void*} were converted to appropriate types at the triangulation data structure levels. This solution had some drawbacks -~: mainly it prevented the user to add in the vertices or faces of the +~: mainly the user could not add in the vertices or faces of the triangulation a functionality related to types defined by -the triangulation data structure (face, vertex or handles) -(except through the use of void* pointers). -The new solution to resolve this dependancy +the triangulation data structure, for instance a handle to a vertex, +and he was lead to use himself +\ccc{void*} pointers). +The new solution to resolve the template dependancy is based on a rebind mecanism similar to the mecanism used in the standard allocator class std::allocator. The rebind mecanism -is described in Section~\ref{} of Chapter~\ref{}. +is described in Section~\ref{2D_TDS_default} +of Chapter~\ref{Chapter_2D_Triangulation_Data_Structure}. For now, we will just notice that the design requires the existence in the vertex and face base classes @@ -1287,19 +1280,20 @@ the rebinding mecanism. The two following examples aim to show how the user -can still put in use the flexibility offered by the +can put in use the flexibility offered by the base classes parameters. {\bf Adding colors} -The first example correspond to a case where the user wishes to add in +The first example corresponds to a case where the user wishes to add in the vertices or faces of the triangulation an additional information that do not depend on types provided by the triangulation data structure. -In that case he (or she) can make use of the predefined classes +In that case, predefined classes \ccc{Triangulation_vertex_base_with_info_2} or \ccc{Triangulation_face_base_with_info_2} -whose parameter \ccc{Info} to be instantiated by the type of the -added information. +can be used. Those classes have +a template parameter \ccc{Info} devoted to +handle additionnal information. The following examples shows how to add a \ccc{CGAL::Color} in the triangulation faces. @@ -1307,9 +1301,9 @@ The following examples shows how to add a \ccIncludeExampleCode{Triangulation_2/colored_face.C} {\bf Adding handles} -The second examples show how the user can still +The second examples shows how the user can still derive and plug in his own vertex base -or face base when he would like to have in vertices or faces +or face base when he would like to have additionnal functionalities depending on types provided by the triangulation data structure. diff --git a/Packages/Triangulation_2/examples/Triangulation_2/Makefile b/Packages/Triangulation_2/examples/Triangulation_2/Makefile index 65461abb2ad..52cc0ec3853 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/Makefile +++ b/Packages/Triangulation_2/examples/Triangulation_2/Makefile @@ -20,6 +20,7 @@ CXXFLAGS = \ $(DEBUG_OPT) \ -pedantic + #---------------------------------------------------------------------# # linker flags #---------------------------------------------------------------------# @@ -39,7 +40,9 @@ all: \ adding_handles$(EXE_EXT) \ colored_face$(EXE_EXT) \ constrained$(EXE_EXT) \ + constrained_hierarchy_plus$(EXE_EXT) \ constrained_plus$(EXE_EXT) \ + hierarchy$(EXE_EXT) \ regular$(EXE_EXT) \ terrain$(EXE_EXT) \ triangulation_prog1$(EXE_EXT) \ @@ -54,9 +57,15 @@ colored_face$(EXE_EXT): colored_face$(OBJ_EXT) constrained$(EXE_EXT): constrained$(OBJ_EXT) $(CGAL_CXX) $(LIBPATH) $(EXE_OPT)constrained constrained$(OBJ_EXT) $(LDFLAGS) +constrained_hierarchy_plus$(EXE_EXT): constrained_hierarchy_plus$(OBJ_EXT) + $(CGAL_CXX) $(LIBPATH) $(EXE_OPT)constrained_hierarchy_plus constrained_hierarchy_plus$(OBJ_EXT) $(LDFLAGS) + constrained_plus$(EXE_EXT): constrained_plus$(OBJ_EXT) $(CGAL_CXX) $(LIBPATH) $(EXE_OPT)constrained_plus constrained_plus$(OBJ_EXT) $(LDFLAGS) +hierarchy$(EXE_EXT): hierarchy$(OBJ_EXT) + $(CGAL_CXX) $(LIBPATH) $(EXE_OPT)hierarchy hierarchy$(OBJ_EXT) $(LDFLAGS) + regular$(EXE_EXT): regular$(OBJ_EXT) $(CGAL_CXX) $(LIBPATH) $(EXE_OPT)regular regular$(OBJ_EXT) $(LDFLAGS) @@ -73,7 +82,9 @@ clean: \ adding_handles.clean \ colored_face.clean \ constrained.clean \ + constrained_hierarchy_plus.clean \ constrained_plus.clean \ + hierarchy.clean \ regular.clean \ terrain.clean \ triangulation_prog1.clean \ diff --git a/Packages/Triangulation_2/examples/Triangulation_2/README b/Packages/Triangulation_2/examples/Triangulation_2/README index 456f9696091..4996a76bb43 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/README +++ b/Packages/Triangulation_2/examples/Triangulation_2/README @@ -43,6 +43,14 @@ constrained_plus Same has above, but the constrained Delaunay triangulation uses an exact number types and a constraint hierachy. +hierarchy +A standard use of a triangulation hierarchy +to enhance the efficiency +of a Delaunay triangulation. +The program output the number of vertices +at the different levels of the hierarchy - - +hierarchy_plus +The program shows how to use +a triangulation hierachy in conjonction with a Constrained +triangulation plus. \ No newline at end of file diff --git a/Packages/Triangulation_2/examples/Triangulation_2/adding_handles.C b/Packages/Triangulation_2/examples/Triangulation_2/adding_handles.C index e23b5b04594..7a208c22f1a 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/adding_handles.C +++ b/Packages/Triangulation_2/examples/Triangulation_2/adding_handles.C @@ -1,8 +1,8 @@ -// file : examples/Triangulation_2/colored_face.C +// file : examples/Triangulation_2/adding_handles.C #include #include -/* A facet with a color member variable. */ +/* A facet with an additionnal handle */ template < class Gt, class Vb = CGAL::Triangulation_vertex_base_2 > class My_vertex_base : public Vb diff --git a/Packages/Triangulation_2/examples/Triangulation_2/cgal_test b/Packages/Triangulation_2/examples/Triangulation_2/cgal_test index 39755d0638a..490ea10613b 100755 --- a/Packages/Triangulation_2/examples/Triangulation_2/cgal_test +++ b/Packages/Triangulation_2/examples/Triangulation_2/cgal_test @@ -67,7 +67,6 @@ if [ $# -ne 0 ] ; then compile_and_run $file done else - compile_and_run points compile_and_run voronoi compile_and_run colored_face compile_and_run triangulation_prog1 @@ -75,5 +74,7 @@ else compile_and_run regular compile_and_run constrained compile_and_run constrained_plus + compile_and_run hierarchy + compile_and_run constrained_hierarchy_plus fi diff --git a/Packages/Triangulation_2/examples/Triangulation_2/constrained.C b/Packages/Triangulation_2/examples/Triangulation_2/constrained.C index df6c7bbe8b1..e820852804c 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/constrained.C +++ b/Packages/Triangulation_2/examples/Triangulation_2/constrained.C @@ -15,11 +15,9 @@ int main( ) { CDT cdt; - std::cerr << "Inserting a grid of constraints " << std::endl; - std::cerr << "Inserting five horizontal constraints " << std::endl; + std::cout << "Inserting a grid of 5x5 constraints " << std::endl; for (int i = 1; i < 6; ++i) cdt.insert_constraint( Point(0,i), Point(6,i)); - std::cerr << "Inserting five vertical constraints " << std::endl; for (int j = 1; j < 6; ++j) cdt.insert_constraint( Point(j,0), Point(j,6)); @@ -29,8 +27,8 @@ main( ) eit != cdt.finite_edges_end(); ++eit) if (cdt.is_constrained(*eit)) ++count; - std::cerr << "The number of resulting constrained edges is "; - std::cerr << count << std::endl; + std::cout << "The number of resulting constrained edges is "; + std::cout << count << std::endl; return 0; } diff --git a/Packages/Triangulation_2/examples/Triangulation_2/constrained_plus.C b/Packages/Triangulation_2/examples/Triangulation_2/constrained_plus.C index 71b01d809d4..ff2fd49e06b 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/constrained_plus.C +++ b/Packages/Triangulation_2/examples/Triangulation_2/constrained_plus.C @@ -1,4 +1,4 @@ -// file examples/Triangulation_2/constrained_plus.C +// file examples/Triangulation_2/constrained_hierarchy_plus.C #include #include #include @@ -18,11 +18,9 @@ int main( ) { CDTplus cdt; - std::cerr << "Inserting a grid of constraints " << std::endl; - std::cerr << "Inserting five horizontal constraints " << std::endl; + std::cout << "Inserting a grid 5 x 5 of constraints " << std::endl; for (int i = 1; i < 6; ++i) cdt.insert_constraint( Point(0,i), Point(6,i)); - std::cerr << "Inserting five vertical constraints " << std::endl; for (int j = 1; j < 6; ++j) cdt.insert_constraint( Point(j,0), Point(j,6)); @@ -31,7 +29,7 @@ main( ) for (CDTplus::Subconstraint_iterator scit = cdt.subconstraints_begin(); scit != cdt.subconstraints_end(); ++scit) ++count; - std::cerr << "The number of resulting constrained edges is "; - std::cerr << count << std::endl; + std::cout << "The number of resulting constrained edges is " + << count << std::endl; return 0; } diff --git a/Packages/Triangulation_2/examples/Triangulation_2/regular.C b/Packages/Triangulation_2/examples/Triangulation_2/regular.C index 958b44bf68d..1f4e7b4d106 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/regular.C +++ b/Packages/Triangulation_2/examples/Triangulation_2/regular.C @@ -17,11 +17,16 @@ int main() std::ifstream in("data/regular.cin"); Gt::Weighted_point wp; + int count = 0; while(in >> wp){ - std::cout << wp << std::endl; + count++; rt.insert(wp); - rt.is_valid(); } rt.is_valid(); + std::cout << "number of inserted points \t" << count << std::endl; + std::cout << "number of vertices \t \t " ; + std::cout << rt.number_of_vertices() << std::endl; + std::cout << "number of hidden vertices \t " ; + std::cout << rt.number_of_hidden_vertices() << std::endl; return 0; } diff --git a/Packages/Triangulation_2/examples/Triangulation_2/voronoi.C b/Packages/Triangulation_2/examples/Triangulation_2/voronoi.C index ad600a533d0..d61f79a1a7f 100644 --- a/Packages/Triangulation_2/examples/Triangulation_2/voronoi.C +++ b/Packages/Triangulation_2/examples/Triangulation_2/voronoi.C @@ -8,12 +8,13 @@ struct K : CGAL::Exact_predicates_inexact_constructions_kernel {}; typedef CGAL::Delaunay_triangulation_2 Triangulation; typedef Triangulation::Edge_iterator Edge_iterator; +typedef Triangulation::Point Point; int main( ) { std::ifstream in("data/voronoi.cin"); - std::istream_iterator begin(in); - std::istream_iterator end; + std::istream_iterator begin(in); + std::istream_iterator end; Triangulation T; T.insert(begin, end); diff --git a/Packages/Triangulation_2/include/CGAL/Triangulation_hierarchy_2.h b/Packages/Triangulation_2/include/CGAL/Triangulation_hierarchy_2.h index cfefcefec72..52d6692335f 100644 --- a/Packages/Triangulation_2/include/CGAL/Triangulation_hierarchy_2.h +++ b/Packages/Triangulation_2/include/CGAL/Triangulation_hierarchy_2.h @@ -232,9 +232,13 @@ is_valid(bool verbose, int level) const int i; Finite_vertices_iterator it; //verify correctness of triangulation at all levels - for(i=0;iis_valid(verbose,level); - //verify that lower level has no down pointers + for(i=0;inumber_of_vertices() << std::endl; + result = result && hierarchy[i]->is_valid(verbose,level); + } + //verify that lower level has no down pointers for( it = hierarchy[0]->finite_vertices_begin(); it != hierarchy[0]->finite_vertices_end(); ++it) result = result && ( it->down() == NULL );