diff --git a/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt b/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt index 7fd1e8d496d..cd43cc5efa4 100644 --- a/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt +++ b/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt @@ -474,7 +474,7 @@ Lastly we remove the dynamic onmerge functor (step 8). This is done by initializ \section sec_definition Mathematical Definitions -The initial definition of combinatorial map in any dimension is given in \cgalCite{cgal:l-tmbrc-91}, \cgalCite{l-ndgcm-94}. But it allows only to represent objects without boundaries. This definition was extended \cgalCite{cgal:pabl-cco-07}, \cgalCite{cgal:d-ccccg-10} in order to allow to represent objects with boundaries, based on the notions of partial permutations and partial involutions. +The initial definition of combinatorial map in any dimension is given in \cgalCite{cgal:l-tmbrc-91}, \cgalCite{l-ndgcm-94}. But it allows only to represent objects without boundaries. This definition was extended \cgalCite{cgal:pabl-cco-07}, \cgalCite{cgal:d-ccccg-10} in order to allow to represent objects with boundaries, based on the notions of partial permutations and partial involutions. See also the book \cgalCite{dl-14} which regroups many definitions, operations and algorithms about combinatorial and generalized maps. Intuitively, a partial permutation on a finite set E is a mapping from E\f$ \cup\{\varnothing\}\f$ to E\f$ \cup\{\varnothing\}\f$ which is injective on the subset of the domain that does not map to \f$\varnothing\f$. More precisely, a mapping p: E\f$ \cup\{\varnothing\} \rightarrow\f$ E\f$ \cup\{\varnothing\}\f$ is a partial permutation defined on E if:
    diff --git a/Generalized_map/doc/Generalized_map/Doxyfile.in b/Generalized_map/doc/Generalized_map/Doxyfile.in index f04fcda678b..28420a22a98 100644 --- a/Generalized_map/doc/Generalized_map/Doxyfile.in +++ b/Generalized_map/doc/Generalized_map/Doxyfile.in @@ -1,3 +1,5 @@ @INCLUDE = ${CGAL_DOC_PACKAGE_DEFAULTS} PROJECT_NAME = "CGAL ${CGAL_FULL_VERSION} - Generalized Maps" +ALIASES += tred{1}="\htmlonly \1 \endhtmlonly" + diff --git a/Generalized_map/doc/Generalized_map/Generalized_map.txt b/Generalized_map/doc/Generalized_map/Generalized_map.txt index 9bb7a33db31..b355636bdf2 100644 --- a/Generalized_map/doc/Generalized_map/Generalized_map.txt +++ b/Generalized_map/doc/Generalized_map/Generalized_map.txt @@ -10,7 +10,9 @@ namespace CGAL { \section Generalized_mapIntroduction Introduction -A d-dimensional generalized map is a data structure representing an orientable or non orientable subdivided d-dimensional object obtained by taking dD cells, and allowing to glue dD cells along (d-1)D cells. It provides a description of all the cells of the subdivision (for example vertices and edges), together with incidence and adjacency relationships. This package is a generalization of the \ref ChapterCombinatorialMap combinatorial maps data structure which allows to describe only orientable objects. +A d-dimensional generalized map is a data structure representing an \tred{orientable or non orientable} subdivided d-dimensional object obtained by taking dD cells, and allowing to glue dD cells along (d-1)D cells. It provides a description of all the cells of the subdivision (for example vertices and edges), together with incidence and adjacency relationships. + +\tred{This package is an extension of the \ref ChapterCombinatorialMap combinatorial maps data structure which allows to describe only orientable objects.} We denote i-cell for an i-dimensional cell (for example in 3D, 0-cells are vertices, 1-cells are edges, 2-cells are facets, and 3-cells are volumes). A boundary relation is defined on these cells, giving for each i-cell c the set of (i-1)-cells contained in the boundary of c. Two cells c1 and c2 are incident if there is a path of cells, starting from the cell of biggest dimension to the other cell, such that each cell of the path (except the first one) belongs to the boundary of the previous cell in the path. Two i-cells c3 and c4 are adjacent if there is an (i-1)-cell incident to both c3 and c4. You can see an example of a 2D object and a 3D object in \cgalFigureRef{figexemple3Dmanifold} showing some cells of the subdivision and some adjacency and incidence relations. @@ -18,38 +20,43 @@ We denote i-cell for an i-dimensional cell (for example in 3D, 0-c Example of subdivided objects that can be described by generalized maps. Left: A 2D object composed of three facets (2-cells), named f1, f2 and f3, nine edges (1-cells) and seven vertices (0-cells). f1 and f2 are adjacent along edge e1, thus e1 is incident both to f1 and f2. Vertex v1 is incident to edge e1, thus v1 is incident to f1 and f2 by transitivity. Right: A 3D object (only partially represented for vertices and edges) composed of three volumes (3-cells), named vol1, vol2 and vol3, twelve facets (2-cells) (there is one facet f4 between vol1 and vol2, and similarly between vol1 and vol3 and vol2 and vol3), sixteen edges (1-cells), and eight vertices (0-cells). vol1 and vol2 are adjacent along facet f4, thus f4 is incident both to vol1 and vol2. Edge e4 is incident to the three facets between vol1 and vol2, vol1 and vol3, and vol2 and vol3. e4 is also incident to the three volumes by transitivity. \cgalFigureEnd -A generalized map is an edge-centered data structure describing the cells and the incidence and adjacency relations, using only one basic element called dart, and a set of pointers between these darts. A dart can be thought as a part of an edge (1-cell), together with a part of incident cells of dimensions 0, 2, 3, ..., d. When a dart d0 describes a part of an -i-cell c, we say that d0 belongs to c, and that c contains d0. Let us look at the example in \cgalFigureRef{figexemplegenmaps} showing the 2D and 3D generalized maps describing the two objects given in \cgalFigureRef{figexemple3Dmanifold}. +A generalized map is an edge-centered data structure describing the cells and the incidence and adjacency relations, using only one basic element called dart, and a set of pointers between these darts. A dart can be thought as a part of an edge (1-cell), together with a part of incident cells of dimensions 0, 2, 3, ..., d. When a dart d0 describes a part of an i-cell c, we say that d0 belongs to c, and that c contains d0. Let us look at the example in \cgalFigureRef{figexemplegenmaps} showing the 2D and 3D generalized maps describing the two objects given in \cgalFigureRef{figexemple3Dmanifold}. \cgalFigureBegin{figexemplegenmaps,gmaps2d-3d.svg} -Generalized maps representing the objects given in \cgalFigureRef{figexemple3Dmanifold}. Left: The 2D generalized map which contains 24 darts. Right: The 3D generalized map which contains 108 darts (36 for each volume). +Generalized maps representing the objects given in \cgalFigureRef{figexemple3Dmanifold}. Left: The 2D generalized map which contains \tred{24} darts. Right: The 3D generalized map which contains \tred{108} darts (\tred{36} for each volume). \cgalFigureEnd -First let us start in 2D (\cgalFigureRef{figexemplegenmaps} (Left)). Edge f1 is described by two darts. These darts are linked together with pointers called \f$ \alpha_0\f$. Starting from a dart and following a \f$ \alpha_0\f$ pointer, we get to a dart which belongs to the same edge, to the same facet but to the other vertex (0-cell, which explains the index 0 of \f$ \alpha_0\f$). Facet f1 is described by four edges, and thus by eight darts. The edges are linked together with pointers called \f$ \alpha_1\f$. Starting from a dart and following a \f$ \alpha_1\f$ pointer, we get to a dart which belongs to the same vertex, the same facet but to the next edge (1-cell, which explains the index 1 of \f$ \alpha_1\f$). Lastly the faces are linked together with pointers called \f$ \alpha_2\f$. Starting from a dart and following a \f$ \alpha_2\f$ pointer, we get to a dart which belongs to the same vertex, the same edge but to the next face (2-cell, which explains the index 2 of \f$ \alpha_2\f$). +\cgalModifBegin + +First let us start in 2D (\cgalFigureRef{figexemplegenmaps} (Left)). Edge e1 is described by four darts. These darts are linked together with pointers called \f$ \alpha_0\f$ and \f$ \alpha_2\f$. Starting from a dart and following an \f$ \alpha_0\f$ pointers, we get to a dart which belongs to the same edge, to the same facet but to the other vertex (0-cell, which explains the index 0 of \f$ \alpha_0\f$). Starting from a dart and following an \f$ \alpha_2\f$ pointers, we get to a dart which belongs to the same vertex, to the same edge but to the other facet (2-cell, which explains the index 2). + +Facet f1 is described by four edges, and thus by eight darts. The edges are linked together with pointers called \f$ \alpha_0\f$ and \f$ \alpha_1\f$. Starting from a dart and following a \f$ \alpha_1\f$ pointer, we get to a dart which belongs to the same vertex, the same facet but to the other edge (1-cell, which explains the index 1 of \f$ \alpha_1\f$). + +Similarly, vertex v1 is described by six darts, linked together with pointers \f$ \alpha_1\f$ and \f$ \alpha_2\f$. + +\cgalModifEnd The main interest of generalized map definition based on darts and \f$ \alpha_i\f$ pointers is to be able to increase the dimension "only" by adding new pointers. We can verify this fact by studying the 3D example (\cgalFigureRef{figexemplegenmaps} (Right)). In addition to \f$ \alpha_0\f$, \f$ \alpha_1\f$ and \f$ \alpha_2\f$ of the 2D case, there is a new pointer \f$ \alpha_3\f$. -If we take a closer look at the central edge e4 shown in \cgalFigureRef{figintuitiveexemple} (Left), we can see that it is described by twelve darts linked together. Starting from a dart and following a \f$ \alpha_3\f$ pointer, we get to a dart which belongs to the same vertex, to the same edge, to the same facet, but to the neighboring volume (a 3-cell, which explains the index 3 in \f$ \alpha_3\f$). Similarly, starting from a dart and following a \f$ \alpha_2\f$ pointer, we get to a dart which belongs to the same vertex, to the same edge, to the same volume, but to the neighboring facet (2-cell). And starting from a dart and following a \f$ \alpha_0\f$ pointer, we get to a dart which belongs to the same edge, to the same facet, to the same volume, but to the neighboring vertex (0-cell). Starting from any of these twelve darts and following \f$ \alpha_0\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ pointers, we can reach exactly the twelve darts describing edge e4. +If we take a closer look at the central edge e4 shown in \cgalFigureRef{figintuitiveexemple} (Left), we can see that it is described by \tred{twelve darts} linked together. Starting from a dart and following a \f$ \alpha_3\f$ pointer, we get to a dart which belongs to the \tred{same vertex, to the same edge, to the same facet, but to the neighboring volume} (a 3-cell, which explains the index 3 in \f$ \alpha_3\f$). Similarly, starting from a dart and following a \f$ \alpha_2\f$ pointer, we get to a dart which belongs to the same vertex, to the same edge, to the same volume, but to the neighboring facet (2-cell). And starting from a dart and following a \f$ \alpha_0\f$ pointer, we get to a dart which belongs to the same edge, to the same facet, to the same volume, but to the neighboring vertex (0-cell). Starting from any of these twelve darts and following \f$ \alpha_0\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ pointers, we can reach exactly the twelve darts describing edge e4. \cgalFigureBegin{figintuitiveexemple,gmaps2d-3d-zoom.svg} -Two zooms on the 3D generalized map given in \cgalFigureRef{figexemplegenmaps} (Right). Left: Zoom around the central edge e4 which details the twelve darts belonging to the edge. Right: Zoom around the facet between volumes vol2 and vol3 which details the sixteen darts belonging to the facet. +Two zooms on the 3D generalized map given in \cgalFigureRef{figexemplegenmaps} (Right). Left: Zoom around the central edge e4 which details the \tred{twelve} darts belonging to the edge. Right: Zoom around the facet between volumes vol2 and vol3 which details the \tred{sixteen} darts belonging to the facet. \cgalFigureEnd -For facets, by following a \f$ \alpha_1\f$ pointer, we get to a dart which belongs to the same vertex, to the same facet, to the same volume, but to the next edge (1-cell, which explains the index 1 of \f$ \alpha_1\f$). Starting from any dart and following \f$ \alpha_0\f$, \f$ \alpha_1\f$ and \f$ \alpha_3\f$ pointers, we can reach exactly all the darts describing the facet (see \cgalFigureRef{figintuitiveexemple} (Right)). For volumes, starting from any dart and following \f$ \alpha_0\f$, \f$ \alpha_1\f$ and \f$ \alpha_2\f$ pointers, we can reach exactly all the darts describing the volume. +For facets, by following a \f$ \alpha_1\f$ pointer, we get to a dart which belongs \tred{to the same vertex}, to the same facet, to the same volume, but to the next edge (1-cell, which explains the index 1 of \f$ \alpha_1\f$). Starting from any dart and following \f$ \alpha_0\f$, \f$ \alpha_1\f$ and \f$ \alpha_3\f$ pointers, we can reach exactly all the darts describing the facet (see \cgalFigureRef{figintuitiveexemple} (Right)). For volumes, starting from any dart and following \f$ \alpha_0\f$, \f$ \alpha_1\f$ and \f$ \alpha_2\f$ pointers, we can reach exactly all the darts describing the volume. \cgalModifBegin For vertices, we have to follow \f$ \alpha_1\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ pointers to reach exactly the darts describing the vertex v. \cgalModifEnd -For vertices, we have to follow \f$ \alpha_1\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ pointers to reach exactly the darts describing the vertex v. +In some cases, the general rule that by following a \f$ \alpha_i\f$ we get a dart which belongs to the neighboring i-cell is not true, as for example for darts belonging to the boundary of the represented object. For example, in \cgalFigureRef{figexemple3Dmanifold} (Left), any dart d0 that does not belong to edge e1, e2 and e3 belongs to a 2-cell, and there is no neighboring facet along the edge containing d0. Another example is in \cgalFigureRef{figexemple3Dmanifold} (Right), for any dart d0 that belongs to facet f5. d0 belongs to volume vol2, but there is no neighboring volume along this facet. The general rule is also not true for unbounded cells. For example if we remove a dart in \cgalFigureRef{figexemplegenmaps} (Left), we obtain an unbounded facet having \tred{one dart without next dart for} \f$ \alpha_0\f$, \tred{and one dart without next dart for} \f$ \alpha_1\f$, and if we remove a facet in \cgalFigureRef{figexemplegenmaps} (Right), we obtain an unbounded volume having some darts without neighboring facet for \f$ \alpha_2\f$. In such a case, \tred{the darts are linked with themselves for} \f$ \alpha_i\f$ to describe that a dart d0 is not linked to another dart in dimension i. -In some cases, the general rule that by following a \f$ \alpha_i\f$ we get a dart which belongs to the neighboring i-cell is not true, as for example for darts belonging to the boundary of the represented object. For example, in \cgalFigureRef{figexemple3Dmanifold} (Left), any dart d0 that does not belong to edge e1, e2 and e3 belongs to a 2-cell, and there is no neighboring facet along the edge containing d0. Another example is in \cgalFigureRef{figexemple3Dmanifold} (Right), for any dart d0 that belongs to facet f5. d0 belongs to volume vol2, but there is no neighboring volume along this facet. The general rule is also not true for unbounded cells. For example if we remove a dart in \cgalFigureRef{figexemplegenmaps} (Left), we obtain an unbounded facet having two darts without next dart for \f$ \alpha_1\f$, and if we remove a facet in \cgalFigureRef{figexemplegenmaps} (Right), we obtain an unbounded volume having some darts without neighboring facet for \f$ \alpha_2\f$. In such a case, the darts are linked with themselves for \f$ \alpha_i\f$ to describe that a dart d0 is not linked to another dart in dimension i. - -Generalized maps are defined in any dimension. A -1D generalized map is a set of isolated darts describing isolated vertices. A 0D generalized map is a set of darts paired by \f$ \alpha_0\f$ describing isolated edges. A 1D generalized map describes paths or cycles of darts corresponding to paths or cycles of edges. The most useful cases are 2D and 3D generalized maps. In 2D, a generalized map is a set of surfaces (orientable or not), and in 3D a generalized map is a set of connected volumes. In the following, notions are mainly illustrated in 3D. But it is important to keep in mind that one main interest of generalized maps is their generic definition in any dimension, and that everything presented in this manual is valid in any dimension. +Generalized maps are defined in any dimension. \cgalModifBegin -1D generalized map is a set of isolated darts describing isolated vertices. A 0D generalized map is a set of darts paired by \f$ \alpha_0\f$ describing isolated edges. \cgalModifEnd A 1D generalized map describes paths or cycles of darts corresponding to paths or cycles of edges. The most useful cases are 2D and 3D generalized maps. In 2D, a generalized map is a set of surfaces \tred{(orientable or not),} and in 3D a generalized map is a set of connected volumes. In the following, notions are mainly illustrated in 3D. But it is important to keep in mind that one main interest of generalized maps is their generic definition in any dimension, and that everything presented in this manual is valid in any dimension. A dD generalized map is useful when you want to describe dD objects and the adjacency relations between these objects, and you want to be able to efficiency traverse these objects by using the different relations. For example, we can use a 3D generalized map to describe a 3D segmented image: each 3-cell corresponds to a region in the image and each 2-cell corresponds to a contact area between two regions. -A generalized map does not contain any geometrical information. However, this package allows to associate any information to the cells of the generalized map. A specific information, which is often used in practice, consists in adding linear geometry to a generalized map by associating a point to each vertex of the map: this is the object of the \ref ChapterLinearCellComplex "Linear cell complex" package (when an object has a point associated to each vertex, each edge is thus a straight line segment, which explains the name "linear geometry"). The \ref ChapterLinearCellComplex "Linear cell complex" package can for example be useful to describe 3D buildings as set of walls, rooms, doors and windows (both generalized and geometrical descriptions) and all the adjacency relations between these elements allowing for example to move a camera in a given building from rooms to rooms by traversing doors. +A generalized map does not contain any geometrical information. However, this package allows to associate any information to the cells of the generalized map. A specific information, which is often used in practice, consists in adding linear geometry to a generalized map by associating a point to each vertex of the map: this is the object of the \ref ChapterLinearCellComplex "Linear cell complex" package (when an object has a point associated to each vertex, each edge is thus a straight line segment, which explains the name "linear geometry"). The \ref ChapterLinearCellComplex "Linear cell complex" package can for example be useful to describe 3D buildings as set of walls, rooms, doors and windows (both combinatorial and geometrical descriptions) and all the adjacency relations between these elements allowing for example to move a camera in a given building from rooms to rooms by traversing doors. -\section sec_presentation Data Structure Presentation +\section sec_presentation_gmap Data Structure Presentation -In this section, we describe dD generalized maps in terms of data structure and operations. Mathematical definitions are provided in Section \ref sec_definition "Mathematical Definitions", and a package description is given in Section \ref secsoftwaredesign "Software Design". +In this section, we describe dD generalized maps in terms of data structure and operations. Mathematical definitions are provided in Section \ref sec_definition_gmap "Mathematical Definitions", and a package description is given in Section \ref secsoftwaredesign_gmap "Software Design". \subsection ssecgenmapanddarts Generalized Map and Darts @@ -58,13 +65,13 @@ A dD generalized map is a set of darts D. A dart d0 is an e A generalized map is without i-boundary if there is no i-free dart, and it is without boundary if it is without i-boundary for all dimensions 1\f$ \leq\f$i\f$ \leq\f$d. -We show in \cgalFigureRef{figexemplecarte3d} a 3D object and the corresponding 3D generalized map. This map has 80 darts, some darts being numbered. In this generalized map, we have for example \f$ \alpha_0\f$(1)=2, \f$ \alpha_1\f$(1)=8, \f$ \alpha_2\f$(1)=24, and \f$ \alpha_3\f$(1)=9. This generalized map is without 0-boundary, without 1-boundary and 2-boundary, but has some 3-boundary, because some darts are 3-free, for example \f$ \alpha_3\f$(17)=17. +We show in \cgalFigureRef{figexemplecarte3d} a 3D object and the corresponding 3D generalized map. This map has \tred{80} darts, some darts being numbered. In this generalized map, we have for example \f$ \alpha_0\f$(1)=2, \f$ \alpha_1\f$(1)=8, \f$ \alpha_2\f$(1)=24, and \f$ \alpha_3\f$(1)=9. This generalized map is without \tred{0-boundary}, without 1-boundary and 2-boundary, but has some 3-boundary, because some darts are 3-free, for example \f$ \alpha_3\f$(17)=17. \cgalFigureBegin{figexemplecarte3d,gmap3d-example2.svg} -Example of a 3D generalized map. Left: A 3D object made of two volumes adjacent along facet f2. Right: The corresponding 3D generalized map. Darts are drawn with black segments, sometimes numbered. Two darts linked by \f$ \alpha_0\f$ are drawn aligned and separated by a small gray orthogonal segment (for example \f$ \alpha_0\f$(1)=2), two darts linked by \f$ \alpha_1\f$ are drawn consecutively and separated by a small gray disk (for example \f$ \alpha_1\f$(1)=8), and two darts linked by \f$ \alpha_2\f$ are drawn parallel, in reverse orientations, with the little gray segment joining them (for example \f$ \alpha_2\f$(1)=24). \f$ \alpha_3\f$ pointers are represented by blue segments in this figure (for example \f$ \alpha_3\f$(1)=9). +Example of a 3D generalized map. Left: A 3D object made of two volumes adjacent along facet f2. Right: The corresponding 3D generalized map. Darts are drawn with \tred{black segments}, sometimes numbered. Two darts linked by \f$ \alpha_0\f$ \tred{are drawn aligned and separated by a small gray orthogonal segment} (for example \f$ \alpha_0\f$(1)=2), \tred{two darts linked by} \f$ \alpha_1\f$ are drawn consecutively \tred{and separated by a small gray disk} (for example \f$ \alpha_1\f$(1)=8), and two darts linked by \f$ \alpha_2\f$ are drawn parallel, in reverse orientations, with the little gray segment joining them (for example \f$ \alpha_2\f$(1)=24). \f$ \alpha_3\f$ pointers are represented by blue segments in this figure (for example \f$ \alpha_3\f$(1)=9). \cgalFigureEnd -\subsection sseccellsinmap Cells as Sets of Darts +\subsection sseccellsingmap Cells as Sets of Darts A cell in a dD generalized map is implicitly represented by a subset of darts. In this section, we will see how to retrieve all cells containing a given dart, how to retrieve all darts belonging to a cell containing a given dart, and how incidence and adjacency relations are defined in terms of darts. @@ -86,21 +93,21 @@ A last important property of cells is that for all dimensions i the set o Let us give some examples of cells in 3D, for the 3D generalized map of \cgalFigureRef{figexemplecarte3d} : Using this definition of cells as sets of darts, we can retrieve all the incidence and adjacency relations between the cells of the subdivision in a generalized map. Two cells are incident if the intersection of their two sets of darts is non empty (whatever the dimension of the two cells). Two i-cells c1 and c2, 1\f$ \leq\f$i\f$ \leq\f$d, are adjacent if there is d1\f$ \in\f$c1 and d2\f$ \in\f$c2 such that d1 and d2 belong to the same (i-1)-cell. -In the example of \cgalFigureRef{figexemplecarte3d}, vertex v and edge e are incident since the intersection of the two corresponding sets of darts is {1,9,24,25}\f$ \neq\f$\f$ \emptyset\f$. Vertex v is incident to facet f2 since the intersection of the two corresponding sets of darts is {1,8,9,16}\f$ \neq\f$\f$ \emptyset\f$. Edge e and facet f1 are incident since the intersection of the two corresponding sets of darts is {23,24}\f$ \neq\f$\f$ \emptyset\f$. Finally, facets f1 and f2 are adjacent because 1\f$ \in\f$f1, 24\f$ \in\f$f2 and 1 and 24 belong to the same edge. +In the example of \cgalFigureRef{figexemplecarte3d}, vertex v and edge e are incident since the intersection of the two corresponding sets of darts is {\tred{1,9,24,25}}\f$ \neq\f$\f$ \emptyset\f$. Vertex v is incident to facet f2 since the intersection of the two corresponding sets of darts is {\tred{1,8,9,16]}\f$ \neq\f$\f$ \emptyset\f$. Edge e and facet f1 are incident since the intersection of the two corresponding sets of darts is {\tred{23,24}}\f$ \neq\f$\f$ \emptyset\f$. Finally, facets f1 and f2 are adjacent because 1\f$ \in\f$f1, \tred{24}\f$ \in\f$f2 and 1 and \tred{24} belong to the same edge. We can consider i-cells in a dimension d' with i\f$ \leq\f$d'\f$ \leq\f$ d. The idea is to consider the i-cells as if the generalized map was in d' dimension. For that, we only take into account the \f$ \alpha_j \f$s for j\f$ \leq\f$d'. The i-cell containing d0 in dimension d' is the orbit \f$ \langle{}\f$\f$ \alpha_0\f$,...,\f$ \alpha_{i-1}\f$,\f$ \alpha_{i+1}\f$,...,\f$ \alpha_{d'}\f$\f$ \rangle{}\f$(d0). By default, i-cells are considered in dimension d, the dimension of the generalized map. -In the example of \cgalFigureRef{figexemplecarte3d}, the 2-cell containing dart 1 is facet f2 which is the set of darts {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16}. If we consider the same 2-cell in dimension 2, we obtain the set of darts {1,2,3,4,5,6,7,8}. Intuitively we "forget" \f$ \alpha_3\f$ and we obtain the set of darts of the facet containing dart 1 restricted to the volume containing this dart. +In the example of \cgalFigureRef{figexemplecarte3d}, the 2-cell containing dart 1 is facet f2 which is the set of darts {\tred{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16}}. If we consider the same 2-cell in dimension 2, we obtain the set of darts {\tred{1,2,3,4,5,6,7,8}}. Intuitively we "forget" \f$ \alpha_3\f$ and we obtain the set of darts of the facet containing dart 1 restricted to the volume containing this dart. -\subsection ssecassociateattributes How to Associate Information to Cells +\subsection ssecassociateattributesgmap How to Associate Information to Cells Generalized maps only describe the cells of the subdvision, and all the incidence and adjacency relations between these cells. This is not enough for many applications which need to associate information to cells. This can be geometric or non-geometric information, such as 3D points associated to vertices, the edge length associated to edges, or a color or normal to a facet. @@ -115,11 +122,12 @@ Since i-cells are not explicitely represented in generalized maps, the as We can see two examples of generalized maps having some attributes in \cgalFigureRef{figexempleattribs}. In the first example (Left), a 2D generalized map has 1-attributes containing a float, for example corresponding to the length of the associated 1-cell, and 2-attributes containing a color in RGB format. In the second example (Right), a 3D generalized map has 2-attributes containing a color in RGB format. \cgalFigureBegin{figexempleattribs,gmap2d-3d-attribs.svg} -Example of generalized maps with attributes. Attributes are represented by black rectangles containing an information, and association between darts and attributes are represented by small red lines. Left: A 2D generalized map with 1-attributes containing a double, for example corresponding to the length of the 1-cell, and 2-attributes containing a color in RGB format. Only three edges of the generalized map, among the nine, are associated to a 1-attribute. All the 2-cells are associated to a 2-attribute. Right: A 3D generalized map with 2-attributes containing a color in RGB format. Only three 2-cells of the generalized map, among the ten, are associated to a 2-attribute. \cgalFigureEnd +Example of generalized maps with attributes. Attributes are represented by black rectangles containing an information, and association between darts and attributes are represented by small red lines. Left: A 2D generalized map with 1-attributes containing a double, for example corresponding to the length of the 1-cell, and 2-attributes containing a color in RGB format. Only three edges of the generalized map, among the nine, are associated to a 1-attribute. All the 2-cells are associated to a 2-attribute. Right: A 3D generalized map with 2-attributes containing a color in RGB format. Only three 2-cells of the generalized map, among the ten, are associated to a 2-attribute. +\cgalFigureEnd \subsection ssecgenmapvalidity Generalized Map Properties -There are some conditions that a generalized map must satisfy to be valid. Some of them have already been given about the \f$ \alpha\f$ pointers (see Section \ref ssecgenmapanddarts "Generalized Map and Darts") and about the association between darts and attributes (see Section \ref ssecassociateattributes "How to Associate Information to Cells"). +There are some conditions that a generalized map must satisfy to be valid. Some of them have already been given about the \f$ \alpha\f$ pointers (see Section \ref ssecgenmapanddarts "Generalized Map and Darts") and about the association between darts and attributes (see Section \ref ssecassociateattributesgmap "How to Associate Information to Cells"). There is an additional condition related to the type of represented objects, which are quasi-manifold dD objects. A dD quasi-manifold is an object obtained by taking some isolated d-cells, and allowing to glue d-cells along (d-1)-cells. In 2D, quasi-manifolds are manifolds, but this is no longer true in higher dimension as we can see in the example presented in \cgalFigureRef{figquasivariete}. In this example, the object to the right is not a manifold since the neighborhood of the point p in the object is not homeomorphic to a 3D ball (intuitively, two objects are homeomorphic if each object can be continuously deformed into the second one; in such a case, the two objects have exactly the same topological properties). @@ -127,7 +135,7 @@ There is an additional condition related to the type of represented objects, whi Example of a 3D quasi-manifold which is not a manifold. The object to the right is made of the four pyramids (shown to the left) glued together along facets, thus it is a quasi-manifold. \cgalFigureEnd -Generalized maps can only represent quasi-manifolds due to the definition of \f$ \alpha\f$ pointers. As we have seen in Section \ref sseccellsinmap "Cells as Sets of Darts", \f$ \alpha_i\f$(d0) (with 0\f$ \leq\f$i\f$ \leq\f$d) belongs to the same cells as d0, only the i-cell is different. In other words, \f$ \alpha_i\f$ links two i-cells that share a common (i-1)-cell: it is not possible to link more than two i-cells along a same (i-1)-cell. For this reason, it is not possible to describe non quasi-manifold objects as those shown in \cgalFigureRef{fignonquasimanifold} by generalized maps. +Generalized maps can only represent quasi-manifolds due to the definition of \f$ \alpha\f$ pointers. As we have seen in Section \ref sseccellsingmap "Cells as Sets of Darts", \f$ \alpha_i\f$(d0) (with 0\f$ \leq\f$i\f$ \leq\f$d) belongs to the same cells as d0, only the i-cell is different. In other words, \f$ \alpha_i\f$ links two i-cells that share a common (i-1)-cell: it is not possible to link more than two i-cells along a same (i-1)-cell. For this reason, it is not possible to describe non quasi-manifold objects as those shown in \cgalFigureRef{fignonquasimanifold} by generalized maps. \cgalFigureBegin{fignonquasimanifold,nonmanifolds.svg} Three examples of non quasi-manifold objects. Left: A 2D object which is not a quasi-manifold since the two 2-cells share a common vertex but no common 1-cell. Middle: A 3D object which is not a quasi-manifold since is it not only composed by 3D cells glued together (there is an isolated 2-cell in dark gray). Right: A 3D object which is not a quasi-manifold since the two 3-cells share a common edge but no common 2-cell. @@ -136,48 +144,48 @@ Three examples of non quasi-manifold objects. Left: A 2D object which is not a q Due to this additional condition, any objects can not be represented by a generalized map but only quasi-manifolds. We need to study now the inverse relation. Does any set of darts linked together by \f$ \alpha_i\f$'s, with 0\f$ \leq\f$i\f$ \leq\f$d correspond to a quasi-manifold? As we can see in \cgalFigureRef{figpbcarte}, the answer is no. \cgalFigureBegin{figpbcarte,problems-gmaps.svg} -Two examples of darts linked together by some \f$ \alpha_0\f$, \f$ \alpha_1\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ which does not represent a 3D quasi-manifold, and thus which are not 3D generalized map. Left: In this example, all the darts are 3-free except \f$ \alpha_3\f$(1)=a (resp. 2-b, 7-g and 8-h, and vice-versa). Right: In this example, darts 1 to 8 and a to h linked by \f$ \alpha_3\f$ are not in the same order in both 3-cells. +Two examples of darts linked together by some \f$ \alpha_0\f$, \f$ \alpha_1\f$, \f$ \alpha_2\f$ and \f$ \alpha_3\f$ which does not represent a 3D quasi-manifold, and thus which are not 3D generalized map. Left: In this example, all the darts are 3-free except \f$ \alpha_3\f$(1)=a (resp. 2-b, 7-g and 8-h, and vice-versa). Right: In this example, darts \tred{1 to 8 and a to h} linked by \f$ \alpha_3\f$ are not in the same order in both 3-cells. \cgalFigureEnd In the first example (Left), there are two 3-cells (one to the left for the cube, a second to the right for the pyramid) which are "partially adjacent" along one 2-cell. Indeed, only four darts of the 2-cell are linked by \f$ \alpha_3\f$. We have \f$ \alpha_3\f$(1)=a (resp. 2-b, 7-g and 8-h, and vice-versa). This configuration is not possible in a quasi-manifold: two d-cells are always glue along an "entire" (d-1)-cells. But as we can see in the second example (Right), the condition that all the darts of the cell are linked in not sufficient. Indeed, in this example, all the darts of the 2-cell between the cube and the pyramid are linked together by \f$ \alpha_3\f$. However, this configuration does not correspond to a 3D quasi-manifold. Indeed, the operation of gluing two d-cells along one (d-1)-cell must preserve the structure of the initial (d-1)-cell. -To avoid these two kinds of configurations, conditions are added on \f$ \alpha\f$ pointers compositions (see Section \ref sec_definition "Mathematical Definitions", condition (4) of the definition of generalized maps). Intuitively these conditions say that if two darts are linked by \f$ \alpha_i\f$, then all the required darts are linked by \f$ \alpha_i\f$ two by two in such a way that neighborhood relations are preserved. +To avoid these two kinds of configurations, conditions are added on \f$ \alpha\f$ pointers compositions (see Section \ref sec_definition_gmap "Mathematical Definitions", condition (4) of the definition of generalized maps). Intuitively these conditions say that if two darts are linked by \f$ \alpha_i\f$, then all the required darts are linked by \f$ \alpha_i\f$ two by two in such a way that neighborhood relations are preserved. We say that a generalized map is valid if it satisfies all the conditions on \f$ \alpha\f$ pointers and on association between darts and attributes. High level operations provided on generalized maps ensure that these conditions are always satisfied. Sometimes, it can be useful to use low level operations in a specific algorithm, for example to modify locally a generalized map in a really fast way. In such a case, additional operations may be needed to restore these validity conditions. -\section secsoftwaredesign Software Design +\section secsoftwaredesign_gmap Software Design -The diagram in \cgalFigureRef{figdiagram_class} shows the different classes of the package. `Generalized_map` is the main class (see Section \ref ssecgeneralizedmap "Generalized Maps"). It allows to manage darts (see Section \ref ssecdarts "Darts") and attributes (see Section \ref ssecattributes "Cell Attributes"). Users can customize a generalized map thanks to an items class (see Section \ref ssecitem "Generalized Map Items"), which defines the dart type and the attribute types. These types may be different for different dimensions, and they may also be void. +The diagram in \cgalFigureRef{figdiagram_class_gmap} shows the different classes of the package. `Generalized_map` is the main class (see Section \ref ssecgeneralizedmap "Generalized Maps"). It allows to manage darts (see Section \ref ssecdartsgmap "Darts") and attributes (see Section \ref ssecattributesgmap "Cell Attributes"). Users can customize a generalized map thanks to an items class (see Section \ref ssecitemgmap "Generalized Map Items"), which defines the dart type and the attribute types. These types may be different for different dimensions, and they may also be void. The darts and attributes are accessed through handles. A handle is a model of the `Handle` concept, thus supporting the two dereference operators `operator*` and `operator->`. All handles are model of `LessThanComparable` and `Hashable`, that is they can be used as keys in containers such as `std::map` and `boost::unordered_map`. \cgalFigureBegin{figdiagram_class,Diagramme_class.svg} -UML diagram of the main classes of the package. k is the number of non void attributes. Gray elements come from the \ref ChapterCombinatorialMap "Combinatorial maps package". +UML diagram of the main classes of the package. k is the number of non void attributes. \tred{Gray element comes from the \ref ChapterCombinatorialMap "Combinatorial maps package".} \cgalFigureEnd \subsection ssecgeneralizedmap Generalized Maps The class `Generalized_map` is a model of the `GeneralizedMap` concept. It has three template parameters standing for the dimension of the generalized map (an `unsigned int`), an items class (a model of the `GeneralizedMapItems` concept), and an allocator which must be a model of the allocator concept of the \stl. %Default classes are provided for the items and the allocator classes. -The main role of the class `Generalized_map` is the storage and the management of darts. It allows to create or remove an isolated dart from the generalized map. The \link GeneralizedMap::Dart_handle `Dart_handle`\endlink type defines a handle to the type of used darts (given in the items class). `Generalized_map` provides several ranges which allow to iterate over specific subsets of darts of the generalized map (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). It also defines several methods to link and to unlink darts by \f$ \alpha_i\f$s (see Section \ref sseclinkdarts "Sewing Orbits and Linking Darts"). We said that a dart d0 is i-free if \f$ \alpha_i\f$(d0)=d0. Finally, some high level operations are defined to update the generalized map (see Section \ref ssecoperations "Removal and Insertion Operations") +The main role of the class `Generalized_map` is the storage and the management of darts. It allows to create or remove an isolated dart from the generalized map. The \link GeneralizedMap::Dart_handle `Dart_handle`\endlink type defines a handle to the type of used darts (given in the items class). `Generalized_map` provides several ranges which allow to iterate over specific subsets of darts of the generalized map (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). It also defines several methods to link and to unlink darts by \f$ \alpha_i\f$s (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts"). We said that a dart d0 is i-free if \f$ \alpha_i\f$(d0)=d0. Finally, some high level operations are defined to update the generalized map (see Section \ref ssecoperationsgmap "Removal and Insertion Operations") The second role of the class `Generalized_map` is the storage and the management of attributes. It allows to create or remove an attribute, and provides methods to associate attributes and cells. A range is defined for each i-attribute allowing to iterate over all the i-attributes of the generalized map. Finally, `Generalized_map` defines several types allowing to manage the attributes. We can use \link GeneralizedMap::Attribute_handle `Generalized_map::Attribute_handle::type`\endlink for a handle to the i-attributes (and the const version \link GeneralizedMap::Attribute_const_handle `Generalized_map::Attribute_const_handle::type` \endlink) and \link GeneralizedMap::Attribute_type `Generalized_map::Attribute_type::type` \endlink for the type of the i-attributes. All information associated to darts (\f$ \alpha\f$ links and attributes) can be accessed through member functions in `GeneralizedMap`. -\subsection ssecitem Generalized Map Items +\subsection ssecitemgmap Generalized Map Items -The `GeneralizedMapItems` concept defines dart and attribute types of a generalized map. It contains one inner class named \link GeneralizedMapItems::Dart_wrapper `Dart_wrapper`\endlink, having one template parameter, `GMap`, a model of `GeneralizedMap` concept. The \link GeneralizedMapItems::Dart_wrapper `Dart_wrapper`\endlink class provides two local types: `%Dart` which must be a model of the `::GDart` concept, and `%Attributes` which defines the attributes and their types. +The \tred{`GeneralizedMapItems`} concept defines dart and attribute types of a generalized map. It contains one inner class named \link GeneralizedMapItems::Dart_wrapper `Dart_wrapper`\endlink, having one template parameter, `GMap`, a model of \tred{`GeneralizedMap`} concept. The \link GeneralizedMapItems::Dart_wrapper `Dart_wrapper`\endlink class provides two local types: `%Dart` which must be a model of the \tred{`::GDart`} concept, and `%Attributes` which defines the attributes and their types. The `%Attributes` tuple must contain at most d+1 types (one for each possible cell dimension of the generalized map). Each type of the tuple must be either a model of the `CellAttribute` concept or `void`. The first type corresponds to 0-attributes, the second to 1-attributes and so on. If the i th type in the tuple is `void`, (i-1)-attributes are disabled: we say that (i-1)-attributes are void. Otherwise, (i-1)-attributes are enabled and have the given type: we say (i-1)-attributes are non void. If the size of the tuple is k, with k\f$ <\f$dimension+1, \f$ \forall\f$i: k\f$ \leq\f$i\f$ \leq\f$dimension, i-attributes are void. -The class `Generalized_map_min_items` is a model of the `GeneralizedMapItems` concept which can be used for default behaviors. It defines `GDart` as type of dart, and `Attributes` as empty tuple. +The class `Generalized_map_min_items` is a model of the `GeneralizedMapItems` concept which can be used for default behaviors. It defines \tred{`GDart`} as type of dart, and `Attributes` as empty tuple. -\subsection ssecdarts Darts +\subsection ssecdartsgmap Darts -The class `GDart`, a model of the `::GDart` concept, defines a dD dart for generalized maps. It has two template parameters standing for the dimension of the generalized map, and a model of the `GeneralizedMap` concept, which provides the two types \link GeneralizedMap::Dart_handle `Dart_handle`\endlink and \link GeneralizedMap::Dart_const_handle `Dart_const_handle`\endlink. +The class \tred{`GDart`}, a model of the \tred{`::GDart`} concept, defines a dD dart for generalized maps. It has two template parameters standing for the dimension of the generalized map, and a model of the `GeneralizedMap` concept, which provides the two types \link GeneralizedMap::Dart_handle `Dart_handle`\endlink and \link GeneralizedMap::Dart_const_handle `Dart_const_handle`\endlink. Each instance `d0` of `GDart` stores the \f$ \alpha_i\f$ pointers in an array of d+1 `Dart_handle`. It also stores the attributes associated to this dart in a tuple of \link GeneralizedMap::Attribute_handle `GMap::Attribute_handle::type` \endlink, one for each non void i-attribute. @@ -185,7 +193,7 @@ Methods are defined allowing to retrieve each \f$ \alpha_i\f$ and each associate Note that the use of the `GDart` class is not hard wired in the generalized map class. Users can provide their own model of the `::GDart` concept, and pass it to the generalized map with the help of a custom item class. -\subsection ssecattributes Cell Attributes +\subsection ssecattributesgmap Cell Attributes The class `Cell_attribute`, a model of the `CellAttribute` concept, represents an attribute associated with a cell of a combinatorial map or a generalized map. The template parameter `Map` must be a model of the `CombinatorialMap` or the `GeneralizedMap` concept. The attribute stores a handle to one dart of its associated cell when the template parameter `Tag` is \link CGAL::Tag_true `Tag_true` \endlink. `Info_` is the type of information stored in the attribute. It may be `void`. `OnMerge` and `OnSplit` must be either `Null_functor`, or models of the `Binary Function` concept having two references to a model of `CellAttribute` as type of both parameters and `void` as return type. There are two default parameters for `OnMerge` and `OnSplit`, which are `Null_functor`, a default parameter for `Tag` which is `Tag_true`, and a default parameter for `Info_` which is `void`. @@ -197,7 +205,7 @@ In addition, there are dynamic onmerge and onsplit functions that can be associa What we said for the dart also holds for the cell attribute. The generalized map can be used with any user defined model of the `CellAttribute` concept. -\subsection ssecexampledef Example of Generalized Map Definition +\subsection ssecexampledefgmap Example of Generalized Map Definition Here comes an example of two generalized map definitions. The first case `Example_gmap4` defines a 4D generalized map which uses all the default values (`GDart` and `Generalized_map_min_items`). The second example `Example_custom_gmap3` uses its own model of the `GeneralizedMapItems` concept. In this model, the type of dart is `GDart<3,GMap>`, thus a dart is in 3D, and an attribute containing an integer is associated to edges. @@ -221,9 +229,9 @@ typedef CGAL::Generalized_map<3, Example_items_3> Example_custom_gmap3; \section Generalized_mapIteration Iteration and Creation Operations -An important operation in generalized maps consists in iterating over specific subsets of darts or over attributes. For that, several ranges are offered (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). A range is a model of the `Range` concept, thus supporting the two methods `begin()` and `end()` allowing to iterate over all the elements in the range. Several functions allow to create specific configurations of darts into a generalized map (see Section \ref ssecconstruction "Construction Operations"). Darts can be marked during operations, for example when performing a breadth-first search traversal, thanks to Boolean marks (see Sections \ref ssecadvmarks "Boolean Marks"). In the following, we denote by `dh0`, `dh1`, `dh2` the dart handles for the darts `d0`, `d1`, `d2`, respectively. That is `d0 == *dh0`. +An important operation in generalized maps consists in iterating over specific subsets of darts or over attributes. For that, several ranges are offered (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). A range is a model of the `Range` concept, thus supporting the two methods `begin()` and `end()` allowing to iterate over all the elements in the range. Several functions allow to create specific configurations of darts into a generalized map (see Section \ref ssecconstructiongmap "Construction Operations"). Darts can be marked during operations, for example when performing a breadth-first search traversal, thanks to Boolean marks (see Sections \ref ssecadvmarksgmap "Boolean Marks"). In the following, we denote by `dh0`, `dh1`, `dh2` the dart handles for the darts `d0`, `d1`, `d2`, respectively. That is `d0 == *dh0`. -\subsection ssecrange Iterating over Orbits, Cells, and Attributes +\subsection ssecrangegmap Iterating over Orbits, Cells, and Attributes The generalized map offers iterators to traverse the darts of a specific orbit, to traverse all darts of one cell, or one dart per cell, and to traverse all i-attributes. @@ -252,7 +260,7 @@ Additionally, there is a range over non void i-attributes: \link Generali For each range, there is an associated const range, a model of the `ConstRange` concept. You can find some examples of ranges in Section \ref ssecexample3DGM "A 3D Generalized Map". -\subsection ssecconstruction Construction Operations +\subsection ssecconstructiongmap Construction Operations Several functions allow to create specific configurations of darts into a generalized map. Existing darts in the generalized map are not modified. Note that the dimension of the generalized map must be large enough: darts must contain all the \f$ \alpha\f$ pointers used by the operation. All these functions return a \link GeneralizedMap::Dart_handle `Dart_handle`\endlink to a new dart created during the operation. @@ -263,12 +271,11 @@ Several functions allow to create specific configurations of darts into a genera
  1. gm.`make_combinatorial_hexahedron()`: creates an isolated combinatorial hexahedron (six combinatorial quadrangles linked together by \f$ \alpha_2\f$); dimension must be greater or equal than two. -\subsection ssecadvmarks Boolean Marks +\subsection ssecadvmarksgmap Boolean Marks It is often necessary to mark darts, for example to retrieve in O(1) if a given dart was already processed during a specific algorithm, for example, iteration over a given range. Users can also mark specific parts of a generalized map (for example mark all the darts belonging to objects having specific semantics). To answer these needs, a `GeneralizedMap` has a certain number of Boolean marks (fixed by the constant \link GeneralizedMap::NB_MARKS `NB_MARKS`\endlink). When one wants to use a Boolean mark, the following methods are available (with `gm` an instance of a generalized map):
      -
    • get a new free mark: `size_type m = gm.`\ref GeneralizedMap::get_new_mark "get_new_mark()" - (throws the exception Exception_no_more_available_mark if no mark is available); +
    • get a new free mark: `size_type m = gm.`\ref GeneralizedMap::get_new_mark "get_new_mark()" (throws the exception Exception_no_more_available_mark if no mark is available);
    • set mark `m` for a given dart `d0`: `gm.`\ref GeneralizedMap::mark "mark(dh0,m)";
    • unset mark `m` for a given dart `d0`: `gm.`\ref GeneralizedMap::unmark "unmark(dh0,m)";
    • test if a given dart `d0` is marked for `m`: `gm.`\ref GeneralizedMap::is_marked "is_marked(dh0,m)"; @@ -279,19 +286,19 @@ It is often necessary to mark darts, for example to retrieve in O(1) if a It is important to free a mark when it is no longer needed, otherwise you may at some point run out of marks. -The following example illustrates how to use marks. Two combinatorial tetrahedra are created and 3-sewn (see Section \ref sseclinkdarts "Sewing Orbits and Linking Darts" for a detailed description of the sew operation). Then a mark is reserved and used to mark all the darts belonging to the first combinatorial tetrahedron. Finally, these tetrahedron are merged. The marks allow us to know which darts come from the first and second tetrahedron. +The following example illustrates how to use marks. Two combinatorial tetrahedra are created and 3-sewn (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts" for a detailed description of the sew operation). Then a mark is reserved and used to mark all the darts belonging to the first combinatorial tetrahedron. Finally, these tetrahedron are merged. The marks allow us to know which darts come from the first and second tetrahedron. \cgalExample{Generalized_map/gmap_3_marks.cpp} -\section ssecmodoperations Modification Operations +\section ssecmodoperations_gmap Modification Operations Several operations allow to modify a given generalized map. There are two main categories of modification operations:
        -
      • \ref GeneralizedMap::sew "Sew", \ref GeneralizedMap::link_alpha "link_alpha", \ref GeneralizedMap::unsew "unsew" and \ref GeneralizedMap::unlink_alpha "unlink_alpha" which modify some existing \f$ \alpha\f$ pointers, without creating or removing darts (see Section \ref sseclinkdarts "Sewing Orbits and Linking Darts"); -
      • Removal and insertion of cells which modify both darts and \f$ \alpha\f$ pointers (see Section \ref ssecoperations "Removal and Insertion Operations"). +
      • \ref GeneralizedMap::sew "Sew", \ref GeneralizedMap::link_alpha "link_alpha", \ref GeneralizedMap::unsew "unsew" and \ref GeneralizedMap::unlink_alpha "unlink_alpha" which modify some existing \f$ \alpha\f$ pointers, without creating or removing darts (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts"); +
      • Removal and insertion of cells which modify both darts and \f$ \alpha\f$ pointers (see Section \ref ssecoperationsgmap "Removal and Insertion Operations").
      -\subsection sseclinkdarts Sewing Orbits and Linking Darts +\subsection sseclinkdarts_gmap Sewing Orbits and Linking Darts The `GeneralizedMap` defines two groups of methods to modify the \f$ \alpha\f$ pointers of existing darts. @@ -310,244 +317,71 @@ Reciprocally, unlinking a given dart d0 by \f$ \alpha_i\f$, with 0\f$ \le Example of \ref GeneralizedMap::sew "3-sew" operation. Left: A 3D generalized map containing two volumes that are not connected, with 2-attributes. Each attribute contains a color in RGB format, and there are four 2-cells associated with attributes. Associations between darts and attributes are drawn with red segments. Right: The 3D generalized map obtained as result of \ref GeneralizedMap::sew "sew<3>(1,5)" (or \ref GeneralizedMap::sew "sew<3>(2,8)", or \ref GeneralizedMap::sew "sew<3>(3,7)", or \ref GeneralizedMap::sew "sew<3>(4,6)"). Darts (1,5), (2,8), (3,7) and (4,6) are linked together by \f$ \alpha_3\f$. The two 2-cells c1={1,2,3,4} and c2={5,6,7,8} are merged after the sew into the 2-cell {1,2,3,4,5,6,7,8}. We are in the case where the two attributes are non NULL, thus the first one is kept, and all the darts of c2 are associated with the first attribute. \cgalFigureEnd -The \ref GeneralizedMap::sew "sew(dh1,dh2)" method consists mainly to link two by two -several darts by \f$ \alpha_i\f$. This operation is possible only if -there is a bijection f between all the darts of the orbit -D1=\f$ \langle{}\f$\f$ \alpha_1\f$,...,\f$ -\alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,...,\f$ \alpha_d\f$\f$ -\rangle{}\f$(d1) and D2=\f$ \langle{}\f$\f$ -\alpha_1\f$,...,\f$ \alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,..., -\f$ \alpha_d\f$\f$ \rangle{}\f$(d2) satisfying: -f(d1)=d2, and for all e\f$ -\in\f$D1, for all j\f$ \in\f${1,..., -i-2,i+2,...,d}, f(\f$ -\alpha_j\f$(e))=\f$ -\alpha_j^{-1}\f$(f(e)). Intuitively, this condition -ensures the validity of the generalized map by verifying that -condition discussed in Section -\ref ssecgenmapvalidity "Generalized Map Properties" will be -satisfied after the operation. This condition can be tested by using -the method \ref GeneralizedMap::is_sewable "is_sewable(dh1,dh2)". -For example, the function -\ref GeneralizedMap::is_sewable "is_sewable<3>" would return `false` if -we tried to 3-sew a triangular -facet with a quad facet. Note that given two darts d1 and -d2, if there is such a bijection, it is uniquely defined. So -giving the two darts as arguments of the \ref GeneralizedMap::sew "sew" -is enough to -retrieve all the pairs of darts to link. If such a bijection exists, -the \ref GeneralizedMap::sew "sew(dh1,dh2)" operation consists only in -linking by \f$ \alpha_i\f$ each couple of darts d3 and d4 such that -d3=f(d4). +The \ref GeneralizedMap::sew "sew(dh1,dh2)" method consists mainly to link two by two several darts by \f$ \alpha_i\f$. This operation is possible only if there is a bijection f between all the darts of the orbit D1=\f$ \langle{}\f$\f$ \alpha_1\f$,...,\f$ \alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,...,\f$ \alpha_d\f$\f$ \rangle{}\f$(d1) and D2=\f$ \langle{}\f$\f$ \alpha_1\f$,...,\f$ \alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,..., \f$ \alpha_d\f$\f$ \rangle{}\f$(d2) satisfying: f(d1)=d2, and for all e\f$ \in\f$D1, for all j\f$ \in\f${1,..., i-2,i+2,...,d}, f(\f$ \alpha_j\f$(e))=\f$ \alpha_j^{-1}\f$(f(e)). Intuitively, this condition ensures the validity of the generalized map by verifying that condition discussed in Section \ref ssecgenmapvalidity "Generalized Map Properties" will be satisfied after the operation. This condition can be tested by using the method \ref GeneralizedMap::is_sewable "is_sewable(dh1,dh2)". For example, the function \ref GeneralizedMap::is_sewable "is_sewable<3>" would return `false` if we tried to 3-sew a triangular facet with a quad facet. Note that given two darts d1 and d2, if there is such a bijection, it is uniquely defined. So giving the two darts as arguments of the \ref GeneralizedMap::sew "sew" is enough to retrieve all the pairs of darts to link. If such a bijection exists, the \ref GeneralizedMap::sew "sew(dh1,dh2)" operation consists only in linking by \f$ \alpha_i\f$ each couple of darts d3 and d4 such that d3=f(d4). -In addition, the sew operation updates the associations between darts -and non void attributes in order to guarantee that all the darts -belonging to a given cell are associated with the same attribute -(which is a condition of generalized map validity). For each couple -of j-cells c1 and c2 that are merged into one -j-cell during the sew, we have to update the two associated -attributes attr1 and attr2. If both are NULL, there is -nothing to do. If one is NULL and the other not, we only associate the -non NULL attribute to all the darts of the resulting cell. When the -two attributes are non NULL, we first apply functor \ref CellAttribute::On_merge "On_merge" on the -two attributes attr1 and attr2 (see Section -\ref ssecattributes "Cell Attributes"). Then, we associate the -attribute attr1 to all -darts of the resulting j-cell. Finally, attribute attr2 -is removed from the generalized map. +In addition, the sew operation updates the associations between darts and non void attributes in order to guarantee that all the darts belonging to a given cell are associated with the same attribute (which is a condition of generalized map validity). For each couple of j-cells c1 and c2 that are merged into one j-cell during the sew, we have to update the two associated attributes attr1 and attr2. If both are NULL, there is nothing to do. If one is NULL and the other not, we only associate the non NULL attribute to all the darts of the resulting cell. When the two attributes are non NULL, we first apply functor \ref CellAttribute::On_merge "On_merge" on the two attributes attr1 and attr2 (see Section \ref ssecattributesgmap "Cell Attributes"). Then, we associate the attribute attr1 to all darts of the resulting j-cell. Finally, attribute attr2 is removed from the generalized map. -Note that when the two attributes are non NULL, the first one is -kept. But user can customize this behavior in order to update the -information contained in the attributes according to its needs. For -that, we can define a specific functor, and use it as template -argument for \ref CellAttribute::On_merge "On_merge" parameter of the `Cell_attribute` -definition. This functor can for example copy the information of the -second attribute in the information of the first one to make as if the -second attribute is kept. +Note that when the two attributes are non NULL, the first one is kept. But user can customize this behavior in order to update the information contained in the attributes according to its needs. For that, we can define a specific functor, and use it as template argument for \ref CellAttribute::On_merge "On_merge" parameter of the `Cell_attribute` definition. This functor can for example copy the information of the second attribute in the information of the first one to make as if the second attribute is kept. -For example, in \cgalFigureRef{figexemplesew}, we want to 3-sew the two -initial volumes. \ref GeneralizedMap::sew "sew<3>(1,5)" links -by \f$ \alpha_3\f$ the pairs of -darts (1,5), (2,8), (3,7) and (4,6), thus the generalized map -obtained is valid. 2-attributes are updated so that all the darts -belonging to the 2-cell containing dart 1 become associated to the -same 2-attribute after the operation. +For example, in \cgalFigureRef{figexemplesew}, we want to 3-sew the two initial volumes. \ref GeneralizedMap::sew "sew<3>(1,5)" links by \f$ \alpha_3\f$ the pairs of darts (1,5), (2,8), (3,7) and (4,6), thus the generalized map obtained is valid. 2-attributes are updated so that all the darts belonging to the 2-cell containing dart 1 become associated to the same 2-attribute after the operation. -Similarly, \ref GeneralizedMap::unsew "unsew(dh0)" operation -unlinks \f$ \alpha_i\f$ for all -the darts in the orbit \f$ \langle{}\f$\f$ \alpha_1\f$,..., -\f$ \alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,...,\f$ -\alpha_d\f$\f$ \rangle{}\f$(d0), and thus guarantees to obtain -a valid generalized map. This operation is possible for any non -i-free dart. +Similarly, \ref GeneralizedMap::unsew "unsew(dh0)" operation unlinks \f$ \alpha_i\f$ for all the darts in the orbit \f$ \langle{}\f$\f$ \alpha_1\f$,..., \f$ \alpha_{i-2}\f$,\f$ \alpha_{i+2}\f$,...,\f$ \alpha_d\f$\f$ \rangle{}\f$(d0), and thus guarantees to obtain a valid generalized map. This operation is possible for any non i-free dart. -As for the sew operations, attributes are updated to guarantee that -two darts belonging to two different j-cells are associated to -two different j-attributes. If the unsew operation splits a -j-cell c in two j-cells c1 and c2, -and if c is associated to a j-attribute attr1, -then this attribute is duplicated into attr2, and all the darts -belonging to c2 are associated with this new -attribute. Finally, we call the functor \ref CellAttribute::On_split "On_split" on the two -attributes attr1 and attr2 (see Section \ref -ssecattributes "Cell Attributes"). +As for the sew operations, attributes are updated to guarantee that two darts belonging to two different j-cells are associated to two different j-attributes. If the unsew operation splits a j-cell c in two j-cells c1 and c2, and if c is associated to a j-attribute attr1, then this attribute is duplicated into attr2, and all the darts belonging to c2 are associated with this new attribute. Finally, we call the functor \ref CellAttribute::On_split "On_split" on the two attributes attr1 and attr2 (see Section \ref ssecattributesgmap "Cell Attributes"). -Let us consider the generalized map given in -\cgalFigureRef{figexemplesew} (Right). If we call -\ref GeneralizedMap::unsew "unsew<3>(2)", we obtain the -generalized map in \cgalFigureRef{figexemplesew} (Left) (except for the -color of the attribute associated to the 2-cell {5,6,7,8} which would -be #00ff00). The \ref GeneralizedMap::unsew "unsew<3>" -operation has duplicated the -2-attribute associated to the 2-cell {1,2,3,4,5,6,7,8} since this -2-cell is split in two after the unsew operation. +Let us consider the generalized map given in \cgalFigureRef{figexemplesew} (Right). If we call \ref GeneralizedMap::unsew "unsew<3>(2)", we obtain the generalized map in \cgalFigureRef{figexemplesew} (Left) (except for the color of the attribute associated to the 2-cell {5,6,7,8} which would be #00ff00). The \ref GeneralizedMap::unsew "unsew<3>" operation has duplicated the 2-attribute associated to the 2-cell {1,2,3,4,5,6,7,8} since this 2-cell is split in two after the unsew operation. \cgalAdvancedBegin -If one wants to modify a generalized map manually, -it is possible to switch off the updating between darts and -attributes by calling \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to call -\ref GeneralizedMap::sew "sew(dh1,dh2)" and -\ref GeneralizedMap::unsew "unsew(dh0)". In these cases, the -generalized map obtained may be no longer valid due to incorrect -associations between darts and attributes. In -\cgalFigureRef{figexemplesew} (Left), if we call \ref GeneralizedMap::sew "sew<3>(1,5)", the resulting -generalized map is similar to the generalized map of -\cgalFigureRef{figexemplesew} (Right) (we have linked by \f$ \alpha_3\f$ the pairs of -darts (1,5), (2,8), (3,7) and (4,6)), but associations between darts -and attributes are not valid. Indeed, we have kept the four initial -attributes and all the associations between darts and attributes, thus -two darts belonging to the same 2-cell (for example darts 1 and 5) are -associated with two different attributes. We can also use the -\ref GeneralizedMap::link_alpha "link_alpha(dh1,dh2)" which links `d1` and -`d2` by \f$ \alpha_i\f$ without modifying the other links. Association -between darts and attributes are only modified for darts `d1` and -`d2`, and similarly as for \ref GeneralizedMap::sew "sew", this updating can be avoided by -calling \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to call -\ref GeneralizedMap::link_alpha "link_alpha(dh1,dh2)". Lastly, we can use -\ref GeneralizedMap::unlink_alpha "unlink_alpha(dh0)" to unlink `d0` for \f$ \alpha_i\f$. In this last -case, there is no modification of association between darts and -attributes. In \cgalFigureRef{figexemplesew} (Left), if we call -\ref GeneralizedMap::link_alpha "link_alpha<3>(1,5)", in the resulting generalized map we have now -\f$ \alpha_3\f$(1)=5 and \f$ \alpha_3\f$(5)=1. This generalized map is -no longer valid (for example dart 2 is 3-free and we should have \f$ -\alpha_3\f$(2)=8). -A call latter to \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink will correct the invalid non void attributes. +If one wants to modify a generalized map manually, it is possible to switch off the updating between darts and attributes by calling \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to call \ref GeneralizedMap::sew "sew(dh1,dh2)" and \ref GeneralizedMap::unsew "unsew(dh0)". In these cases, the generalized map obtained may be no longer valid due to incorrect associations between darts and attributes. In \cgalFigureRef{figexemplesew} (Left), if we call \ref GeneralizedMap::sew "sew<3>(1,5)", the resulting generalized map is similar to the generalized map of \cgalFigureRef{figexemplesew} (Right) (we have linked by \f$ \alpha_3\f$ the pairs of darts (1,5), (2,8), (3,7) and (4,6)), but associations between darts and attributes are not valid. Indeed, we have kept the four initial attributes and all the associations between darts and attributes, thus two darts belonging to the same 2-cell (for example darts 1 and 5) are associated with two different attributes. We can also use the \ref GeneralizedMap::link_alpha "link_alpha(dh1,dh2)" which links `d1` and `d2` by \f$ \alpha_i\f$ without modifying the other links. Association between darts and attributes are only modified for darts `d1` and `d2`, and similarly as for \ref GeneralizedMap::sew "sew", this updating can be avoided by calling \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to call \ref GeneralizedMap::link_alpha "link_alpha(dh1,dh2)". Lastly, we can use \ref GeneralizedMap::unlink_alpha "unlink_alpha(dh0)" to unlink `d0` for \f$ \alpha_i\f$. In this last case, there is no modification of association between darts and attributes. In \cgalFigureRef{figexemplesew} (Left), if we call \ref GeneralizedMap::link_alpha "link_alpha<3>(1,5)", in the resulting generalized map we have now \f$ \alpha_3\f$(1)=5 and \f$ \alpha_3\f$(5)=1. This generalized map is no longer valid (for example dart 2 is 3-free and we should have \f$ \alpha_3\f$(2)=8). A call latter to \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink will correct the invalid non void attributes. \cgalAdvancedEnd -\subsection ssecoperations Removal and Insertion Operations +\subsection ssecoperationsgmap Removal and Insertion Operations -The following high level operations are defined as global functions -taking an instance `gm` of `GeneralizedMap` as first argument. All -these methods ensure that given a valid generalized map and a -possible operation, the modified generalized map is also valid. +The following high level operations are defined. All these methods ensure that given a valid generalized map and a possible operation, the modified generalized map is also valid. -The first one is `::remove_cell(gm,dh0)` which modifies the -generalized map to remove the i-cell containing dart `d0`, -with 0\f$ \leq\f$i\f$ \leq\f$d. This operation is -possible if i=d or if the given i-cell is -incident to at most two (i+1)-cells which can be tested thanks -to `::is_removable(gm,dh0)`. If the removed i-cell was -incident to two different (i+1)-cells, these two cells are -merged into one (i+1)-cell. In this case, the \ref CellAttribute::On_merge "On_merge" -functor is called if two (i+1)-attributes are associated to the -two (i+1)-cells. If the i-cell is associated with a non -void attribute, it is removed from the generalized map (see three -examples on \cgalFigureRef{figinsertvertex}, \cgalFigureRef{figinsertedge} -and \cgalFigureRef{figinsertface}). +The first one is `gm.remove_cell(dh0)` which modifies the generalized map to remove the i-cell containing dart `d0`, with 0\f$ \leq\f$i\f$ \leq\f$d. This operation is possible if i=d or if the given i-cell is incident to at most two (i+1)-cells which can be tested thanks to `gm.is_removable(dh0)`. If the removed i-cell was incident to two different (i+1)-cells, these two cells are merged into one (i+1)-cell. In this case, the \ref CellAttribute::On_merge "On_merge" functor is called if two (i+1)-attributes are associated to the two (i+1)-cells. If the i-cell is associated with a non void attribute, it is removed from the generalized map (see three examples on \cgalFigureRef{figinsertvertex}, \cgalFigureRef{figinsertedge} and \cgalFigureRef{figinsertface}). \cgalFigureBegin{figinsertvertex,insert-vertex.svg} -Example of `::insert_cell_0_in_cell_1` and `::remove_cell<0>` -operations. Left: Initial generalized map. Right: -After the insertion of a 0-cell in the 1-cell containing dart -`d1`. Now if we remove the 0-cell containing dart `d2`, we obtain the -initial generalized map. +Example of `insert_cell_0_in_cell_1` and `remove_cell<0>` operations. Left: Initial generalized map. Right: After the insertion of a 0-cell in the 1-cell containing dart `d1`. Now if we remove the 0-cell containing dart `d2`, we obtain the initial generalized map. \cgalFigureEnd -The inverse operation of the removal is the insertion operation. -Several versions exist, sharing a common principle. They consist in -adding a new i-cell "inside" an existing j-cell, -i\f$ <\f$j, by splitting the j-cell into several -j-cells. Contrary to `::remove_cell`, is it not possible -to define a unique `insert_cell_i_in_cell_j` function -because parameters are different depending on `i` and `j`. +The inverse operation of the removal is the insertion operation. Several versions exist, sharing a common principle. They consist in adding a new i-cell "inside" an existing j-cell, i\f$ <\f$j, by splitting the j-cell into several j-cells. Contrary to `remove_cell`, is it not possible to define a unique `insert_cell_i_in_cell_j` function because parameters are different depending on `i` and `j`. -`::insert_cell_0_in_cell_1(gm,dh0)` adds a 0-cell in the 1-cell -containing dart `d0`. The 1-cell is split in two. This operation is -possible if `d0`\f$ \in\f$\ref GeneralizedMap::darts "gm.darts()" (see example on -\cgalFigureRef{figinsertvertex}). +`gm.insert_cell_0_in_cell_1(dh0)` adds a 0-cell in the 1-cell containing dart `d0`. The 1-cell is split in two. This operation is possible if `d0`\f$ \in\f$\ref GeneralizedMap::darts "gm.darts()" (see example on \cgalFigureRef{figinsertvertex}). -`::insert_cell_0_in_cell_2(gm,dh0)` adds a 0-cell in the 2-cell -containing dart `d0`. The 2-cell is split in triangles, one for each -initial edge of the facet. This operation is possible if `d0`\f$ -\in\f$\ref GeneralizedMap::darts "gm.darts()" (see example on \cgalFigureRef{figtriangulate}). +`gm.insert_cell_0_in_cell_2(dh0)` adds a 0-cell in the 2-cell containing dart `d0`. The 2-cell is split in triangles, one for each initial edge of the facet. This operation is possible if `d0`\f$ \in\f$\ref GeneralizedMap::darts "gm.darts()" (see example on \cgalFigureRef{figtriangulate}). \cgalFigureBegin{figtriangulate,triangulation.svg} -Example of `::insert_cell_0_in_cell_2` operation. +Example of `insert_cell_0_in_cell_2` operation. \cgalFigureEnd -`::insert_cell_1_in_cell_2(gm,dh1,dh2)` adds a 1-cell in the -2-cell containing darts `d1` and `d2`, between the two 0-cells -containing darts `d1` and `d2`. The 2-cell is split in two. This -operation is possible if d1\f$ \in\f$\f$ \langle{}\f$\f$ -\alpha_1\f$\f$ \rangle{}\f$(d2) which can be tested thanks to -`::is_insertable_cell_1_in_cell_2(gm,dh1,dh2)`. In the example on -\cgalFigureRef{figinsertedge}, it is possible to insert an edge between darts -d2 and d3, but it is not possible to insert an edge -between d1 and d3. +`gm.insert_cell_1_in_cell_2(dh1,dh2)` adds a 1-cell in the 2-cell containing darts `d1` and `d2`, between the two 0-cells containing darts `d1` and `d2`. The 2-cell is split in two. This operation is possible if d1\f$ \in\f$\f$ \langle{}\f$\f$ \alpha_1\f$\f$ \rangle{}\f$(d2) which can be tested thanks to `gm.is_insertable_cell_1_in_cell_2(dh1,dh2)`. In the example on \cgalFigureRef{figinsertedge}, it is possible to insert an edge between darts d2 and d3, but it is not possible to insert an edge between d1 and d3. \cgalFigureBegin{figinsertedge,insert-edge.svg} -Example of `::insert_cell_1_in_cell_2` and `::remove_cell<1>` -operations. Left: Initial generalized map. Right: -After the insertion of two 1-cells: a first one between the two -0-cells containing darts `d2` and `d3`, and a second one incident to -the 0-cell containing dart `d1`. Now if we remove the two 1-cells -containing darts `d4` and `d5`, we obtain the initial generalized -map. +Example of `insert_cell_1_in_cell_2` and `remove_cell<1>` operations. Left: Initial generalized map. Right: After the insertion of two 1-cells: a first one between the two 0-cells containing darts `d2` and `d3`, and a second one incident to the 0-cell containing dart `d1`. Now if we remove the two 1-cells containing darts `d4` and `d5`, we obtain the initial generalized map. \cgalFigureEnd -`::insert_dangling_cell_1_in_cell_2(gm,dh0)` adds a 1-cell in the -2-cell containing dart `d0`, the 1-cell being attached by only one of -its vertex to the 0-cell containing dart `d0`. This operation is -possible if `d0`\f$ \in\f$\ref GeneralizedMap::darts "gm.darts()". +`gm.insert_dangling_cell_1_in_cell_2(dh0)` adds a 1-cell in the 2-cell containing dart `d0`, the 1-cell being attached by only one of its vertex to the 0-cell containing dart `d0`. This operation is possible if `d0`\f$ \in\f$\ref GeneralizedMap::darts "gm.darts()". -`::insert_cell_2_in_cell_3(gm,itbegin,itend)` adds a 2-cell in the -3-cell containing all the darts between `itbegin` and `itend`, along -the path of 1-cells containing darts in [`itbegin`,`itend`). The -3-cell is split in two. This operation is possible if all the darts -in [`itbegin`,`itend`) form a closed path inside a same 3-cell which -can be tested thanks to -`::is_insertable_cell_2_in_cell_3(gm,itbegin,itend)` (see example on -\cgalFigureRef{figinsertface}). +`gm.insert_cell_2_in_cell_3(itbegin,itend)` adds a 2-cell in the 3-cell containing all the darts between `itbegin` and `itend`, along the path of 1-cells containing darts in [`itbegin`,`itend`). The 3-cell is split in two. This operation is possible if all the darts in [`itbegin`,`itend`) form a closed path inside a same 3-cell which can be tested thanks to `gm.is_insertable_cell_2_in_cell_3(itbegin,itend)` (see example on \cgalFigureRef{figinsertface}). \cgalFigureBegin{figinsertface,insert-facet.svg} -Example of `::insert_cell_2_in_cell_3` and `::remove_cell<2>` -operations. Left: Initial generalized map. Right: After the -insertion of a 2-cell along the path of 1-cells containing -respectively `d1,d2,d3,d4`. Now if we remove the 2-cell containing -dart `d5`, we obtain the initial generalized map. +Example of `insert_cell_2_in_cell_3` and `remove_cell` operations. Left: Initial generalized map. Right: After the insertion of a 2-cell along the path of 1-cells containing respectively `d1,d2,d3,d4`. Now if we remove the 2-cell containing dart `d5`, we obtain the initial generalized map. \cgalFigureEnd -Some examples of use of these operations are given in Section \ref -ssecexempleoperations "High Level Operations". +Some examples of use of these operations are given in Section \ref ssecexempleoperationsgmap "High Level Operations". \cgalAdvancedBegin -If \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future insertion or removal operations will not update non void attributes. These attributes will be updated latter by the call to \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink. This can be useful to speed up an algorithm which uses several successive insertion and removal operations. See example \ref ssecAttributesManagement "Automatic attributes management". +If \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future insertion or removal operations will not update non void attributes. These attributes will be updated latter by the call to \link GeneralizedMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink. This can be useful to speed up an algorithm which uses several successive insertion and removal operations. See example \ref ssecAttributesManagementGMap "Automatic attributes management". \cgalAdvancedEnd \section Generalized_mapExamples Examples \subsection ssecexample3DGM A 3D Generalized Map -In this example, a 3-dimensional generalized map is constructed. Two -combinatorial tetrahedra are created, then the numbers of cells of the -generalized map are displayed, and the validity of the generalized -map is checked. Then, we illustrate the use of ranges to iterate over -specific darts. The first loop enumerates all the darts of the first -tetrahedron by using the range \ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range<1,2>", and the -second loop enumerates all the darts of the facet containing dart -`dh2` by using the range \ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range<1>". +In this example, a 3-dimensional generalized map is constructed. Two combinatorial tetrahedra are created, then the numbers of cells of the generalized map are displayed, and the validity of the generalized map is checked. Then, we illustrate the use of ranges to iterate over specific darts. The first loop enumerates all the darts of the first tetrahedron by using the range \ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range<1,2>", and the second loop enumerates all the darts of the facet containing dart `dh2` by using the range \ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range<1>". \cgalExample{Generalized_map/gmap_3_simple_example.cpp} @@ -558,17 +392,9 @@ Number of darts of the first tetrahedron: 12 Number of darts of the facet containing dh2: 3 \endverbatim -which gives the number of darts of the generalized map, the numbers -of different cells, the number of connected components, and finally a -Boolean showing the validity of the generalized map (a tetrahedron -is made up of 12 darts because there are 3 darts per facet and there -are 4 facets). +which gives the number of darts of the generalized map, the numbers of different cells, the number of connected components, and finally a Boolean showing the validity of the generalized map (a tetrahedron is made up of 12 darts because there are 3 darts per facet and there are 4 facets). -Note the creation in the for loops of the two instances of -\ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range"::`const_iterator`: `it` is the current iterator, -and `itend` an iterator to the end of the range. Having `itend` avoids -calling \ref GeneralizedMap::darts_of_orbit "gm.darts_of_orbit<1,2>(dh1)"`.end()` again and again as in the -following example (which is a bad solution): +Note the creation in the for loops of the two instances of \ref GeneralizedMap::Dart_of_orbit_range "Dart_of_orbit_range"::`const_iterator`: `it` is the current iterator, and `itend` an iterator to the end of the range. Having `itend` avoids calling \ref GeneralizedMap::darts_of_orbit "gm.darts_of_orbit<1,2>(dh1)"`.end()` again and again as in the following example (which is a bad solution): \code{.cpp} @@ -581,22 +407,11 @@ for (GMap_3::Dart_of_orbit_range<1,2>::const_iterator \subsection Generalized_mapHighLevelOperations High Level Operations -\anchor ssecexempleoperations +\anchor ssecexempleoperationsgmap -This example shows some uses of high level operations. First we create -a combinatorial hexahedron, the generalized map obtained is shown in -\cgalFigureRef{fig_exemple_ope} (Left). Then we insert two 1-cells along -two opposite 2-cells of the hexahedron. The generalized map obtained -is shown in \cgalFigureRef{fig_exemple_ope} (Middle). Finally, we insert a -2-cell in the diagonal of the hexahedron in order to split it into two -parts. We obtain the generalized map shown in -\cgalFigureRef{fig_exemple_ope} (Right). We display the characteristics of -the generalized map and check its validity. +This example shows some uses of high level operations. First we create a combinatorial hexahedron, the generalized map obtained is shown in \cgalFigureRef{fig_exemple_ope} (Left). Then we insert two 1-cells along two opposite 2-cells of the hexahedron. The generalized map obtained is shown in \cgalFigureRef{fig_exemple_ope} (Middle). Finally, we insert a 2-cell in the diagonal of the hexahedron in order to split it into two parts. We obtain the generalized map shown in \cgalFigureRef{fig_exemple_ope} (Right). We display the characteristics of the generalized map and check its validity. -The second part of this example removes the inserted elements. First -we remove the inserted 2-cell, then the two inserted 1-cells. We get -back the initial combinatorial hexahedron, which is verified by -displaying once again the characteristics of the generalized map. +The second part of this example removes the inserted elements. First we remove the inserted 2-cell, then the two inserted 1-cells. We get back the initial combinatorial hexahedron, which is verified by displaying once again the characteristics of the generalized map. \cgalExample{Generalized_map/gmap_3_operations.cpp} @@ -606,64 +421,23 @@ The output is: #Darts=24, #0-cells=8, #1-cells=12, #2-cells=6, #3-cells=1, #ccs=1, valid=1 \endverbatim -The first line gives the characteristics of the generalized map -after all the insertions (the generalized map drawn in -\cgalFigureRef{fig_exemple_ope} (Right)). There are two 3-cells (since the -combinatorial hexahedron was split in two by the 2-cell insertion), -nine 2-cells (since two 2-cells of the original hexahedron were split -in two by the two 1-cell insertions, and a new 2-cell was created -during the 2-cell insertion), fourteen 1-cells (since there are two -new 1-cells created by the 1-cell insertion) while the number of -0-cells remains unchanged. +The first line gives the characteristics of the generalized map after all the insertions (the generalized map drawn in \cgalFigureRef{fig_exemple_ope} (Right)). There are two 3-cells (since the combinatorial hexahedron was split in two by the 2-cell insertion), nine 2-cells (since two 2-cells of the original hexahedron were split in two by the two 1-cell insertions, and a new 2-cell was created during the 2-cell insertion), fourteen 1-cells (since there are two new 1-cells created by the 1-cell insertion) while the number of 0-cells remains unchanged. The second line is the result after the removal operations. We retrieve the original combinatorial hexahedron since we have removed all the inserted elements. \cgalFigureBegin{fig_exemple_ope,example-insertions.svg} -Example of high level operations. Left: Initial 3D -generalized map after the creation of the generalized -hexahedron. Middle: Generalized map obtained after the two -1-cell insertions. The two 2-cells were split in two. Right: -Generalized map obtained after the 2-cell insertion. The 3-cell was -split in two. +Example of high level operations. Left: Initial 3D generalized map after the creation of the generalized hexahedron. Middle: Generalized map obtained after the two 1-cell insertions. The two 2-cells were split in two. Right: Generalized map obtained after the 2-cell insertion. The 3-cell was split in two. \cgalFigureEnd \subsection Generalized_mapA4DGeneralizedMap A 4D Generalized Map -In this example, a 4-dimensional generalized map is used. Two -tetrahedral cells are created and sewn by \f$ \alpha_4\f$. Then the -numbers of cells of the generalized map are displayed, and its -validity is checked. +In this example, a 4-dimensional generalized map is used. Two tetrahedral cells are created and sewn by \f$ \alpha_4\f$. Then the numbers of cells of the generalized map are displayed, and its validity is checked. -By looking at these numbers of cells, we can see that the 4D -generalized map contains only one 3-cell. Indeed, the \ref GeneralizedMap::sew "sew<4>" -operation has identified by pairs all the darts of the two 3-cells by -definition of the sew operation (see Section -\ref sseclinkdarts "Sewing Orbits and Linking Darts") -which, in 4D, links by \f$ \alpha_3\f$ all the darts in \f$ -\langle{}\f$\f$ \alpha_1\f$,\f$ \alpha_2\f$\f$ \rangle{}\f$(d1) -and in \f$ \langle{}\f$\f$ \alpha_1\f$,\f$ \alpha_2\f$\f$ -\rangle{}\f$(d2). The situation is similar (but in higher -dimension) to the configuration where we have two triangles in a 3D -generalized map, and you use \ref GeneralizedMap::sew "sew<3>" between these two -triangles. The two triangles are identified since all their darts are -linked by \f$ \alpha_3\f$, thus we obtain a 3D generalized map -containing only one 3-cell. Note that this 3-cell is unbounded since -the darts of the two triangles are all 2-free. In the 4D case, the -4-cell is unbounded since all its darts are 3-free. +By looking at these numbers of cells, we can see that the 4D generalized map contains only one 3-cell. Indeed, the \ref GeneralizedMap::sew "sew<4>" operation has identified by pairs all the darts of the two 3-cells by definition of the sew operation (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts") which, in 4D, links by \f$ \alpha_3\f$ all the darts in \f$ \langle{}\f$\f$ \alpha_1\f$,\f$ \alpha_2\f$\f$ \rangle{}\f$(d1) and in \f$ \langle{}\f$\f$ \alpha_1\f$,\f$ \alpha_2\f$\f$ \rangle{}\f$(d2). The situation is similar (but in higher dimension) to the configuration where we have two triangles in a 3D generalized map, and you use \ref GeneralizedMap::sew "sew<3>" between these two triangles. The two triangles are identified since all their darts are linked by \f$ \alpha_3\f$, thus we obtain a 3D generalized map containing only one 3-cell. Note that this 3-cell is unbounded since the darts of the two triangles are all 2-free. In the 4D case, the 4-cell is unbounded since all its darts are 3-free. -In this example, we also illustrate how to use the basic methods to -build "by hand" some specific configuration in a generalized map. In -fact, these functions are already present in the package: function -`make_triangle(gm)` is equivalent to -\link make_combinatorial_polygon() `make_combinatorial_polygon(gm,3)`\endlink -and `make_tetrahedral(gm)` is -equivalent to \link make_combinatorial_tetrahedron() `make_combinatorial_tetrahedron(gm)`\endlink. -If we want -to create a 4D simplex, we must create five 3D simplexes, and sew them -correctly two by two by \f$ \alpha_3\f$ (and so on if you want to -create higher dimensional generalized map). +In this example, we also illustrate how to use the basic methods to build "by hand" some specific configuration in a generalized map. In fact, these functions are already present in the package: function `make_triangle(gm)` is equivalent to \link make_combinatorial_polygon() `gm.make_combinatorial_polygon(3)`\endlink and `make_tetrahedral(gm)` is equivalent to \link make_combinatorial_tetrahedron() `gm.make_combinatorial_tetrahedron()`\endlink. If we want to create a 4D simplex, we must create five 3D simplexes, and sew them correctly two by two by \f$ \alpha_3\f$ (and so on if you want to create higher dimensional generalized map). \cgalExample{Generalized_map/gmap_4_simple_example.cpp} @@ -674,18 +448,9 @@ The output is: \subsection ssecgenmapwithcolor Generalized Map With Attributes -In the following example, we illustrate how to specify the -2-attributes in a 3D generalized map. For that, we define our own -item class using `Dart<3,GMap>` as type of dart, and -\link Cell_attribute `Cell_attribute`\endlink -as attributes which contain an `int` and which are associated to -2-cells of the generalized map. +In the following example, we illustrate how to specify the 2-attributes in a 3D generalized map. For that, we define our own item class using `Dart<3,GMap>` as type of dart, and \link Cell_attribute `Cell_attribute`\endlink as attributes which contain an `int` and which are associated to 2-cells of the generalized map. -Functors `Sum_functor` and `Divide_by_two_functor` define a custom -behavior: when two attributes `ca1` and `ca2` are merged into `ca1`, -the value of `ca1` is the sum of the two initial values. When an -attribute `ca1` is split in the two attributes `ca1` and `ca2`, the -value of each attribute is half of the first value. +Functors `Sum_functor` and `Divide_by_two_functor` define a custom behavior: when two attributes `ca1` and `ca2` are merged into `ca1`, the value of `ca1` is the sum of the two initial values. When an attribute `ca1` is split in the two attributes `ca1` and `ca2`, the value of each attribute is half of the first value. \cgalExample{Generalized_map/gmap_3_with_colored_facets.cpp} @@ -696,25 +461,9 @@ The output is: #Darts=64, #0-cells=13, #1-cells=24, #2-cells=14, #3-cells=2, #ccs=1, valid=1 \endverbatim -Before the \ref GeneralizedMap::sew "gm.sew<3>", each 2-cell of the first cube is associated -with an attribute having 7 as value, and each 2-cell of the second -cube with an attribute having 13 as value. During the \ref GeneralizedMap::sew "gm.sew<3>", two -2-cells are merged, thus the functor `Sum_functor` is called on the -two associated 2-attributes, and the value of the new 2-cell is the -sum of the two previous one: 20. +Before the \ref GeneralizedMap::sew "gm.sew<3>", each 2-cell of the first cube is associated with an attribute having 7 as value, and each 2-cell of the second cube with an attribute having 13 as value. During the \ref GeneralizedMap::sew "gm.sew<3>", two 2-cells are merged, thus the functor `Sum_functor` is called on the two associated 2-attributes, and the value of the new 2-cell is the sum of the two previous one: 20. -Then we call `::insert_cell_0_in_cell_2` on a dart which belong to -this 2-cell. This method splits the existing 2-cell in k -2-cells, k being the number of 1-cells of the initial 2-cell (4 -in this example). These splits are made consecutively, thus for the -first split, we create a new attribute as copy of the initial one and -call functor `Divide_by_two_functor` on these two attributes: the -value of each attribute is thus 20/2=10. For the second split, the -value of each attribute is thus 10/2=5, and for the last split the -value of each attribute is thus 5/2=2 (remember that information -contained in 2-attributes in an `int`). At the end, we obtain five -2-attributes with 7 as value, five 2-attributes with 13 as value, and -four 2-attributes having respectively 2, 2, 5 and 10 as values. +Then we call `insert_cell_0_in_cell_2` on a dart which belong to this 2-cell. This method splits the existing 2-cell in k 2-cells, k being the number of 1-cells of the initial 2-cell (4 in this example). These splits are made consecutively, thus for the first split, we create a new attribute as copy of the initial one and call functor `Divide_by_two_functor` on these two attributes: the value of each attribute is thus 20/2=10. For the second split, the value of each attribute is thus 10/2=5, and for the last split the value of each attribute is thus 5/2=2 (remember that information contained in 2-attributes in an `int`). At the end, we obtain five 2-attributes with 7 as value, five 2-attributes with 13 as value, and four 2-attributes having respectively 2, 2, 5 and 10 as values. \subsection ssecgenmapdynamicattibute Use of Dynamic Onmerge and Onsplit Functors @@ -729,93 +478,37 @@ Lastly we remove the dynamic onmerge functor (step 8). This is done by initializ \cgalExample{Generalized_map/gmap_3_dynamic_onmerge.cpp} -\section sec_definition Mathematical Definitions +\section sec_definition_gmap Mathematical Definitions -The definition of generalized map in any dimension is given -in \cgalCite{cgal:l-tmbrc-91}, \cgalCite{l-ndgcm-94}. But it allows only to -represent objects without boundaries. This definition was extended -\cgalCite{cgal:pabl-cco-07}, \cgalCite{cgal:d-ccccg-10} in order to allow to -represent objects with boundaries, based on the notions of partial -permutations and partial involutions. +\cgalModifBegin -Intuitively, a partial permutation on a finite set E is -a mapping from E\f$ \cup\{\varnothing\}\f$ to E\f$ -\cup\{\varnothing\}\f$ which is injective on the subset of the -domain that does not map to \f$\varnothing\f$. More precisely, a -mapping p: E\f$ \cup\{\varnothing\} -\rightarrow\f$ E\f$ \cup\{\varnothing\}\f$ is a partial -permutation defined on E if: -
        -
      1. p\f$(\varnothing)=\varnothing\f$; -
      2. \f$ \forall\f$e1\f$ \in\f$E, \f$ \forall\f$e2\f$ \in\f$E, -p(e1)=p(e2)\f$ \neq\f$\f$ \varnothing\f$ \f$ \Rightarrow\f$ e1=e2. -
      +The definition of generalized map in any dimension is given in \cgalCite{cgal:l-tmbrc-91}, \cgalCite{l-ndgcm-94}. See also the book \cgalCite{dl-14} which regroups many definitions, operations and algorithms about combinatorial and generalized maps. -The inverse \f$ p^{-1}\f$ of this partial permutation is also a -partial permutation and is defined by: -
        -
      1. \f$ p^{-1}(\varnothing)=\varnothing\f$; -
      2. \f$ \forall\f$e\f$ \in\f$E, if it exists a\f$ \in\f$E such that -p(a)=e, -then \f$ p^{-1}\f$(e)=a, otherwise \f$ p^{-1}\f$(e)\f$= \varnothing\f$. -
      +An involution on a finite set E is a mapping f from E to E which is bijective and equal to its inverse. Thus \f$ \forall\f$e\f$ \in\f$E, we have f(e) = \f$ f^{-1}\f$(e) and f(f(e))=e. -Let E be a set, and p a partial permutation on -E. An element e is called a fixed point for -p if p(e)=e. p is a partial involution if -\f$ \forall\f$e\f$ \in\f$E: p(e)\f$ -\neq\f$\f$ \varnothing\f$ \f$ \Rightarrow\f$ -p(p(e))=e. - -Now we can give the definition of a generalized map in any -dimension. Let d\f$ \geq\f$ 0. A d-dimensional -generalized map (or d-map) is a (d+1)-tuple -M=(D,\f$ \alpha_1\f$,...,\f$ \alpha_d\f$) -where: +Let d\f$ \geq\f$ 0. A d-dimensional generalized map (or d-Gmap) is a (d+1)-tuple G=(D,\f$ \alpha_0\f$,...,\f$ \alpha_d\f$) where:
      1. D is a finite set of darts; -
      2. \f$ \alpha_1\f$ is a partial permutation on D; -
      3. \f$ \forall\f$i, 2\f$ \leq\f$i\f$ \leq\f$d, \f$ \alpha_i\f$ is a -partial involution on D without fixed point; -
      4. \anchor condcomposition \f$ \forall\f$i: 0\f$ \leq\f$i\f$ \leq\f$d-2, -\f$ \forall\f$j: 3\f$ \leq\f$j\f$ \leq\f$d, i+2\f$ \leq\f$j, -\f$ \alpha_i\f$\f$ \circ\f$\f$ \alpha_j\f$ is a partial involution. +
      5. \f$ \forall\f$i, 0\f$ \leq\f$i\f$ \leq\f$d, \f$ \alpha_i\f$ is an involution on D; +
      6. \anchor condcomposition \f$ \forall\f$i: 0\f$ \leq\f$i\f$ \leq\f$d-2, \f$ \forall\f$j: 2\f$ \leq\f$j\f$ \leq\f$d, i+2\f$ \leq\f$j, \f$ \alpha_i\f$\f$ \circ\f$\f$ \alpha_j\f$ is an involution.
      -A d-dimensional generalized map represents a subdivision of -an orientable d-dimensional quasi-manifold. A dart is an -abstract element which is only required to define partial -permutations. The last line of the definition fixes constraints which -guarantee the topological validity of the represented object, i.e., -the fact that it is a quasi-manifold. This definition allows us to -verify the validity of a given generalized map by checking if each -item of the definition is satisfied. +A d-dimensional generalized map represents a subdivision of an orientable or non orientable d-dimensional quasi-manifold. A dart is an abstract element which is only required to define involutions. The last line of the definition fixes constraints which guarantee the topological validity of the represented object, i.e., the fact that it is a quasi-manifold. This definition allows us to verify the validity of a given generalized map by checking if each item of the definition is satisfied. -Given a set of partial permutations S=\f$\{f_1\f$,..., -\f$ f_k\}\f$, we denote by \f$ \langle{}\f$ S \f$ -\rangle{}\f$ the permutation group generated by \f$\{f_1\f$,..., -\f$ f_k\}\f$ and whose group operation is the composition of -partial permutations. The orbit \f$ \langle{}\f$\f$ f_1\f$,..., -\f$ f_k\f$\f$ \rangle{}\f$(a) is the set of darts -which can be obtained from a by elements of \f$ -\langle{}\f$ S \f$ \rangle{}\f$: \f$ \langle{}\f$\f$ f_1\f$,..., -\f$ f_k\f$\f$ \rangle{}\f$(a)=\f$\{ -\phi\f$(a)\f$ |\f$\f$ \phi\f$\f$ \in\f$\f$ -\langle{}\f$S\f$ \rangle{}\}\setminus\{\varnothing\}\f$. +\cgalModifEnd -Let d0\f$ \in\f$D be a dart. Given i, 1\f$ -\leq\f$i\f$ \leq\f$d, the i-cell containing -d0 is \f$ \langle{}\f$\f$ \alpha_1\f$,...,\f$ -\alpha_{i-1}\f$,\f$ \alpha_{i+1}\f$,...,\f$ \alpha_d\f$\f$ -\rangle{}\f$(d0). The 0-cell containing d0 is -\f$ \langle{}\f${\f$ \alpha_i\f$\f$ \circ\f$\f$ \alpha_j\f$\f$ |\f$\f$ -\forall\f$i,j: 1\f$ \leq\f$i\f$ <\f$j\f$ -\leq\f$d}\f$ \rangle{}\f$(d0). +Given a set of \tred{involutions} S=\f$\{f_1\f$,..., \f$ f_k\}\f$, we denote by \f$ \langle{}\f$ S \f$ \rangle{}\f$ the permutation group generated by \f$\{f_1\f$,..., \f$ f_k\}\f$ and whose group operation is the composition of involutions. The orbit \f$ \langle{}\f$\f$ f_1\f$,..., \f$ f_k\f$\f$ \rangle{}\f$(a) is the set of darts which can be obtained from a by elements of \f$ \langle{}\f$ S \f$ \rangle{}\f$: \f$ \langle{}\f$\f$ f_1\f$,..., \f$ f_k\f$\f$ \rangle{}\f$(a)=\f$\{ \phi\f$(a)\f$ |\f$\f$ \phi\f$\f$ \in\f$\f$ \langle{}\f$S\f$ \rangle{}\}\f$. + +\cgalModifBegin + +Let d0\f$ \in\f$D be a dart. Given i, 0\f$ \leq\f$i\f$ \leq\f$d, the i-cell containing d0 is \f$ \langle{}\f$\f$ \alpha_0\f$,...,\f$ \alpha_{i-1}\f$,\f$ \alpha_{i+1}\f$,...,\f$ \alpha_d\f$\f$ \rangle{}\f$(d0). \section Generalized_mapDesign Design and Implementation History The code of this package followed the code of Combinatorial maps. +\cgalModifEnd + */ } /* namespace CGAL */ diff --git a/Generalized_map/examples/Generalized_map/gmap_3_dynamic_onmerge.cpp b/Generalized_map/examples/Generalized_map/gmap_3_dynamic_onmerge.cpp new file mode 100644 index 00000000000..6e9ae1a73d6 --- /dev/null +++ b/Generalized_map/examples/Generalized_map/gmap_3_dynamic_onmerge.cpp @@ -0,0 +1,134 @@ +#include +#include +#include +#include +#include + +// My item class: no functor is associated with Face_attribute. +struct Myitem +{ + template + struct Dart_wrapper + { + typedef CGAL::Dart<3, CMap> Dart; + typedef CGAL::Cell_attribute Face_attribute; + typedef CGAL::cpp11::tuple Attributes; + }; +}; + +// Definition of my combinatorial map. +typedef CGAL::Combinatorial_map<3,Myitem> CMap_3; +typedef CMap_3::Dart_handle Dart_handle; +typedef CMap_3::Attribute_type<2>::type Face_attribute; + +// Functor called when two faces are merged. +struct Merge_functor +{ + // operator() automatically called before a merge. + void operator()(Face_attribute& ca1, Face_attribute& ca2) + { + ca1.info()=ca1.info()+ca2.info(); + std::cout<<"After on merge faces: info of face1="<()=boost::function(); + + // 9) Remove one edge: this merges two faces, however no dynamic + // functor is called (because it was removed). + cm.remove_cell<1>(resdart); + + // 10) Display all the values of 2-attributes. + display_map_and_2attributes(cm); + + return EXIT_SUCCESS; +}