point set processing: update text in ref manual (parameters)

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/compute_average_spacing.tex

@@ -19,9 +19,7 @@
 
 \ccDefinition
 
-\ccc{CGAL::compute_average_spacing()} computes the average spacing of all points from the input set to their $k$ nearest neighbors.
-
-The average spacing depends on the \ccc{k} parameter. In general, it is set to 1 ring, i.e. 6.
+\ccc{CGAL::compute_average_spacing()} computes the average spacing of all points from the input set to their $k$ nearest neighbors. This value depends on the \ccc{k} parameter which can be set to 6 for isotropically sampled surfaces.
 
 \ccInclude{CGAL/compute_average_spacing.h}
 

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/jet_estimate_normals.tex

@@ -21,11 +21,8 @@
 
 \ccc{CGAL::jet_estimate_normals()} estimates normal directions of all points from the input set by fitting jet surfaces over the $k$ nearest neighbors. The default jet surface is a quadric, and the result is an unoriented normal vector for each input point.
 
-The quality of the normal estimation algorithm highly depends on the \ccc{k} parameter.
-The number of neighbors controls the width of the point subset considered for jet fitting at each input point.
-Larger value leads to smoother surface approximations and better normal estimations. Obviously, it also leads to longer computation times.
-For clean datasets, this value can be set to a few rings, e.g. 18. On the other hand, as the amount of noise increases, this value should be increased as well.
-For these reasons, we do not provide any default value for this parameter.
+The output of the normal estimation algorithm highly depends on the \ccc{k} parameter.
+The number of neighbors controls the size of the point subset considered for jet fitting at each input point. As this parameter is application-specific we do not provide any default value. Larger values lead to smoother normal fields and are more time consuming. For point sets with limited noise this value can be set to small number such as 18. For noisy point sets this value must be increased.
 
 \ccInclude{CGAL/jet_estimate_normals.h}
 

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/jet_smooth_point_set.tex

@@ -21,11 +21,9 @@
 
 \ccc{CGAL::jet_smooth_point_set()} smooths a point set by fitting for each point a jet surface and projecting it onto the jet. The default jet surface is a quadric.
 
-The quality of the smoothing algorithm highly depends on the \ccc{k} parameter.
-The number of neighbors controls the width of the point subset considered for jet fitting at each input point.
-Larger value leads to smoother surfaces and longer computation times.
-For datasets with limited noise, this value can be set to a few rings, e.g. 24. On the other hand, as the amount of noise increases, this value should be increased as well.
-For these reasons, we do not provide any default value for this parameter.
+The output of the smoothing algorithm highly depends on the \ccc{k} parameter.
+The number of neighbors controls the size of the point subset considered for jet fitting at each input point. As this parameter is application-specific we do not provide any default value. Larger values lead to smoother point sets and are more time consuming. For point sets with limited noise this value can be set to small number such as 24. For noisy point sets this value must be increased.
+
 
 \ccInclude{CGAL/jet_smooth_point_set.h}
 

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/mst_orient_normals.tex

@@ -21,15 +21,8 @@
 
 \ccc{CGAL::mst_orient_normals()} orients the normals of a point set using the propagation of a seed orientation through a minimum spanning tree computed over the Riemannian graph \cite{cgal:hddms-srup-92}.
 
-The seed is the top point of the point set. Its normal is oriented towards +Z axis.
-
-The success of the orientation algorithm depends on the \ccc{k} parameter.
-The number of neighbors controls the candidates to progagate the orientation around each input point.
-In general, a value equal to a few rings, e.g. 18, works well.
-With smaller values, the propagation may be blocked by gaps in the point set.
-Large values will cause problems with points scattered over thin objects: the algorithm may incorrectly propagate the orientation from one side of the object to the other one.
-
-In the presence of several clusters of points, this algorithm cannot propagate the orientation from one cluster to the others, and will orient only the top cluster.
+The seed is chosen as the top point of the point set. Its normal is oriented towards +Z axis. The success of the orientation algorithm depends on the \ccc{k} parameter.
+The number of neighbors controls the number of candidates to propagate the orientation to around each input point. In general the value 18 works well. With smaller values the propagation may be blocked by large gaps in sparse point sets as the graph may be disconnected. Large values cause problems with points scattered over thin objects as the algorithm may incorrectly propagate the orientation from one side of the object to the other. In presence of disconnected clusters of points the algorithm may fail propagating the orientation from one cluster to the others and may only orient the top cluster.
 
 This method modifies the order of the input points so as to pack all successfully oriented normals first, and returns an iterator over the first point with an unoriented normal (see erase-remove idiom). For this reason it should not be called on sorted containers.
 

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/pca_estimate_normals.tex

@@ -21,11 +21,8 @@
 
 \ccc{CGAL::pca_estimate_normals()} estimates normal directions at all points of an input point set by linear least squares fitting of a plane over their $k$ nearest neighbors. The result is an unoriented normal for each input point.
 
-The quality of the normal estimation algorithm highly depends on the \ccc{k} parameter.
-The number of neighbors controls the width of the point subset considered for plane fitting at each input point.
-Larger value leads to smoother surface approximations and better normal estimations. Obviously, it also leads to longer computation times.
-For clean datasets, this value can be set to a few rings, e.g. 18. On the other hand, as the amount of noise increases, this value should be increased as well.
-For these reasons, we do not provide any default value for this parameter.
+The output of the normal estimation algorithm highly depends on the \ccc{k} parameter.
+The number of neighbors controls the size of the point subset considered for plane fitting at each input point. As this parameter is application-specific we do not provide any default value. For noise-free point sets this value can be set to a small number, e.g., 15. Larger values (e.g., 30 or more) lead to smoother normal fields and are more time consuming. We thus recommend using them only for noisy data sets. 
 
 \ccInclude{CGAL/pca_estimate_normals.h}
 

Point_set_processing_3/doc_tex/Point_set_processing_3_ref/random_simplify_point_set.tex

@@ -19,9 +19,7 @@
 
 \ccDefinition
 
-\ccc{CGAL::random_simplify_point_set()} randomly deletes a user-specified fraction of the input points.
-
-This method modifies the order of input points so as to pack all remaining points first, and returns and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers.
+\ccc{CGAL::random_simplify_point_set()} randomly deletes a user-specified fraction of the input points. This method modifies the order of input points so as to pack all remaining points first, and returns and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers.
 
 \ccInclude{CGAL/random_simplify_point_set.h}