From 0052bf9643d58ce8ea5aa7a0ed432f656d71c695 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= <sebastien.loriot@cgal.org>
Date: Wed, 4 Sep 2013 17:44:12 +0200
Subject: [PATCH] do not document Fast_sdf_calculation_mode

---
 .../Surface_Mesh_Segmentation.txt             |  19 +++-
 .../include/CGAL/mesh_segmentation.h          | 106 +++++++++---------
 2 files changed, 66 insertions(+), 59 deletions(-)

diff --git a/Surface_mesh_segmentation/doc/Surface_mesh_segmentation/Surface_Mesh_Segmentation.txt b/Surface_mesh_segmentation/doc/Surface_mesh_segmentation/Surface_Mesh_Segmentation.txt
index 8785e06dcc5..224f7b876f7 100644
--- a/Surface_mesh_segmentation/doc/Surface_mesh_segmentation/Surface_Mesh_Segmentation.txt
+++ b/Surface_mesh_segmentation/doc/Surface_mesh_segmentation/Surface_Mesh_Segmentation.txt
@@ -141,7 +141,7 @@ On the contrary, assigning smaller values to smoothness parameter results in a h
 (notice that setting \f$ \lambda=0 \f$ provides the result of the soft clustering). See \cgalFigureRef{Segmentation_lambdas} for the effect of different smoothness parameters.
 
 \cgalFigureBegin{Segmentation_lambdas,dino_different_lambda_small.png}
-Influence of the smoothness parameter lambda over the segmentation(using 10 clusters). Smoothness parameters are set to 0.0, 0.1, 0.25, 0.5 and 1.0 respectively. The coloring reflects the segmentation result before assigning each connected component to its own segment.
+Influence of the smoothness parameter lambda over the segmentation (using 10 clusters). Smoothness parameters are set to 0.0, 0.1, 0.25, 0.5 and 1.0 respectively. The coloring reflects the segmentation result before assigning each connected component to its own segment.
 \cgalFigureEnd
 
 The hard clustering assigns a cluster id to each facet (see \cgalFigureRef{Cluster_vs_segment} (a)).
@@ -203,8 +203,17 @@ We provide performance results of `compute_sdf_values()` and `segment_from_sdf_v
 These results are produced with the release 4.X of \cgal, on an Intel i7 3.2 Ghz laptop with 8 GB RAM, compiled by Visual C++ 2010 with /O2 option.
 \todo Update release number as well as first introduced in.
 
-Performance of `compute_sdf_values()` with 25 rays (in seconds):
+Runtime of `compute_sdf_values()` with 25 rays (in seconds) showing the cost of the robustness:
 
+<center>
+Number of triangles  | `%Simple_cartesian<double>` | `%Exact_predicates_inexact_constructions_kernel` (`EPICK`)
+---------------------| -------------------------:  | --------------------------------------------------------:
+  5,558              |  1.6                        |  3.9
+ 34,986              | 13.6                        | 26.2
+100,332              | 48.7                        | 88.1
+</center>
+
+<!-- This is only to keep the results, the flag is not documentated
 <center>
 Number of triangles  | `%Simple_cartesian<double>` | `%Exact_predicates_inexact_constructions_kernel` (`EPICK`) | `EPICK` with `Fast_sdf_calculation_mode = false`
 ---------------------| -------------------------:  | --------------------------------------------------------:  | -----------------------------------------------:
@@ -212,9 +221,9 @@ Number of triangles  | `%Simple_cartesian<double>` | `%Exact_predicates_inexact_
  34,986              | 13.6                        | 26.2                                                       |  63.9
 100,332              | 48.7                        | 88.1                                                       | 169.2
 </center>
+-->
 
-
-Performance of `segment_from_sdf_values()` (in milliseconds):
+Runtime of `segment_from_sdf_values()` (in milliseconds):
 
 <center>
 Number of triangles  | Number of cluster = 2 | Number of cluster = 5 | Number of cluster = 10 | Number of cluster = 15
@@ -236,7 +245,7 @@ Number of triangles  | Number of cluster = 2 | Number of cluster = 5 | Number of
 100,332              |   437                 | 1,042                 |  2,373                 |   3,947
 </center>
 
-<!--
+<!-- Keep this internal for developers
 \section ImplementationDetails Implementation Details
 \subsection RaySamplingInShapeDiameterFunction Ray Sampling in Shape Diameter Function
 \cgalFigureBegin{Segmentation_vogel,vogel_uniform_biased.png}
diff --git a/Surface_mesh_segmentation/include/CGAL/mesh_segmentation.h b/Surface_mesh_segmentation/include/CGAL/mesh_segmentation.h
index a18605eda48..12fc46758ad 100644
--- a/Surface_mesh_segmentation/include/CGAL/mesh_segmentation.h
+++ b/Surface_mesh_segmentation/include/CGAL/mesh_segmentation.h
@@ -12,28 +12,7 @@ namespace CGAL
 {
 
 
-/*!
- * \ingroup PkgSurfaceSegmentation
- * @brief Function computing the Shape Diameter Function over a surface mesh.
- *
- * This function implements the Shape Diameter Function (SDF) as described in \cgalCite{shapira2008consistent}.
- * It is possible to compute raw SDF values (see \ref Surface_mesh_segmentationRawSDF) and apply post-processing steps (see \ref Surface_mesh_segmentationPostprocessing).
- * For raw SDF values, -1.0 is used to indicate that no SDF value could be computed for a facet.
- *
- * @pre @a polyhedron.is_pure_triangle()
- * @tparam Fast_sdf_calculation_mode regardless of `GeomTraits`, use inexact predicates while traversing AABB tree nodes.
- *          It is set by default to true, and can be omitted.
- * @tparam Polyhedron a %CGAL polyhedron
- * @tparam SDFPropertyMap  a `ReadWritePropertyMap` with `Polyhedron::Facet_const_handle` as key and `double` as value type
- * @tparam GeomTraits a model of SegmentationGeomTraits
- * @param polyhedron surface mesh on which SDF values are computed
- * @param[out] sdf_values the SDF value of each facet
- * @param cone_angle opening angle for cone, expressed in radians
- * @param number_of_rays number of rays picked from cone for each facet. In general, increasing the number of rays beyond the default value has little influence upon the resulting segmentation.
- * @param postprocess if true apply post-processing steps in `CGAL::postprocess_sdf_values`, otherwise return raw SDF values.
- * @param traits traits object
- * @return minimum and maximum SDF values if @a postprocess is true, otherwise minimum and maximum SDF values before linear normalization
- */
+/// @cond SKIP_IN_MANUAL
 template <bool Fast_sdf_calculation_mode, class Polyhedron,
          class SDFPropertyMap, class GeomTraits
 #ifndef BOOST_NO_FUNCTION_TEMPLATE_DEFAULT_ARGS
@@ -53,8 +32,28 @@ compute_sdf_values(const Polyhedron& polyhedron,
   return algorithm.calculate_sdf_values(cone_angle, number_of_rays, sdf_values,
                                         postprocess);
 }
+/// @endcond
 
-/// @cond SKIP_IN_MANUAL
+/*!
+ * \ingroup PkgSurfaceSegmentation
+ * @brief Function computing the Shape Diameter Function over a surface mesh.
+ *
+ * This function implements the Shape Diameter Function (SDF) as described in \cgalCite{shapira2008consistent}.
+ * It is possible to compute raw SDF values (see \ref Surface_mesh_segmentationRawSDF) and apply post-processing steps (see \ref Surface_mesh_segmentationPostprocessing).
+ * For raw SDF values, -1.0 is used to indicate that no SDF value could be computed for a facet.
+ *
+ * @pre @a polyhedron.is_pure_triangle()
+ * @tparam Polyhedron a %CGAL polyhedron
+ * @tparam SDFPropertyMap  a `ReadWritePropertyMap` with `Polyhedron::Facet_const_handle` as key and `double` as value type
+ * @tparam GeomTraits a model of SegmentationGeomTraits
+ * @param polyhedron surface mesh on which SDF values are computed
+ * @param[out] sdf_values the SDF value of each facet
+ * @param cone_angle opening angle for cone, expressed in radians
+ * @param number_of_rays number of rays picked from cone for each facet. In general, increasing the number of rays beyond the default value has little influence upon the resulting segmentation.
+ * @param postprocess if true apply post-processing steps in `CGAL::postprocess_sdf_values`, otherwise return raw SDF values.
+ * @param traits traits object
+ * @return minimum and maximum SDF values if @a postprocess is true, otherwise minimum and maximum SDF values before linear normalization
+ */
 template <class Polyhedron, class SDFPropertyMap, class GeomTraits
 #ifndef BOOST_NO_FUNCTION_TEMPLATE_DEFAULT_ARGS
 = typename Polyhedron::Traits
@@ -71,7 +70,7 @@ compute_sdf_values(const Polyhedron& polyhedron,
   return compute_sdf_values<true, Polyhedron, SDFPropertyMap, GeomTraits>
          (polyhedron, sdf_values, cone_angle, number_of_rays, postprocess, traits);
 }
-/// @endcond
+
 
 /*!
  * \ingroup PkgSurfaceSegmentation
@@ -153,34 +152,7 @@ segment_from_sdf_values(const Polyhedron& polyhedron,
                              segment_ids, extract_segments);
 }
 
-
-/*!
- * \ingroup PkgSurfaceSegmentation
- * @brief Function computing the segmentation of a surface mesh.
- *
- * This function combines `CGAL::compute_sdf_values` and
- * `CGAL::segment_from_sdf_values` functions by computing SDF values and segmenting the mesh in one go.
- *
- * \note For computing segmentations of the mesh with different parameters (i.e. number of levels, and smoothing lambda),
- * it is more efficient to first compute the SDF values using `CGAL::compute_sdf_values` and use them for each call to
- * `CGAL::segment_from_sdf_values`.
- *
- * @pre @a polyhedron.is_pure_triangle()
- * @tparam Fast_sdf_calculation_mode regardless of `GeomTraits`, use inexact predicates while traversing AABB tree nodes.
- *          It is set by default to true, and can be omitted.
- * @tparam Polyhedron a %CGAL polyhedron
- * @tparam SegmentPropertyMap a `ReadWritePropertyMap` with `Polyhedron::Facet_const_handle` as key and `int` as value type
- * @tparam GeomTraits a model of SegmentationGeomTraits
- * @param polyhedron surface mesh on which SDF values are computed
- * @param[out] segment_ids the segment id of each facet
- * @param cone_angle opening angle for cone, expressed in radians
- * @param number_of_rays number of rays picked from cone for each facet. In general, increasing the number of rays has a little effect on the quality of the result
- * @param number_of_levels number of clusters for soft clustering
- * @param smoothing_lambda factor which indicates the importance of the surface features for the energy minimization. It is recommended to choose a value in the interval [0,1]. See the section \ref Surface_mesh_segmentationGraphCut for more details.
- * @param extract_segments if true fill @a segment_ids with segment-ids, otherwise fill with cluster-ids \cgalFigureRef{Cluster_vs_segment}
- * @param traits traits object
- * @return number of segments if @a extract_segments true, @a number_of_levels otherwise
- */
+///\cond SKIP_IN_MANUAL
 template < bool Fast_sdf_calculation_mode, class Polyhedron,
          class SegmentPropertyMap, class GeomTraits
 #ifndef BOOST_NO_FUNCTION_TEMPLATE_DEFAULT_ARGS
@@ -209,8 +181,34 @@ compute_sdf_values_and_segment(const Polyhedron& polyhedron,
          (polyhedron, sdf_property_map, segment_ids, number_of_levels, smoothing_lambda,
           extract_segments, traits);
 }
+/// \endcond
 
-/// @cond SKIP_IN_MANUAL
+
+/*!
+ * \ingroup PkgSurfaceSegmentation
+ * @brief Function computing the segmentation of a surface mesh.
+ *
+ * This function combines `CGAL::compute_sdf_values` and
+ * `CGAL::segment_from_sdf_values` functions by computing SDF values and segmenting the mesh in one go.
+ *
+ * \note For computing segmentations of the mesh with different parameters (i.e. number of levels, and smoothing lambda),
+ * it is more efficient to first compute the SDF values using `CGAL::compute_sdf_values` and use them for each call to
+ * `CGAL::segment_from_sdf_values`.
+ *
+ * @pre @a polyhedron.is_pure_triangle()
+ * @tparam Polyhedron a %CGAL polyhedron
+ * @tparam SegmentPropertyMap a `ReadWritePropertyMap` with `Polyhedron::Facet_const_handle` as key and `int` as value type
+ * @tparam GeomTraits a model of SegmentationGeomTraits
+ * @param polyhedron surface mesh on which SDF values are computed
+ * @param[out] segment_ids the segment id of each facet
+ * @param cone_angle opening angle for cone, expressed in radians
+ * @param number_of_rays number of rays picked from cone for each facet. In general, increasing the number of rays has a little effect on the quality of the result
+ * @param number_of_levels number of clusters for soft clustering
+ * @param smoothing_lambda factor which indicates the importance of the surface features for the energy minimization. It is recommended to choose a value in the interval [0,1]. See the section \ref Surface_mesh_segmentationGraphCut for more details.
+ * @param extract_segments if true fill @a segment_ids with segment-ids, otherwise fill with cluster-ids \cgalFigureRef{Cluster_vs_segment}
+ * @param traits traits object
+ * @return number of segments if @a extract_segments true, @a number_of_levels otherwise
+ */
 template < class Polyhedron, class SegmentPropertyMap, class GeomTraits
 #ifndef BOOST_NO_FUNCTION_TEMPLATE_DEFAULT_ARGS
 = typename Polyhedron::Traits
@@ -230,7 +228,7 @@ compute_sdf_values_and_segment(const Polyhedron& polyhedron,
          (polyhedron, segment_ids, cone_angle, number_of_rays, number_of_levels,
           smoothing_lambda, extract_segments, traits);
 }
-/// @endcond
+
 
 #ifdef BOOST_NO_FUNCTION_TEMPLATE_DEFAULT_ARGS
 template <bool Fast_sdf_calculation_mode, class Polyhedron, class SDFPropertyMap>