Point Cloud Library (PCL) 1.15.0
Loading...
Searching...
No Matches
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 : 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). */
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. */
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:
316 using PCLBase<PointT>::input_;
318
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
PointCloudConstPtr input_
The input point cloud dataset.
Definition pcl_base.h:147
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:175
PointCloud represents the base class in PCL for storing collections of 3D points.
shared_ptr< PointCloud< PointT > > Ptr
shared_ptr< const PointCloud< PointT > > ConstPtr
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.
typename PointCloud::ConstPtr PointCloudConstPtr
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 SampleConsensusModel< PointT >::Ptr SampleConsensusModelPtr
typename SampleConsensusModelFromNormals< PointT, PointNT >::Ptr SampleConsensusModelFromNormalsPtr
double getDistanceFromOrigin() const
Get the distance of a plane model from the origin.
typename PointCloud::Ptr PointCloudPtr
typename PointCloudN::Ptr PointCloudNPtr
typename SampleConsensus< PointT >::Ptr SampleConsensusPtr
typename SACSegmentation< PointT >::PointCloud PointCloud
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.
typename PointCloud::Ptr PointCloudPtr
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.
pcl::PointCloud< PointT > PointCloud
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.
typename PointCloud::ConstPtr PointCloudConstPtr
shared_ptr< SampleConsensus< T > > Ptr
Definition sac.h:69
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:204
A point structure representing Euclidean xyz coordinates, and the RGB color.