Copy-paste official doc

Point_set_processing_3/include/CGAL/OpenGR/compute_registration_transformation.h

@@ -150,15 +150,54 @@ compute_registration_transformation(const PointRange1& range1,    const PointRan
      \cgalParamBegin{normal_map} a model of `ReadablePropertyMap` whose key
      type is the value type of the iterator of `PointRange1` and whose value
      type `geom_traits::Vector_3`.\cgalParamEnd
+
      \cgalParamBegin{number_of_samples} size of the subset of input points used
-     to compute registration.\cgalParamEnd
-     \cgalParamBegin{accuracy} registration accuracy expressed in scene
-     units.\cgalParamEnd
+     to compute registration. Input clouds are sub-sampled prior exploration,
+     to ensure fast computations. Super4PCS has a linear complexity w.r.t. the
+     number of input samples, allowing to use larger values than 4PCS. Simple
+     geometry with large overlap can be matched with only 200 samples. However,
+     with Super4PCS, smaller details can be used during the process by using up
+     to thousands of points. There is no theoretical limit to this parameter,
+     however using too large values leads to very a large congruent set, which
+     requires more time and memory to be explored. Using a large number of
+     samples is recommended when: geometrical details are required to perform
+     the matching, for instance to disambiguate between several similar
+     configurations; the clouds have a very low overlap: using a too sparse
+     sampling can prevent to have samples in the overlapping area, causing the
+     algorithm to fail; the clouds are very noisy, and require a dense
+     sampling. Note that Super4PCS is a global registration algorithm, which
+     finds a good approximate of the rigid transformation aligning too
+     clouds. Increasing the number of samples in order to get a fine
+     registration is not optimal: it is usually faster to use less samples, and
+     refine the transformation using a local algorithm, like the ICP, or its
+     variant SparseICP.\cgalParamEnd
+
+     \cgalParamBegin{accuracy} registration accuracy (delta in the
+     paper). Setting a small value means that the two clouds needs to be very
+     close to be considered as well aligned. It is expressed in scene units. A
+     simple way to understand its impact is to consider the computation of the
+     Largest Common Pointset (LCP), the metric used to verify how much the
+     clouds are aligned. For each transformation matrix produced by Super4PCS,
+     we compute the LCP measure by considering a shell around the reference
+     cloud, and count the % of points of the target cloud lying in the
+     shell. The thickness of the shell is defined by the parameter
+     delta.\cgalParamEnd
+
      \cgalParamBegin{overlap} ratio of expected overlap between the two point
-     sets (between 0 for no overlap to 1 for a full overlap).\cgalParamEnd
-     \cgalParamBegin{maximum_running_time} number of seconds after which the
-     algorithm is forced to stop and returns the best solution found so
-     far.\cgalParamEnd
+     sets: it is ranging between 0 (no overlap) to 1 (100% overlap). The
+     overlap parameter controls the size of the basis used for
+     registration. Usually, the larger the overlap, the faster the
+     algorithm. When the overlap is unknown, a simple way to set this parameter
+     is to start from 100% overlap, and decrease the value until obtaining a
+     good result. Using too small values will slow down the algorithm, and
+     reduce the accuracy of the result.\cgalParamEnd
+
+     \cgalParamBegin{maximum_running_time} maximum number of seconds after
+     which the algorithm stops. Super4PCS explores the transformation space to
+     align the two input clouds. Since the exploration is performed randomly,
+     it is recommended to use a large time value to explore the whole space
+     (e.g., 1000).\cgalParamEnd
+
      \cgalParamBegin{geom_traits} an instance of a geometric traits class,
      model of `Kernel`\cgalParamEnd
    \cgalNamedParamsEnd

Point_set_processing_3/include/CGAL/OpenGR/register_point_sets.h

@@ -78,7 +78,7 @@ register_point_sets(const PointRange1& range1,    PointRange2& range2,
    applies it.
 
    Registration is computed using the Super4PCS algorithm
-   \cgalCite{cgal:mam-sffgp-14}.
+   \cgalCite{cgal:mam-sffgp-14}. Parameters documentation is copy-pasted from [the official documentation of OpenCR](https://storm-irit.github.io/OpenGR/a00012.html). For more details on this method, please refer to it.
 
    \note This function requires the \ref thirdpartyOpenGR library.
 
@@ -99,15 +99,54 @@ register_point_sets(const PointRange1& range1,    PointRange2& range2,
      \cgalParamBegin{normal_map} a model of `ReadablePropertyMap` whose key
      type is the value type of the iterator of `PointRange1` and whose value
      type `geom_traits::Vector_3`.\cgalParamEnd
+
      \cgalParamBegin{number_of_samples} size of the subset of input points used
-     to compute registration.\cgalParamEnd
-     \cgalParamBegin{accuracy} registration accuracy expressed in scene
-     units.\cgalParamEnd
+     to compute registration. Input clouds are sub-sampled prior exploration,
+     to ensure fast computations. Super4PCS has a linear complexity w.r.t. the
+     number of input samples, allowing to use larger values than 4PCS. Simple
+     geometry with large overlap can be matched with only 200 samples. However,
+     with Super4PCS, smaller details can be used during the process by using up
+     to thousands of points. There is no theoretical limit to this parameter,
+     however using too large values leads to very a large congruent set, which
+     requires more time and memory to be explored. Using a large number of
+     samples is recommended when: geometrical details are required to perform
+     the matching, for instance to disambiguate between several similar
+     configurations; the clouds have a very low overlap: using a too sparse
+     sampling can prevent to have samples in the overlapping area, causing the
+     algorithm to fail; the clouds are very noisy, and require a dense
+     sampling. Note that Super4PCS is a global registration algorithm, which
+     finds a good approximate of the rigid transformation aligning too
+     clouds. Increasing the number of samples in order to get a fine
+     registration is not optimal: it is usually faster to use less samples, and
+     refine the transformation using a local algorithm, like the ICP, or its
+     variant SparseICP.\cgalParamEnd
+
+     \cgalParamBegin{accuracy} registration accuracy (delta in the
+     paper). Setting a small value means that the two clouds needs to be very
+     close to be considered as well aligned. It is expressed in scene units. A
+     simple way to understand its impact is to consider the computation of the
+     Largest Common Pointset (LCP), the metric used to verify how much the
+     clouds are aligned. For each transformation matrix produced by Super4PCS,
+     we compute the LCP measure by considering a shell around the reference
+     cloud, and count the % of points of the target cloud lying in the
+     shell. The thickness of the shell is defined by the parameter
+     delta.\cgalParamEnd
+
      \cgalParamBegin{overlap} ratio of expected overlap between the two point
-     sets (between 0 for no overlap to 1 for a full overlap).\cgalParamEnd
-     \cgalParamBegin{maximum_running_time} number of seconds after which the
-     algorithm is forced to stop and returns the best solution found so
-     far.\cgalParamEnd
+     sets: it is ranging between 0 (no overlap) to 1 (100% overlap). The
+     overlap parameter controls the size of the basis used for
+     registration. Usually, the larger the overlap, the faster the
+     algorithm. When the overlap is unknown, a simple way to set this parameter
+     is to start from 100% overlap, and decrease the value until obtaining a
+     good result. Using too small values will slow down the algorithm, and
+     reduce the accuracy of the result.\cgalParamEnd
+
+     \cgalParamBegin{maximum_running_time} maximum number of seconds after
+     which the algorithm stops. Super4PCS explores the transformation space to
+     align the two input clouds. Since the exploration is performed randomly,
+     it is recommended to use a large time value to explore the whole space
+     (e.g., 1000).\cgalParamEnd
+
      \cgalParamBegin{geom_traits} an instance of a geometric traits class,
      model of `Kernel`\cgalParamEnd
    \cgalNamedParamsEnd