Merge pull request #1240 from kerautret/MoveExample

Move examples in source file

ChangeLog.md

@@ -27,7 +27,12 @@
  - *Configuration/General*
   - Continuous integration Travis bots are now based on ubunutu/trusty containers.
     (David Coeurjolly, [#1227](https://github.com/DGtal-team/DGtal/pull/1208))
-
+
+ - *Documentation*
+  - All the example descriptions are now in their the examples file (instead in
+    dox files).
+    (Bertrand Kerautret, #1240](https://github.com/DGtal-team/DGtal/pull/1240)
+
 ## Bug Fixes
 
 - *Configuration/General*

examples/arithmetic/approximation.cpp

@@ -10,6 +10,40 @@
  *
  * This file is part of the DGtal library.
  */
+/**
+   Computes a fraction from a floating-point number
+
+@see \ref dgtal_irrfrac_sec3_8
+
+@verbatim
+$ ./examples/arithmetic/approximation 1.33333333333333
+z = 1 / 1 =~ 1
+z = 4 / 3 =~ 1.333333333333333
+z = 4 / 3
+
+$./examples/arithmetic/approximation 1.33333333333338
+z = 1 / 1 =~ 1
+z = 3 / 2 =~ 1.5
+z = 4 / 3 =~ 1.333333333333333
+z = 9523805234895 / 7142853926171 =~ 1.33333333333338
+z = 9523805234895 / 7142853926171
+
+$ ./examples/arithmetic/approximation 3.141592654 
+z = 3 / 1 =~ 3
+z = 22 / 7 =~ 3.142857142857143
+z = 333 / 106 =~ 3.141509433962264
+z = 355 / 113 =~ 3.141592920353982
+z = 104348 / 33215 =~ 3.141592653921421
+z = 1148183 / 365478 =~ 3.141592654003798
+z = 1252531 / 398693 =~ 3.141592653996935
+z = 2400714 / 764171 =~ 3.141592654000217
+z = 18057529 / 5747890 =~ 3.14159265399999
+z = 38515772 / 12259951 =~ 3.141592654000004
+z = 38515772 / 12259951
+@endverbatim
+
+\example arithmetic/approximation.cpp
+*/
 
 ///////////////////////////////////////////////////////////////////////////////
 //! [approximation-basicIncludes]

examples/arithmetic/convergents-biginteger.cpp

@@ -10,6 +10,32 @@
  *
  * This file is part of the DGtal library.
  */
+/**
+
+   Computes the quotients and the convergents of a given fraction,
+   which may be arbitrarily large.
+
+@see \ref dgtal_irrfrac_sec3_2
+
+@verbatim
+# A huge fraction
+$ ./examples/arithmetic/convergents-biginteger 243224233245235253407096734543059 4324213412343432913758138673203834
+z = [0,17,1,3,1,1,12,1,2,33,2,1,1,1,1,49,1,1,1,1,17,34,1,1,304,1,2,1,1,1,2,1,48,1,20,2,3,5,1,1,16,9,1,1,5,1,2,2,7,4,3,1,7,1,1,17,1,1,29,1,12,2,5]
+z_0 = 0 / 1
+z_1 = 1 / 17
+z_2 = 1 / 18
+z_3 = 4 / 71
+z_4 = 5 / 89
+...
+z_18 = 23610961 / 419772458
+...
+z_40 = 832739221613445323225 / 14805030169237188131024
+...
+z_62 = 243224233245235253407096734543059 / 4324213412343432913758138673203834
+@endverbatim
+
+\example arithmetic/convergents-biginteger.cpp
+*/
 
 ///////////////////////////////////////////////////////////////////////////////
 //! [convergents-biginteger-basicIncludes]

examples/arithmetic/convergents.cpp

@@ -11,6 +11,26 @@
  * This file is part of the DGtal library.
  */
 
+/**
+   Computes the quotients and the convergents of a given fraction.
+
+@see \ref dgtal_irrfrac_sec3_2
+
+@verbatim
+# Approximations of pi
+$ ./examples/arithmetic/convergents 103993 33102
+z = [3,7,15,1,292]
+z_0 = 3 / 1
+z_1 = 22 / 7
+z_2 = 333 / 106
+z_3 = 355 / 113
+z_4 = 103993 / 33102
+@endverbatim
+
+\example arithmetic/convergents.cpp
+*/
+
+
 ///////////////////////////////////////////////////////////////////////////////
 //! [convergents-basicIncludes]
 #include <iostream>

examples/arithmetic/extended-euclid.cpp

@@ -11,6 +11,23 @@
  * This file is part of the DGtal library.
  */
 
+/**
+   Computes a solution to the diophantine equation \f$ ax+by=c \f$, where the
+   integers \a a, \a b, \a c are given and \a x, \a y are the unknowns
+   (integers). Note that \a c must be a multiple of gcd( \a a, \a b ).
+
+@see \ref dgtal_integer_computations_sec2
+
+@verbatim
+$ ./examples/arithmetic/extended-euclid 5 7 1
+x=3 y=-2
+$ ./examples/arithmetic/extended-euclid 12 32 4
+x=3 y=-1
+@endverbatim
+
+\example arithmetic/extended-euclid.cpp
+*/
+
 ///////////////////////////////////////////////////////////////////////////////
 //! [extended-euclid-basicIncludes]
 #include <cstdlib>

examples/arithmetic/fraction.cpp

@@ -11,6 +11,20 @@
  * This file is part of the DGtal library.
  */
 
+/**
+   Computes a fraction from its quotients.
+
+@see \ref dgtal_irrfrac_sec3_4
+
+@verbatim
+# More precise approximation of pi
+$ ./examples/arithmetic/fraction 3 7 15 1 292 1 1 1 2 1 3 1 14
+z = 80143857 / 25510582
+@endverbatim
+
+\example arithmetic/fraction.cpp
+*/
+
 ///////////////////////////////////////////////////////////////////////////////
 //! [fraction-basicIncludes]
 #include <iostream>

examples/arithmetic/lower-integer-convex-hull.cpp

@@ -10,6 +10,34 @@
  *
  * This file is part of the DGtal library.
  */
+/**
+   This example shows how to create a LatticePolytope2D that
+   represents a square. Then given integer parameters \a a, \a b, \a
+   c, it cuts the polygon by the half-plane \f$ ax+by \le c \f$. It
+   also outputs some statistics.
+
+@see \ref dgtal_lattice_polytope_2d_sec6
+
+@verbatim
+$ ./examples/arithmetic/lower-integer-convex-hull -5 8 41
+Number of vertices        = 8
+Area                      = 299.5
+Number of interior points = 273
+Number of boundary points = 55
+# The animation below was created by this script (needs ImageMagick)
+$ let x=130; while test $x -ge -130; do echo "--- $x ---"; ./examples/arithmetic/lower-integer-convex-hull -5 8 $x; let z=x+130; y=`printf "%03d" $z`; convert -resize 300x300 -background white -layers flatten lower-integer-convex-hull-cut.eps lower-integer-convex-hull-$y.gif; let x=x-2; done
+...
+$ convert -delay 20 -loop 0 lower-integer-convex-hull-*.gif lower-animation.gif
+$ animate lower-animation.gif 
+@endverbatim
+
+@image html lower-integer-convex-hull-cut-2.png "Square of side 20 cut by the half-plane -5x+8y <= 41"
+@image latex lower-integer-convex-hull-cut-2.png "Square of side 20 cut by the half-plane -5x+8y <= 41" width=5cm
+
+@image html lower-animation.gif "Square cut by the half space -5x+8y <= c, for c from -130 to 130"
+
+\example arithmetic/lower-integer-convex-hull.cpp
+*/
 
 ///////////////////////////////////////////////////////////////////////////////
 //! [lower-integer-convex-hull-basicIncludes]

examples/arithmetic/pattern.cpp

@@ -11,6 +11,24 @@
  * This file is part of the DGtal library.
  */
 
+/**
+   Computes a pattern from a given slope p / q.
+
+@see \ref dgtal_digstraighness_sec2
+
+@verbatim
+# Pattern 5 / 12
+$ ./examples/arithmetic/pattern 5 12
+00010010001001001
+
+# Pattern 5 / 12 with its recursive subdivision
+$ ./examples/arithmetic/pattern 5 12 SUB
+((0|(00|1)(00|1))(0|(00|1)(00|1))|(00|1))
+@endverbatim
+
+\example arithmetic/pattern.cpp
+*/
+
 ///////////////////////////////////////////////////////////////////////////////
 //! [pattern-basicIncludes]
 #include <cstdlib>

examples/dec/exampleDECSurface.cpp

@@ -1,4 +1,10 @@
 /// @file dec/exampleDECSurface.cpp
+/**
+   Example of solving Poisson equation using the DEC package.
+    @see \ref sectDECPoissonProblem
+   \image html alcapone_phi.png "Solution dual 0-form."
+   \example dec/exampleDECSurface.cpp
+**/
 #include "DGtal/io/readers/VolReader.h"
 #include "DGtal/io/viewers/Viewer3D.h"
 #include "DGtal/topology/SurfelAdjacency.h"

examples/dec/exampleDiscreteExteriorCalculusChladni.cpp

@@ -1,4 +1,11 @@
 /// @file dec/exampleDiscreteExteriorCalculusChladni.cpp
+/**
+   Example of Discrete Exterior Calculus with Chladni.
+   @see \ref sectDECHelmoltzProblem
+   \image  html  exampleDECChladni.png "Primal Helmoltz decomposition harmonic component."
+   \example dec/exampleDiscreteExteriorCalculusChladni.cpp
+**/
+
 #include <sstream>
 #include <string>
 

examples/dec/exampleDiscreteExteriorCalculusSolve.cpp

@@ -1,4 +1,11 @@
 /// @file dec/exampleDiscreteExteriorCalculusSolve.cpp
+/**
+   Example of primal and dual Helmoltz decomposition in 2D and 3D using Discrete Exterior Calculus.
+   @see \ref sectDECHelmoltzProblem
+   \image  html  solve_2d_primal_decomposition_calculusSmall.png "Primal Helmoltz decomposition harmonic component."
+   \example dec/exampleDiscreteExteriorCalculusSolve.cpp
+**/
+
 #include <string>
 
 #include <QApplication>

examples/dec/exampleDiscreteExteriorCalculusUsage.cpp

@@ -1,4 +1,10 @@
 /// @file dec/exampleDiscreteExteriorCalculusUsage.cpp
+/**
+   Example of vector field manipulation using Discrete Exterior Calculus.
+   @see \ref sectDECIntroduction
+   \image html usage_primal_one_form_sharp_flat.png "Flat sharped primal gradient vector field."
+   \example dec/exampleDiscreteExteriorCalculusUsage.cpp
+**/
 #include <string>
 
 #include "DECExamplesCommon.h"

examples/dec/examplePropagation.cpp

@@ -1,8 +1,13 @@
 /// @file dec/examplePropagation.cpp
-#include <iomanip>
+/**
+   Example of 2D wave propagation using the DEC package.
+    @see \ref moduleDECPropagation
+   \image html  propagation_time_wave_ii.gif  "You should obtain such wave propagation (by converting svg files)."
+   \example dec/examplePropagation.cpp
+**/
 
+#include <iomanip>
 #include "DECExamplesCommon.h"
-
 #include "DGtal/math/linalg/EigenSupport.h"
 #include "DGtal/dec/DiscreteExteriorCalculus.h"
 #include "DGtal/dec/DiscreteExteriorCalculusSolver.h"

examples/doc-examples/demo-kernel-1.cpp

@@ -26,6 +26,12 @@
  * This file is part of the DGtal library.
  */
 
+/**
+ * Example of DGtal kernel and export with Board2D.
+ *  \image html exampleDemoKernel-1.png "Display 2D points in its domain and export woth Board2D."
+ *  \example doc-examples/demo-kernel-1.cpp
+ */
+
 ///////////////////////////////////////////////////////////////////////////////
 #include <iostream>
 #include "DGtal/base/Common.h"

examples/doc-examples/exampleCatch.cpp

@@ -26,6 +26,13 @@
  *
  * This file is part of the DGtal library.
  */
+/**
+DGtal/Catch examples
+
+@see \ref moduleCatch
+
+\example doc-examples/exampleCatch.cpp
+*/
 
 ///////////////////////////////////////////////////////////////////////////////
 #include <iostream>

examples/doc-examples/kernelDomain.cpp

@@ -27,6 +27,16 @@
  * This file is part of the DGtal library.
  */
 
+
+
+/**
+ * Example of DGtal kernel with Domain.
+ * @see \ref sectSpace
+ * \image html kernel-domain-it-arrow.png "Iteration over a domain with displacements depicted as arrows."
+ * \example doc-examples/kernelDomain.cpp
+ */
+
+
 ///////////////////////////////////////////////////////////////////////////////
 #include <iostream>
 #include "DGtal/base/Common.h"

examples/doc-examples/range.cpp

@@ -28,6 +28,15 @@
  * This file is part of the DGtal library.
  */
 
+
+
+/**
+ * Example of range on Domain.
+ *  @see \ref sectSpace
+ *  \example doc-examples/range.cpp
+ */
+
+
 ///////////////////////////////////////////////////////////////////////////////
 #include <iostream>
 #include "DGtal/base/Common.h"

examples/geometry/curves/convex-and-concave-parts.cpp

@@ -25,6 +25,30 @@
  *
  * This file is part of the DGtal library.
  */
+/**
+   This example outputs the cover of an open digital curve by maximal DSSs. 
+Maximal DSSs are displayed in blue, green, yellow in convex, concave, inflexion parts respectively. 
+Ends are black. 
+Convex (resp. concave) parts are defined as sequences of maximal DSSs of increasing (resp. decreasing) slope. 
+
+@verbatim
+$ ./examples/geometry/curves/convex-and-concave-parts
+@endverbatim
+
+Note that the chain code of the input digital curve may be passed as argument as follows: 
+@verbatim
+$ ./examples/geometry/curves/convex-and-concave-parts 0300303303033030303000010101011010110100000303303033030303
+@endverbatim
+
+
+@image html convex-and-concave-parts.png "Decomposition into convex and concave parts"
+@image latex convex-and-concave-parts.png "Decomposition into convex and concave parts"
+
+
+@see \ref moduleArithDSSReco and \ref moduleGridCurveAnalysis
+
+\example geometry/curves/convex-and-concave-parts.cpp
+*/
 
 ///////////////////////////////////////////////////////////////////////////////
 #include <cmath>

examples/geometry/curves/estimation/exampleCurvature.cpp

@@ -27,6 +27,14 @@
  * This file is part of the DGtal library.
  */
 
+
+/**
+   Example of curvature estimation based on Digital Circular Arc (DCA) estimator.
+   \image  html  exampleCurvature.png "Curvature estimated using DCA estimator on a flower shape."
+   \example geometry/curves/estimation/exampleCurvature.cpp
+**/
+
+
 ///////////////////////////////////////////////////////////////////////////////
 #include <iostream>
 #include "DGtal/base/Common.h"