Merge pull request #3301 from mvieth/doc-fixes

Fix and improve documentation, mostly in sample consensus

filters/include/pcl/filters/conditional_removal.h

@@ -579,6 +579,7 @@ namespace pcl
     * hsi color space.
     *
     * Here is an example usage:
+    * \code
     *  // Build the condition
     *  pcl::ConditionAnd<PointT>::Ptr range_cond (new pcl::ConditionAnd<PointT> ());
     *  range_cond->addComparison (pcl::FieldComparison<PointT>::Ptr (new pcl::FieldComparison<PointT>("z", pcl::ComparisonOps::LT, 2.0)));
@@ -587,6 +588,7 @@ namespace pcl
     *  pcl::ConditionalRemoval<PointT> range_filt;
     *  range_filt.setCondition (range_cond);
     *  range_filt.setKeepOrganized (false);
+    * \endcode
     *
     * \author Louis LeGrand, Intel Labs Seattle
     * \ingroup filters

sample_consensus/include/pcl/sample_consensus/impl/sac_model_circle.hpp

@@ -112,7 +112,7 @@ pcl::SampleConsensusModelCircle2D<PointT>::getDistancesToModel (const Eigen::Vec
   }
   distances.resize (indices_->size ());
 
-  // Iterate through the 3d points and calculate the distances from them to the sphere
+  // Iterate through the 3d points and calculate the distances from them to the circle
   for (size_t i = 0; i < indices_->size (); ++i)
     // Calculate the distance from the point to the circle as the difference between
     // dist(point,circle_origin) and circle_radius
@@ -141,11 +141,11 @@ pcl::SampleConsensusModelCircle2D<PointT>::selectWithinDistance (
   inliers.resize (indices_->size ());
   error_sqr_dists_.resize (indices_->size ());
 
-  // Iterate through the 3d points and calculate the distances from them to the sphere
+  // Iterate through the 3d points and calculate the distances from them to the circle
   for (size_t i = 0; i < indices_->size (); ++i)
   {
-    // Calculate the distance from the point to the sphere as the difference between
-    // dist(point,sphere_origin) and sphere_radius
+    // Calculate the distance from the point to the circle as the difference between
+    // dist(point,circle_origin) and circle_radius
     float distance = std::abs (std::sqrt (
                                       ( input_->points[(*indices_)[i]].x - model_coefficients[0] ) *
                                       ( input_->points[(*indices_)[i]].x - model_coefficients[0] ) +
@@ -175,11 +175,11 @@ pcl::SampleConsensusModelCircle2D<PointT>::countWithinDistance (
     return (0);
   int nr_p = 0;
 
-  // Iterate through the 3d points and calculate the distances from them to the sphere
+  // Iterate through the 3d points and calculate the distances from them to the circle
   for (size_t i = 0; i < indices_->size (); ++i)
   {
-    // Calculate the distance from the point to the sphere as the difference between
-    // dist(point,sphere_origin) and sphere_radius
+    // Calculate the distance from the point to the circle as the difference between
+    // dist(point,circle_origin) and circle_radius
     float distance = std::abs (std::sqrt (
                                       ( input_->points[(*indices_)[i]].x - model_coefficients[0] ) *
                                       ( input_->points[(*indices_)[i]].x - model_coefficients[0] ) +
@@ -254,7 +254,7 @@ pcl::SampleConsensusModelCircle2D<PointT>::projectPoints (
       // Iterate over each dimension
       pcl::for_each_type <FieldList> (NdConcatenateFunctor <PointT, PointT> (input_->points[i], projected_points.points[i]));
 
-    // Iterate through the 3d points and calculate the distances from them to the plane
+    // Iterate through the points and project them to the circle
     for (const int &inlier : inliers)
     {
       float dx = input_->points[inlier].x - model_coefficients[0];
@@ -278,7 +278,7 @@ pcl::SampleConsensusModelCircle2D<PointT>::projectPoints (
       // Iterate over each dimension
       pcl::for_each_type <FieldList> (NdConcatenateFunctor <PointT, PointT> (input_->points[inliers[i]], projected_points.points[i]));
 
-    // Iterate through the 3d points and calculate the distances from them to the plane
+    // Iterate through the points and project them to the circle
     for (size_t i = 0; i < inliers.size (); ++i)
     {
       float dx = input_->points[inliers[i]].x - model_coefficients[0];
@@ -304,8 +304,8 @@ pcl::SampleConsensusModelCircle2D<PointT>::doSamplesVerifyModel (
   }
 
   for (const int &index : indices)
-    // Calculate the distance from the point to the sphere as the difference between
-    //dist(point,sphere_origin) and sphere_radius
+    // Calculate the distance from the point to the circle as the difference between
+    //dist(point,circle_origin) and circle_radius
     if (std::abs (std::sqrt (
                          ( input_->points[index].x - model_coefficients[0] ) *
                          ( input_->points[index].x - model_coefficients[0] ) +

sample_consensus/include/pcl/sample_consensus/impl/sac_model_cylinder.hpp

@@ -365,7 +365,7 @@ pcl::SampleConsensusModelCylinder<PointT, PointNT>::projectPoints (
       // Iterate over each dimension
       pcl::for_each_type <FieldList> (NdConcatenateFunctor <PointT, PointT> (input_->points[inliers[i]], projected_points.points[i]));
 
-    // Iterate through the 3d points and calculate the distances from them to the plane
+    // Iterate through the 3d points and calculate the distances from them to the cylinder
     for (size_t i = 0; i < inliers.size (); ++i)
     {
       pcl::Vector4fMap pp = projected_points.points[i].getVector4fMap ();

sample_consensus/include/pcl/sample_consensus/impl/sac_model_normal_sphere.hpp

@@ -70,7 +70,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::selectWithinDistance (
   inliers.resize (indices_->size ());
   error_sqr_dists_.resize (indices_->size ());
 
-  // Iterate through the 3d points and calculate the distances from them to the plane
+  // Iterate through the 3d points and calculate the distances from them to the sphere
   for (size_t i = 0; i < indices_->size (); ++i)
   {
     // Calculate the distance from the point to the sphere center as the difference between
@@ -88,7 +88,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::selectWithinDistance (
     Eigen::Vector4f n_dir = p - center;
     double d_euclid = std::abs (n_dir.norm () - model_coefficients[3]);
 
-    // Calculate the angular distance between the point normal and the plane normal
+    // Calculate the angular distance between the point normal and the sphere normal
     double d_normal = std::abs (getAngle3D (n, n_dir));
     d_normal = (std::min) (d_normal, M_PI - d_normal);
 
@@ -127,7 +127,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::countWithinDistance (
 
   int nr_p = 0;
 
-  // Iterate through the 3d points and calculate the distances from them to the plane
+  // Iterate through the 3d points and calculate the distances from them to the sphere
   for (size_t i = 0; i < indices_->size (); ++i)
   {
     // Calculate the distance from the point to the sphere centroid as the difference between
@@ -145,7 +145,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::countWithinDistance (
     Eigen::Vector4f n_dir = (p-center);
     double d_euclid = std::abs (n_dir.norm () - model_coefficients[3]);
     //
-    // Calculate the angular distance between the point normal and the plane normal
+    // Calculate the angular distance between the point normal and the sphere normal
     double d_normal = std::abs (getAngle3D (n, n_dir));
     d_normal = (std::min) (d_normal, M_PI - d_normal);
 
@@ -179,7 +179,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::getDistancesToModel (
 
   distances.resize (indices_->size ());
 
-  // Iterate through the 3d points and calculate the distances from them to the plane
+  // Iterate through the 3d points and calculate the distances from them to the sphere
   for (size_t i = 0; i < indices_->size (); ++i)
   {
     // Calculate the distance from the point to the sphere as the difference between
@@ -197,7 +197,7 @@ pcl::SampleConsensusModelNormalSphere<PointT, PointNT>::getDistancesToModel (
     Eigen::Vector4f n_dir = (p-center);
     double d_euclid = std::abs (n_dir.norm () - model_coefficients[3]);
     //
-    // Calculate the angular distance between the point normal and the plane normal
+    // Calculate the angular distance between the point normal and the sphere normal
     double d_normal = std::abs (getAngle3D (n, n_dir));
     d_normal = (std::min) (d_normal, M_PI - d_normal);
 

sample_consensus/include/pcl/sample_consensus/sac_model.h

@@ -331,7 +331,7 @@ namespace pcl
       inline boost::shared_ptr <std::vector<int> > 
       getIndices () const { return (indices_); }
 
-      /** \brief Return an unique id for each type of model employed. */
+      /** \brief Return a unique id for each type of model employed. */
       virtual SacModel 
       getModelType () const = 0;
 

sample_consensus/include/pcl/sample_consensus/sac_model_circle.h

@@ -192,7 +192,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_CIRCLE2D). */
+      /** \brief Return a unique id for this model (SACMODEL_CIRCLE2D). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_CIRCLE2D); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_circle3d.h

@@ -194,7 +194,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_CIRCLE3D). */
+      /** \brief Return a unique id for this model (SACMODEL_CIRCLE3D). */
       inline pcl::SacModel
       getModelType () const override { return (SACMODEL_CIRCLE3D); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_cone.h

@@ -262,7 +262,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_CONE). */
+      /** \brief Return a unique id for this model (SACMODEL_CONE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_CONE); }
 
@@ -291,10 +291,10 @@ namespace pcl
       isSampleGood (const std::vector<int> &samples) const override;
 
     private:
-      /** \brief The axis along which we need to search for a plane perpendicular to. */
+      /** \brief The axis along which we need to search for a cone direction. */
       Eigen::Vector3f axis_;
 
-      /** \brief The maximum allowed difference between the plane normal and the given axis. */
+      /** \brief The maximum allowed difference between the cone direction and the given axis. */
       double eps_angle_;
 
       /** \brief The minimum and maximum allowed opening angles of valid cone model. */

sample_consensus/include/pcl/sample_consensus/sac_model_cylinder.h

@@ -233,7 +233,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_CYLINDER). */
+      /** \brief Return a unique id for this model (SACMODEL_CYLINDER). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_CYLINDER); }
 
@@ -290,10 +290,10 @@ namespace pcl
       isSampleGood (const std::vector<int> &samples) const override;
 
     private:
-      /** \brief The axis along which we need to search for a plane perpendicular to. */
+      /** \brief The axis along which we need to search for a cylinder direction. */
       Eigen::Vector3f axis_;
 
-      /** \brief The maximum allowed difference between the plane normal and the given axis. */
+      /** \brief The maximum allowed difference between the cylinder direction and the given axis. */
       double eps_angle_;
 
       /** \brief Functor for the optimization function */

sample_consensus/include/pcl/sample_consensus/sac_model_line.h

@@ -175,7 +175,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_LINE). */
+      /** \brief Return a unique id for this model (SACMODEL_LINE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_LINE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_normal_parallel_plane.h

@@ -51,7 +51,8 @@ namespace pcl
     * this means that checking for inliers will not only involve a "distance to
     * model" criterion, but also an additional "maximum angular deviation"
     * between the plane's normal and the inlier points normals. In addition,
-    * the plane normal must lie parallel to an user-specified axis.
+    * the plane <b>normal</b> must lie parallel to a user-specified axis.
+    * This means that the plane itself will lie perpendicular to that axis, similar to \link pcl::SampleConsensusModelPerpendicularPlane SACMODEL_PERPENDICULAR_PLANE \endlink.
     *
     * The model coefficients are defined as:
     *   - \b a : the X coordinate of the plane's normal (normalized)
@@ -182,7 +183,7 @@ namespace pcl
       inline double
       getEpsDist () const { return (eps_dist_); }
 
-      /** \brief Return an unique id for this model (SACMODEL_NORMAL_PARALLEL_PLANE). */
+      /** \brief Return a unique id for this model (SACMODEL_NORMAL_PARALLEL_PLANE). */
       inline pcl::SacModel
       getModelType () const override { return (SACMODEL_NORMAL_PARALLEL_PLANE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_normal_plane.h

@@ -154,7 +154,7 @@ namespace pcl
       getDistancesToModel (const Eigen::VectorXf &model_coefficients,
                            std::vector<double> &distances) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_NORMAL_PLANE). */
+      /** \brief Return a unique id for this model (SACMODEL_NORMAL_PLANE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_NORMAL_PLANE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_normal_sphere.h

@@ -56,10 +56,10 @@ namespace pcl
     *
     * The model coefficients are defined as:
     * <ul>
-    * <li><b>a</b> : the X coordinate of the plane's normal (normalized)
-    * <li><b>b</b> : the Y coordinate of the plane's normal (normalized)
-    * <li><b>c</b> : the Z coordinate of the plane's normal (normalized)
-    * <li><b>d</b> : radius of the sphere
+    * <li><b>center.x</b> : the X coordinate of the sphere's center
+    * <li><b>center.y</b> : the Y coordinate of the sphere's center
+    * <li><b>center.z</b> : the Z coordinate of the sphere's center
+    * <li><b>radius</b> : radius of the sphere
     * </ul>
     *
     * \author Stefan Schrandt
@@ -147,7 +147,7 @@ namespace pcl
       getDistancesToModel (const Eigen::VectorXf &model_coefficients,
                            std::vector<double> &distances) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_NORMAL_SPHERE). */
+      /** \brief Return a unique id for this model (SACMODEL_NORMAL_SPHERE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_NORMAL_SPHERE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_parallel_line.h

@@ -155,7 +155,7 @@ namespace pcl
       getDistancesToModel (const Eigen::VectorXf &model_coefficients,
                            std::vector<double> &distances) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_PARALLEL_LINE). */
+      /** \brief Return a unique id for this model (SACMODEL_PARALLEL_LINE). */
       inline pcl::SacModel
       getModelType () const override { return (SACMODEL_PARALLEL_LINE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_parallel_plane.h

@@ -47,7 +47,8 @@ namespace pcl
 {
   /** \brief @b SampleConsensusModelParallelPlane defines a model for 3D plane segmentation using additional
     * angular constraints. The plane must be parallel to a user-specified axis
-    * (\ref setAxis) within an user-specified angle threshold (\ref setEpsAngle).
+    * (\ref setAxis) within a user-specified angle threshold (\ref setEpsAngle).
+    * In other words, the plane <b>normal</b> must be (nearly) <b>perpendicular</b> to the specified axis.
     *
     * Code example for a plane model, parallel (within a 15 degrees tolerance) with the Z axis:
     * \code
@@ -159,7 +160,7 @@ namespace pcl
       getDistancesToModel (const Eigen::VectorXf &model_coefficients,
                            std::vector<double> &distances) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_PARALLEL_PLANE). */
+      /** \brief Return a unique id for this model (SACMODEL_PARALLEL_PLANE). */
       inline pcl::SacModel
       getModelType () const override { return (SACMODEL_PARALLEL_PLANE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_perpendicular_plane.h

@@ -46,7 +46,8 @@
 namespace pcl
 {
   /** \brief SampleConsensusModelPerpendicularPlane defines a model for 3D plane segmentation using additional
-    * angular constraints. The plane must be perpendicular to an user-specified axis (\ref setAxis), up to an user-specified angle threshold (\ref setEpsAngle).
+    * angular constraints. The plane must be perpendicular to a user-specified axis (\ref setAxis), up to a user-specified angle threshold (\ref setEpsAngle).
+    * In other words, the plane <b>normal</b> must be (nearly) <b>parallel</b> to the specified axis.
     * The model coefficients are defined as:
     *   - \b a : the X coordinate of the plane's normal (normalized)
     *   - \b b : the Y coordinate of the plane's normal (normalized)
@@ -162,7 +163,7 @@ namespace pcl
       getDistancesToModel (const Eigen::VectorXf &model_coefficients,
                            std::vector<double> &distances) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_PERPENDICULAR_PLANE). */
+      /** \brief Return a unique id for this model (SACMODEL_PERPENDICULAR_PLANE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_PERPENDICULAR_PLANE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_plane.h

@@ -248,7 +248,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_PLANE). */
+      /** \brief Return a unique id for this model (SACMODEL_PLANE). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_PLANE); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_registration.h

@@ -210,7 +210,7 @@ namespace pcl
         return (false);
       }
 
-      /** \brief Return an unique id for this model (SACMODEL_REGISTRATION). */
+      /** \brief Return a unique id for this model (SACMODEL_REGISTRATION). */
       inline pcl::SacModel
       getModelType () const override { return (SACMODEL_REGISTRATION); }
 

sample_consensus/include/pcl/sample_consensus/sac_model_sphere.h

@@ -195,7 +195,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_SPHERE). */
+      /** \brief Return a unique id for this model (SACMODEL_SPHERE). */
       inline pcl::SacModel getModelType () const override { return (SACMODEL_SPHERE); }
 
     protected:

sample_consensus/include/pcl/sample_consensus/sac_model_stick.h

@@ -47,7 +47,7 @@
 namespace pcl
 {
   /** \brief SampleConsensusModelStick defines a model for 3D stick segmentation. 
-    * A stick is a line with an user given minimum/maximum width.
+    * A stick is a line with a user given minimum/maximum width.
     * The model coefficients are defined as:
     *   - \b point_on_line.x  : the X coordinate of a point on the line
     *   - \b point_on_line.y  : the Y coordinate of a point on the line
@@ -56,6 +56,7 @@ namespace pcl
     *   - \b line_direction.y : the Y coordinate of a line's direction
     *   - \b line_direction.z : the Z coordinate of a line's direction
     *   - \b line_width       : the width of the line
+    *
     * \author Radu B. Rusu
     * \ingroup sample_consensus
     */
@@ -179,7 +180,7 @@ namespace pcl
                             const Eigen::VectorXf &model_coefficients,
                             const double threshold) const override;
 
-      /** \brief Return an unique id for this model (SACMODEL_STICK). */
+      /** \brief Return a unique id for this model (SACMODEL_STICK). */
       inline pcl::SacModel 
       getModelType () const override { return (SACMODEL_STICK); }