diff --git a/Combinatorial_map/doc_tex/Combinatorial_map/Combinatorial_map.tex b/Combinatorial_map/doc_tex/Combinatorial_map/Combinatorial_map.tex index 94f8fff0f4d..84cded16fba 100644 --- a/Combinatorial_map/doc_tex/Combinatorial_map/Combinatorial_map.tex +++ b/Combinatorial_map/doc_tex/Combinatorial_map/Combinatorial_map.tex @@ -4,28 +4,31 @@ \newcommand{\orb}[1]{\langle{}#1\rangle{}} \newcommand{\nulldart}{\texttt{null\_dart\_handle}} -\section{Introduction} -A $d$-dimensional combinatorial map is a data structure representing -an orientable subdivided $d$-dimensional object obtained by taking -$d$D cells, and allowing to glue $d$D 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 halfedge data -structure to higher dimension.\footnote{A 2D combinatorial map is - equivalent to a halfedge data structure: there is a one-to-one - mapping between elements of both data structures, halfedges - corresponding to darts.} +\newcommand{\cell}[1]{\emph{#1}-cell} +\newcommand{\cells}[1]{\emph{#1}-cells} -We denote $i$-cell for an $i$-dimensional cell (for example in 3D, +\section{Introduction} +A \emph{d}-dimensional combinatorial map is a data structure +representing an orientable subdivided \emph{d}-dimensional object +obtained by taking \emph{d}D cells, and allowing to glue \emph{d}D +cells along \emph{(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 halfedge data structure to higher +dimension.\footnote{A 2D combinatorial map is equivalent to a halfedge + data structure: there is a one-to-one mapping between elements of + both data structures, halfedges corresponding to darts.} + +We denote \cell{i} for an \emph{i}-dimensional cell (for example in 3D, 0-cells are \emph{vertices}, 1-cells are \emph{edges}, 2-cells are \emph{facets}, and 3-cells are \emph{volumes}). A \emph{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 + relation} is defined on these cells, giving for each \cell{i} $c$ +the set of \cells{(i-1)} contained in the boundary of $c$. Two cells $c_1$ and $c_2$ are \emph{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 $c$ and $c'$ -are \emph{adjacent} if there is an $(i-1)$-cell incident to both $c$ +boundary of the previous cell in the path. Two \cells{i} $c$ and $c'$ +are \emph{adjacent} if there is an \cell{(i-1)} incident to both $c$ and $c'$. You can see an example of a 2D object and a 3D object in Figure~\ref{fig-exemple-3Dmanifold} showing some cells of the subdivision and some adjacency and incidence relations. @@ -47,17 +50,17 @@ subdivision and some adjacency and incidence relations. \end{ccHtmlOnly} \caption{Example of subdivided objects that can be described by combinatorial maps. \textbf{Left}: A 2D object composed of - three facets ($2$-cells), named $f_1$, $f_2$ and $f_3$, nine - edges ($1$-cells) and seven vertices ($0$-cells). $f_1$ and + three facets (2-cells), named $f_1$, $f_2$ and $f_3$, nine + edges (1-cells) and seven vertices (0-cells). $f_1$ and $f_2$ are adjacent along edge $e_1$, thus $e_1$ is incident both to $f_1$ and $f_2$. Vertex $v_1$ is incident to edge $e_1$, thus $v_1$ is incident to $f_1$ and $f_2$ by transitivity. \textbf{Right}: A 3D object (only partially represented for vertices and edges) - composed of three volumes ($3$-cells), named $vol_1$, $vol_2$ - and $vol_3$, twelve facets ($2$-cells) (there is one facet + composed of three volumes (3-cells), named $vol_1$, $vol_2$ + and $vol_3$, twelve facets (2-cells) (there is one facet $f_4$ between $vol_1$ and $vol_2$, and similarly between $vol_1$ - and $vol_3$ and $vol_2$ and $vol_3$), sixteen edges ($1$-cells), - and eight vertices ($0$-cells). $vol_1$ and $vol_2$ are adjacent + and $vol_3$ and $vol_2$ and $vol_3$), sixteen edges (1-cells), + and eight vertices (0-cells). $vol_1$ and $vol_2$ are adjacent along facet $f_4$, thus $f_4$ is incident both to $vol_1$ and $vol_2$. Edge $e_4$ is incident to the three facets between $vol_1$ and $vol_2$, $vol_1$ and $vol_3$, and $vol_2$ and @@ -71,7 +74,7 @@ cells and the incidence and adjacency relations, using only one basic element called \emph{dart}, and a set of \emph{pointers} between these darts. A dart can be thought as a part of an oriented edge (1-cell), together with a part of incident cells of dimensions 0, 2, 3,\ldots, -$d$. When a dart $d_0$ describe a part of an $i$-cell $c$, we say that +\emph{d}. When a dart $d_0$ describe a part of an \cell{i} $c$, we say that $d_0$ \emph{belongs} to $c$, and that $c$ \emph{contains} $d_0$. Let us look at the example in Figure~\ref{fig-exemple-combi-maps} showing the 2D and 3D combinatorial maps describing the two objects given in @@ -105,7 +108,7 @@ First let us start in 2D (Figure~\ref{fig-exemple-combi-maps} (Left)). Facet $f_1$ is described by four darts. These darts are linked together with pointers. Starting from a dart and following a $\beta_1$ pointer, we get to a dart which belongs to the same facet but to the -next edge (1-cell, which explains the index~$1$ of~$\beta_1$). +next edge (1-cell, which explains the index~1 of~$\beta_1$). Starting from any dart and following $\beta_1$ pointers, we can reach exactly all the darts describing the facet. Starting from a dart and following a $\beta_2$ pointer, we get to a dart which belongs to the @@ -115,8 +118,8 @@ $\beta_2$ pointers, we can reach exactly all the darts describing the edge (in 2D one or two darts). Things are slightly different for vertices. Indeed, each $\beta_i$ -points to a dart belonging to a different $i$-cell, but also to a -different $0$-cell (vertex). This is so because two linked darts have +points to a dart belonging to a different \cell{i}, but also to a +different 0-cell (vertex). This is so because two linked darts have opposite orientations. For this reason, starting from any dart belonging to a vertex $v$, we have to follow $\beta_2$ then $\beta_1$ to reach exactly the darts describing the vertex $v$. In fact, by @@ -135,7 +138,7 @@ Figure~\ref{fig-intuitive-exemple} (Left), we can see that it is described by six darts linked together. Starting from a dart and following a $\beta_3$ pointer, we get to a dart which belongs to the same edge, to the same facet, but to the neighboring volume (a 3-cell, -which explains the index $3$ in $\beta_3$). Similarly, starting from +which explains the index 3 in $\beta_3$). Similarly, starting from a dart and following a $\beta_2$ pointer, we get to a dart which belongs to the same edge, to the same volume, but to the neighboring facet (2-cell). Starting from any of these six darts and following @@ -178,7 +181,7 @@ describing edge $e_4$. % rather than an edge (see Figure~\ref{fig-intuitive-exemple} (Right)). For facets, by following a $\beta_1$ pointer, we get to a dart which belongs to the same facet, to the same volume, but to the next edge -(1-cell, which explains the index~$1$ of~$\beta_1$). Starting from any +(1-cell, which explains the index~1 of~$\beta_1$). Starting from any dart and following $\beta_1$ and $\beta_3$ pointers, we can reach exactly all the darts describing the facet (see Figure~\ref{fig-intuitive-exemple} (Right)). @@ -188,11 +191,11 @@ $\beta_2$ pointers, we can reach exactly all the darts describing the volume. % Things are slightly different for vertices. Indeed, each $\beta_i$ -% points to a dart belonging to a different $i$-cell, but also to a -% different $0$-cell (vertex). +% points to a dart belonging to a different \cell{i}, but also to a +% different 0-cell (vertex). % In the above paragraphs, % we explained that when following a $\beta_i$ pointer we change the -% $i$-cell. We have not mentioned that this also changes the 0-cell +% \cell{i}. We have not mentioned that this also changes the 0-cell % (vertex). % This is so because two linked darts have opposite orientations. For % this reason, starting from any dart belonging to a vertex $v$, we have @@ -202,7 +205,7 @@ vertex $v$. Indeed, as in 2D, we have to compose two $\beta_i$s to obtain a dart belonging to the same vertex. In some cases, the general rule that by following a $\beta_i$ we get a -dart which belongs to the neighboring $i$-cell is not true, as for example +dart which belongs to the neighboring \cell{i} is not true, as for example for darts belonging to the boundary of the represented object. For example, in Figure~\ref{fig-exemple-3Dmanifold} (Left), any dart $d_0$ that does not belong to edge $e_1$, $e_2$ and $e_3$ @@ -226,16 +229,16 @@ a facet in Figure~\ref{fig-exemple-combi-maps} (Right), we obtain an unbounded volume having some darts without neighboring facet for $\beta_2$. In such a case, there is a particular value called $\varnothing$ used to describe that a dart $d_0$ is not linked to -another dart in dimension~$i$. +another dart in dimension~\emph{i}. % No it is false (case when c_i=c'_i) and we exchange also c_0... % A dart $a$ corresponds to a tuple of cells: % $(c_0,\ldots,c_d)$, all incident, each $c_i$ being an -% $i$-cell. Given a dart $a$ corresponding to +% \cell{i}. Given a dart $a$ corresponding to % $(c_0\ldots,c_{i-1},c_i,c_{i+1},\ldots,c_d)$, $\beta_i(a)$ gives the % dart $a'$ corresponding to % $(c_0\ldots,c_{i-1},c'_i,c_{i+1},\ldots,c_d)$ with $c'_i$ the only -% $i$-cell different from $c_i$ incident both to $c_{i-1}$ and +% \cell{i} different from $c_i$ incident both to $c_{i-1}$ and % $c_{i+1}$, or NULL if such a cell does not exist. Combinatorial maps are defined in any dimension. A 0D combinatorial @@ -250,7 +253,7 @@ that one main interest of combinatorial maps is their generic definition in any dimension, and that everything presented in this manual is valid in any dimension. -A $d$D combinatorial map is useful when you want to describe $d$D +A \emph{d}D combinatorial map is useful when you want to describe \emph{d}D 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 combinatorial map @@ -285,20 +288,20 @@ doors. % attributes, and it provides a mechanism to merge or split attributes % when cells are merged or split. Attributes may exist for only some of % the dimensions, and if they exist for dimension $i$, they do not -% necessarily exist for each of the $i$-cells. +% necessarily exist for each of the \cells{i}. \section{Data Structure Presentation}\label{sec_presentation} -In this section, we describe $d$D combinatorial maps in terms of data +In this section, we describe \emph{d}D combinatorial maps in terms of data structure and operations. Mathematical definitions are provided in Section~\ref{sec_definition}, and a package description is given in Section~\ref{sec-software-design}. \subsection{Combinatorial Map and Darts}\label{ssec-combi-map-and-darts} -A $d$D combinatorial map is a set of darts $D$. A dart $d_0$ is an +A \emph{d}D combinatorial map is a set of darts $D$. A dart $d_0$ is an element that can be \emph{linked} with $d+1$ darts by pointers called -$\mb{i}$, with $0 \leq i \leq d$. Dart $d_0$ is said \emph{$i$-free} +$\mb{i}$, with $0 \leq i \leq d$. Dart $d_0$ is said \emph{i-free} when $\mb{i}(d_0)=\varnothing$. Each $\mb{i}$, for $2 \leq i \leq d$, -is its own inverse, i.e., if dart $d_0$ is not $i$-free, then +is its own inverse, i.e., if dart $d_0$ is not \emph{i}-free, then $\mb{i}(\mb{i}(d_0))=d_0$. This is different for $\mb{0}$ and $\mb{1}$: $\mb{0}$ is the inverse of $\mb{1}$, i.e., if darts $d_1$ and $d_2$ are such that $\mb{1}(d_1)=d_2$, then @@ -323,9 +326,9 @@ $\mb{i}(\varnothing)=\varnothing$. % (even if in practice this % one-to-one mapping is often explicitly encoded for complexity reasons). -A combinatorial map is \emph{without $i$-boundary} if there is no -$i$-free dart, and it is \emph{without boundary} if it is without -$i$-boundary for all dimensions $1 \leq i \leq d$. +A combinatorial map is \emph{without i-boundary} if there is no +\emph{i}-free dart, and it is \emph{without boundary} if it is without +\emph{i}-boundary for all dimensions $1 \leq i \leq d$. We show in Figure~\ref{fig-exemple-carte3d} a 3D object and the @@ -365,10 +368,10 @@ for example $\beta_3(10)=\varnothing$ and $\beta_3(12)=\varnothing$. \end{figure} \subsection{Cells as Sets of Darts}\label{ssec-cells-in-map} -A cell in a $d$D combinatorial map is implicitly represented by a +A cell in a \emph{d}D combinatorial map is implicitly represented by a subset of darts. % When a dart $d_0$ is an element of the set of darts of -% an $i$-cell $c$, we say that $d_0$ \emph{belongs} to $c$, and that $c$ +% an \cell{i} $c$, we say that $d_0$ \emph{belongs} to $c$, and that $c$ % \emph{contains} $d_0$. 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 @@ -376,7 +379,7 @@ given dart, and how incidence and adjacency relations are defined in terms of darts. The first important property of a combinatorial map is that -each dart belongs to an $i$-cell, $\forall i$, $0 \leq i \leq d$. +each dart belongs to an \cell{i}, $\forall i$, $0 \leq i \leq d$. For example in 3D, a dart belongs to a vertex, an edge, a facet, and a volume. This means that a 3D combinatorial map containing an isolated dart contains exactly one vertex, one edge, one facet and one volume. @@ -395,19 +398,19 @@ $\orb{\beta_1,\beta_4}(d_0)$ to denote $\orb{S}(d_0)$ with $S=\{\beta_1,\beta_4\}$). Given a dart $d_0$, in general, $\mb{i}(d_0)$ (with $1\leq i \leq d$) -belongs to the same cells as $d_0$, only the $i$-cell and $0$-cell are -different. There are two exceptions: (1)~if $d_0$ is $i$-free, then -$\mb{i}(d_0)=\varnothing$; (2)~if $\mb{i}(d_0)$ belongs to the same $i$-cell +belongs to the same cells as $d_0$, only the \cell{i} and 0-cell are +different. There are two exceptions: (1)~if $d_0$ is \emph{i}-free, then +$\mb{i}(d_0)=\varnothing$; (2)~if $\mb{i}(d_0)$ belongs to the same \cell{i} as $d_0$ (case of multi-incidence). For example if an edge is an isolated loop, it is incident twice to the same vertex, then given a dart $d_0$ belonging to this edge, $\mb{1}(d_0)$ goes to the next edge, which is in fact the same edge. Since $\mb{i}(d_0)$ (with $1\leq i \leq d$) allows to change the -current $i$-cell, all the darts that can be reached from $d_0$ by +current \cell{i}, all the darts that can be reached from $d_0$ by using any combination of $\mb{j}$'s, $\forall j$, $1 \leq j \leq d$ and -$j\neq i$ and their inverse are contained in the same $i$-cell as -$d_0$. The $i$-cell containing $d_0$ is defined in terms of orbit by +$j\neq i$ and their inverse are contained in the same \cell{i} as +$d_0$. The \cell{i} containing $d_0$ is defined in terms of orbit by $\orb{\beta_1,\ldots,\beta_{i-1},\beta_{i+1},\ldots,\beta_d}(d_0)$. % since $\mb{0}$ is not a relation @@ -416,7 +419,7 @@ $\orb{\beta_1,\ldots,\beta_{i-1},\beta_{i+1},\ldots,\beta_d}(d_0)$. There is a special case for vertices. Given a dart $d_0$, the set of darts contained in the same vertex as $d_0$ are the darts that can be reached from $d_0$ by using any combination of $\mb{i}\circ\mb{j}$, -$\forall i,j$, $1 \leq i< j \leq d$, and their inverse. The $0$-cell +$\forall i,j$, $1 \leq i< j \leq d$, and their inverse. The 0-cell containing $d_0$ is defined in terms of orbit by $\orb{\{\mb{i}\circ\mb{j}|\forall i,j: 1\leq i::type} for a handle to the -$i$-attributes (and the const version +\emph{i}-attributes (and the const version \ccc{Combinatorial_map::Attribute_const_handle::type}) and \ccc{Combinatorial_map::Attribute_type::type} for the type of the -$i$-attributes. +\emph{i}-attributes. \subsection{Combinatorial Map Items}\label{ssec-item} @@ -925,16 +928,16 @@ provides two local types: \ccc{Dart} which must be a model of the \ccc{Dart} concept, and \ccc{Attributes} which defines the attributes and their types. -The \ccc{Attributes} tuple must contain at most $d+1$ types (one for +The \ccc{Attributes} tuple must contain at most \emph{d+1} types (one for each possible cell dimension of the combinatorial map). Each type of the tuple must be either a model of the \ccc{CellAttribute} concept or \ccc{void}. The first type corresponds to 0-attributes, the second to 1-attributes and so on. If the $i^{\mbox{th}}$ type in the tuple is -\ccc{void}, $(i-1)$-attributes are disabled: we say that -$(i-1)$-attributes are \emph{void}. Otherwise, $(i-1)$-attributes are -enabled and have the given type: we say $(i-1)$-attributes are -\emph{non void}. If the size of the tuple is $k$, with $k < -dimension+1$, $\forall i: k \leq i \leq dimension$, $i$-attributes are +\ccc{void}, \emph{(i-1)}-attributes are disabled: we say that +\emph{(i-1)}-attributes are \emph{void}. Otherwise, \emph{(i-1)}-attributes are +enabled and have the given type: we say \emph{(i-1)}-attributes are +\emph{non void}. If the size of the tuple is \emph{k}, with $k < +dimension+1$, $\forall i: k \leq i \leq dimension$, \emph{i}-attributes are void. The class \ccc{Combinatorial_map_min_items} is a model of the @@ -945,20 +948,20 @@ It defines \ccc{CGAL::Dart} as type of dart, and \subsection{Darts}\label{ssec-darts} The class \ccc{Dart}, a model of the \ccc{Dart} concept, -defines a $d$D dart. It has two template parameters standing for the +defines a \emph{d}D dart. It has two template parameters standing for the dimension of the combinatorial map, and a model of the \ccc{CombinatorialMap} concept, which provides the two types \ccc{Dart_handle} and \ccc{Dart_const_handle}. Each instance \ccc{d0} of \ccc{Dart} stores the $\beta_i$ pointers in an -array of $d+1$ \ccc{Dart_handle} (because we describe also the +array of \emph{d+1} \ccc{Dart_handle} (because we describe also the $\beta_0$ pointer). It also stores the attributes associated to this dart in a tuple of \ccc{CMap::Attribute_handle::type}, one for each -non void $i$-attribute. +non void \emph{i}-attribute. Methods are defined allowing to retrieve each $\beta_i$ and each -associated $i$-attribute of \ccc{d0}, and allowing to test if \ccc{d0} -dart is $i$-free. +associated \emph{i}-attribute of \ccc{d0}, and allowing to test if \ccc{d0} +dart is \emph{i}-free. Note that the use of the \ccc{Dart} class is not hard wired in the combinatorial map class. Users can provide their own model of the @@ -1124,7 +1127,7 @@ There are three different categories of dart range classes: \ccc{Dart_of_orbit_range<1,2>} for the orbit $\orb{\mb{1},\mb{2}}(d0)$); \item \ccc{Dart_of_cell_range}: range of all the darts of - the $i$-cell containing a given dart. The $i$-cell is considered in + the \cell{i} containing a given dart. The \cell{i} is considered in dimension \ccc{dim} (with $0 \leq dim \leq d$, $dim=d$ by default), with $0\leq i \leq dim+1$. If $i=dim+1$, \ccc{Dart_of_cell_range} is the range of all the darts of @@ -1138,17 +1141,17 @@ There are three different categories of dart range classes: % example in a \ccc{set} of the \stl). There are also two different classes of ranges containing one dart per -$i$-cell. Note that in these classes, the dart of each $i$-cell can -be any dart of the cell. Moreover, each $i$-cell (and $j$-cell in the +\cell{i}. Note that in these classes, the dart of each \cell{i} can +be any dart of the cell. Moreover, each \cell{i} (and \cell{j} in the second case) is considered in dimension \ccc{dim} (with $0 \leq dim \leq d$, $dim=d$ by default). \begin{itemize} \item \ccc{One_dart_per_cell_range}: range containing one dart of - each $i$-cell of the combinatorial map, $0\leq i \leq dim+1$ (for + each \cell{i} of the combinatorial map, $0\leq i \leq dim+1$ (for example \ccc{One_dart_per_cell_range<2>} for the range of one dart per 2-cell of the combinatorial map); \item \ccc{One_dart_per_incident_cell_range}: range - containing one dart of each $i$-cell incident to the $j$-cell + containing one dart of each \cell{i} incident to the \cell{j} containing a given dart, with $0\leq i \leq dim+1$ and $0\leq j \leq dim+1$ (for example \ccc{One_dart_per_incident_cell_range<0,3>} for the range of @@ -1183,7 +1186,7 @@ a \ccc{Dart_handle} to a new dart created during the operation. linked by $\beta_2$); dimension must be greater or equal than two; \item \ccc{make_combinatorial_polygon(cm,alg)}: creates an isolated combinatorial polygon of length \ccc{alg} (\ccc{alg} darts - linked by $\beta_1$), for \ccc{alg}$>0$; dimension must be greater + linked by $\beta_1$), for \ccc{alg>0}; dimension must be greater or equal than one; \item \ccc{make_combinatorial_tetrahedron(cm)}: creates an isolated combinatorial tetrahedron (four combinatorial triangles @@ -1198,7 +1201,7 @@ a \ccc{Dart_handle} to a new dart created during the operation. \begin{ccAdvanced} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Boolean Marks\label{ssec-adv-marks}} -It is often necessary to mark darts, for example to retrieve in $O(1)$ +It is often necessary to mark darts, for example to retrieve in \emph{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 combinatorial map (for example mark all the darts belonging to objects @@ -1211,22 +1214,22 @@ wants to use a Boolean mark, the following methods are available (with \item get a new free mark: \ccc{int m = cm.get_new_mark()} (return -1 if no mark is available); -\item set mark $m$ for a given dart \ccc{d0}: \ccc{cm.mark(dh0,m)}; -\item unset mark $m$ for a given dart \ccc{d0}: \ccc{cm.unmark(dh0,m)}; -\item test if a given dart \ccc{d0} is marked for $m$: \ccc{cm.is_marked(dh0,m)}; +\item set mark \ccc{m} for a given dart \ccc{d0}: \ccc{cm.mark(dh0,m)}; +\item unset mark \ccc{m} for a given dart \ccc{d0}: \ccc{cm.unmark(dh0,m)}; +\item test if a given dart \ccc{d0} is marked for \ccc{m}: \ccc{cm.is_marked(dh0,m)}; -\item unmark all the darts of \ccc{cm} for $m$: \ccc{cm.unmark_all(m)}; +\item unmark all the darts of \ccc{cm} for \ccc{m}: \ccc{cm.unmark_all(m)}; % The complexity of this method is $O(1)$, if % the darts of \ccc{cm} $D$ are all marked or all unmarked, and it is $O(|D|)$ % otherwise -\item negate mark $m$ of all the darts of \ccc{cm}: \ccc{cm.negate_mark(m)}. +\item negate mark \ccc{m} of all the darts of \ccc{cm}: \ccc{cm.negate_mark(m)}. All the marked darts become unmarked and all the unmarked darts become marked; % The complexity of this method is $O(1)$; -\item free mark $m$: +\item free mark \ccc{m}: \ccc{cm.free_mark(m)}. This method unmarks all the darts of \ccc{cm} - for $m$ before freeing it.% (same complexity as \ccc{cm.unmark_all(m)}). + for \ccc{m} before freeing it.% (same complexity as \ccc{cm.unmark_all(m)}). \end{itemize} It is important to free a mark when it is no longer needed, otherwise @@ -1296,11 +1299,11 @@ $\beta$ pointers of existing darts. \begin{itemize} \item The \ccc{sew} and \ccc{unsew} methods iterate over two orbits in order to link or unlink specific darts two by two. Intuitively, a - \ccc{sew} operation glues two $i$-cells by identifying two of - their $(i-1)$-cells (see example in Figure~\ref{fig-exemple-sew} + \ccc{sew} operation glues two \cells{i} by identifying two of + their \cells{(i-1)} (see example in Figure~\ref{fig-exemple-sew} where \ccc{sew<3>} is used to glue two 3-cells along one 2-cell). - Reciprocally, a \ccc{unsew} operation un-glues two $i$-cells which - were glued along one of their $(i-1)$-cells. + Reciprocally, a \ccc{unsew} operation un-glues two \cells{i} which + were glued along one of their \cells{(i-1)}. These methods guarantee that given a valid combinatorial map and a possible operation we obtain a valid combinatorial map as result of the operation. @@ -1373,14 +1376,14 @@ In addition, the sew operations update 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 combinatorial map validity). For each couple -of $j$-cells $c_1$ and $c_2$ that are merged into one $j$-cell during +of \cells{j} $c_1$ and $c_2$ that are merged into one \cell{j} during the sew, we have to update the two associated attributes $attr_1$ and $attr_2$. 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 \ccc{On_merge} on the two attributes $attr_1$ and $attr_2$ (see Section~\ref{ssec-attributes}). Then, we associate the -attribute $attr_1$ to all darts of the resulting $j$-cell. Finally, +attribute $attr_1$ to all darts of the resulting \cell{j}. Finally, attribute $attr_2$ is removed from the combinatorial map. Note that when the two attributes are non NULL, the first one is @@ -1396,7 +1399,7 @@ For example, in Figure~\ref{fig-exemple-sew}, we want to 3-sew the two initial volumes. \ccc{sew<3>(1,5)} links by $\mb{3}$ the pairs of darts $(1,5)$, $(2,8)$, $(3,7)$ and $(4,6)$, thus the combinatorial 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 +belonging to the 2-cell containing dart 1 become associated to the same 2-attribute after the operation. % @@ -1406,9 +1409,9 @@ and thus guarantee to obtain a valid combinatorial 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 +guarantee that two darts belonging to two different \cells{j} are associated to two different $j$-attributes. If the unsew operation -splits a $j$-cell $c$ in two $j$-cells $c_1$ and $c_2$, and if $c$ is +splits a \cell{j} $c$ in two \cells{j} $c_1$ and $c_2$, and if $c$ is associated to a $j$-attribute $attr_1$, then this attribute is duplicated into $attr_2$, and all the darts belonging to $c_2$ are associated with this new attribute. Finally, we call the functor \ccc{On_split} @@ -1490,14 +1493,14 @@ valid. % \end{figure} The first one is \ccc{remove_cell(cm,dh0)} which modifies the -combinatorial map to remove the $i$-cell containing dart \ccc{d0}, +combinatorial map to remove the \cell{i} containing dart \ccc{d0}, with $0 \leq i \leq 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 \ccc{is_removable(cm,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 \ccc{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 +\cell{i} is incident to at most two \cells{(i+1)} which can be tested +thanks to \ccc{is_removable(cm,dh0)}. If the removed \cell{i} +was incident to two different \cells{(i+1)}, these two cells are +merged into one \cell{(i+1)}. In this case, the \ccc{On_merge} functor +is called if two \emph{(i+1)}-attributes are associated to the two +\cells{(i+1)}. If the \cell{i} is associated with a non void attribute, it is removed from the combinatorial map (see three examples on Figures~\ref{fig-insert-vertex}, \ref{fig-insert-edge} and \ref{fig-insert-face}). @@ -1522,11 +1525,11 @@ examples on Figures~\ref{fig-insert-vertex}, \ref{fig-insert-edge} and 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}, is it not possible to define a unique \ccc{insert_cell_i_in_cell_j} function because parameters -are different depending on $i$ and $j$. +are different depending on \ccc{i} and \ccc{j}. %The following versions exist: % \begin{itemize} @@ -1610,6 +1613,7 @@ This operation is possible if \ccc{d0}$\in$\ccc{cm.darts()}. \ccc{d5}, we obtain the initial combinatorial map.} \label{fig-insert-face} \end{figure} + % \item \ccc{insert_cell_2_in_cell_3(cm,itbegin,itend)} adds a 2-cell in the 3-cell containing all the darts between @@ -1741,14 +1745,14 @@ of cells of the combinatorial map are displayed, and its validity is checked. By looking at these numbers of cells, we can see that the 4D -combinatorial map contains only one 3-cell. Indeed, the $sew<4>$ +combinatorial map contains only one 3-cell. Indeed, the \ccc{sew<4>} operation has identified by pairs all the darts of the two 3-cells by definition of the sew operation (see Section~\ref{ssec-link-darts}) which, in 4D, links by $\beta_3$ all the darts in $\orb{\mb{1},\mb{2}}(d_1)$ and in $\orb{\mb{1},\mb{2}}(d_2)$. The situation is similar (but in higher dimension) to the configuration where we have two triangles in a 3D combinatorial map, -and you use $sew<3>$ between these two triangles. The two triangles +and you use \ccc{sew<3>} between these two triangles. The two triangles are identified since all their darts are linked by $\beta_3$, thus we obtain a 3D combinatorial map containing only one 3-cell. Note that this 3-cell is unbounded since the darts of the two triangles are all @@ -1806,8 +1810,8 @@ second cube with attribute having 13 as value. During the the value of the new 2-cell is the sum of the two previous one: 20. Then we call \ccc{CGAL::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 +belong to this 2-cell. This method splits the existing 2-cell in \emph{k} +2-cells, \emph{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 \ccc{Divide_by_two_functor} on these two attributes: the value @@ -1883,7 +1887,7 @@ of darts which can be obtained from $a$ by elements of $\orb{S}$: $\orb{f_1,\ldots,f_k}(a)=\{\phi(a)|\phi \in \orb{S}\}\setminus\{\varnothing\}$. Let $d_0 \in D$ be a dart. Given $i$, $1\leq i \leq d$, -the $i$-cell containing $d_0$ is +the \cell{i} containing $d_0$ is $\orb{\beta_1,\ldots,\beta_{i-1},\beta_{i+1},\ldots,\beta_d}(d_0)$. The $0$-cell containing $d_0$ is $\orb{\{\mb{i}\circ\mb{j}|\forall i,j: 1\leq i