From bb13a0e7ef8b3b656e6522dfc75a72490e92d5df Mon Sep 17 00:00:00 2001
From: Simon Giraudot <simon.giraudot@geometryfactory.com>
Date: Tue, 19 Dec 2017 14:25:42 +0100
Subject: [PATCH] Add new figure for Wasserstein tolerance example (+ minor
 fixes in user manual)

---
 ...ptimal_transportation_reconstruction_2.txt |  38 +++++++++++++-----
 .../fig/tolerances.png                        | Bin 0 -> 9173 bytes
 2 files changed, 28 insertions(+), 10 deletions(-)
 create mode 100644 Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/fig/tolerances.png

diff --git a/Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/Optimal_transportation_reconstruction_2.txt b/Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/Optimal_transportation_reconstruction_2.txt
index e6fd1102c3a..f2c140be609 100644
--- a/Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/Optimal_transportation_reconstruction_2.txt
+++ b/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
 
diff --git a/Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/fig/tolerances.png b/Optimal_transportation_reconstruction_2/doc/Optimal_transportation_reconstruction_2/fig/tolerances.png
new file mode 100644
index 0000000000000000000000000000000000000000..b9123f15b05a819f8129d51409d7d3c9e360a62d
GIT binary patch
literal 9173
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
Ya(pqQK|8iQY`0*jD{Cv&D7+2-U%`^JCjbBd

literal 0
HcmV?d00001