namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_Linear_Cell_Complex
\anchor ChapterLinearCellComplex

\author Guillaume Damiand
\cgalAutoToc

\section Linear_cell_complexIntroduction Introduction

A <I>d</I>D linear cell complex allows to represent an orientable subdivided <I>d</I>D object having linear geometry: each vertex of the subdivision is associated with a point. The geometry of each edge is a segment whose end points are associated with the two vertices of the edge, the geometry of each 2-cell is obtained from all the segments associated to the edges describing the boundary of the 2-cell and so on.

The combinatorial part of a linear cell complex is described either by a <I>d</I>D \ref CombinatorialMap "combinatorial map" or by a <I>d</I>D \ref GeneralizedMap "generalized map" (it is strongly recommended to first read the \ref ChapterCombinatorialMap "Combinatorial maps user manual" or \ref ChapterGeneralizedMap "Generalized maps user manual" for definitions). To add the linear geometrical embedding, a point (a model of \link Kernel::Point_2 `Point_2`\endlink or \link Kernel::Point_3 `Point_3`\endlink or \link Kernel_d::Point_d `Point_d`\endlink) is associated to each vertex of the combinatorial data-structure.

\cgalFigureBegin{fig_lcc_example_subdivisions,lcc_example_subdivisions.svg}
Examples of objects with linear geometry. <B>Left</B>: A 2D object composed of three 2-cells, nine 1-cells and seven points associated to the seven 0-cells . <B>Right</B>: A 3D object composed of three 3-cells, twelve 2-cells, sixteen 1-cells and eight points associated to the eight 0-cells.
\cgalFigureEnd

If we reconsider the example introduced in the combinatorial map package, recalled in \cgalFigureRef{fig_lcc_example_subdivisions} (Right), the combinatorial part of the 3D object is described by a 3D combinatorial map. As illustrated in \cgalFigureRef{fig_lcc_examples_zoom}, the geometrical part of the object is described by associating a point to each vertex of the map.

\cgalFigureBegin{fig_lcc_examples_zoom,lcc_examples_zoom.svg}
Example of 3D linear cell complex describing the object given in \cgalFigureRef{fig_lcc_example_subdivisions} (Right). <B>Left</B>: The 3D linear cell complex which contains 54 darts (18 for each 3-cell) where each vertex is associated with a point, here a `Point_3`. Blue segments represent \f$ \beta_3\f$ relations. <B>Middle</B>: Zoom around the central edge which details the six darts belonging to the edge and the associations between darts and points. <B>Right</B>: Zoom around the facet between light gray and white 3-cells, which details the eight darts belonging to the facet and the associations between darts and points (given by red segments).
\cgalFigureEnd

Things are similar for generalized map, as illustrated in \cgalFigureRef{fig_lcc_example_gmap}. In this example, a 2D generalized map is used as underlying data-structure to describe the object given in \cgalFigureRef{fig_lcc_example_subdivisions} (Left). The 2D linear cell complex shown in \cgalFigureRef{fig_lcc_example_gmap} (Left) is obtained from this 2D generalized map by associating a point to each vertex of the map. We can compare in \cgalFigureRef{fig_lcc_example_subdivisions} (Right) this 2D linear cell complex with the 2D linear cell complex describing the same 2D object but using 2D combinatorial maps (instead of generalized map). The only difference comes from the original definitions of combinatorial and generalized maps. Combinatorial maps have twice less darts than generalized maps, and thus the corresponding 2D linear cell complex has twice less association between darts and points.

\cgalFigureBegin{fig_lcc_example_gmap,lcc_example_gmap.svg}
Example of 2D linear cell complexes describing the object given in \cgalFigureRef{fig_lcc_example_subdivisions} (Left). (Left) Based on a 2D generalized map. (Right) Based on a 2D combinatorial map. In both cases, each vertex of the combinatorial data-structure is associated with a point, here a `Point_2`. Associations between darts and points is drawn by red segments.
\cgalFigureEnd

Note that the dimension of the combinatorial or the generalized map <I>d</I> is not necessarily equal to the dimension of the ambient space <I>d2</I>. Indeed, we can use for example a 2D combinatorial map in a 2D ambient space to describe a planar graph (<I>d</I>=<I>d2</I>=<I>2</I>), or a 2D combinatorial map in a 3D ambient space to describe a surface in 3D space (<I>d</I>=2, <I>d2</I>=3) (case of the `Polyhedron_3` package), or a 3D generalized map in a 3D ambient space (<I>d</I>=<I>d2</I>=3) and so on.

\section Linear_cell_complexSoftware Software Design

The diagram in \cgalFigureRef{fig_lcc_diagramme_class} shows the main classes of the package. `Linear_cell_complex_for_combinatorial_map` is the main class if you use combinatorial maps as combinatorial data-structure, and `Linear_cell_complex_for_generalized_map` is the main class if you use generalized maps as combinatorial data-structure (see Section \ref sseclinearcellcomplex). `Linear_cell_complex_for_combinatorial_map` inherits from the `Combinatorial_map` class and `Linear_cell_complex_for_generalized_map` inherits from the `Generalized_map` class. Attributes can be associated to some cells of the linear cell complex thanks to an items class (see Section \ref sseclccitem "Linear Cell Complex Items"), which defines the information associated to darts, and the attributes types. These types may be different for different dimensions of cells, and they may also be void. In the class `Linear_cell_complex_for_combinatorial_map`, it is required that specific attributes are associated to all vertices of the combinatorial or generalized map. These attributes must contain a point (a model of \link Kernel::Point_2 `Point_2`\endlink or \link Kernel::Point_3 `Point_3`\endlink or \link Kernel_d::Point_d `Point_d`\endlink), and can be represented by instances of class `Cell_attribute_with_point` (see Section \ref ssecattributewp "Cell Attributes").

\cgalFigureBegin{fig_lcc_diagramme_class,lcc_diagramme_class.svg}
UML diagram of the main classes of the package. Gray elements come from the \ref ChapterCombinatorialMap "Combinatorial maps" and \ref ChapterGeneralizedMap "Generalized maps" packages.
\cgalFigureEnd


\section sseclinearcellcomplex Linear Cell Complex

The \link CGAL::Linear_cell_complex_for_combinatorial_map `Linear_cell_complex_for_combinatorial_map<d,d2,LCCTraits,Items,Alloc>`\endlink class is a model of the `LinearCellComplex` concept that uses a combinatorial map as underlying combinatorial data-structure. Similarly, the \link CGAL::Linear_cell_complex_for_generalized_map `Linear_cell_complex_for_generalized_map<d,d2,LCCTraits,Items,Alloc>`\endlink class is a model of the `LinearCellComplex` concept that uses a generalized map as underlying combinatorial data-structure. These two classes guarantee that each vertex is associated with an attribute containing a point. These classes can be used in geometric algorithms (they play the same role as `Polyhedron_3` for \ref chapterHalfedgeDS "Halfedge Data Structures").

These classes has five template parameters standing for the dimension of the map, the dimension of the ambient space, a traits class (a model of the `LinearCellComplexTraits` concept, see Section \ref sseclcctraits "Linear Cell Complex Traits"), an items class (a model of the `LinearCellComplexItems` concept, see Section \ref sseclccitem "Linear Cell Complex Items"), and an allocator which must be a model of the allocator concept of \stl. %Default classes are provided for the traits, items, and for the allocator classes, and by default `d2=d`.

A linear cell complex is valid, if it is a valid combinatorial or generalized map where each dart is associated with an attribute containing a point (i.e.\ an instance of a model of the `CellAttributeWithPoint`
concept). Note that there are no validity constraints on the geometry (test on self intersection, planarity of 2-cells...). We can see two examples of `Linear_cell_complex_for_combinatorial_map` in \cgalFigureRef{fig_lcc_instantiations}.

\cgalFigureBegin{fig_lcc_instantiations,lcc_instantiations.svg}
Examples of `Linear_cell_complex_for_combinatorial_map`. Gray disks show the attributes associated to vertices. Associations between darts and attributes are drawn by small lines between darts and disks. <B>Left:</B> Example of `Linear_cell_complex_for_combinatorial_map<2,2>`. <B>Right:</B> Example of `Linear_cell_complex_for_combinatorial_map<3,3>`.
\cgalFigureEnd


\subsection Linear_cell_complexCellAttributes Cell Attributes
\anchor ssecattributewp

The `Cell_attribute_with_point<LCC,Info_,Tag,OnMerge,OnSplit>` class is a model of the `CellAttributeWithPoint` concept, which is a refinement of the `CellAttribute` concept. It represents an attribute associated with a cell, which can contain an information (depending on whether `Info_==void` or not), but which always contains a point, an instance of \link LinearCellComplex::Point `LCC::Point`\endlink.

\subsection Linear_cell_complexLinearCellComplexTraits Linear Cell Complex Traits
\anchor sseclcctraits

The `LinearCellComplexTraits` geometric traits concept defines the required types and functors used in the `Linear_cell_complex_for_combinatorial_map` class. For example it defines \link LinearCellComplexTraits::Point `Point`\endlink, the type of points used, and \link LinearCellComplexTraits::Vector `Vector`\endlink, the corresponding vector type. It also defines all the required functors used for constructions and operations, as for example \link LinearCellComplexTraits::Construct_translated_point `Construct_translated_point`\endlink or \link LinearCellComplexTraits::Construct_sum_of_vectors `Construct_sum_of_vectors`\endlink.

The class `Linear_cell_complex_traits<d,K>` is a model of `LinearCellComplexTraits`. It defines the different types which are obtained from `K` that, depending on `d`, is a model of the concept `Kernel` if `d==2` or `d==3`, and a model of the concept `Kernel_d` otherwise.

\subsection Linear_cell_complexLinearCellComplexItems Linear Cell Complex Items
\anchor sseclccitem

The `LinearCellComplexItems` concept refines the `GenericMapItems` concept by adding the requirement that 0-attributes are enabled, and associated with a type of attribute being a model of the `CellAttributeWithPoint` concept. Like for combinatorial and generalized maps, it is possible to use indices instead of handles as descriptors, by defining CGAL::Tag_true for Use_index type in the item class.

The class `Linear_cell_complex_min_items<d>` is a model of `LinearCellComplexItems`. It defines `void` as information associated to darts, and instances of `Cell_attribute_with_point` (which contain no information) associated to each vertex. All other attributes are `void`.

\section Linear_cell_complexOperations Operations

Several operations defined in the combinatorial maps or generalized maps package can be used on a linear cell complex. This is the case for all the iteration operations that do not modify the model (see example in Section \ref ssec3Dlcc "A 3D Linear Cell Complex"). This is also the case for all the operations that do not create new 0-cells: `sew`, `unsew`, \link GenericMap::remove_cell `remove_cell`\endlink,  \link GenericMap::insert_cell_1_in_cell_2 `insert_cell_1_in_cell_2`\endlink, \link GenericMap::insert_cell_1_between_two_cells_2 `insert_cell_1_between_two_cells_2`\endlink or \link GenericMap::insert_cell_2_in_cell_3 `insert_cell_2_in_cell_3`\endlink. Indeed, all these operations update non `void` attributes, and thus update vertex attributes of a linear cell complex. Note that some existing 0-attributes can be duplicated by the `unsew` method, but these 0-attributes are not new but copies of existing old 0-attributes.

However, operations that create a new 0-cell can not be directly used since the new 0-cell would not be associated with a vertex attribute. Indeed, it is not possible for these operations to automatically decide which point to create. These operations are: \link GenericMap::insert_cell_0_in_cell_1 `insert_cell_0_in_cell_1`\endlink, \link GenericMap::insert_cell_0_in_cell_2 `insert_cell_0_in_cell_2`\endlink, \link GenericMap::insert_dangling_cell_1_in_cell_2 `insert_dangling_cell_1_in_cell_2`\endlink, plus all the creation operations. For these operations, new versions are proposed taking some points as additional parameters. Lastly, some new operations are defined, which use the geometry (see sections \ref ssecconstructionsop "Construction Operations" and \ref ssecmodifop "Modification Operations").

All the operations given in this section guarantee that given a valid linear cell complex and a possible operation, the result is a valid linear cell complex. As for a combinatorial or generalized map, it is also possible to use low level operations but additional operations may be needed to restore the validity conditions.

\subsection sseclcclinkdarts Sewing and Unsewing

As explained in the  \ref sseclinkdarts "combinatorial map" and \ref sseclinkdarts_gmap "generalized map" user manuals, it is possible to glue two <I>i</I>-cells along an (<I>i</I>-1)-cell by using the `sew<i>` method. Since this method updates non void attributes, and since points are specific attributes, they are automatically updated during the `sew<i>` method. Thus the sewing of two <I>i</I>-cells could deform the geometry of the concerned objects.

For example, in \cgalFigureRef{fig_lcc_example_3d_sew}, we want to 3-sew the two initial 3-cells. \link CombinatorialMap::sew `sew<3>(1,5)`\endlink links by \f$ \beta_3\f$ the pairs of darts (1,5), (2,8), (3,7) and (4,6). The eight vertex attributes around the facet between the two 3-cells before the sew are merged by pair during the sew operation (and the \link CellAttribute::On_merge `On_merge`\endlink functor is called four times). Thus, after the sew, there are only four 0-attributes around the facet. By default, the attributes associated with the first dart of the sew operation are kept (but this can be modified by defining your own functor in the attribute class as explained in the packages combinatorial map and generalized map. Intuitively, the geometry of the second 2-cell is deformed to fit to the first 2-cell.

\cgalFigureBegin{fig_lcc_example_3d_sew,lcc_example_3d_sew.svg}
Example of 3-sew operation for linear cell complex. <B>Left</B>: A 3D linear cell complex containing two 3-cells that are not connected. Vertex attributes are drawn with circles containing point coordinates. Associations between darts and attributes are drawn with small lines between darts and disks. <B>Right</B>: The 3D linear cell complex obtained as result of \link CombinatorialMap::sew `sew<3>(1,5)`\endlink (or \link CombinatorialMap::sew `sew<3>(2,8)`\endlink, or \link CombinatorialMap::sew `sew<3>(3,7)`\endlink, or \link CombinatorialMap::sew `sew<3>(4,6)`\endlink). The eight 0-attributes around the facet between the two 3-cells before the sew operation, are merged into four 0-attributes after. The geometry of the pyramid is deformed since its base is fitted on the 2-cell of the cube.
\cgalFigureEnd

This is similar for `unsew<i>` operation, which removes <I>i</I>-links of all the darts in a given <I>(i-1)</I>-cell, and updates non void attributes which are no more associated to a same cell due to the unlinks. If we take the linear cell complex given in \cgalFigureRef{fig_lcc_example_3d_sew} (Right), and we call \link CombinatorialMap::unsew `unsew<3>(2)`\endlink, we obtain the linear cell complex in \cgalFigureRef{fig_lcc_example_3d_sew} (Left) except for the coordinates of the new four vertices, which by default are copies of original vertices (this behavior can be modified thanks to the functor \link CellAttribute::On_split `On_split`\endlink in the attribute class). The \link CombinatorialMap::unsew `unsew<3>`\endlink operation has removed the four \f$ \beta_3\f$ links, and has duplicated the 0-attributes since vertices are split in two after the unsew operation.

\cgalAdvancedBegin
If \link GenericMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future sew and unsew operations will not update non void attributes. These attributes will be updated latter by the call to \link GenericMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink.
\cgalAdvancedEnd

\subsection Linear_cell_complexConstructionOperations Construction Operations
\anchor ssecconstructionsop

There are several member functions allowing to insert specific configurations of darts into a linear cell complex. These functions return a `Dart_descriptor` to the new object. Note that the dimension of the linear cell complex must be large enough: darts must contain all the applications (\f$ \alpha\f$ or \f$ \beta\f$) used by the operation. All these methods add new darts in the current linear cell complex, existing darts are not modified. These functions are \link LinearCellComplex::make_segment `make_segment`\endlink, \link LinearCellComplex::make_triangle `make_triangle`\endlink, \link LinearCellComplex::make_tetrahedron `make_tetrahedron`\endlink and \link LinearCellComplex::make_hexahedron `make_hexahedron`\endlink.

There are two functions allowing to build a linear cell complex from two other \cgal data types:
<UL>
<LI>\link CGAL::import_from_triangulation_3 `import_from_triangulation_3(lcc,atr)`\endlink: adds in `lcc` all the tetrahedra present in `atr`, a \link CGAL::Triangulation_3 `Triangulation_3`\endlink;
<LI>\link CGAL::import_from_polyhedron_3 `import_from_polyhedron_3(lcc,ap)`\endlink: adds in `lcc` all the cells present in `ap`, a `Polyhedron_3`.
</UL>

Lastly, the function \link CGAL::import_from_plane_graph `import_from_plane_graph(lcc,ais)`\endlink adds in `lcc` all the cells reconstructed from the planar graph read in `ais`, a `std::istream` (see the  \link CGAL::import_from_plane_graph `reference manual`\endlink for the file format).

\subsection Linear_cell_complexModificationOperations Modification Operations
\anchor ssecmodifop

Some methods are defined in `LinearCellComplex` to modify a linear cell complex and update the vertex attributes. In the following, we denote by `d0`, `d1`, `d2` for three dart descriptors.

\cgalFigureBegin{fig_lcc_insert_vertex,lcc_insert_vertex.svg}
Example of \link LinearCellComplex::insert_barycenter_in_cell `insert_barycenter_in_cell<1>`\endlink and `remove_cell<0>` operations. <B>Left</B>: Initial linear cell complex. <B>Right</B>: After the insertion of a point in the barycenter of the 1-cell containing dart <I>d1</I>. Now if we remove the 0-cell containing dart <I>d2</I>, we obtain a linear cell complex isomorphic to the initial one.
\cgalFigureEnd


\link LinearCellComplex::insert_barycenter_in_cell `lcc.insert_barycenter_in_cell<unsigned int i>(d0)`\endlink adds the barycenter of the <I>i</I>-cell containing dart `d0`. This operation is possible if `d0`\f$ \in\f$\link GenericMap::darts `lcc.darts()`\endlink (see examples on \cgalFigureRef{fig_lcc_insert_vertex} and \cgalFigureRef{fig_lcc_triangulation}).

\link LinearCellComplex::insert_point_in_cell `lcc.insert_point_in_cell<unsigned int i>(d0,p)`\endlink is an operation similar to the previous operation, the only difference being that the coordinates of the new point are here given by `p` instead of being computed as the barycenter of the <I>i</I>-cell. Currently, these two operations are only defined for `i=1` to insert a point in an edge, or `i=2` to insert a point in a facet.

\cgalFigureBegin{fig_lcc_triangulation,lcc_triangulation.svg}
Examples of \link LinearCellComplex::insert_barycenter_in_cell `insert_barycenter_in_cell<2>`\endlink operation.
\cgalFigureEnd

\link LinearCellComplex::insert_dangling_cell_1_in_cell_2 `lcc.insert_dangling_cell_1_in_cell_2(d0,p)`\endlink 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`. The second vertex of the new edge is associated with a new 0-attribute containing a copy of `p` as point. This operation is possible if `d0`\f$ \in\f$\link GenericMap::darts `lcc.darts()`\endlink (see example on \cgalFigureRef{fig_lcc_insert_edge}).

\cgalFigureBegin{fig_lcc_insert_edge,lcc_insert_edge.svg}
Example of \link LinearCellComplex::insert_dangling_cell_1_in_cell_2 `insert_dangling_cell_1_in_cell_2`\endlink, `insert_cell_1_in_cell_2` and `remove_cell<1>` operations. <B>Left</B>: Initial linear cell complex. <B>Right</B>: After the insertion of a dangling 1-cell in the 2-cell containing dart <I>d1</I>, and of a 1-cell in the 2-cell containing dart <I>d2</I>. Now if we remove the 1-cells containing dart <I>d4</I> and <I>d5</I>, we obtain a linear cell complex isomorphic to the initial one.
\cgalFigureEnd

Some examples of use of these operations are given in Section \ref ssec5dexample "A 4D Linear Cell Complex".

\cgalAdvancedBegin
If \link GenericMap::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 GenericMap::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".
\cgalAdvancedEnd


\subsection Linear_cell_complexIncrementalBuilder Incremental Builder

A utility class `Linear_cell_complex_incremental_builder_3` helps in creating 2D and 3D linear cell complexes
from a list of points followed by a list of facets that are represented as indices into the point list.
Note that, compared to `Polyhedron_incremental_builder_3` it has only absolute indexing and no rollback
mechanism.

\section Linear_cell_complexExamples Examples

\subsection Linear_cell_complexA3DLinearCellComplex A 3D Linear Cell Complex
\anchor ssec3Dlcc

This example uses a 3-dimensional linear cell complex based on combinatorial maps. It creates two tetrahedra and displays all the points of the linear cell complex thanks to a \link LinearCellComplex::Vertex_attribute_const_range `Vertex_attribute_const_range`\endlink. Then, the two tetrahedra are \link CombinatorialMap::sew `3-sewn`\endlink and we translate all the points of the second tetrahedron along vector `v(3,1,1)`. Since the two tetrahedra are 3-sewn, this translation moves also the 2-cell of the first tetrahedron shared with the second one. This is illustrated by displaying all the points of each 3-cell. For that we use a `std::for_each` and the `Display_vol_vertices` functor.

\cgalExample{Linear_cell_complex/linear_cell_complex_3.cpp}

The output is:
\verbatim
Vertices: 1 1 2; 1 0 0; 0 2 0; -1 0 0; 1 1 -3; 1 0 -1; -1 0 -1; 0 2 -1;
Volume 1 : -1 0 0; 0 2 0; 1 0 0; 1 1 2;
Volume 2 : 0 2 -1; -1 0 -1; 1 0 -1; 1 1 -3;
Volume 1 : -1 0 0; 0 2 0; 1 0 0; 1 1 2;
Volume 2 : 0 2 0; -1 0 0; 1 0 0; 1 1 -3;
Volume 1 : 2 1 1; 3 3 1; 4 1 1; 1 1 2;
Volume 2 : 3 3 1; 2 1 1; 4 1 1; 4 2 -2;
LCC characteristics: #Darts=24, #0-cells=5, #1-cells=9, #2-cells=7, #3-cells=2, #ccs=1, valid=1
\endverbatim

The first line gives the points of the linear cell complex before the
\link CombinatorialMap::sew `sew<3>`\endlink. There are eight points, four for each tetrahedron.
After the sew, six vertices are merged two by two, thus there are five
vertices. We can see the points of each 3-cell (lines Volume 1 and
Volume 2) before the sew, after the sew and after the translation of
the second volume. We can see that this translation has also modified
the three common points between the two 3-cells. The last line shows
the number of cells of the linear cell complex, the number of
connected components, and finally a Boolean to show the validity of
the linear cell complex.

\subsection Linear_cell_complexA4DLinearCellComplex A 4D Linear Cell Complex
\anchor ssec5dexample

This example uses a 4-dimensional linear cell complex embedded in a 5-dimensional ambient space and based on generalized maps. It creates two tetrahedra having 5D points and sews the two tetrahedra by \f$ \beta_4\f$. Then we use some high level operations, display the number of cells of the linear cell complex, and check its validity. Last we use the reverse operations to get back to the initial configuration.

\cgalExample{Linear_cell_complex/linear_cell_complex_4.cpp}

The output is:
\verbatim
#Darts=48, #0-cells=8, #1-cells=12, #2-cells=8, #3-cells=2, #4-cells=2, #ccs=2, orientable=true, valid=1
#Darts=48, #0-cells=4, #1-cells=6, #2-cells=4, #3-cells=1, #4-cells=2, #ccs=1, orientable=true, valid=1
#Darts=56, #0-cells=5, #1-cells=7, #2-cells=4, #3-cells=1, #4-cells=2, #ccs=1, orientable=true, valid=1
#Darts=64, #0-cells=5, #1-cells=8, #2-cells=5, #3-cells=1, #4-cells=2, #ccs=1, orientable=true, valid=1
#Darts=48, #0-cells=8, #1-cells=12, #2-cells=8, #3-cells=2, #4-cells=2, #ccs=2, orientable=true, valid=1
\endverbatim

\subsection Linear_cell_complexA3DLinearCellComplexwith A 3D Linear Cell Complex with Colored Vertices

\anchor ssecexemplecolorvertices

This example illustrates the way to use a 3D linear cell complex by
adding another information to vertices. For that, we need to define
our own items class. The difference with the
`Linear_cell_complex_min_items` class is about the definition of
the vertex attribute where we use a `Cell_attribute_with_point`
with a non `void` info. In this example, the <em>vertex color</em> is just
given by an `int` (the second template parameter of the
`Cell_attribute_with_point`). Lastly, we define the
`Average_functor` class in order to set the color of a vertex
resulting of the merging of two vertices to the average of the two
initial values. This functor is associated with the vertex attribute
by passing it as template parameter. Using this items class instead of
the default one is done during the instantiation of template
parameters of the `Linear_cell_complex_for_combinatorial_map` class.

Now we can use `LCC_3` in which each vertex is associated with an
attribute containing both a point and an information. In the following
example, we create two cubes, and set the color of the vertices of the
first cube to 1 and of the second cube to 19 (by iterating through two
\link GenericMap::One_dart_per_incident_cell_range `One_dart_per_incident_cell_range<0, 3>`\endlink ranges). Then we
\link CombinatorialMap::sew `3-sew`\endlink the two cubes along one facet. This operation merges some
vertices (as in the example of \cgalFigureRef{fig_lcc_example_3d_sew}). We
insert a vertex in the common 2-cell between the two cubes, and set
the information of the new 0-attribute to 5. In the last loop, we
display the point and the information of each vertex of the linear
cell complex.

\cgalExample{Linear_cell_complex/linear_cell_complex_3_with_colored_vertices.cpp}

The output is:
\verbatim
point: -1 1 1, color: 10
point: -1 0 1, color: 10
point: -2 0 1, color: 1
point: -2 1 1, color: 1
point: -2 1 0, color: 1
point: -1 1 0, color: 10
point: -1 0 0, color: 10
point: -2 0 0, color: 1
point: 1 1 1, color: 19
point: 1 0 1, color: 19
point: -1 0.5 0.5, color: 5
point: 1 1 0, color: 19
point: 1 0 0, color: 19
\endverbatim

Before applying the sew operation, the eight vertices of the first cube are colored by `1`, and the eight vertices of the second cube by `19`. After the sew operation, there are eight vertices which are merged two by two, and due to the average functor, the color of the four resulting vertices is now 10. Then we insert a vertex in the center of the common 2-cell between the two cubes. The coordinates of this vertex are initialized with the barycenter of the 2-cell (-1,0.5,0.5), and its color is not initialized by the method, thus we set its color manually by using the result of \link LinearCellComplex::insert_barycenter_in_cell `insert_barycenter_in_cell<2>`\endlink which is a dart incident to the new vertex.

\subsection Linear_cell_complexAutomaticAttributesManagement Automatic Attribute Management
\anchor ssecAttributesManagement

The following example illustrates the use of the automatic attributes management for a linear cell complex. An off file is loaded into a 2D linear cell complex embedded in 3D. Then, a certain percentage of edges is removed from the linear cell complex. The same method is applied twice: the first time by using the automatic attributes management (which is the default behavior) and the second time by calling first  \link GenericMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink to disable the automatic updating of attributes.

We can observe that the second run is faster than the first one. Indeed, updating attribute for each edge removal give a bigger complexity. Moreover, the gain increases when the percentage of removed edges increases.

\cgalExample{Linear_cell_complex/linear_cell_complex_3_attributes_management.cpp}

\subsection Linear_cell_complexDraw Draw a Linear Cell Complex
\anchor ssecDrawLCC

A linear cell complex can be visualized by calling the \link PkgDrawLinearCellComplex CGAL::draw<LCC>() \endlink function as shown in the following example. This function opens a new window showing the given linear cell complex. A call to this function is blocking, that is the program continues as soon as the user closes the window.

\cgalExample{Linear_cell_complex/draw_linear_cell_complex.cpp}

This function requires `CGAL_Qt6`, and is only available if the macro `CGAL_USE_BASIC_VIEWER` is defined.
Linking with the cmake target `CGAL::CGAL_Basic_viewer` will link with `CGAL_Qt6` and add the definition `CGAL_USE_BASIC_VIEWER`.

\cgalFigureBegin{fig_draw_lcc,draw_lcc.png}
Result of the run of the draw_linear_cell_complex program. A window shows two 3D cubes and allows to navigate through the 3D scene.
\cgalFigureEnd

\subsection Linear_cell_complexIncrementalBuilderExample Incremental Builder

The following example shows the incremental builder.

\cgalExample{Linear_cell_complex/linear_cell_complex_3_incremental_builder.cpp}

\subsection Linear_cell_complexInsert Insert an Edge Between Two Different Faces

The following example shows the use of \link GenericMap::insert_cell_1_between_two_cells_2 `insert_cell_1_between_two_cells_2`\endlink operation that inserts an edge between two different faces, thus creating an hole in the first face.

\cgalExample{Linear_cell_complex/linear_cell_complex_3_insert.cpp}

\cgalFigureBegin{fig_lcc_insert,lcc_insert_example.png}
Result of the run of the linear_cell_complex_3_insert program. A window shows the 3D cube where one face has a hole.
\cgalFigureEnd

\section Linear_cell_complexDesign Design and Implementation History

This package was developed by Guillaume Damiand, with the help of Andreas Fabri, S&eacute;bastien Loriot and Laurent Rineau. Monique Teillaud and Bernd G&auml;rtner contributed to the manual.

*/
} /* namespace CGAL */
