Add of src/common/include/gudhi/Points_3D_off_io.h to read specific 3D OFF Files for CGAL Point_3

Add an example to read 3D OFF Files for CGAL Point_3
Modify alpha_complex_3d_persistence.cpp to read OFF files
Add periodic_alpha_complex_3d_persistence.cpp in Persistent_cohomology examples
Add info about new examples in README


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

Former-commit-id: 6b423b598869a0f4f9c62d93c93b69efd93c0161

5 files changed, 272 insertions, 12 deletions

diff --git a/src/common/example/CGAL_3D_points_off_reader.cpp b/src/common/example/CGAL_3D_points_off_reader.cpp
new file mode 100644
index 00000000..d48bb17d
--- /dev/null
+++ b/src/common/example/CGAL_3D_points_off_reader.cpp
@@ -0,0 +1,41 @@
+#include <gudhi/Points_3D_off_io.h>
+
+#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Point_3 = Kernel::Point_3;
+
+void usage(char * const progName) {
+  std::cerr << "Usage: " << progName << " inputFile.off" << std::endl;
+  exit(-1);
+}
+
+int main(int argc, char **argv) {
+  if (argc != 2) {
+    std::cerr << "Error: Number of arguments (" << argc << ") is not correct" << std::endl;
+    usage(argv[0]);
+  }
+
+  std::string offInputFile(argv[1]);
+  // Read the OFF file (input file name given as parameter) and triangulate points
+  Gudhi::Points_3D_off_reader<Point_3> off_reader(offInputFile);
+  // Check the read operation was correct
+  if (!off_reader.is_valid()) {
+    std::cerr << "Unable to read file " << offInputFile << std::endl;
+    usage(argv[0]);
+  }
+
+  // Retrieve the triangulation
+  std::vector<Point_3> point_cloud = off_reader.get_point_cloud();
+
+  int n {0};
+  for (auto point : point_cloud) {
+    ++n;
+    std::cout << "Point[" << n << "] = (" << point[0] << ", " << point[1] << ", " << point[2] << ")\n";
+  }
+  return 0;
+}
diff --git a/src/common/example/CGAL_points_off_reader.cpp b/src/common/example/CGAL_points_off_reader.cpp
index 45e9f1e6..997b47c1 100644
--- a/src/common/example/CGAL_points_off_reader.cpp
+++ b/src/common/example/CGAL_points_off_reader.cpp
@@ -8,17 +8,19 @@
 #include <string>
 #include <vector>
 
-typedef CGAL::Epick_d< CGAL::Dynamic_dimension_tag > Kernel;
-typedef typename Kernel::Point_d Point_d;
+using Kernel = CGAL::Epick_d< CGAL::Dynamic_dimension_tag >;
+using Point_d = typename Kernel::Point_d;
 
-void usage(int argc, char * const progName) {
-  std::cerr << "Error: Number of arguments (" << argc << ") is not correct" << std::endl;
+void usage(char * const progName) {
   std::cerr << "Usage: " << progName << " inputFile.off" << std::endl;
   exit(-1);
 }
 
 int main(int argc, char **argv) {
-  if (argc != 2) usage(argc, (argv[0] - 1));
+  if (argc != 2) {
+    std::cerr << "Error: Number of arguments (" << argc << ") is not correct" << std::endl;
+    usage(argv[0]);
+  }
 
   std::string offInputFile(argv[1]);
   // Read the OFF file (input file name given as parameter) and triangulate points
@@ -26,16 +28,16 @@ int main(int argc, char **argv) {
   // Check the read operation was correct
   if (!off_reader.is_valid()) {
     std::cerr << "Unable to read file " << offInputFile << std::endl;
-    exit(-1);
+    usage(argv[0]);
   }
 
   // Retrieve the triangulation
   std::vector<Point_d> point_cloud = off_reader.get_point_cloud();
 
-  int n = 0;
+  int n {0};
   for (auto point : point_cloud) {
     std::cout << "Point[" << n << "] = ";
-    for (int i = 0; i < point.dimension(); i++)
+    for (int i {0}; i < point.dimension(); i++)
       std::cout << point[i] << " ";
     std::cout << "\n";
     ++n;
diff --git a/src/common/example/CMakeLists.txt b/src/common/example/CMakeLists.txt
index 5aeaa8c6..ee6c9058 100644
--- a/src/common/example/CMakeLists.txt
+++ b/src/common/example/CMakeLists.txt
@@ -3,6 +3,10 @@ project(GUDHIDelaunayTriangulationOffFileReadWrite)
 
 # need CGAL 4.7
 if(CGAL_FOUND)
+  add_executable ( cgal3Doffreader CGAL_3D_points_off_reader.cpp )
+  target_link_libraries(cgal3Doffreader  ${Boost_SYSTEM_LIBRARY} ${CGAL_LIBRARY})
+  add_test(cgal3Doffreader ${CMAKE_CURRENT_BINARY_DIR}/cgaloffreader ${CMAKE_SOURCE_DIR}/data/points/tore3D_300.off)
+
   if (NOT CGAL_VERSION VERSION_LESS 4.7.0)
     find_package(Eigen3 3.1.0)
     if (EIGEN3_FOUND)
diff --git a/src/common/include/gudhi/Points_3D_off_io.h b/src/common/include/gudhi/Points_3D_off_io.h
new file mode 100644
index 00000000..02e6f910
--- /dev/null
+++ b/src/common/include/gudhi/Points_3D_off_io.h
@@ -0,0 +1,206 @@
+/*    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) 2015  INRIA Saclay (France)
+ *
+ *    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 POINTS_3D_OFF_IO_H_
+#define POINTS_3D_OFF_IO_H_
+
+#include <gudhi/Off_reader.h>
+
+#include <string>
+#include <vector>
+#include <fstream>
+#include <map>
+
+namespace Gudhi {
+
+/** 
+ * @brief OFF file visitor implementation according to Off_reader in order to read points from an OFF file.
+ */
+template<typename Point_3>
+class Points_3D_off_visitor_reader {
+ private:
+  std::vector<Point_3> point_cloud_;
+  bool valid_;
+
+ public:
+
+  /** @brief Off_reader visitor init implementation. 
+   * 
+   * The init parameters are set from OFF file header.
+   * Dimension value is required and the value must be 3.
+   *
+   * @param[in] dim space dimension of vertices.
+   * @param[in] num_vertices number of vertices in the OFF file (not used).
+   * @param[in] num_faces number of faces in the OFF file (not used).
+   * @param[in] num_edges number of edges in the OFF file (not used).
+   */
+  void init(int dim, int num_vertices, int num_faces, int num_edges) {
+#ifdef DEBUG_TRACES
+    std::cout << "Points_3D_off_visitor_reader::init - dim=" << dim << " - num_vertices=" <<
+        num_vertices << " - num_faces=" << num_faces << " - num_edges=" << num_edges << std::endl;
+#endif  // DEBUG_TRACES
+    if (dim == 3) {
+      valid_ = true;
+    } else {
+      valid_ = false;
+      std::cerr << "Points_3D_off_reader::Points_3D_off_reader cannot read OFF files in dimension " << dim << "\n";
+    }
+
+    if (num_faces > 0) {
+      std::cerr << "Points_3D_off_visitor_reader::init faces are not taken into account from OFF file for Points.\n";
+    }
+    if (num_edges > 0) {
+      std::cerr << "Points_3D_off_visitor_reader::init edges are not taken into account from OFF file for Points.\n";
+    }
+  }
+
+  /** @brief Off_reader visitor point implementation. 
+   * 
+   * The point function is called on each vertex line from OFF file.
+   * This function inserts the vertex in the vector of points.
+   *
+   * @param[in] point vector of vertex coordinates.
+   * 
+   * @details
+   * Point_3 must have a constructor with the following form:
+   * 
+   * @code template<class InputIterator > Point_3::Point_3(double x, double y, double z) @endcode
+   */
+  void point(const std::vector<double>& point) {
+    if (valid_) {
+#ifdef DEBUG_TRACES
+      std::cout << "Points_3D_off_visitor_reader::point ";
+      for (auto coordinate : point) {
+        std::cout << coordinate << " | ";
+      }
+      std::cout << std::endl;
+#endif  // DEBUG_TRACES
+      // Fill the point cloud
+      point_cloud_.push_back(Point_3(point[0], point[1], point[2]));
+    }
+  }
+
+  // Off_reader visitor maximal_face implementation - Only points are read
+
+  void maximal_face(const std::vector<int>& face) { }
+
+  // Off_reader visitor done implementation - Only points are read
+
+  void done() { }
+
+  /** @brief Point cloud getter.
+   *
+   * @return The point cloud.
+   */
+  const std::vector<Point_3>& get_point_cloud() const {
+    return point_cloud_;
+  }
+
+  /** @brief Returns if the OFF file read operation was successful or not.
+   *
+   * @return OFF file read status.
+   */
+  bool is_valid() const {
+    return valid_;
+  }
+};
+
+/** 
+ * \@brief OFF file reader implementation in order to read dimension 3 points from an OFF file.
+ * 
+ * @details
+ * This class is using the Points_3D_off_visitor_reader to visit the OFF file according to Off_reader.
+ * 
+ * Point_3 must have a constructor with the following form:
+ * 
+ * @code template<class InputIterator > Point_3::Point_3(double x, double y, double z) @endcode
+ * 
+ * @section Example
+ *
+ * This example loads points from an OFF file and builds a vector of CGAL points in dimension 3.
+ * Then, it is asked to display the points.
+ * 
+ * Asserts
+ * 
+ * @include common/CGAL_Points_3D_off_reader.cpp
+ * 
+ * When launching:
+ * 
+ * @code $> ./cgal3Doffreader ../../data/points/alphacomplexdoc.off
+ * @endcode
+ *
+ * the program output is:
+ * 
+ * @include common/cgal3Doffreader_result.txt
+ */
+template<typename Point_3>
+class Points_3D_off_reader {
+ public:
+
+  /** @brief Reads the OFF file and constructs a vector of points from the points
+   * that are in the OFF file.
+   *
+   * @param[in] name_file OFF file to read.
+   * 
+   * @post Check with is_valid() function to see if read operation was successful.
+   */
+  Points_3D_off_reader(const std::string& name_file)
+      : valid_(false) {
+    std::ifstream stream(name_file);
+    if (stream.is_open()) {
+      Off_reader off_reader(stream);
+      Points_3D_off_visitor_reader<Point_3> off_visitor;
+      valid_ = off_reader.read(off_visitor);
+      valid_ = valid_ && off_visitor.is_valid();
+      if (valid_) {
+        point_cloud = off_visitor.get_point_cloud();
+      }
+    } else {
+      std::cerr << "Points_3D_off_reader::Points_3D_off_reader could not open file " << name_file << "\n";
+    }
+  }
+
+  /** @brief Returns if the OFF file read operation was successful or not.
+   *
+   * @return OFF file read status.
+   */
+  bool is_valid() const {
+    return valid_;
+  }
+
+  /** @brief Point cloud getter.
+   *
+   * @return point_cloud.
+   */
+  const std::vector<Point_3>& get_point_cloud() const {
+    return point_cloud;
+  }
+
+ private:
+  /** @brief point_cloud.*/
+  std::vector<Point_3> point_cloud;
+  /** @brief OFF file read status.*/
+  bool valid_;
+};
+
+} // namespace Gudhi
+
+#endif  // POINTS_3D_OFF_IO_H_
diff --git a/src/common/include/gudhi/Points_off_io.h b/src/common/include/gudhi/Points_off_io.h
index 77f36be2..74b49386 100644
--- a/src/common/include/gudhi/Points_off_io.h
+++ b/src/common/include/gudhi/Points_off_io.h
@@ -43,7 +43,7 @@ class Points_off_visitor_reader {
   /** \brief Off_reader visitor init implementation. 
    * 
    * The init parameters are set from OFF file header.
-   * Dimension value is required in order to construct Alpha complex.
+   * Dimension value is required in order to construct a vector of points.
    *
    * @param[in] dim space dimension of vertices.
    * @param[in] num_vertices number of vertices in the OFF file (not used).
@@ -63,12 +63,19 @@ class Points_off_visitor_reader {
     }
   }
 
-  /** \brief Off_reader visitor point implementation. 
+  /** @brief Off_reader visitor point implementation. 
    * 
    * The point function is called on each vertex line from OFF file.
-   * This function inserts the vertex in the Alpha complex.
+   * This function inserts the vertex in the vector of points.
    *
    * @param[in] point vector of vertex coordinates.
+   * 
+   * @details
+   * Point_d must have a constructor with the following form:
+   * 
+   * @code template<class InputIterator > Point_d::Point_d(int d, InputIterator first, InputIterator last) @endcode
+   * 
+   * where d is the point dimension. 		
    */
   void point(const std::vector<double>& point) {
 #ifdef DEBUG_TRACES
@@ -127,7 +134,7 @@ class Points_off_visitor_reader {
 template<typename Point_d>
 class Points_off_reader {
  public:
-  /** \brief Reads the OFF file and constructs the Alpha complex from the points
+  /** \brief Reads the OFF file and constructs a vector of points from the points
    * that are in the OFF file.
    *
    * @param[in] name_file OFF file to read.