massaging doc (other shapes) - unfinished

Point_set_shape_detection_3/doc/Point_set_shape_detection_3/Doxyfile.in

@@ -1,6 +1,6 @@
 @INCLUDE = ${CGAL_DOC_PACKAGE_DEFAULTS}
 
-PROJECT_NAME                       =  "CGAL ${CGAL_CREATED_VERSION_NUM} - Point Set Shape Detection"
+PROJECT_NAME               =  "CGAL ${CGAL_CREATED_VERSION_NUM} - Point Set Shape Detection"
 
 INPUT                      =  ${CMAKE_SOURCE_DIR}/Point_set_shape_detection_3/doc/Point_set_shape_detection_3/ \ 
                               ${CMAKE_SOURCE_DIR}/Point_set_shape_detection_3/include

Point_set_shape_detection_3/doc/Point_set_shape_detection_3/PackageDescription.txt

@@ -1,4 +1,4 @@
-/// \defgroup PkgPointSetShapeDetection3 Point Set Shape Detection Reference
+/// \defgroup PkgPointSetShapeDetection3 Point Set Shape Detection Reference
 /*!
 \addtogroup PkgPointSetShapeDetection3
 
@@ -7,7 +7,7 @@
 
 \cgalPkgSummaryBegin
 \cgalPkgAuthors{Sven Oesau, Yannick Verdie, Clément Jamin, Pierre Alliez}
-\cgalPkgDesc{This component implements an efficient RANSAC-based primitive shape detection algorithm for point sets with unoriented normals. The types of shapes covered are plane, sphere, cylinder, cone and torus.}
+\cgalPkgDesc{This component implements an efficient RANSAC-based primitive shape detection algorithm for point sets with unoriented normals. Five types of primitive shapes are detected: plane, sphere, cylinder, cone and torus. Other types of shapes can be detected via implementing a class deriving from the base class.}
 \cgalPkgManuals{Chapter_Point Set Shape Detection, PkgPointSetShapeDetection3}
 \cgalPkgSummaryEnd
 

Point_set_shape_detection_3/doc/Point_set_shape_detection_3/Shape_detection_3.txt

@@ -10,10 +10,10 @@ namespace CGAL {
 
 \section Point_set_shape_detection_3Introduction Introduction
 
-This \cgal component implements the Efficient RANSAC method for primitive shape detection contributed by Schnabel et al. in 2007 \cite cgal:-erpcsd-07. From an unstructured point set with unoriented normals the algorithm detects a set of primitive shapes (see \cgalFigureRef{Point_set_shape_detection_3_overview}). The supported shapes are plane, sphere, cylinder, cone and torus.
+This \cgal component implements the Efficient RANSAC method for primitive shape detection contributed by Schnabel et al. \cite cgal:-erpcsd-07. From an unstructured point set with unoriented normals the algorithm detects a set of primitive shapes (see \cgalFigureRef{Point_set_shape_detection_3_overview}). Five types of shapes are detected: plane, sphere, cylinder, cone and torus. Other types can be detected through implementing a class derived from a base shape.
 
 \cgalFigureBegin{Point_set_shape_detection_3_overview,overview2.png}
-(a) Input point set. (b) Point set with one color per detected primitive. 
+(a) Input point set. (b) Point set depicted with one color per detected shape. 
 \cgalFigureEnd
 
 \section Point_set_shape_detection_3Method Method
@@ -76,18 +76,18 @@ This example illustrates how to access the points assigned to each shape and com
 
 \cgalExample{Point_set_shape_detection_3/shape_detection_3_point_access.cpp}
 
-\section Point_set_shape_detection_3Arbitrary_shapes Arbitrary shapes
+\section Point_set_shape_detection_3Arbitrary_shapes Other shapes
 
-The detection can be extended to own shape types by implementing the interface `Shape_base`. The RANSAC mechanism is efficient for shape types with a low degree of freedom. With other words, shape types that require only few minimal samples to be uniquely defined. This component aims at identifying the largest shape, i.e. the most accurate shape, within the input data. This is determined by the combinatorial choice: choose n minimal samples from N input points, which increases quickly with an increasing number of minimal samples.
+Other shapes can be detected by implementing a shape class derived from the class `Shape_base` and registering it to the shape detection factory. This class must provide the following functions: construct a shape from a small set of given points, compute the squared distance from a query point and the shape and compute the normal deviation between a query point with normal and the normal to the shape at the closest point from the query. The used shape parameters are added as members to the derived class.
 
-For providing an own shape type one has to provide functionality to extract shape parameters from a minimal set of points, to calculate the squared distance between a given point and the shape and to calculate the normal deviation to the shape normal for a point normal pair located close to the shape. The used shape parameters are added as members to the derived class.
+Note however that the RANSAC approach is efficient for shapes that are uniquely defined by a small number of points, denoted by the number of required samples. The algorithm aims at detected the largest shape via many random samples, and the combinatorial complexity of possible samples increases rapidly with the number of points required to define a shape.
 
-The exact functions to be implemented are defined in the interface `Shape_base`:
-- `Shape_base::required_samples``()` const: Provides the minimal number of required samples.
+More specifically, the functions to be implemented are defined in the interface `Shape_base`:
+- `Shape_base::required_samples``()` const: Returns the minimal number of required samples.
 
-- `Shape_base::create_shape``(const std::vector<size_t> &indices)`: The drawn samples are provided via a vector of indices. `Shape_base::get_point``(size_t i)` and `Shape_base::get_normal``(size_t i)` are used to retrieve the actual points and normals (see example below). The provided number of samples might actually be larger than the set minimal number of required samples, depending on the other sought after shape types. If the provided samples are not sufficient for extracting shape parameters, e.g. in a singular case, the m_isValid variable is set to false, in case of success it is set to true.
+- `Shape_base::create_shape``(const std::vector<size_t> &indices)`: The randomly generated samples are provided via a vector of indices. `Shape_base::get_point``(size_t i)` and `Shape_base::get_normal``(size_t i)` are used to retrieve the actual points and normals (see example below). The provided number of samples might actually be larger than the set minimal number of required samples, depending on the other types of shape types. If the provided samples are not sufficient for define a unique shape, e.g., in a degenerated case, the variable m_is_valid is set to false, in case of success it is set to true.
 
-- `Shape_base::squared_distance``(const Point &p)` const: This function provides the squared distance of a point to the shape. It is used for traversing a spatial data structure.
+- `Shape_base::squared_distance``(const Point &p)` const: This function computes the squared distance from a query point to the shape. It is used for traversing a spatial data structure.
 - `Shape_base::squared_distance``(std::vector<FT> &dists, const std::vector<size_t> &indices)`
 - `Shape_base::cos_to_normal``(std::vector<FT> &angles, const std::vector<size_t> &indices)` const:
 These functions are used to determine the supporting points to the shape and provide the squared distance and the dot product between shape normal and point normal for point and normal pairs located close to the shape surface. The access to the actual point and normal data is carried out via `Shape_base::get_point``(size_t i)` and `Shape_base::get_normal``(size_t i)` (see example below). The resulting squared distance/dot product is stored in the vector provided as the first argument.
@@ -95,11 +95,11 @@ These functions are used to determine the supporting points to the shape and pro
 Optionally, the user can provide an implementation for the connected component determination:
 - `Shape_base::connected_component``(FT cluster_epsilon)`: The indices of all supporting points are stored in the vector `m_indices`. All points not belonging to the largest cluster of points have to be removed from the vector `m_indices`. If this method is not overwritten a fallback solution is applied using a kd-tree to organize the support and performing a region growing to determine the largest cluster of points. The main reason to implement an own shape specific solution would be to lower computational time.
 
-Another optional method can be implemented to provide a helper function provinding the shape parameters written to a string:
-- `Shape_base::info``()`: This function returns a string suitable for printing the shape parameters into a log/console. The default solution just provides an empty string.
+Another optional method can be implemented to provide a helper function providing the shape parameters written to a string:
+- `Shape_base::info``()`: This function returns a string suitable for printing the shape parameters into a log/console. The default solution provides an empty string.
 
 The property maps are used to map the indices to the corresponding points and normals. The following example shows a simple implementation of a planar shape primitive.
-\cgalExample{Point_set_shape_detection_3/shape_detection_3_minimal_planar_shape.h}
+\cgalExample{Point_set_shape_detection_3/shape_detection_3_custom_shape.h}
 
 \section Point_set_shape_detection_3Performance Performance
  

Point_set_shape_detection_3/doc/Point_set_shape_detection_3/examples.txt

@@ -2,4 +2,5 @@
 \example Point_set_shape_detection_3/shape_detection_3_basic.cpp
 \example Point_set_shape_detection_3/shape_detection_3_parameters.cpp
 \example Point_set_shape_detection_3/shape_detection_3_point_access.cpp
+\example Point_set_shape_detection_3/shape_detection_3_custom_shape.cpp
 */

Point_set_shape_detection_3/examples/Point_set_shape_detection_3/shape_detection_3_basic.cpp

@@ -19,7 +19,7 @@ typedef CGAL::Normal_of_point_with_normal_pmap<Kernel>      Normal_pmap;
 // In Shape_detection_traits_3 the basic types, i.e., Point and Vector types
 // as well as iterator type and property maps, are defined.
 typedef CGAL::Shape_detection_traits_3<Kernel,
-  Pwn_vector::iterator, Point_pmap, Normal_pmap>              Traits;
+  Pwn_vector::iterator, Point_pmap, Normal_pmap>            Traits;
 typedef CGAL::Shape_detection_3<Traits>                     Shape_detection;
 
 

Point_set_shape_detection_3/examples/Point_set_shape_detection_3/shape_detection_3_point_access.cpp

@@ -27,7 +27,7 @@ typedef CGAL::Normal_of_point_with_normal_pmap<Kernel>      Normal_pmap;
 // as well as iterator type and property maps, are defined.
 typedef CGAL::Shape_detection_traits_3<Kernel,
   Pwn_vector::iterator, Point_pmap, Normal_pmap>            Traits;
-typedef CGAL::Shape_detection_3<Traits>                   Shape_detection;
+typedef CGAL::Shape_detection_3<Traits>                     Shape_detection;
 
 
 int main()