Point Cloud Library (PCL) 1.12.1
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
55namespace 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
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)
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). */
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. */
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. */
304
305 /** \brief Desired probability of choosing at least one sample free from outliers (user given parameter). */
307
308 /** \brief Set to true if we need a random seed. */
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:
332 using PCLBase<PointT>::input_;
334
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)
355 , min_angle_ (0.0)
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 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
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
406
407 /** \brief Get the distance of a plane model from the origin. */
408 inline double
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. */
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
PCL base class.
Definition: pcl_base.h:70
PointCloudConstPtr input_
The input point cloud dataset.
Definition: pcl_base.h:147
typename PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:73
typename PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:74
IndicesPtr indices_
A pointer to the vector of point indices to use.
Definition: pcl_base.h:150
bool initCompute()
This method should get called before starting the actual computation.
Definition: pcl_base.hpp:138
bool deinitCompute()
This method should get called after finishing the actual computation.
Definition: pcl_base.hpp:174
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.
~SACSegmentation()
Empty destructor.
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.
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:617
shared_ptr< SampleConsensusModel< PointT > > Ptr
Definition: sac_model.h:77
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:81
Definition: bfgs.h:10
#define M_PI_2
Definition: pcl_macros.h:202
A point structure representing Euclidean xyz coordinates, and the RGB color.