update doc

Surface_mesh_approximation/doc/Surface_mesh_approximation/Doxyfile.in

@@ -18,3 +18,5 @@ ALIASES += "cgalNPTableBegin=<dl class=\"params\"><dt></dt><dd> <table class=\"p
 ALIASES += "cgalNPTableEnd=</table> </dd> </dl>"
 ALIASES += "cgalNPBegin{1}=<tr><td class=\"paramname\">\1 </td><td>"
 ALIASES += "cgalNPEnd=</td></tr>"
+
+EXCLUDE = ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/internal

Surface_mesh_approximation/doc/Surface_mesh_approximation/NamedParameters.txt

@@ -67,10 +67,16 @@ typename CGAL::Kernel_traits<
 \b Default value is \code boost::get(CGAL::vertex_point, pmesh)\endcode
 \cgalNPEnd
 
+\cgalNPBegin{verbose_level} \anchor VSA_verbose_level
+set the verbose level of the function.\n
+\b Type : \c CGAL::Approximation_verbose_level \n
+\b Default value is `CGAL::Approximation_verbose_level::Main_steps`
+\cgalNPEnd
+
 \cgalNPBegin{seeding_method} \anchor VSA_seeding_method
 the selection of seeding method.\n
-\b Type : \c CGAL::Seeding \n
+\b Type : \c CGAL::Approximation_seeding_tag \n
-\b Default value is `CGAL::Seeding::Hierarchical`
+\b Default value is `CGAL::Approximation_seeding_tag::Hierarchical`
 \cgalNPEnd
 
 \cgalNPBegin{max_nb_proxies} \anchor VSA_max_nb_proxies
@@ -103,28 +109,52 @@ the chord subdivision threshold used in the meshing step.\n
 \b Default value is `5.0`
 \cgalNPEnd
 
-\cgalNPBegin{face_proxy_map} \anchor VSA_face_proxy_map
+\cgalNPBegin{is_relative_to_chord} \anchor VSA_is_relative_to_chord
+set the chord subdivision threshold relative to the chord length.\n
+\b Type : `bool` \n
+\b Default value is `false`
+\cgalNPEnd
+
+\cgalNPBegin{with_dihedral_angle} \anchor VSA_with_dihedral_angle
+set the chord subdivision with dihedral angle weighting.\n
+\b Type : `bool` \n
+\b Default value is `false`
+\cgalNPEnd
+
+\cgalNPBegin{optimize_anchor_location} \anchor VSA_optimize_anchor_location
+set if optimize the anchor position in the meshing step.\n
+\b Type : `bool` \n
+\b Default value is `true`
+\cgalNPEnd
+
+\cgalNPBegin{pca_plane} \anchor VSA_pca_plane
+set the plane approximated with the PCA algorithm in the meshing step.\n
+\b Type : `bool` \n
+\b Default value is `false`
+\cgalNPEnd
+
+\cgalNPBegin{facet_proxy_map} \anchor VSA_facet_proxy_map
 the property map outputs the proxy index of each face of the input polygon mesh.\n
 \b Type: a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::%face_descriptor` as key type and the value type `std::size_t`\n
-\b Default : if this parameter is omitted, no output operation are performed
+\b Default : if this parameter is omitted, no output operation is performed
 \cgalNPEnd
 
 \cgalNPBegin{proxies} \anchor VSA_proxies
 an `OutputIterator` to write proxies in.\n
-\b Type : a class model of `OutputIterator` with `CGAL::PlaneProxy<GeomTraits>` value type.\n
+\b Type : a class model of `OutputIterator` with `CGAL::VSA::L21_metric_vector_proxy_no_area_weighting::Proxy` value type.\n
-\b Default : if this parameter is omitted, no output operation are performed
+\b Default : if this parameter is omitted, no output operation is performed
 \cgalNPEnd
 
-\cgalNPBegin{anchors} \anchor VSA_anchor_points
+\cgalNPBegin{anchors} \anchor VSA_anchors
 an `OutputIterator` to write anchor points in.\n
-\b Type : a class model of `OutputIterator` with `boost::graph_traits<TriangleMesh>::%vertex_descriptor` value type.\n
+\b Type : a class model of `OutputIterator` with `GeomTraits::%Point_3` value type.\n
-\b Default : if this parameter is omitted, no output operation are performed
+\b Default : if this parameter is omitted, no output operation is performed
 \cgalNPEnd
 
-\cgalNPBegin{triangles} \anchor VSA_indexed_triangles
+\cgalNPBegin{triangles} \anchor VSA_triangles
 an `OutputIterator` to write indexed triangles in.\n
 \b Type : a class model of `OutputIterator` with `CGAL::cpp11::array<std::size_t, 3>` value type.\n
-\b Default : if this parameter is omitted, no output operation are performed
+\b Default : if this parameter is omitted, no output operation is performed
 \cgalNPEnd
 
 \cgalNPTableEnd

Surface_mesh_approximation/doc/Surface_mesh_approximation/PackageDescription.txt

@@ -32,14 +32,15 @@ The page \ref namedparameters describes their usage
 and provides the list of parameters used in this package.
 
 ## Concepts ##
-- `ErrorMetric`
+- `ErrorMetricProxy`
 
 ## Main Functions ##
 - `CGAL::mesh_approximation()`
 
 ## Classes ##
-- `CGAL::VSA::L21_metric_planar_proxy`
+- `CGAL::VSA::L21_metric_vector_proxy`
-- `CGAL::VSA::L2_metric_planar_proxy`
+- `CGAL::VSA::L21_metric_vector_proxy_no_area_weighting`
+- `CGAL::VSA::L2_metric_plane_proxy`
 - `CGAL::VSA_approximation`
 
 \todo add option to enforce guarantee of 2-manifold and oriented output mesh

Surface_mesh_approximation/doc/Surface_mesh_approximation/surface_mesh_approximation.txt

@@ -11,7 +11,7 @@ namespace CGAL {
 This package implements the <em>Variational Shape Approximation</em> \cgalCite{cgal:cad-vsa-04} (%VSA) method to approximate an input surface mesh by a simpler surface triangle mesh.
 
 Given an input surface triangle mesh, %VSA leverages a discrete clustering algorithm to approximate it by a set of local simple shapes referred to as proxies. Each cluster is represented as a connected set of triangles of the input mesh, and the output mesh is constructed by generating a surface triangle mesh which approximates the clusters.
-The approximation error is one-sided, defined between the clusters and their associated proxies. Two error metrics (\f$ \mathcal{L}^2 \f$, \f$ \mathcal{L}^{2,1} \f$) for planar proxies are provided via the classes `CGAL::L2_metric_planar_proxy` and `CGAL::L21_metric_planar_proxy`, and the algorithm design is generic to other user-defined metrics. The current proxies are planar, but the algorithm design is generic for future extensions to non-planar proxies \cgalCite{cgal:ywly-vmsqs-12}. A brief background about <em>%Proxy</em> and <em>%ErrorMetric</em> is provided in Section \ref sma_background.
+The approximation error is one-sided, defined between the clusters and their associated proxies. Two error metrics (\f$ \mathcal{L}^2 \f$, \f$ \mathcal{L}^{2,1} \f$) for planar proxies are provided via the classes `CGAL::VSA::L2_metric_plane_proxy` and `CGAL::VSA::L21_metric_vector_proxy`, and the algorithm design is generic to other user-defined metrics. The current proxies are planar, but the algorithm design is generic for future extensions to non-planar proxies \cgalCite{cgal:ywly-vmsqs-12}. A brief background about <em>%Proxy</em> and <em>%ErrorMetric</em> is provided in Section \ref sma_background.
 
 \cgalFigureBegin{Approximation_teaser, teaser.png}
 Variational shape approximation on two models with the \f$ \mathcal{L}^{2,1} \f$ error metric and planar proxies. From left to right: partition of the input surface triangle mesh, anchor vertices and edges, and output triangle mesh. The partition is optimized via discrete clustering of the input triangles, so as to minimize the approximation error from the clusters to the planar proxies (not shown). 
@@ -175,7 +175,7 @@ The input of the algorithm is expected to be:
 
 \subsection sma_example1 Free Function Approximation
 
-The following example calls the free function `CGAL::mesh_approximation()` on the input triangle mesh with default `CGAL::L21_metric`.
+The following example calls the free function `CGAL::mesh_approximation()` on the input triangle mesh with default `CGAL::VSA::L21_metric_plane_proxy_no_area_weighting`.
 
 \cgalExample{Surface_mesh_approximation/vsa_approximation_example.cpp}
 

Surface_mesh_approximation/include/CGAL/L21_metric_vector_proxy_no_area_weighting.h

@@ -45,10 +45,18 @@ class L21_metric_vector_proxy_no_area_weighting {
   typedef typename CGAL::internal::dynamic_property_map<TriangleMesh, Face_area_tag >::type Face_area_map;
 
 public:
-  // Public types
+  /// \name Types
+  /// @{
   typedef typename GeomTraits::Vector_3 Proxy;
+  /// @}
 
-  // Constructor.
+  /// \name Constructor
+  /// @{
+  /*!
+   * @brief Constructor
+   * @param tm triangle mesh
+   * @param vpmap vertex point map
+   */
   L21_metric_vector_proxy_no_area_weighting(const TriangleMesh &tm, const VertexPointMap &vpmap) {
     GeomTraits traits;
     m_scalar_product_functor = traits.compute_scalar_product_3_object();
@@ -67,14 +75,26 @@ public:
       put(m_fnmap, f, CGAL::unit_normal(p0, p1, p2));
     }
   }
+  /// @}
 
-  // Computes the L21 error between a facet and a proxy.
+  /// \name Operations
+  /*!
+   * @brief Computes the L2,1 error from a facet to a proxy. 
+   * @param f face_descriptor of a face
+   * @param px proxy
+   * @return computed error
+   */
   FT compute_error(const face_descriptor &f, const Proxy &px) const {
     Vector_3 v = m_sum_functor(get(m_fnmap, f), m_scale_functor(px, FT(-1.0)));
     return m_scalar_product_functor(v, v);
   }
 
-  // Fits a proxy from a face range.
+  /*!
+   * @brief Fits a proxy to a face range.
+   * @param beg face range begin
+   * @param end face range end
+   * @return fitted proxy
+   */
   template <typename FacetIterator>
   Proxy fit_proxy(const FacetIterator beg, const FacetIterator end) const {
     CGAL_assertion(beg != end);
@@ -89,6 +109,7 @@ public:
 
     return norm;
   }
+  /// @}
 
 private:
   Face_normal_map m_fnmap;

Surface_mesh_approximation/include/CGAL/mesh_approximation.h

@@ -21,11 +21,11 @@ namespace CGAL {
 /// \ingroup PkgTSMA
 /// @brief Verbose level enumeration for Variational Shape Approximation algorithm.
 enum Approximation_verbose_level {
-  /// Silent seeding
+  /// Silent
   Silent,
-  /// Incremental seeding
+  /// Main steps
   Main_steps,
-  /// Hierarchical seeding
+  /// Verbose
   Verbose
 };
 
@@ -63,7 +63,7 @@ enum Approximation_verbose_level {
  *  \cgalParamEnd
  *  \cgalParamBegin{mesh_chord_error} maximum chord approximation error used for meshing (TODO: precise unit).
  *  \cgalParamEnd
- *  \cgalParamBegin{face_proxy_map} a ReadWritePropertyMap with
+ *  \cgalParamBegin{facet_proxy_map} a ReadWritePropertyMap with
  * `boost::graph_traits<TriangleMesh>::%face_descriptor` as key and `std::size_t` as value type.
  * A proxy is a set of connected facets which are placed under the same proxy patch (see \cgalFigureRef{iterations}).
  * The proxy-ids are contiguous in range [0, number_of_proxies - 1].