Point Cloud Library (PCL)  1.14.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  : random_(random)
86  {}
87 
88  /** \brief Empty destructor. */
89  ~SACSegmentation () override = default;
90 
91  /** \brief The type of model to use (user given parameter).
92  * \param[in] model the model type (check \a model_types.h)
93  */
94  inline void
95  setModelType (int model) { model_type_ = model; }
96 
97  /** \brief Get the type of SAC model used. */
98  inline int
99  getModelType () const { return (model_type_); }
100 
101  /** \brief Get a pointer to the SAC method used. */
102  inline SampleConsensusPtr
103  getMethod () const { return (sac_); }
104 
105  /** \brief Get a pointer to the SAC model used. */
107  getModel () const { return (model_); }
108 
109  /** \brief The type of sample consensus method to use (user given parameter).
110  * \param[in] method the method type (check \a method_types.h)
111  */
112  inline void
113  setMethodType (int method) { method_type_ = method; }
114 
115  /** \brief Get the type of sample consensus method used. */
116  inline int
117  getMethodType () const { return (method_type_); }
118 
119  /** \brief Distance to the model threshold (user given parameter).
120  * \param[in] threshold the distance threshold to use
121  */
122  inline void
123  setDistanceThreshold (double threshold) { threshold_ = threshold; }
124 
125  /** \brief Get the distance to the model threshold. */
126  inline double
127  getDistanceThreshold () const { return (threshold_); }
128 
129  /** \brief Set the maximum number of iterations before giving up.
130  * \param[in] max_iterations the maximum number of iterations the sample consensus method will run
131  */
132  inline void
133  setMaxIterations (int max_iterations) { max_iterations_ = max_iterations; }
134 
135  /** \brief Get maximum number of iterations before giving up. */
136  inline int
137  getMaxIterations () const { return (max_iterations_); }
138 
139  /** \brief Set the probability of choosing at least one sample free from outliers.
140  * \param[in] probability the model fitting probability
141  */
142  inline void
143  setProbability (double probability) { probability_ = probability; }
144 
145  /** \brief Get the probability of choosing at least one sample free from outliers. */
146  inline double
147  getProbability () const { return (probability_); }
148 
149  /** \brief Set the number of threads to use or turn off parallelization.
150  * \param[in] nr_threads the number of hardware threads to use (0 sets the value automatically, a negative number turns parallelization off)
151  * \note Not all SAC methods have a parallel implementation. Some will ignore this setting.
152  */
153  inline void
154  setNumberOfThreads (const int nr_threads = -1) { threads_ = nr_threads; }
155 
156  /** \brief Set to true if a coefficient refinement is required.
157  * \param[in] optimize true for enabling model coefficient refinement, false otherwise
158  */
159  inline void
160  setOptimizeCoefficients (bool optimize) { optimize_coefficients_ = optimize; }
161 
162  /** \brief Get the coefficient refinement internal flag. */
163  inline bool
165 
166  /** \brief Set the minimum and maximum allowable radius limits for the model (applicable to models that estimate
167  * a radius)
168  * \param[in] min_radius the minimum radius model
169  * \param[in] max_radius the maximum radius model
170  */
171  inline void
172  setRadiusLimits (const double &min_radius, const double &max_radius)
173  {
174  radius_min_ = min_radius;
175  radius_max_ = max_radius;
176  }
177 
178  /** \brief Get the minimum and maximum allowable radius limits for the model as set by the user.
179  * \param[out] min_radius the resultant minimum radius model
180  * \param[out] max_radius the resultant maximum radius model
181  */
182  inline void
183  getRadiusLimits (double &min_radius, double &max_radius)
184  {
185  min_radius = radius_min_;
186  max_radius = radius_max_;
187  }
188 
189  /** \brief Set the maximum distance allowed when drawing random samples
190  * \param[in] radius the maximum distance (L2 norm)
191  * \param search
192  */
193  inline void
194  setSamplesMaxDist (const double &radius, SearchPtr search)
195  {
196  samples_radius_ = radius;
197  samples_radius_search_ = search;
198  }
199 
200  /** \brief Get maximum distance allowed when drawing random samples
201  *
202  * \param[out] radius the maximum distance (L2 norm)
203  */
204  inline void
205  getSamplesMaxDist (double &radius)
206  {
207  radius = samples_radius_;
208  }
209 
210  /** \brief Set the axis along which we need to search for a model perpendicular to.
211  * \param[in] ax the axis along which we need to search for a model perpendicular to
212  */
213  inline void
214  setAxis (const Eigen::Vector3f &ax) { axis_ = ax; }
215 
216  /** \brief Get the axis along which we need to search for a model perpendicular to. */
217  inline Eigen::Vector3f
218  getAxis () const { return (axis_); }
219 
220  /** \brief Set the angle epsilon (delta) threshold.
221  * \param[in] ea the maximum allowed difference between the model normal and the given axis in radians.
222  */
223  inline void
224  setEpsAngle (double ea) { eps_angle_ = ea; }
225 
226  /** \brief Get the epsilon (delta) model angle threshold in radians. */
227  inline double
228  getEpsAngle () const { return (eps_angle_); }
229 
230  /** \brief Base method for segmentation of a model in a PointCloud given by <setInputCloud (), setIndices ()>
231  * \param[out] inliers the resultant point indices that support the model found (inliers)
232  * \param[out] model_coefficients the resultant model coefficients
233  */
234  virtual void
235  segment (PointIndices &inliers, ModelCoefficients &model_coefficients);
236 
237  protected:
238  /** \brief Initialize the Sample Consensus model and set its parameters.
239  * \param[in] model_type the type of SAC model that is to be used
240  */
241  virtual bool
242  initSACModel (const int model_type);
243 
244  /** \brief Initialize the Sample Consensus method and set its parameters.
245  * \param[in] method_type the type of SAC method to be used
246  */
247  virtual void
248  initSAC (const int method_type);
249 
250  /** \brief The model that needs to be segmented. */
252 
253  /** \brief The sample consensus segmentation method. */
255 
256  /** \brief The type of model to use (user given parameter). */
257  int model_type_{-1};
258 
259  /** \brief The type of sample consensus method to use (user given parameter). */
260  int method_type_{0};
261 
262  /** \brief Distance to the model threshold (user given parameter). */
263  double threshold_{0.0};
264 
265  /** \brief Set to true if a coefficient refinement is required. */
267 
268  /** \brief The minimum and maximum radius limits for the model. Applicable to all models that estimate a radius. */
269  double radius_min_{-std::numeric_limits<double>::max()}, radius_max_{std::numeric_limits<double>::max()};
270 
271  /** \brief The maximum distance of subsequent samples from the first (radius search) */
272  double samples_radius_{0.0};
273 
274  /** \brief The search object for picking subsequent samples using radius search */
276 
277  /** \brief The maximum allowed difference between the model normal and the given axis. */
278  double eps_angle_{0.0};
279 
280  /** \brief The axis along which we need to search for a model perpendicular to. */
281  Eigen::Vector3f axis_{Eigen::Vector3f::Zero()};
282 
283  /** \brief Maximum number of iterations before giving up (user given parameter). */
285 
286  /** \brief The number of threads the scheduler should use, or a negative number if no parallelization is wanted. */
287  int threads_{-1};
288 
289  /** \brief Desired probability of choosing at least one sample free from outliers (user given parameter). */
290  double probability_{0.99};
291 
292  /** \brief Set to true if we need a random seed. */
293  bool random_;
294 
295  /** \brief Class get name method. */
296  virtual std::string
297  getClassName () const { return ("SACSegmentation"); }
298  };
299 
300  /** \brief @b SACSegmentationFromNormals represents the PCL nodelet segmentation class for Sample Consensus methods and
301  * models that require the use of surface normals for estimation.
302  * \ingroup segmentation
303  */
304  template <typename PointT, typename PointNT>
306  {
314 
315  public:
318 
320  using PointCloudPtr = typename PointCloud::Ptr;
322 
326 
330 
331  /** \brief Empty constructor.
332  * \param[in] random if true set the random seed to the current time, else set to 12345 (default: false)
333  */
334  SACSegmentationFromNormals (bool random = false)
335  : SACSegmentation<PointT> (random)
336  {};
337 
338  /** \brief Provide a pointer to the input dataset that contains the point normals of
339  * the XYZ dataset.
340  * \param[in] normals the const shared pointer to a PointCloud message
341  */
342  inline void
343  setInputNormals (const PointCloudNConstPtr &normals) { normals_ = normals; }
344 
345  /** \brief Get a pointer to the normals of the input XYZ point cloud dataset. */
346  inline PointCloudNConstPtr
347  getInputNormals () const { return (normals_); }
348 
349  /** \brief Set the relative weight (between 0 and 1) to give to the angular
350  * distance (0 to pi/2) between point normals and the plane normal.
351  * \param[in] distance_weight the distance/angular weight
352  */
353  inline void
354  setNormalDistanceWeight (double distance_weight) { distance_weight_ = distance_weight; }
355 
356  /** \brief Get the relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point
357  * normals and the plane normal. */
358  inline double
360 
361  /** \brief Set the minimum opning angle for a cone model.
362  * \param min_angle the opening angle which we need minimum to validate a cone model.
363  * \param max_angle the opening angle which we need maximum to validate a cone model.
364  */
365  inline void
366  setMinMaxOpeningAngle (const double &min_angle, const double &max_angle)
367  {
368  min_angle_ = min_angle;
369  max_angle_ = max_angle;
370  }
371 
372  /** \brief Get the opening angle which we need minimum to validate a cone model. */
373  inline void
374  getMinMaxOpeningAngle (double &min_angle, double &max_angle)
375  {
376  min_angle = min_angle_;
377  max_angle = max_angle_;
378  }
379 
380  /** \brief Set the distance we expect a plane model to be from the origin
381  * \param[in] d distance from the template plane model to the origin
382  */
383  inline void
385 
386  /** \brief Get the distance of a plane model from the origin. */
387  inline double
389 
390  protected:
391  /** \brief A pointer to the input dataset that contains the point normals of the XYZ dataset. */
393 
394  /** \brief The relative weight (between 0 and 1) to give to the angular
395  * distance (0 to pi/2) between point normals and the plane normal.
396  */
397  double distance_weight_{0.1};
398 
399  /** \brief The distance from the template plane to the origin. */
401 
402  /** \brief The minimum and maximum allowed opening angle of valid cone model. */
403  double min_angle_{0.0};
405 
406  /** \brief Initialize the Sample Consensus model and set its parameters.
407  * \param[in] model_type the type of SAC model that is to be used
408  */
409  bool
410  initSACModel (const int model_type) override;
411 
412  /** \brief Class get name method. */
413  std::string
414  getClassName () const override { return ("SACSegmentationFromNormals"); }
415  };
416 }
417 
418 #ifdef PCL_NO_PRECOMPILE
419 #include <pcl/segmentation/impl/sac_segmentation.hpp>
420 #endif
PCL base class.
Definition: pcl_base.h:70
typename PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:73
typename PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:74
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:414
SACSegmentationFromNormals represents the PCL nodelet segmentation class for Sample Consensus methods...
double distance_weight_
The relative weight (between 0 and 1) to give to the angular distance (0 to pi/2) between point norma...
void setInputNormals(const PointCloudNConstPtr &normals)
Provide a pointer to the input dataset that contains the point normals of the XYZ dataset.
double min_angle_
The minimum and maximum allowed opening angle of valid cone model.
PointCloudNConstPtr getInputNormals() const
Get a pointer to the normals of the input XYZ point cloud dataset.
typename PointCloudN::ConstPtr PointCloudNConstPtr
void getMinMaxOpeningAngle(double &min_angle, double &max_angle)
Get the opening angle which we need minimum to validate a cone model.
std::string getClassName() const override
Class get name method.
SACSegmentationFromNormals(bool random=false)
Empty constructor.
bool initSACModel(const int model_type) override
Initialize the Sample Consensus model and set its parameters.
void setMinMaxOpeningAngle(const double &min_angle, const double &max_angle)
Set the minimum opning angle for a cone model.
PointCloudNConstPtr normals_
A pointer to the input dataset that contains the point normals of the XYZ dataset.
double distance_from_origin_
The distance from the template plane to the origin.
void setDistanceFromOrigin(const double d)
Set the distance we expect a plane model to be from the origin.
typename SampleConsensusModelFromNormals< PointT, PointNT >::Ptr SampleConsensusModelFromNormalsPtr
double getDistanceFromOrigin() const
Get the distance of a plane model from the origin.
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 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...
SACSegmentation represents the Nodelet segmentation class for Sample Consensus methods and models,...
int getMethodType() const
Get the type of sample consensus method used.
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...
SampleConsensusModelPtr model_
The model that needs to be segmented.
~SACSegmentation() override=default
Empty destructor.
void setMethodType(int method)
The type of sample consensus method to use (user given parameter).
void setAxis(const Eigen::Vector3f &ax)
Set the axis along which we need to search for a model perpendicular to.
virtual void initSAC(const int method_type)
Initialize the Sample Consensus method and set its parameters.
double probability_
Desired probability of choosing at least one sample free from outliers (user given parameter).
double getDistanceThreshold() const
Get the distance to the model threshold.
double getProbability() const
Get the probability of choosing at least one sample free from outliers.
int model_type_
The type of model to use (user given parameter).
void setMaxIterations(int max_iterations)
Set the maximum number of iterations before giving up.
virtual void segment(PointIndices &inliers, ModelCoefficients &model_coefficients)
Base method for segmentation of a model in a PointCloud given by <setInputCloud (),...
bool getOptimizeCoefficients() const
Get the coefficient refinement internal flag.
SampleConsensusPtr getMethod() const
Get a pointer to the SAC method used.
void setProbability(double probability)
Set the probability of choosing at least one sample free from outliers.
virtual bool initSACModel(const int model_type)
Initialize the Sample Consensus model and set its parameters.
void setEpsAngle(double ea)
Set the angle epsilon (delta) threshold.
bool random_
Set to true if we need a random seed.
SampleConsensusPtr sac_
The sample consensus segmentation method.
typename SampleConsensusModel< PointT >::Ptr SampleConsensusModelPtr
double radius_min_
The minimum and maximum radius limits for the model.
virtual std::string getClassName() const
Class get name method.
SearchPtr samples_radius_search_
The search object for picking subsequent samples using radius search.
double getEpsAngle() const
Get the epsilon (delta) model angle threshold in radians.
void getSamplesMaxDist(double &radius)
Get maximum distance allowed when drawing random samples.
int getModelType() const
Get the type of SAC model used.
void setModelType(int model)
The type of model to use (user given parameter).
void setDistanceThreshold(double threshold)
Distance to the model threshold (user given parameter).
typename pcl::search::Search< PointT >::Ptr SearchPtr
Eigen::Vector3f axis_
The axis along which we need to search for a model perpendicular to.
bool optimize_coefficients_
Set to true if a coefficient refinement is required.
void setNumberOfThreads(const int nr_threads=-1)
Set the number of threads to use or turn off parallelization.
double eps_angle_
The maximum allowed difference between the model normal and the given axis.
SampleConsensusModelPtr getModel() const
Get a pointer to the SAC model used.
void setSamplesMaxDist(const double &radius, SearchPtr search)
Set the maximum distance allowed when drawing random samples.
void setOptimizeCoefficients(bool optimize)
Set to true if a coefficient refinement is required.
double samples_radius_
The maximum distance of subsequent samples from the first (radius search)
typename SampleConsensus< PointT >::Ptr SampleConsensusPtr
int getMaxIterations() const
Get maximum number of iterations before giving up.
SACSegmentation(bool random=false)
Empty constructor.
void getRadiusLimits(double &min_radius, double &max_radius)
Get the minimum and maximum allowable radius limits for the model as set by the user.
int method_type_
The type of sample consensus method to use (user given parameter).
double threshold_
Distance to the model threshold (user given parameter).
Eigen::Vector3f getAxis() const
Get the axis along which we need to search for a model perpendicular to.
int max_iterations_
Maximum number of iterations before giving up (user given parameter).
int threads_
The number of threads the scheduler should use, or a negative number if no parallelization is wanted.
SampleConsensus represents the base class.
Definition: sac.h:61
shared_ptr< SampleConsensusModelFromNormals< PointT, PointNT > > Ptr
Definition: sac_model.h:618
shared_ptr< SampleConsensusModel< PointT > > Ptr
Definition: sac_model.h:78
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:81
#define M_PI_2
Definition: pcl_macros.h:202
A point structure representing Euclidean xyz coordinates, and the RGB color.