write_VTK fixes

-> created and documented write_VTK functions for `GeometricChainComplex` models and for chains in such complexes.
-> removed documentation for chain_complex_to_vtk and chain_to_vtk in `GeometricChainComplex` models
-> tested in test_hdvf_examples

HDVF/examples/HDVF/test_hdvf_example.cpp

@@ -87,7 +87,7 @@ int main(int argc, char **argv)
         cycle2.set_coefficient(12, 1) ;
         HDVF_type::Column_chain annot2(hdvf.get_annotation(cycle2,1));
         std::cout << "Cycle2:" << cycle1 << std::endl ;
-        Complex::chain_to_vtk(complex, "cycle2.vtk", cycle2, 1) ;
+        CGAL::IO::write_VTK(complex, "cycle2.vtk", cycle2, 1) ;
         std::cout << "Annotation of cycle 2: " << annot2 << std::endl ;
 
         // Test get_coannotation
@@ -117,7 +117,7 @@ int main(int argc, char **argv)
         HDVF_type::Column_chain cycle4(cycle3) ;
         cycle4 += hdvf.homology_chain(criticals.at(1), 1) ; // Cycle4: cycle3 + second hole
         std::cout << "Cycle4: " << cycle4 << std::endl ;
-        Complex::chain_to_vtk(complex, "cycle4.vtk", cycle4, 1) ;
+        CGAL::IO::write_VTK(complex, "cycle4.vtk", cycle4, 1) ;
         std::cout << "are_same_cycles cycle1 and cycle4: " << hdvf.are_same_cycles(cycle1, cycle4, 1) << std::endl ;
 
         // Test are_same_cocycles

HDVF/include/CGAL/HDVF/Cubical_chain_complex.h

@@ -464,7 +464,7 @@ public:
 
     // VTK export
 
-    /**
+    /*
      * \brief Exports a cubical complex (plus, optionally, labels) to a VTK file.
      *
      * The method generates legacy text VTK files. Labels are exported as such in a VTK property, together with CellID property, containing the index of each cell.
@@ -579,7 +579,7 @@ public:
         out.close() ;
     }
 
-    /**
+    /*
      * \brief Exports a chain over a cubical complex to a VTK file.
      *
      * The method generates legacy text VTK files. All the cells of the chain with non zero coefficient are exported. If a cellId is provided, labels are exported in a VTK property (2 for all cells, 0 for cell of index cellId).  The index of each cell is exported in a CellID property.

HDVF/include/CGAL/HDVF/Geometric_chain_complex_tools.h

@@ -290,6 +290,40 @@ void write_VTK (Homological_discrete_vector_field::Hdvf_duality<ChainComplex> &h
         }
     }
 }
+
+/**
+ * \brief Exports a model of `GeometricChainComplex` (plus, optionally, labels) to a VTK file.
+ *
+ * The method generates legacy text VTK files. Labels are exported as such in a VTK property, together with CellID property, containing the index of each cell.
+ *
+ * \tparam LabelType Type of labels provided (default: int).
+ *
+ * \param K Model of `GeometricChainComplex` exported.
+ * \param filename Output file root (output filenames will be built from this root).
+ * \param labels Pointer to a vector of labels in each dimension. (*labels).at(q) is the set of integer labels of cells of dimension q. If labels is NULL, only CellID property is exported.
+ * \param label_type_name Typename used in vtk export (e.g. "int" or "unsigned_long", see <a href = "https://docs.vtk.org/en/latest/design_documents/VTKFileFormats.html">VTK manual </a>).
+ */
+template <typename Chain_complex, typename LabelType = int>
+static void write_VTK(const Chain_complex &K, const std::string &filename, const std::vector<std::vector<LabelType> > *labels=NULL, std::string label_type_name = "int") {
+    Chain_complex::chain_complex_to_vtk(K, filename, labels, label_type_name);
+}
+
+/**
+ * \brief Exports a chain over a model of `GeometricChainComplex` to a VTK file.
+ *
+ * The method generates legacy text VTK files. All the cells of the chain with non zero coefficient are exported. If a cellId is provided, labels are exported in a VTK property (2 for all cells, 0 for cell of index cellId).  The index of each cell is exported in a CellID property.
+ *
+ * \param K Model of `GeometricChainComplex` exported.
+ * \param filename Output file root (output filenames will be built from this root).
+ * \param chain Sparse_chain exported (all the cells with non-zero coefficients in the chain are exported to vtk).
+ * \param q Dimension of the cells of the chain.
+ * \param cellId If different from MAX_SIZE_T, labels are exported to distinguish cells of the chain (label 2) from cellId cell (label 0).
+ */
+template <typename Chain_complex>
+void write_VTK(const Chain_complex &K, const std::string &filename, const OSM::Sparse_chain<typename Chain_complex::Coefficient_ring, OSM::COLUMN>& chain, int q, size_t cellId = -1){
+    Chain_complex::chain_to_vtk(K, filename, chain, q, cellId);
+}
+
 } /* end namespace IO */
 
 namespace Homological_discrete_vector_field {

HDVF/include/CGAL/HDVF/Simplicial_chain_complex.h

@@ -108,7 +108,7 @@ public:
 
     // VTK export
 
-    /**
+    /*
      * \brief Exports a simplicial complex (plus, optionally, labels) to a VTK file.
      *
      * The method generates legacy text VTK files. Labels are exported as such in a VTK property, together with CellID property, containing the index of each cell.
@@ -218,7 +218,7 @@ public:
         out.close() ;
     }
 
-    /**
+    /*
      * \brief Exports a chain over a simplicial complex to a VTK file.
      *
      * The method generates legacy text VTK files. All the cells of the chain with non zero coefficient are exported. If a cellId is provided, labels are exported in a VTK property (2 for all cells, 0 for cell of index cellId).  The index of each cell is exported in a CellID property.