Modify the Alpha complex doc wit a concept to create a simplicial complex from alpha complex

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/alpha_complex_create_complex@1546 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: d8083c3b0e03e1cf0033e5c7c1ba6f95618efdc1

3 files changed, 117 insertions, 18 deletions

diff --git a/src/Alpha_complex/concept/Simplicial_complex_for_alpha.h b/src/Alpha_complex/concept/Simplicial_complex_for_alpha.h
new file mode 100644
index 00000000..2fd5dc03
--- /dev/null
+++ b/src/Alpha_complex/concept/Simplicial_complex_for_alpha.h
@@ -0,0 +1,98 @@
+/*    This file is part of the Gudhi Library. The Gudhi library 
+ *    (Geometric Understanding in Higher Dimensions) is a generic C++ 
+ *    library for computational topology.
+ *
+ *    Author(s):       Vincent Rouvreau
+ *
+ *    Copyright (C) 2016  INRIA
+ *
+ *    This program is free software: you can redistribute it and/or modify
+ *    it under the terms of the GNU General Public License as published by
+ *    the Free Software Foundation, either version 3 of the License, or
+ *    (at your option) any later version.
+ *
+ *    This program is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU General Public License for more details.
+ *
+ *    You should have received a copy of the GNU General Public License
+ *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef CONCEPT_ALPHA_COMPLEX_SIMPLICIAL_COMPLEX_FOR_ALPHA_H_
+#define CONCEPT_ALPHA_COMPLEX_SIMPLICIAL_COMPLEX_FOR_ALPHA_H_
+
+namespace Gudhi {
+
+namespace alpha_complex {
+
+/** \brief The concept SimplicialComplexForAlpha describes the requirements for a type to implement a simplicial
+ * complex, that can be created from a `Alpha_complex`.
+ */
+struct SimplicialComplexForAlpha {
+  /** Handle to specify a simplex. */
+  typedef unspecified Simplex_handle;
+  /** Handle to specify a vertex. Must be a non-negative integer. */
+  typedef unspecified Vertex_handle;
+  /** Handle to specify the simplex filtration value. */
+  typedef unspecified Filtration_value;
+
+  /** Returns the number of vertices in the simplicial complex. */
+  std::size_t num_vertices();
+  
+  /** Gets the simplicial complex dimension. */
+  int dimension();
+
+  /** Sets the simplicial complex dimension. */
+  void set_dimension(int dimension);
+
+  /** Gets the 'simplex' dimension. */
+  int dimension(Simplex_handle simplex);
+
+  /** Assigns the 'simplex' with the given 'filtration' value. */
+  int assign_filtration(Simplex_handle simplex, Filtration_value filtration);
+
+  /** \brief Inserts a simplex with vertices from a given range 'vertex_range' in the simplicial complex with the given
+   * 'filtration' value. */
+  template< typedef Input_vertex_range >
+  Insertion_result_type insert_simplex_and_subfaces(Input_vertex_range const & vertex_range,
+                                                    Filtration_value filtration);
+
+  /** Browses the simplicial complex to make the filtration non-decreasing. */
+  void make_filtration_non_decreasing();
+  
+  /** Prune the simplicial complex above 'filtration' value given as parameter. */
+  void prune_above_filtration(Filtration_value filtration);
+  
+  /** Sorts the filtration values in the simplicial complex. */
+  void initialize_filtration();
+
+  /** \brief Iterator over vertices of a simplex.
+   *
+   * 'value type' must be 'Vertex_handle'.*/
+  typedef unspecified Simplex_vertex_range;
+
+  /** \brief Returns a range over vertices of a given
+   *  simplex. */
+  Simplex_vertex_range simplex_vertex_range(Simplex_handle const & simplex);
+
+  /** \brief Iterator over the boundaries of the complex, in an arbitrary order.
+   *
+   * 'value_type' must be 'Simplex_handle'.*/
+  typedef unspecified Boundary_simplex_range;
+
+  /** \brief Returns a range over boundaries of a given simplex. */
+  Boundary_simplex_range boundary_simplex_range(Simplex_handle const & simplex);
+
+  /** \brief Return type of an insertion of a simplex
+   */
+  typedef unspecified Insertion_result_type;
+
+};
+
+}  // namespace alpha_complex
+
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ALPHA_COMPLEX_SIMPLICIAL_COMPLEX_FOR_ALPHA_H_
diff --git a/src/Alpha_complex/doc/Intro_alpha_complex.h b/src/Alpha_complex/doc/Intro_alpha_complex.h
index 4ca3271b..3ffdae7f 100644
--- a/src/Alpha_complex/doc/Intro_alpha_complex.h
+++ b/src/Alpha_complex/doc/Intro_alpha_complex.h
@@ -51,7 +51,7 @@ namespace alpha_complex {
  * 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 `Simplicial_complex_for_alpha`.
+ * Algorithms Library \cite cgal:eb-15b) 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>
@@ -135,12 +135,12 @@ namespace alpha_complex {
  * 
  * 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).
- * We fix that up by calling `Simplicial_complex_for_alpha::make_filtration_non_decreasing()`.
+ * We fix that up by calling `SimplicialComplexForAlpha::make_filtration_non_decreasing()`.
  * 
  * \subsubsection pruneabove Prune above given filtration value
  * 
  * The simplex tree is pruned from the given maximum alpha squared value (cf.
- * `Simplicial_complex_for_alpha::prune_above_filtration()`).
+ * `SimplicialComplexForAlpha::prune_above_filtration()`).
  * In the following example, the value is given by the user as argument of the program.
  * 
  * 
diff --git a/src/Alpha_complex/include/gudhi/Alpha_complex.h b/src/Alpha_complex/include/gudhi/Alpha_complex.h
index 66a55ac7..ab96531f 100644
--- a/src/Alpha_complex/include/gudhi/Alpha_complex.h
+++ b/src/Alpha_complex/include/gudhi/Alpha_complex.h
@@ -206,17 +206,17 @@ class Alpha_complex {
   }
 
  public:
-  template <typename Simplicial_complex>
-  bool create_complex(Simplicial_complex& complex) {
-    typedef typename Simplicial_complex::Filtration_value Filtration_value;
+  template <typename SimplicialComplexForAlpha>
+  bool create_complex(SimplicialComplexForAlpha& complex) {
+    typedef typename SimplicialComplexForAlpha::Filtration_value Filtration_value;
     return create_complex(complex, std::numeric_limits<Filtration_value>::infinity());
   }
 
   /** \brief Initialize the simplicial complex from the Delaunay triangulation.
    *
-   * \tparam Simplicial_complex must meet Simplicial_complex_for_alpha concept.
+   * \tparam SimplicialComplexForAlpha must meet `SimplicialComplexForAlpha` concept.
    * 
-   * @param[in] complex Simplicial_complex to be created.
+   * @param[in] complex SimplicialComplexForAlpha to be created.
    * @param[in] max_alpha_square maximum for alpha square value. Default value is +\f$\infty\f$.
    * 
    * @return true if creation succeeds, false otherwise.
@@ -226,10 +226,11 @@ class Alpha_complex {
    * 
    * Initialization can be launched once.
    */
-  template <typename Simplicial_complex, typename Filtration_value>
-  bool create_complex(Simplicial_complex& complex, Filtration_value max_alpha_square) {
-    // From Simplicial_complex type required to insert into a simplicial complex (with or without subfaces).
-    typedef typename Simplicial_complex::Vertex_handle Vertex_handle;
+  template <typename SimplicialComplexForAlpha, typename Filtration_value>
+  bool create_complex(SimplicialComplexForAlpha& complex, Filtration_value max_alpha_square) {
+    // From SimplicialComplexForAlpha type required to insert into a simplicial complex (with or without subfaces).
+    typedef typename SimplicialComplexForAlpha::Vertex_handle Vertex_handle;
+    typedef typename SimplicialComplexForAlpha::Simplex_handle Simplex_handle;
     typedef std::vector<Vertex_handle> Vector_vertex;
     
     if (triangulation_ == nullptr) {
@@ -294,7 +295,7 @@ class Alpha_complex {
     // ### For i : d -> 0
     for (int decr_dim = complex.dimension(); decr_dim >= 0; decr_dim--) {
       // ### Foreach Sigma of dim i
-      for (auto f_simplex : complex.skeleton_simplex_range(decr_dim)) {
+      for (Simplex_handle f_simplex : complex.skeleton_simplex_range(decr_dim)) {
         int f_simplex_dim = complex.dimension(f_simplex);
         if (decr_dim == f_simplex_dim) {
           pointVector.clear();
@@ -345,12 +346,12 @@ class Alpha_complex {
   }
 
  private:
-  template <typename Simplicial_complex, typename Simplex_handle>
-  void propagate_alpha_filtration(Simplicial_complex& complex, Simplex_handle f_simplex, int decr_dim) {
-    // From Simplicial_complex type required to assign filtration values.
-    typedef typename Simplicial_complex::Filtration_value Filtration_value;
+  template <typename SimplicialComplexForAlpha, typename Simplex_handle>
+  void propagate_alpha_filtration(SimplicialComplexForAlpha& complex, Simplex_handle f_simplex, int decr_dim) {
+    // From SimplicialComplexForAlpha type required to assign filtration values.
+    typedef typename SimplicialComplexForAlpha::Filtration_value Filtration_value;
 #ifdef DEBUG_TRACES
-    typedef typename Simplicial_complex::Vertex_handle Vertex_handle;
+    typedef typename SimplicialComplexForAlpha::Vertex_handle Vertex_handle;
 #endif  // DEBUG_TRACES
     
     // ### Foreach Tau face of Sigma