Fix SimplicialComplexForAlpha (dD version)

Write SimplicialComplexForAlpha3d concept
Add make_filtration_non_decreasing and prune_above_filtration mechanism for Alpha_complex_3d
Write documentation for Alpha_complex_3d ( still missing the user version)
Remove exact static bool from Alpha_complex_3d_options mechanism and add some comments on value_from_iterator functions
Fix Alpha_complex/utilities/CMakeLists.txt warnings






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

Former-commit-id: 32e15aaf98df14a43eaef4a4af00de2ec418924c

5 files changed, 97 insertions, 15 deletions

diff --git a/src/Alpha_complex/concept/SimplicialComplexForAlpha.h b/src/Alpha_complex/concept/SimplicialComplexForAlpha.h
index a51df127..ba97c802 100644
--- a/src/Alpha_complex/concept/SimplicialComplexForAlpha.h
+++ b/src/Alpha_complex/concept/SimplicialComplexForAlpha.h
@@ -41,9 +41,6 @@ struct SimplicialComplexForAlpha {
   /** Returns the number of vertices in the simplicial complex. */
   std::size_t num_vertices();
 
-  /** Sets the simplicial complex dimension. */
-  void set_dimension(int dimension);
-
   /** Gets the 'simplex' dimension. */
   int dimension(Simplex_handle simplex);
 
@@ -65,8 +62,7 @@ struct SimplicialComplexForAlpha {
    * 'value type' must be 'Vertex_handle'.*/
   typedef unspecified Simplex_vertex_range;
 
-  /** \brief Returns a range over vertices of a given
-   *  simplex. */
+  /** \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.
@@ -77,6 +73,14 @@ struct SimplicialComplexForAlpha {
   /** \brief Returns a range over boundaries of a given simplex. */
   Boundary_simplex_range boundary_simplex_range(Simplex_handle const & simplex);
 
+  /** \brief Iterator over the simplices of the skeleton of the complex, for a given dimension.
+   *
+   * 'value_type' must be 'Simplex_handle'. */
+  typedef unspecified Skeleton_simplex_range;
+  /** \brief Returns a range over the simplices of the skeleton of the simplicial complex, for a given
+   * dimension. */
+  Skeleton_simplex_range skeleton_simplex_range;
+
   /** \brief Return type of an insertion of a simplex
    */
   typedef unspecified Insertion_result_type;
diff --git a/src/Alpha_complex/concept/SimplicialComplexForAlpha3d.h b/src/Alpha_complex/concept/SimplicialComplexForAlpha3d.h
new file mode 100644
index 00000000..f6085a26
--- /dev/null
+++ b/src/Alpha_complex/concept/SimplicialComplexForAlpha3d.h
@@ -0,0 +1,58 @@
+/*    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) 2018 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_3D_H_
+#define CONCEPT_ALPHA_COMPLEX_SIMPLICIAL_COMPLEX_FOR_ALPHA_3D_H_
+
+namespace Gudhi {
+
+namespace alpha_complex {
+
+/** \brief The concept SimplicialComplexForAlpha3d describes the requirements for a type to implement a simplicial
+ * complex, that can be created from a `Alpha_complex_3d`.
+ */
+struct SimplicialComplexForAlpha3d {
+  /** 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();
+
+  /** \brief Inserts a simplex from a given simplex (represented by a vector of Vertex_handle) in the
+   * simplicial complex with the given 'filtration' value. */
+  void insert_simplex(std::vector<Vertex_handle> 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);
+
+};
+
+}  // namespace alpha_complex
+
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ALPHA_COMPLEX_SIMPLICIAL_COMPLEX_FOR_ALPHA_3D_H_
diff --git a/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h b/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h
index 1d171f7d..f37c0816 100644
--- a/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h
+++ b/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h
@@ -56,19 +56,23 @@ namespace Gudhi {
 namespace alpha_complex {
 
 /**
- * \class Alpha_complex_3d Alpha_complex_3d.h gudhi/Alpha_complex_3d.h
+ * \class Alpha_complex_3d
  * \brief Alpha complex data structure for 3d specific case.
  *
  * \ingroup alpha_complex
  *
  * \details
- * The data structure is constructing a CGAL Delaunay triangulation (for more informations on CGAL Delaunay
- * triangulation, please refer to the corresponding chapter in page http://doc.cgal.org/latest/Triangulation/) from a
- * range of points or from an OFF file (cf. Points_off_reader).
+ * The data structure is constructing a <a href="https://doc.cgal.org/latest/Alpha_shapes_3/index.html">CGAL 3D Alpha
+ * Shapes</a> from a range of points (can be read from an OFF file, cf. Points_off_reader).
+ *
+ * \tparam AlphaComplex3dOptions can be `Gudhi::alpha_complex::Alpha_shapes_3d`,
+ * `Gudhi::alpha_complex::Exact_alpha_shapes_3d`, `Gudhi::alpha_complex::Weighted_alpha_shapes_3d`,
+ * `Gudhi::alpha_complex::Periodic_alpha_shapes_3d` or `Gudhi::alpha_complex::Weighted_periodic_alpha_shapes_3d`.
  *
  * Please refer to \ref alpha_complex for examples.
  *
- * \remark When Alpha_complex is constructed with an infinite value of alpha, the complex is a Delaunay complex.
+ * \remark When Alpha_complex_3d is constructed with an infinite value of alpha (default value), the complex is a
+ * Delaunay complex.
  *
  */
 template<typename AlphaComplex3dOptions>
@@ -100,6 +104,9 @@ public:
   *
   * @param[in] points Range of points to triangulate. Points must be in AlphaComplex3dOptions::Point_3
   *
+  * @pre Available if AlphaComplex3dOptions is `Gudhi::alpha_complex::Alpha_shapes_3d` or
+  * `Gudhi::alpha_complex::Exact_alpha_shapes_3d`.
+  *
   * The type InputPointRange must be a range for which std::begin and
   * std::end return input iterators on a AlphaComplex3dOptions::Point_3.
   */
@@ -135,6 +142,8 @@ public:
   * @param[in] points Range of points to triangulate. Points must be in AlphaComplex3dOptions::Point_3
   * @param[in] weights Range of weights on points. Points must be in AlphaComplex3dOptions::Point_3
   *
+  * @pre Available if AlphaComplex3dOptions is `Weighted_alpha_shapes_3d`.
+  *
   * The type InputPointRange must be a range for which std::begin and
   * std::end return input iterators on a AlphaComplex3dOptions::Point_3.
   * The type WeightRange must be a range for which std::begin and
@@ -192,6 +201,8 @@ public:
   * @param[in] y_max Iso-oriented cuboid y_max.
   * @param[in] z_max Iso-oriented cuboid z_max.
   *
+  * @pre Available if AlphaComplex3dOptions is `Periodic_alpha_shapes_3d`.
+  *
   * The type InputPointRange must be a range for which std::begin and
   * std::end return input iterators on a AlphaComplex3dOptions::Point_3.
   * The type of x_min, y_min, z_min, x_max, y_max and z_max is AlphaComplex3dOptions::Alpha_shape_3::FT.
@@ -265,6 +276,8 @@ public:
   * @param[in] y_max Iso-oriented cuboid y_max.
   * @param[in] z_max Iso-oriented cuboid z_max.
   *
+  * @pre Available if AlphaComplex3dOptions is `Weighted_periodic_alpha_shapes_3d`.
+  *
   * The type InputPointRange must be a range for which std::begin and
   * std::end return input iterators on a AlphaComplex3dOptions::Point_3.
   * The type WeightRange must be a range for which std::begin and
@@ -461,6 +474,12 @@ public:
     std::cout << "facets \t\t" << count_facets << std::endl;
     std::cout << "cells \t\t" << count_cells << std::endl;
 #endif  // DEBUG_TRACES
+    // --------------------------------------------------------------------------------------------
+    // As Alpha value is an approximation, we have to make filtration non decreasing while increasing the dimension
+    complex.make_filtration_non_decreasing();
+    // Remove all simplices that have a filtration value greater than max_alpha_square
+    complex.prune_above_filtration(max_alpha_square);
+    // --------------------------------------------------------------------------------------------
     return true;
   }
 
diff --git a/src/Alpha_complex/include/gudhi/Alpha_complex_3d_options.h b/src/Alpha_complex/include/gudhi/Alpha_complex_3d_options.h
index e1b246c5..567b19cb 100644
--- a/src/Alpha_complex/include/gudhi/Alpha_complex_3d_options.h
+++ b/src/Alpha_complex/include/gudhi/Alpha_complex_3d_options.h
@@ -55,6 +55,7 @@ public:
   static const bool weighted = false;
   static const bool periodic = false;
 
+  // Default value_from_iterator as Alpha_shape_3 is not exact
   template<class Filtration_value, class Alpha_value_iterator>
   static Filtration_value value_from_iterator(const Alpha_value_iterator avi) {
     return /*std::sqrt*/ *avi;
@@ -77,8 +78,8 @@ public:
 
   static const bool weighted = false;
   static const bool periodic = false;
-  static const bool exact = true;
 
+  // value_from_iterator needs to compute filtration value as Alpha_shape_3 is exact
   template<class Filtration_value, class Alpha_value_iterator>
   static Filtration_value value_from_iterator(const Alpha_value_iterator avi) {
     return /*std::sqrt*/ CGAL::to_double(avi->exact());
@@ -103,8 +104,8 @@ public:
 
   static const bool weighted = true;
   static const bool periodic = false;
-  static const bool exact = false;
 
+  // Default value_from_iterator as Alpha_shape_3 is not exact
   template<class Filtration_value, class Alpha_value_iterator>
   static Filtration_value value_from_iterator(const Alpha_value_iterator avi) {
     return /*std::sqrt*/ *avi;
@@ -134,8 +135,8 @@ public:
 
   static const bool weighted = false;
   static const bool periodic = true;
-  static const bool exact = false;
 
+  // Default value_from_iterator as Alpha_shape_3 is not exact
   template<class Filtration_value, class Alpha_value_iterator>
   static Filtration_value value_from_iterator(const Alpha_value_iterator avi) {
     return /*std::sqrt*/ *avi;
@@ -163,8 +164,8 @@ public:
 
   static const bool weighted = true;
   static const bool periodic = true;
-  static const bool exact = false;
 
+  // Default value_from_iterator as Alpha_shape_3 is not exact
   template<class Filtration_value, class Alpha_value_iterator>
   static Filtration_value value_from_iterator(const Alpha_value_iterator avi) {
     return /*std::sqrt*/ *avi;
diff --git a/src/Alpha_complex/utilities/CMakeLists.txt b/src/Alpha_complex/utilities/CMakeLists.txt
index 86e761ef..13476ba5 100644
--- a/src/Alpha_complex/utilities/CMakeLists.txt
+++ b/src/Alpha_complex/utilities/CMakeLists.txt
@@ -53,6 +53,6 @@ if(CGAL_FOUND)
 
     install(TARGETS alpha_complex_3d_persistence DESTINATION bin)
 
-  endif (NOT CGAL_VERSION VERSION_LESS 4.11.0)
+  endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.11.0)
 
 endif(CGAL_FOUND)