Point Cloud Library (PCL)  1.10.0-dev
sac_segmentation.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2012, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of the copyright holder(s) nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  * $Id$
37  *
38  */
39 
40 #pragma once
41 
42 #include <pcl/pcl_base.h>
43 #include <pcl/PointIndices.h>
44 #include <pcl/ModelCoefficients.h>
45 
46 // Sample Consensus methods
47 #include <pcl/sample_consensus/method_types.h>
48 #include <pcl/sample_consensus/sac.h>
49 // Sample Consensus models
50 #include <pcl/sample_consensus/model_types.h>
51 #include <pcl/sample_consensus/sac_model.h>
52 
53 #include <pcl/search/search.h>
54 
55 namespace pcl
56 {
57  /** \brief @b SACSegmentation represents the Nodelet segmentation class for
58  * Sample Consensus methods and models, in the sense that it just creates a
59  * Nodelet wrapper for generic-purpose SAC-based segmentation.
60  * \author Radu Bogdan Rusu
61  * \ingroup segmentation
62  */
63  template <typename PointT>
64  class SACSegmentation : public PCLBase<PointT>
65  {
68 
69  public:
72 
74  using PointCloudPtr = typename PointCloud::Ptr;
77 
80 
81  /** \brief Empty constructor.
82  * \param[in] random if true set the random seed to the current time, else set to 12345 (default: false)
83  */
84  SACSegmentation (bool random = false)
85  : model_ ()
86  , sac_ ()
87  , model_type_ (-1)
88  , method_type_ (0)
89  , threshold_ (0)
90  , optimize_coefficients_ (true)
91  , radius_min_ (-std::numeric_limits<double>::max ())
92  , radius_max_ (std::numeric_limits<double>::max ())
93  , samples_radius_ (0.0)
95  , eps_angle_ (0.0)
96  , axis_ (Eigen::Vector3f::Zero ())
97  , max_iterations_ (50)
98  , threads_ (-1)
99  , probability_ (0.99)
100  , random_ (random)
101  {
102  }
103 
104  /** \brief Empty destructor. */
105  ~SACSegmentation () { /*srv_.reset ();*/ };
106 
107  /** \brief The type of model to use (user given parameter).
108  * \param[in] model the model type (check \a model_types.h)
109  */
110  inline void
111  setModelType (int model) { model_type_ = model; }
112 
113  /** \brief Get the type of SAC model used. */
114  inline int
115  getModelType () const { return (model_type_); }
116 
117  /** \brief Get a pointer to the SAC method used. */
118  inline SampleConsensusPtr
119  getMethod () const { return (sac_); }
120 
121  /** \brief Get a pointer to the SAC model used. */
123  getModel () const { return (model_); }
124 
125  /** \brief The type of sample consensus method to use (user given parameter).
126  * \param[in] method the method type (check \a method_types.h)
127  */
128  inline void
129  setMethodType (int method) { method_type_ = method; }
130 
131  /** \brief Get the type of sample consensus method used. */
132  inline int
133  getMethodType () const { return (method_type_); }
134 
135  /** \brief Distance to the model threshold (user given parameter).
136  * \param[in] threshold the distance threshold to use
137  */
138  inline void
139  setDistanceThreshold (double threshold) { threshold_ = threshold; }
140 
141  /** \brief Get the distance to the model threshold. */
142  inline double
143  getDistanceThreshold () const { return (threshold_); }
144 
145  /** \brief Set the maximum number of iterations before giving up.
146  * \param[in] max_iterations the maximum number of iterations the sample consensus method will run
147  */
148  inline void
149  setMaxIterations (int max_iterations) { max_iterations_ = max_iterations; }
150 
151  /** \brief Get maximum number of iterations before giving up. */
152  inline int
153  getMaxIterations () const { return (max_iterations_); }
154 
155  /** \brief Set the probability of choosing at least one sample free from outliers.
156  * \param[in] probability the model fitting probability
157  */
158  inline void
159  setProbability (double probability) { probability_ = probability; }
160 
161  /** \brief Get the probability of choosing at least one sample free from outliers. */
162  inline double
163  getProbability () const { return (probability_); }
164 
165  /** \brief Set the number of threads to use or turn off parallelization.
166  * \param[in] nr_threads the number of hardware threads to use (0 sets the value automatically, a negative number turns parallelization off)
167  * \note Not all SAC methods have a parallel implementation. Some will ignore this setting.
168  */
169  inline void
170  setNumberOfThreads (const int nr_threads = -1) { threads_ = nr_threads; }
171 
172  /** \brief Set to true if a coefficient refinement is required.
173  * \param[in] optimize true for enabling model coefficient refinement, false otherwise
174  */
175  inline void
176  setOptimizeCoefficients (bool optimize) { optimize_coefficients_ = optimize; }
177 
178  /** \brief Get the coefficient refinement internal flag. */
179  inline bool
181 
182  /** \brief Set the minimum and maximum allowable radius limits for the model (applicable to models that estimate
183  * a radius)
184  * \param[in] min_radius the minimum radius model
185  * \param[in] max_radius the maximum radius model
186  */
187  inline void
188  setRadiusLimits (const double &min_radius, const double &max_radius)
189  {
190  radius_min_ = min_radius;
191  radius_max_ = max_radius;
192  }
193 
194  /** \brief Get the minimum and maximum allowable radius limits for the model as set by the user.
195  * \param[out] min_radius the resultant minimum radius model
196  * \param[out] max_radius the resultant maximum radius model
197  */
198  inline void
199  getRadiusLimits (double &min_radius, double &max_radius)
200  {
201  min_radius = radius_min_;
202  max_radius = radius_max_;
203  }
204 
205  /** \brief Set the maximum distance allowed when drawing random samples
206  * \param[in] radius the maximum distance (L2 norm)
207  * \param search
208  */
209  inline void
210  setSamplesMaxDist (const double &radius, SearchPtr search)
211  {
212  samples_radius_ = radius;
213  samples_radius_search_ = search;
214  }
215 
216  /** \brief Get maximum distance allowed when drawing random samples
217  *
218  * \param[out] radius the maximum distance (L2 norm)
219  */
220  inline void
221  getSamplesMaxDist (double &radius)
222  {
223  radius = samples_radius_;
224  }
225 
226  /** \brief Set the axis along which we need to search for a model perpendicular to.
227  * \param[in] ax the axis along which we need to search for a model perpendicular to
228  */
229  inline void
230  setAxis (const Eigen::Vector3f &ax) { axis_ = ax; }
231 
232  /** \brief Get the axis along which we need to search for a model perpendicular to. */
233  inline Eigen::Vector3f
234  getAxis () const { return (axis_); }
235 
236  /** \brief Set the angle epsilon (delta) threshold.
237  * \param[in] ea the maximum allowed difference between the model normal and the given axis in radians.
238  */
239  inline void
240  setEpsAngle (double ea) { eps_angle_ = ea; }
241 
242  /** \brief Get the epsilon (delta) model angle threshold in radians. */
243  inline double
244  getEpsAngle () const { return (eps_angle_); }
245 
246  /** \brief Base method for segmentation of a model in a PointCloud given by <setInputCloud (), setIndices ()>
247  * \param[out] inliers the resultant point indices that support the model found (inliers)
248  * \param[out] model_coefficients the resultant model coefficients
249  */
250  virtual void
251  segment (PointIndices &inliers, ModelCoefficients &model_coefficients);
252 
253  protected:
254  /** \brief Initialize the Sample Consensus model and set its parameters.
255  * \param[in] model_type the type of SAC model that is to be used
256  */
257  virtual bool
258  initSACModel (const int model_type);
259 
260  /** \brief Initialize the Sample Consensus method and set its parameters.
261  * \param[in] method_type the type of SAC method to be used
262  */
263  virtual void
264  initSAC (const int method_type);
265 
266  /** \brief The model that needs to be segmented. */
268 
269  /** \brief The sample consensus segmentation method. */
271 
272  /** \brief The type of model to use (user given parameter). */
274 
275  /** \brief The type of sample consensus method to use (user given parameter). */
277 
278  /** \brief Distance to the model threshold (user given parameter). */
279  double threshold_;
280 
281  /** \brief Set to true if a coefficient refinement is required. */
283 
284  /** \brief The minimum and maximum radius limits for the model. Applicable to all models that estimate a radius. */
286 
287  /** \brief The maximum distance of subsequent samples from the first (radius search) */
289 
290  /** \brief The search object for picking subsequent samples using radius search */
292 
293  /** \brief The maximum allowed difference between the model normal and the given axis. */
294  double eps_angle_;
295 
296  /** \brief The axis along which we need to search for a model perpendicular to. */
297  Eigen::Vector3f axis_;
298 
299  /** \brief Maximum number of iterations before giving up (user given parameter). */
301 
302  /** \brief The number of threads the scheduler should use, or a negative number if no parallelization is wanted. */
303  int threads_;
304 
305  /** \brief Desired probability of choosing at least one sample free from outliers (user given parameter). */
306  double probability_;
307 
308  /** \brief Set to true if we need a random seed. */
309  bool random_;
310 
311  /** \brief Class get name method. */
312  virtual std::string
313  getClassName () const { return ("SACSegmentation"); }
314  };
315 
316  /** \brief @b SACSegmentationFromNormals represents the PCL nodelet segmentation class for Sample Consensus methods and
317  * models that require the use of surface normals for estimation.
318  * \ingroup segmentation
319  */
320  template <typename PointT, typename PointNT>
322  {
330 
331  public:
334 
336  using PointCloudPtr = typename PointCloud::Ptr;
338 
342 
346 
347  /** \brief Empty constructor.
348  * \param[in] random if true set the random seed to the current time, else set to 12345 (default: false)
349  */
350  SACSegmentationFromNormals (bool random = false)
351  : SACSegmentation<PointT> (random)
352  , normals_ ()
353  , distance_weight_ (0.1)
354  , distance_from_origin_ (0)
355  , min_angle_ (0.0)
356  , max_angle_ (M_PI_2)
357  {};
358 
359  /** \brief Provide a pointer to the input dataset that contains the point normals of
360  * the XYZ dataset.
361  * \param[in] normals the const boost shared pointer to a PointCloud message
362  */
363  inline void
364  setInputNormals (const PointCloudNConstPtr &normals) { normals_ = normals; }
365 
366  /** \brief Get a pointer to the normals of the input XYZ point cloud dataset. */
367  inline PointCloudNConstPtr
368  getInputNormals () const { return (normals_); }
369 
370  /** \brief Set the relative weight (between 0 and 1) to give to the angular
371  * distance (0 to pi/2) between point normals and the plane normal.
372  * \param[in] distance_weight the distance/angular weight
373  */
374  inline void
375  setNormalDistanceWeight (double distance_weight) { distance_weight_ = distance_weight; }
376 
377  /** \brief Get the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point
378  * normals and the plane normal. */
379  inline double
380  getNormalDistanceWeight () const { return (distance_weight_); }
381 
382  /** \brief Set the minimum opning angle for a cone model.
383  * \param min_angle the opening angle which we need minimum to validate a cone model.
384  * \param max_angle the opening angle which we need maximum to validate a cone model.
385  */
386  inline void
387  setMinMaxOpeningAngle (const double &min_angle, const double &max_angle)
388  {
389  min_angle_ = min_angle;
390  max_angle_ = max_angle;
391  }
392 
393  /** \brief Get the opening angle which we need minimum to validate a cone model. */
394  inline void
395  getMinMaxOpeningAngle (double &min_angle, double &max_angle)
396  {
397  min_angle = min_angle_;
398  max_angle = max_angle_;
399  }
400 
401  /** \brief Set the distance we expect a plane model to be from the origin
402  * \param[in] d distance from the template plane model to the origin
403  */
404  inline void
405  setDistanceFromOrigin (const double d) { distance_from_origin_ = d; }
406 
407  /** \brief Get the distance of a plane model from the origin. */
408  inline double
409  getDistanceFromOrigin () const { return (distance_from_origin_); }
410 
411  protected:
412  /** \brief A pointer to the input dataset that contains the point normals of the XYZ dataset. */
414 
415  /** \brief The relative weight (between 0 and 1) to give to the angular
416  * distance (0 to pi/2) between point normals and the plane normal.
417  */
419 
420  /** \brief The distance from the template plane to the origin. */
422 
423  /** \brief The minimum and maximum allowed opening angle of valid cone model. */
424  double min_angle_;
425  double max_angle_;
426 
427  /** \brief Initialize the Sample Consensus model and set its parameters.
428  * \param[in] model_type the type of SAC model that is to be used
429  */
430  bool
431  initSACModel (const int model_type) override;
432 
433  /** \brief Class get name method. */
434  std::string
435  getClassName () const override { return ("SACSegmentationFromNormals"); }
436  };
437 }
438 
439 #ifdef PCL_NO_PRECOMPILE
440 #include <pcl/segmentation/impl/sac_segmentation.hpp>
441 #endif
typename PointCloudN::Ptr PointCloudNPtr
double getNormalDistanceWeight() const
Get the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point n...
void setOptimizeCoefficients(bool optimize)
Set to true if a coefficient refinement is required.
double min_angle_
The minimum and maximum allowed opening angle of valid cone model.
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:415
int max_iterations_
Maximum number of iterations before giving up (user given parameter).
bool random_
Set to true if we need a random seed.
void setSamplesMaxDist(const double &radius, SearchPtr search)
Set the maximum distance allowed when drawing random samples.
void setEpsAngle(double ea)
Set the angle epsilon (delta) threshold.
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
SACSegmentation represents the Nodelet segmentation class for Sample Consensus methods and models...
void setInputNormals(const PointCloudNConstPtr &normals)
Provide a pointer to the input dataset that contains the point normals of the XYZ dataset...
SampleConsensusPtr getMethod() const
Get a pointer to the SAC method used.
typename SampleConsensusModel< PointT >::Ptr SampleConsensusModelPtr
double probability_
Desired probability of choosing at least one sample free from outliers (user given parameter)...
int threads_
The number of threads the scheduler should use, or a negative number if no parallelization is wanted...
SampleConsensusModelPtr getModel() const
Get a pointer to the SAC model used.
void setMethodType(int method)
The type of sample consensus method to use (user given parameter).
Definition: bfgs.h:9
void setProbability(double probability)
Set the probability of choosing at least one sample free from outliers.
void setNumberOfThreads(const int nr_threads=-1)
Set the number of threads to use or turn off parallelization.
double getDistanceFromOrigin() const
Get the distance of a plane model from the origin.
double samples_radius_
The maximum distance of subsequent samples from the first (radius search)
virtual bool initSACModel(const int model_type)
Initialize the Sample Consensus model and set its parameters.
double threshold_
Distance to the model threshold (user given parameter).
typename pcl::search::Search< PointT >::Ptr SearchPtr
double radius_min_
The minimum and maximum radius limits for the model.
double distance_from_origin_
The distance from the template plane to the origin.
void getSamplesMaxDist(double &radius)
Get maximum distance allowed when drawing random samples.
Eigen::Vector3f getAxis() const
Get the axis along which we need to search for a model perpendicular to.
double getProbability() const
Get the probability of choosing at least one sample free from outliers.
int getModelType() const
Get the type of SAC model used.
void getMinMaxOpeningAngle(double &min_angle, double &max_angle)
Get the opening angle which we need minimum to validate a cone model.
int model_type_
The type of model to use (user given parameter).
shared_ptr< SampleConsensusModelFromNormals< PointT, PointNT > > Ptr
Definition: sac_model.h:586
typename PointCloudN::ConstPtr PointCloudNConstPtr
SampleConsensusModelPtr model_
The model that needs to be segmented.
double eps_angle_
The maximum allowed difference between the model normal and the given axis.
SACSegmentationFromNormals(bool random=false)
Empty constructor.
double distance_weight_
The relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point norma...
SearchPtr samples_radius_search_
The search object for picking subsequent samples using radius search.
PCL base class.
Definition: pcl_base.h:69
Eigen::Vector3f axis_
The axis along which we need to search for a model perpendicular to.
void setAxis(const Eigen::Vector3f &ax)
Set the axis along which we need to search for a model perpendicular to.
typename PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:73
void setRadiusLimits(const double &min_radius, const double &max_radius)
Set the minimum and maximum allowable radius limits for the model (applicable to models that estimate...
int getMaxIterations() const
Get maximum number of iterations before giving up.
int getMethodType() const
Get the type of sample consensus method used.
~SACSegmentation()
Empty destructor.
PointCloudNConstPtr getInputNormals() const
Get a pointer to the normals of the input XYZ point cloud dataset.
SACSegmentationFromNormals represents the PCL nodelet segmentation class for Sample Consensus methods...
bool optimize_coefficients_
Set to true if a coefficient refinement is required.
std::string getClassName() const override
Class get name method.
PointCloud represents the base class in PCL for storing collections of 3D points. ...
void setModelType(int model)
The type of model to use (user given parameter).
virtual std::string getClassName() const
Class get name method.
typename SampleConsensus< PointT >::Ptr SampleConsensusPtr
SampleConsensusPtr sac_
The sample consensus segmentation method.
virtual void segment(PointIndices &inliers, ModelCoefficients &model_coefficients)
Base method for segmentation of a model in a PointCloud given by <setInputCloud (), setIndices ()>
void setMaxIterations(int max_iterations)
Set the maximum number of iterations before giving up.
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:416
void setDistanceFromOrigin(const double d)
Set the distance we expect a plane model to be from the origin.
void getRadiusLimits(double &min_radius, double &max_radius)
Get the minimum and maximum allowable radius limits for the model as set by the user.
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:80
typename SampleConsensusModelFromNormals< PointT, PointNT >::Ptr SampleConsensusModelFromNormalsPtr
SACSegmentation(bool random=false)
Empty constructor.
void setMinMaxOpeningAngle(const double &min_angle, const double &max_angle)
Set the minimum opning angle for a cone model.
A point structure representing Euclidean xyz coordinates, and the RGB color.
void setDistanceThreshold(double threshold)
Distance to the model threshold (user given parameter).
shared_ptr< SampleConsensusModel< PointT > > Ptr
Definition: sac_model.h:76
virtual void initSAC(const int method_type)
Initialize the Sample Consensus method and set its parameters.
double getEpsAngle() const
Get the epsilon (delta) model angle threshold in radians.
bool getOptimizeCoefficients() const
Get the coefficient refinement internal flag.
PointCloudNConstPtr normals_
A pointer to the input dataset that contains the point normals of the XYZ dataset.
double getDistanceThreshold() const
Get the distance to the model threshold.
SampleConsensus represents the base class.
Definition: sac.h:58
void setNormalDistanceWeight(double distance_weight)
Set the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point n...
typename PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:74
int method_type_
The type of sample consensus method to use (user given parameter).