diff options
Diffstat (limited to 'src/Alpha_complex/doc/Intro_alpha_complex.h')
| -rw-r--r-- | src/Alpha_complex/doc/Intro_alpha_complex.h | 95 |
1 files changed, 70 insertions, 25 deletions
diff --git a/src/Alpha_complex/doc/Intro_alpha_complex.h b/src/Alpha_complex/doc/Intro_alpha_complex.h index b075d1fc..41e5e16d 100644 --- a/src/Alpha_complex/doc/Intro_alpha_complex.h +++ b/src/Alpha_complex/doc/Intro_alpha_complex.h @@ -22,6 +22,18 @@ namespace alpha_complex { * * @{ * +<div class="toc"> +Table of Contents +<ul> +<li class="level1"><a href="#definition">Definition</a></li> +<li class="level1"><a href="#pointsexample">Example from points</a></li> +<li class="level1"><a href="#createcomplexalgorithm">Create complex algorithm</a></li> +<li class="level1"><a href="#weightedversion">Weighted specific version</a></li> +<li class="level1"><a href="#offexample">Example from OFF file</a></li> +<li class="level1"><a href="#weighted3dexample">3d specific version</a></li> +</ul> +</div> + * \section definition Definition * * Alpha_complex is a <a target="_blank" href="https://en.wikipedia.org/wiki/Simplicial_complex">simplicial complex</a> @@ -31,26 +43,38 @@ namespace alpha_complex { * circumsphere is empty (the simplex is then said to be Gabriel), and as the minimum of the filtration * values of the codimension 1 cofaces that make it not Gabriel otherwise. * - * All simplices that have a filtration value strictly greater than a given alpha squared value are not inserted into - * the complex. + * All simplices that have a filtration value \f$ > \alpha^2 \f$ are removed from the Delaunay complex + * when creating the simplicial complex if it is specified. * * \image html "alpha_complex_representation.png" "Alpha-complex representation" * * Alpha_complex is constructing a <a target="_blank" * href="http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations">Delaunay Triangulation</a> - * \cite cgal:hdj-t-15b from <a target="_blank" href="http://www.cgal.org/">CGAL</a> (the Computational Geometry - * Algorithms Library \cite cgal:eb-15b) and is able to create a `SimplicialComplexForAlpha`. + * \cite cgal:hdj-t-19b from <a target="_blank" href="http://www.cgal.org/">CGAL</a> (the Computational Geometry + * Algorithms Library \cite cgal:eb-19b) and is able to create a `SimplicialComplexForAlpha`. * * The complex is a template class requiring an Epick_d <a target="_blank" * href="http://doc.cgal.org/latest/Kernel_d/index.html#Chapter_dD_Geometry_Kernel">dD Geometry Kernel</a> - * \cite cgal:s-gkd-15b from CGAL as template parameter. + * \cite cgal:s-gkd-19b from CGAL as template parameter. * * \remark - * - When the simplicial complex is constructed with an infinite value of alpha, the complex is a Delaunay - * complex. + * - When the simplicial complex is constructed with an infinite value of \f$ \alpha^2 \f$, the complex is a Delaunay + * complex with special filtration values. The Delaunay complex without filtration values is also available by passing + * `default_filtration_value=true` to `Alpha_complex::create_complex`. * - For people only interested in the topology of the \ref alpha_complex (for instance persistence), * \ref alpha_complex is equivalent to the \ref cech_complex and much smaller if you do not bound the radii. * \ref cech_complex can still make sense in higher dimension precisely because you can bound the radii. + * - Using the default `CGAL::Epeck_d` makes the construction safe. If you pass `exact=true` to + * `Alpha_complex::create_complex`, the filtration values are the exact ones converted to the filtration value type of + * the simplicial complex. This can be very slow. If you pass `exact=false` (the default), the filtration values are + * only guaranteed to have a small multiplicative error compared to the exact value, see <code> + * <a class="el" target="_blank" href="https://doc.cgal.org/latest/Number_types/classCGAL_1_1Lazy__exact__nt.html"> + * CGAL::Lazy_exact_nt<NT>::set_relative_precision_of_to_double</a></code> for details. A drawback, when computing + * persistence, is that an empty exact interval [10^12,10^12] may become a non-empty approximate interval + * [10^12,10^12+10^6]. Using `CGAL::Epick_d` makes the computations slightly faster, and the combinatorics are still + * exact, but the computation of filtration values can exceptionally be arbitrarily bad. In all cases, we still + * guarantee that the output is a valid filtration (faces have a filtration value no larger than their cofaces). + * - For performances reasons, it is advised to use \ref eigen ≥ 3.3.5 and \ref cgal ≥ 5.2.0. * * \section pointsexample Example from points * @@ -59,7 +83,7 @@ namespace alpha_complex { * * Then, it is asked to display information about the simplicial complex. * - * \include Alpha_complex/Alpha_complex_from_points.cpp + * \include Alpha_complex_from_points.cpp * * When launching: * @@ -68,7 +92,7 @@ namespace alpha_complex { * * the program output is: * - * \include Alpha_complex/alphaoffreader_for_doc_60.txt + * \include alphaoffreader_for_doc_60.txt * * \section createcomplexalgorithm Create complex algorithm * @@ -83,6 +107,7 @@ namespace alpha_complex { * \subsection filtrationcomputation Filtration value computation algorithm * <br> * \f$ + * \begin{array}{l} * \textbf{for } \text{i : dimension } \rightarrow 0 \textbf{ do}\\ * \quad \textbf{for all } \sigma \text{ of dimension i}\\ * \quad\quad \textbf{if } \text{filtration(} \sigma ) \text{ is NaN} \textbf{ then}\\ @@ -103,6 +128,7 @@ namespace alpha_complex { * \textbf{end for}\\ * \text{make_filtration_non_decreasing()}\\ * \text{prune_above_filtration()}\\ + * \end{array} * \f$ * * \subsubsection dimension2 Dimension 2 @@ -124,16 +150,42 @@ namespace alpha_complex { * * \subsubsection nondecreasing Non decreasing filtration values * - * As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not - * quite define a proper filtration (i.e. non-decreasing with respect to inclusion). + * As the squared radii computed by CGAL are an approximation, it might happen that these \f$ \alpha^2 \f$ values do + * not quite define a proper filtration (i.e. non-decreasing with respect to inclusion). * We fix that up by calling `SimplicialComplexForAlpha::make_filtration_non_decreasing()`. * + * \note This is not the case in `exact` version, this is the reason why it is not called in this case. + * * \subsubsection pruneabove Prune above given filtration value * - * The simplex tree is pruned from the given maximum alpha squared value (cf. + * The simplex tree is pruned from the given maximum \f$ \alpha^2 \f$ value (cf. * `SimplicialComplexForAlpha::prune_above_filtration()`). * In the following example, the value is given by the user as argument of the program. * + * \section weightedversion Weighted specific version + * <b>Requires:</b> \ref eigen ≥ 3.1.0 and \ref cgal ≥ 5.1.0. + * + * A weighted version for Alpha complex is available (cf. Alpha_complex). It is like a usual Alpha complex, but based + * on a <a href="https://doc.cgal.org/latest/Triangulation/index.html#TriangulationSecRT">CGAL regular triangulation</a> instead + * of Delaunay. + * + * This example builds the CGAL weighted alpha shapes from a small molecule, and initializes the alpha complex with + * it. This example is taken from <a href="https://doc.cgal.org/latest/Alpha_shapes_3/index.html#AlphaShape_3DExampleforWeightedAlphaShapes">CGAL 3d + * weighted alpha shapes</a>. + * + * Then, it is asked to display information about the alpha complex. + * + * \include Weighted_alpha_complex_from_points.cpp + * + * When launching: + * + * \code $> ./Weighted_alpha_complex_example_from_points + * \endcode + * + * the program output is: + * + * \include weightedalpha3dfrompoints_for_doc.txt + * * * \section offexample Example from OFF file * @@ -142,7 +194,7 @@ namespace alpha_complex { * * Then, it is asked to display information about the alpha complex. * - * \include Alpha_complex/Alpha_complex_from_off.cpp + * \include Alpha_complex_from_off.cpp * * When launching: * @@ -151,10 +203,10 @@ namespace alpha_complex { * * the program output is: * - * \include Alpha_complex/alphaoffreader_for_doc_32.txt + * \include alphaoffreader_for_doc_32.txt * * - * \section weighted3dexample 3d specific example + * \section weighted3dexample 3d specific version * * A specific module for Alpha complex is available in 3d (cf. Alpha_complex_3d) and allows to construct standard, * weighted, periodic or weighted and periodic versions of alpha complexes. Alpha values computation can be @@ -162,21 +214,14 @@ namespace alpha_complex { * Gudhi::alpha_complex::complexity::EXACT. * * This example builds the CGAL 3d weighted alpha shapes from a small molecule, and initializes the alpha complex with - * it. This example is taken from <a href="https://doc.cgal.org/latest/Alpha_shapes_3/index.html#title13">CGAL 3d + * it. This example is taken from <a href="https://doc.cgal.org/latest/Alpha_shapes_3/index.html#AlphaShape_3DExampleforWeightedAlphaShapes">CGAL 3d * weighted alpha shapes</a>. * * Then, it is asked to display information about the alpha complex. * - * \include Alpha_complex/Weighted_alpha_complex_3d_from_points.cpp - * - * When launching: - * - * \code $> ./Alpha_complex_example_weighted_3d_from_points - * \endcode - * - * the program output is: + * \include Weighted_alpha_complex_3d_from_points.cpp * - * \include Alpha_complex/weightedalpha3dfrompoints_for_doc.txt + * The results will be the same as in \ref weightedversion . * */ /** @} */ // end defgroup alpha_complex |