no initialization in manual

move initialization under seeding as stop criteria part
update method figure
formulate method

Surface_mesh_approximation/doc/Surface_mesh_approximation/surface_mesh_approximation.txt

@@ -12,9 +12,9 @@ namespace CGAL {
 
 For many applications ranging from reverse engineering to computational engineering, finding the concise and faithful approximation of an excessively verbose 3D data (in particular, scanned meshes) is beneficial for subsequent processing and may reduce the computational cost dramatically.
 
-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 indexed face set or polyhedral surface mesh. 
+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 indexed face set or polyhedral surface 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 triangle mesh approximation of the clusters. 
+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 triangle mesh approximation of the clusters. 
 By default the proxies are planar, and the algorithm design is generic for future extensions to non-planar proxies. 
 The approximation error is one-side, defined between the clusters and their associated proxies. Two error metrics (\f$ \mathcal{L}^2 \f$, \f$ \mathcal{L}^{2,1} \f$) are provided via the classes `CGAL::VSA::L2_metric` and `CGAL::VSA::L21_metric`, and the algorithm design is generic to other user-defined metrics.
 
@@ -36,43 +36,47 @@ A class interface is also provided for advanced users, with interactive capabili
 Figure \cgalFigureRef{relaxation} depicts several Lloyd clustering iterations on the plane-sphere model with planar proxies and the \f$ \mathcal{L}^{2,1} \f$ metric.
 
 \cgalFigureBegin{relaxation, relaxation.png}
-Lloyd iterations on the plane-sphere model with planar proxies and the \f$ \mathcal{L}^{2,1} \f$ metric: (left) random initialization of 6 proxies; (center) after one iteration; (right) after 8 iterations, the regions settle. The red lines depict the proxy normals.
+Discrete Lloyd iterations on the plane-sphere model with planar proxies and the \f$ \mathcal{L}^{2,1} \f$ metric: (left) random seeding of 6 proxies; (center) after one iteration; (right) after 8 iterations, the regions settle. The red lines depict the proxy normals drawn at the seed facets.
 \cgalFigureEnd
 
-On the right side of the figure is the fitting error curve at each iteration. After 8 iterations, the error barely changes. Based on this observation, we assume that the iteration converges if the error change of current iteration to the last one is less than a threshold (indicated by two green dash lines).
+On the right side of the figure is the fitting error curve at each iteration. After 8 iterations, the error barely changes. Based on this observation, we assume that the clustering converges if the error change of current iteration to the last one is less than a threshold (indicated by two green dash lines).
 
-\subsection sma_init Initialization
+\subsection sma_seeding Seeding
 
-<!-- As discussed above, the clustering iteration requires a set of initial proxies \f$ \{ P_1^0, \cdots, P_k^0 \} \f$.  -->
+Each proxy is always associated with a <em>seed</em> triangle facet in the input surface mesh, and with a facet we can always fit a new proxy. While the proxies may be viewed as centers (or best representative) in a geometric error sense, the seed of each proxy is used as the topological start point in the clustering process. Seeding is the processing of deciding how to select a seed facet where a new proxy/partition can be initialized from.
 
-The clustering algorithm must be initialized by determining either the maximum number of proxies required to approximate the geometry or the minimum error drop rate between two iterations. More specifically, we can decide:
-- <b>Maximum number of proxies</b>. The algorithm adds proxies until the specified target number is met.
-- <b>Minimum error drop</b>. We start from the proxy fitted from the first facet of the surface with the fitting error \f$ \hat E \f$. The algorithm adds proxies until the approximation error drops below the specified percentage \f$ target\_drop * \hat E \f$, between two iterations.
+\subsubsection sma_method Method
+
+To start the clustering iterations, we need a set of initial proxies. Starting from a single partition fitted with one proxy initialized from the first facet of the input mesh, we add more and more proxies to drive the error down gradually.
+
+Suppose we have a clustering of \f$n\f$ partitions with errors \f$ \{E_k\}_{k=1\cdots n} \f$, and we want \f$m\f$ more proxies, the package provides 3 different seeding methods:
+- <b>Random</b>. \f$m\f$ seed facets are picked randomly on the surface.
+- <b>Incremental</b>. Each new proxy is initialized from a facet of the worse region matching the largest approximation error. The facet itself is chosen as the one realizing the largest error in its region.
+- <b>Hierarchical</b>. \f$m\f$ seed facets are dispatched within the current partition, where each partition is refined with a number of proxies chosen in accordance to their fitting error:
+  - calculate total error \f$ E_{total} \f$, then average error \f$ E_{avg} = E_{total} / m \f$ (hoping that each new proxy shares the same amount of error)
+  - sort errors \f$ \{E_{min},\cdots,E_{max}\} \f$
+  - from \f$ E_{min} \f$ to \f$ E_{max} \f$, we diffuse the error <em>hierarchically</em> one after another. More specifically, the number of proxies added to the \f$k\f$th region is proportional to its error given by the formula:
+\f[ nb\_to\_add\_k = rounded\_to\_nearest\_integer(E_k / E_{avg}), \f]
+and the remaining error is added to the next proxy error in order to keep the total error unchanged:
+\f[ E'_{k+1} = (E_k - nb\_to\_add\_k * E_{avg}) + E_{k+1}. \f]
+
+\cgalFigureBegin{seeding_method, seeding_method.png}
+Comparison of seeding methods on the sphere-cube model. From left to right: initial partition (\f$ \mathcal{L}^{2,1} \f$ metrics and 20 proxies), add 5 proxy seeds (red facets) with random, incremental and hierarchical methods respectively.
+\cgalFigureEnd
+
+Figure \cgalFigureRef{seeding_method} depicts the effect of different seeding methods. Random initialization randomly selects a set of input triangle facets as proxy seeds. It is very fast but the subsequent clustering process can be entrapped in local minima, especially on shapes with regions surrounded by sharp creases (left rectangle). Incremental initialization adds the proxies one by one at the most distorted region, interleaved with several inner iterations of clustering. It can thus be slow due to the interleaving with the clustering process. Hierarchical initialization adds proxies in a hierarchical refinement sequence, so as the generate clustering refions with more evenly distributed fitting errors. Time consumption is somewhere in-between the former two. Some statistics and comparisons are available in \ref sma_perf.
+
+\subsubsection sma_stop Stop Criteria
+
+To determine when to stop adding more proxies, we can specify either the maximum number of proxies required to approximate the geometry or the minimum error drop percentage with respect to the very first partition. More specifically, we can decide:
+- <b>Maximum number of proxies</b>. Adding proxies until the specified target number is met.
+- <b>Minimum error drop</b>. Starting from the proxy fitted from the first facet of the surface with the fitting error \f$ \hat E \f$, the algorithm adds proxies until the approximation error drops below the specified percentage \f$ target\_drop * \hat E \f$.
 
 \cgalFigureBegin{nb_proxies, nb_proxies.png}
 Using different number of proxies to approximate the plane-sphere model. From left to right: 8, 14, 20 proxies. On the right most is the number_of_proxies to error curve.
 \cgalFigureEnd
 
-In figure \cgalFigureRef{nb_proxies}, if we specify the minimum error drop to 10% (yellow dash lines), we will end up with 12 proxies on the plane-sphere model. Different initialization examples are provided in \cgalFigureRef{meshing}.
-
-\subsection sma_seeding Seeding
-
-Seeding is used to decide how to insert a new proxy. 
-Each proxy is always associated with a <em>seed</em> triangle facet in the input surface mesh. 
-While the proxies may be viewed as centers (or best representative) in a geometric error sense, the seed of each proxy is used as the topological start point in the partition process. When we want to add more proxies to drive the approximation error down, we must specify facets of the input surface mesh as seeds to initialize the proxy parameters.
-
-The package provides 3 different seeding methods:
-- <b>Random</b>. The proxy seeds are picked randomly on the surface mesh.
-- <b>Incremental</b>. Each new proxy is initialized from a facet of the worse region matching the largest approximation error. The facet itself is chosen as the one realizing the largest error in its region.
-- <b>Hierarchical</b>. The requested number of proxies are dispatched within the current partition, where each region is refined with a number of proxies chosen in accordance to their fitting error. 
-
-(TODO: precise formula used and justify)
-
-\cgalFigureBegin{seeding_method, seeding_method.png}
-Comparison of different seeding methods on the sphere-cube model. From left to right: initial partition (\f$ \mathcal{L}^{2,1} \f$ metrics and 20 proxies), add 5 proxy seeds (red facets) with random, incremental hierarchical methods respectively.
-\cgalFigureEnd
-
-Figure \cgalFigureRef{seeding_method} depicts the effect of different seeding methods to initialize the algorithm with 20 proxies. Random initialization randomly selects a set of input triangle facets as proxy seeds. It is very fast but the subsequent clustering process can be entrapped in local minima, especially on shapes with regions surrounded by sharp creases (left). Incremental initialization adds the proxies one by one at the most distorted region, interleaved with several inner iterations of clustering. It can thus be slow due to the interleaving with the clustering process. Hierarchical initialization adds proxies in a hierarchical refinement sequence, so as the generate clustering refions with more evenly distributed fitting errors. Time consumption is somewhere in-between the former two. Some statistics and comparisons are available in \ref sma_perf.
+In figure \cgalFigureRef{nb_proxies}, if we specify the minimum error drop to 10% (yellow dash lines), we will end up with 12 proxies on the plane-sphere model. If both are provided, the first met criterion stops the seeding. Different seeding examples are provided in \cgalFigureRef{meshing}.
 
 \subsection sma_operations Operations