Add new figure for Wasserstein tolerance example (+ minor fixes in user manual)

Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/Optimal_transportation_reconstruction_2.txt

@@ -26,12 +26,25 @@ The output of the reconstruction algorithm is a subset of edges and vertices of
 
 \subsection Optimal_transportation_reconstruction_2Simplest_example Simplest Examples
 
-The following example first generates a set of input points on a square. The points, with no mass attribute, are then passed to the Optimal_transportation_reconstruction_2 object. After initialization, 100 iterations of the reconstruction process are performed. 
+The following example first generates a set of input points on a
+square. The points, with no mass attribute, are then passed to the
+Optimal_transportation_reconstruction_2 object. After initialization,
+100 iterations of the reconstruction process are performed.
 \cgalExample{Optimal_transportation_reconstruction_2/otr2_simplest_example.cpp}
 
-Usually, the number of edges in the output reconstruction (and hence the number of iterations to perform) is not known by the user: in that case, the algorithm can be run with a Wasserstein distance tolerance used as a stop criterion (instead of a number of iterations).
+There is no direct relationship between the target number of edges for
+the output reconstruction and a notion of approximation error. The
+simplification algorithm can thus be stopped via a maximum tolerance
+error homogeneous to a distance. More specifically, the tolerance
+error is specified as the maximum square root of transport cost per
+unit of mass, which is homogeneous to a distance.
 
-Note that the tolerance is given in the sense of the Wasserstein distance (see \ref Optimal_transportation_reconstruction_2Wasserstein). It is _not_ a Hausdorff tolerance: it does not mean that the distance between the input samples and the output polyline is guaranteed to be less than `tolerance`. It means that the square root of transport cost per mass (homogeneous to a distance) is at most `tolerance`. 
+Note that the tolerance is given in the sense of the Wasserstein
+distance (see \ref Optimal_transportation_reconstruction_2Wasserstein). It is _not_ a
+Hausdorff tolerance: it does not mean that the distance between the
+input samples and the output polyline is guaranteed to be less than
+`tolerance`. It means that the square root of transport cost per mass
+(homogeneous to a distance) is at most `tolerance`.
 \cgalExample{Optimal_transportation_reconstruction_2/otr2_simplest_example_with_tolerance.cpp}
 
 \subsection Optimal_transportation_reconstruction_2Output_example Output Examples
@@ -85,19 +98,24 @@ and specify the number of output vertices one wants to keep as illustrated in
   otr2.run_until(20); // perform edge collapse operators until 20 vertices remain.
 \endcode
 
-Finally, calling \link Optimal_transportation_reconstruction_2::run_under_wasserstein_tolerance `run_under_wasserstein_tolerance()` \endlink
-allows the user to run the algorithm based on a distance criterion
-when the number of output edges is not known.
-\code{.cpp}
-otr2.run_under_wasserstein_tolerance(0.1); // perform collapses until no more can be done within tolerance
-\endcode
-
 \cgalFigureBegin{Optimal_Transportation_Curve_Reconstruction_twenty_vertices,twenty_vertices.png}
 Examples of 20-vertex reconstructions from datasets consisting of 2000, 400 
 and 200 input points respectively. These examples illustrate the behavior of
 the algorithm when the input point density decreases. 
 \cgalFigureEnd
 
+Finally, calling \link Optimal_transportation_reconstruction_2::run_under_wasserstein_tolerance `run_under_wasserstein_tolerance()` \endlink
+allows the user to run the algorithm based on a distance criterion
+when the number of output edges is not known as illustrated in
+ \cgalFigureRef{Optimal_Transportation_Curve_Reconstruction_tolerance}.
+\code{.cpp}
+otr2.run_under_wasserstein_tolerance(0.1); // perform collapses until no more can be done within tolerance
+\endcode
+
+\cgalFigureBegin{Optimal_Transportation_Curve_Reconstruction_tolerance,tolerances.png}
+Examples of reconstructions with different Wasserstein tolerance threshold. Top: input point set and reconstruction with a tolerance of 0.005. Bottom: reconstructions with a tolerance of 0.05 and with a tolerance of 0.1.
+\cgalFigureEnd
+
 
 \subsection Optimal_transportation_reconstruction_2Global_relocation Global Point Relocation