Point Cloud Library (PCL)  1.12.0-dev
organized_multi_plane_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/segmentation/planar_region.h>
43 #include <pcl/pcl_base.h>
44 #include <pcl/pcl_macros.h>
45 #include <pcl/common/angles.h>
46 #include <pcl/common/utils.h>
47 #include <pcl/PointIndices.h>
48 #include <pcl/ModelCoefficients.h>
49 #include <pcl/segmentation/plane_coefficient_comparator.h>
50 #include <pcl/segmentation/plane_refinement_comparator.h>
51 
52 namespace pcl
53 {
54  /** \brief OrganizedMultiPlaneSegmentation finds all planes present in the
55  * input cloud, and outputs a vector of plane equations, as well as a vector
56  * of point clouds corresponding to the inliers of each detected plane. Only
57  * planes with more than min_inliers points are detected.
58  * Templated on point type, normal type, and label type
59  *
60  * \author Alex Trevor, Suat Gedikli
61  */
62  template<typename PointT, typename PointNT, typename PointLT>
64  {
69 
70  public:
72  using PointCloudPtr = typename PointCloud::Ptr;
74 
76  using PointCloudNPtr = typename PointCloudN::Ptr;
78 
80  using PointCloudLPtr = typename PointCloudL::Ptr;
82 
86 
90 
91  /** \brief Constructor for OrganizedMultiPlaneSegmentation. */
93  normals_ (),
94  min_inliers_ (1000),
95  angular_threshold_ (pcl::deg2rad (3.0)),
96  distance_threshold_ (0.02),
97  maximum_curvature_ (0.001),
98  project_points_ (false),
100  {
101  }
102 
103  /** \brief Destructor for OrganizedMultiPlaneSegmentation. */
104 
106  {
107  }
108 
109  /** \brief Provide a pointer to the input normals.
110  * \param[in] normals the input normal cloud
111  */
112  inline void
114  {
115  normals_ = normals;
116  }
117 
118  /** \brief Get the input normals. */
119  inline PointCloudNConstPtr
121  {
122  return (normals_);
123  }
124 
125  /** \brief Set the minimum number of inliers required for a plane
126  * \param[in] min_inliers the minimum number of inliers required per plane
127  */
128  inline void
129  setMinInliers (unsigned min_inliers)
130  {
131  min_inliers_ = min_inliers;
132  }
133 
134  /** \brief Get the minimum number of inliers required per plane. */
135  inline unsigned
136  getMinInliers () const
137  {
138  return (min_inliers_);
139  }
140 
141  /** \brief Set the tolerance in radians for difference in normal direction between neighboring points, to be considered part of the same plane.
142  * \param[in] angular_threshold the tolerance in radians
143  */
144  inline void
145  setAngularThreshold (double angular_threshold)
146  {
147  angular_threshold_ = angular_threshold;
148  }
149 
150  /** \brief Get the angular threshold in radians for difference in normal direction between neighboring points, to be considered part of the same plane. */
151  inline double
153  {
154  return (angular_threshold_);
155  }
156 
157  /** \brief Set the tolerance in meters for difference in perpendicular distance (d component of plane equation) to the plane between neighboring points, to be considered part of the same plane.
158  * \param[in] distance_threshold the tolerance in meters
159  */
160  inline void
161  setDistanceThreshold (double distance_threshold)
162  {
163  distance_threshold_ = distance_threshold;
164  }
165 
166  /** \brief Get the distance threshold in meters (d component of plane equation) between neighboring points, to be considered part of the same plane. */
167  inline double
169  {
170  return (distance_threshold_);
171  }
172 
173  /** \brief Set the maximum curvature allowed for a planar region.
174  * \param[in] maximum_curvature the maximum curvature
175  */
176  inline void
177  setMaximumCurvature (double maximum_curvature)
178  {
179  maximum_curvature_ = maximum_curvature;
180  }
181 
182  /** \brief Get the maximum curvature allowed for a planar region. */
183  inline double
185  {
186  return (maximum_curvature_);
187  }
188 
189  /** \brief Provide a pointer to the comparator to be used for segmentation.
190  * \param[in] compare A pointer to the comparator to be used for segmentation.
191  */
192  void
194  {
195  compare_ = compare;
196  }
197 
198  /** \brief Provide a pointer to the comparator to be used for refinement.
199  * \param[in] compare A pointer to the comparator to be used for refinement.
200  */
201  void
203  {
204  refinement_compare_ = compare;
205  }
206 
207  /** \brief Set whether or not to project boundary points to the plane, or leave them in the original 3D space.
208  * \param[in] project_points true if points should be projected, false if not.
209  */
210  void
211  setProjectPoints (bool project_points)
212  {
213  project_points_ = project_points;
214  }
215 
216  /** \brief Segmentation of all planes in a point cloud given by setInputCloud(), setIndices()
217  * \param[out] model_coefficients a vector of model_coefficients for each plane found in the input cloud
218  * \param[out] inlier_indices a vector of inliers for each detected plane
219  * \param[out] centroids a vector of centroids for each plane
220  * \param[out] covariances a vector of covariance matricies for the inliers of each plane
221  * \param[out] labels a point cloud for the connected component labels of each pixel
222  * \param[out] label_indices a vector of PointIndices for each labeled component
223  */
224  void
225  segment (std::vector<ModelCoefficients>& model_coefficients,
226  std::vector<PointIndices>& inlier_indices,
227  std::vector<Eigen::Vector4f, Eigen::aligned_allocator<Eigen::Vector4f> >& centroids,
228  std::vector <Eigen::Matrix3f, Eigen::aligned_allocator<Eigen::Matrix3f> >& covariances,
229  pcl::PointCloud<PointLT>& labels,
230  std::vector<pcl::PointIndices>& label_indices);
231 
232  /** \brief Segmentation of all planes in a point cloud given by setInputCloud(), setIndices()
233  * \param[out] model_coefficients a vector of model_coefficients for each plane found in the input cloud
234  * \param[out] inlier_indices a vector of inliers for each detected plane
235  */
236  void
237  segment (std::vector<ModelCoefficients>& model_coefficients,
238  std::vector<PointIndices>& inlier_indices);
239 
240  /** \brief Segmentation of all planes in a point cloud given by setInputCloud(), setIndices()
241  * \param[out] regions a list of resultant planar polygonal regions
242  */
243  void
244  segment (std::vector<PlanarRegion<PointT>, Eigen::aligned_allocator<PlanarRegion<PointT> > >& regions);
245 
246  /** \brief Perform a segmentation, as well as an additional refinement step. This helps with including points whose normals may not match neighboring points well, but may match the planar model well.
247  * \param[out] regions A list of regions generated by segmentation and refinement.
248  */
249  void
250  segmentAndRefine (std::vector<PlanarRegion<PointT>, Eigen::aligned_allocator<PlanarRegion<PointT> > >& regions);
251 
252  /** \brief Perform a segmentation, as well as additional refinement step. Returns intermediate data structures for use in
253  * subsequent processing.
254  * \param[out] regions A vector of PlanarRegions generated by segmentation
255  * \param[out] model_coefficients A vector of model coefficients for each segmented plane
256  * \param[out] inlier_indices A vector of PointIndices, indicating the inliers to each segmented plane
257  * \param[out] labels A PointCloud<PointLT> corresponding to the resulting segmentation.
258  * \param[out] label_indices A vector of PointIndices for each label
259  * \param[out] boundary_indices A vector of PointIndices corresponding to the outer boundary / contour of each label
260  */
261  void
262  segmentAndRefine (std::vector<PlanarRegion<PointT>, Eigen::aligned_allocator<PlanarRegion<PointT> > >& regions,
263  std::vector<ModelCoefficients>& model_coefficients,
264  std::vector<PointIndices>& inlier_indices,
265  PointCloudLPtr& labels,
266  std::vector<pcl::PointIndices>& label_indices,
267  std::vector<pcl::PointIndices>& boundary_indices);
268 
269  /** \brief Perform a refinement of an initial segmentation, by comparing points to adjacent regions detected by the initial segmentation.
270  * \param [in] model_coefficients The list of segmented model coefficients
271  * \param [in] inlier_indices The list of segmented inlier indices, corresponding to each model
272  * \param [in] labels The labels produced by the initial segmentation
273  * \param [in] label_indices The list of indices corresponding to each label
274  */
275  void
276  refine (std::vector<ModelCoefficients>& model_coefficients,
277  std::vector<PointIndices>& inlier_indices,
278  PointCloudLPtr& labels,
279  std::vector<pcl::PointIndices>& label_indices);
280 
281  protected:
282 
283  /** \brief A pointer to the input normals */
285 
286  /** \brief The minimum number of inliers required for each plane. */
287  unsigned min_inliers_;
288 
289  /** \brief The tolerance in radians for difference in normal direction between neighboring points, to be considered part of the same plane. */
291 
292  /** \brief The tolerance in meters for difference in perpendicular distance (d component of plane equation) to the plane between neighboring points, to be considered part of the same plane. */
294 
295  /** \brief The tolerance for maximum curvature after fitting a plane. Used to remove smooth, but non-planar regions. */
297 
298  /** \brief Whether or not points should be projected to the plane, or left in the original 3D space. */
300 
301  /** \brief A comparator for comparing neighboring pixels' plane equations. */
303 
304  /** \brief A comparator for use on the refinement step. Compares points to regions segmented in the first pass. */
306 
307  /** \brief Class getName method. */
308  virtual std::string
309  getClassName () const
310  {
311  return ("OrganizedMultiPlaneSegmentation");
312  }
313  };
314 
315 }
316 
317 #ifdef PCL_NO_PRECOMPILE
318 #include <pcl/segmentation/impl/organized_multi_plane_segmentation.hpp>
319 #endif
pcl_macros.h
Defines all the PCL and non-PCL macros used.
pcl
Definition: convolution.h:46
pcl::OrganizedMultiPlaneSegmentation::setAngularThreshold
void setAngularThreshold(double angular_threshold)
Set the tolerance in radians for difference in normal direction between neighboring points,...
Definition: organized_multi_plane_segmentation.h:145
pcl::PCLBase< pcl::PointXYZRGBA >::PointCloudConstPtr
typename PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:74
pcl::PCLBase< pcl::PointXYZRGBA >::PointCloudPtr
typename PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:73
pcl::OrganizedMultiPlaneSegmentation::refine
void refine(std::vector< ModelCoefficients > &model_coefficients, std::vector< PointIndices > &inlier_indices, PointCloudLPtr &labels, std::vector< pcl::PointIndices > &label_indices)
Perform a refinement of an initial segmentation, by comparing points to adjacent regions detected by ...
Definition: organized_multi_plane_segmentation.hpp:321
pcl::OrganizedMultiPlaneSegmentation::setRefinementComparator
void setRefinementComparator(const PlaneRefinementComparatorPtr &compare)
Provide a pointer to the comparator to be used for refinement.
Definition: organized_multi_plane_segmentation.h:202
pcl::OrganizedMultiPlaneSegmentation::OrganizedMultiPlaneSegmentation
OrganizedMultiPlaneSegmentation()
Constructor for OrganizedMultiPlaneSegmentation.
Definition: organized_multi_plane_segmentation.h:92
pcl::OrganizedMultiPlaneSegmentation::compare_
PlaneComparatorPtr compare_
A comparator for comparing neighboring pixels' plane equations.
Definition: organized_multi_plane_segmentation.h:302
pcl::OrganizedMultiPlaneSegmentation::setMinInliers
void setMinInliers(unsigned min_inliers)
Set the minimum number of inliers required for a plane.
Definition: organized_multi_plane_segmentation.h:129
pcl::OrganizedMultiPlaneSegmentation::refinement_compare_
PlaneRefinementComparatorPtr refinement_compare_
A comparator for use on the refinement step.
Definition: organized_multi_plane_segmentation.h:305
pcl::PlaneCoefficientComparator::Ptr
shared_ptr< PlaneCoefficientComparator< PointT, PointNT > > Ptr
Definition: plane_coefficient_comparator.h:65
pcl::PCLBase
PCL base class.
Definition: pcl_base.h:69
pcl::OrganizedMultiPlaneSegmentation::getClassName
virtual std::string getClassName() const
Class getName method.
Definition: organized_multi_plane_segmentation.h:309
pcl::OrganizedMultiPlaneSegmentation::~OrganizedMultiPlaneSegmentation
~OrganizedMultiPlaneSegmentation()
Destructor for OrganizedMultiPlaneSegmentation.
Definition: organized_multi_plane_segmentation.h:105
pcl::PointCloud< pcl::PointXYZRGBA >
pcl::OrganizedMultiPlaneSegmentation::getDistanceThreshold
double getDistanceThreshold() const
Get the distance threshold in meters (d component of plane equation) between neighboring points,...
Definition: organized_multi_plane_segmentation.h:168
pcl::OrganizedMultiPlaneSegmentation::segment
void segment(std::vector< ModelCoefficients > &model_coefficients, std::vector< PointIndices > &inlier_indices, std::vector< Eigen::Vector4f, Eigen::aligned_allocator< Eigen::Vector4f > > &centroids, std::vector< Eigen::Matrix3f, Eigen::aligned_allocator< Eigen::Matrix3f > > &covariances, pcl::PointCloud< PointLT > &labels, std::vector< pcl::PointIndices > &label_indices)
Segmentation of all planes in a point cloud given by setInputCloud(), setIndices()
Definition: organized_multi_plane_segmentation.hpp:83
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PointCloudNConstPtr
typename PointCloudN::ConstPtr PointCloudNConstPtr
Definition: organized_multi_plane_segmentation.h:77
pcl::OrganizedMultiPlaneSegmentation::setInputNormals
void setInputNormals(const PointCloudNConstPtr &normals)
Provide a pointer to the input normals.
Definition: organized_multi_plane_segmentation.h:113
pcl::OrganizedMultiPlaneSegmentation::segmentAndRefine
void segmentAndRefine(std::vector< PlanarRegion< PointT >, Eigen::aligned_allocator< PlanarRegion< PointT > > > &regions)
Perform a segmentation, as well as an additional refinement step.
Definition: organized_multi_plane_segmentation.hpp:233
pcl::OrganizedMultiPlaneSegmentation::setComparator
void setComparator(const PlaneComparatorPtr &compare)
Provide a pointer to the comparator to be used for segmentation.
Definition: organized_multi_plane_segmentation.h:193
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PlaneComparatorPtr
typename PlaneComparator::Ptr PlaneComparatorPtr
Definition: organized_multi_plane_segmentation.h:84
angles.h
pcl::OrganizedMultiPlaneSegmentation
OrganizedMultiPlaneSegmentation finds all planes present in the input cloud, and outputs a vector of ...
Definition: organized_multi_plane_segmentation.h:63
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PointCloudLPtr
typename PointCloudL::Ptr PointCloudLPtr
Definition: organized_multi_plane_segmentation.h:80
pcl::OrganizedMultiPlaneSegmentation::getInputNormals
PointCloudNConstPtr getInputNormals() const
Get the input normals.
Definition: organized_multi_plane_segmentation.h:120
pcl::OrganizedMultiPlaneSegmentation::min_inliers_
unsigned min_inliers_
The minimum number of inliers required for each plane.
Definition: organized_multi_plane_segmentation.h:287
pcl::OrganizedMultiPlaneSegmentation::maximum_curvature_
double maximum_curvature_
The tolerance for maximum curvature after fitting a plane.
Definition: organized_multi_plane_segmentation.h:296
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PointCloudNPtr
typename PointCloudN::Ptr PointCloudNPtr
Definition: organized_multi_plane_segmentation.h:76
pcl::deg2rad
float deg2rad(float alpha)
Convert an angle from degrees to radians.
Definition: angles.hpp:67
pcl::OrganizedMultiPlaneSegmentation::getMinInliers
unsigned getMinInliers() const
Get the minimum number of inliers required per plane.
Definition: organized_multi_plane_segmentation.h:136
pcl::OrganizedMultiPlaneSegmentation::project_points_
bool project_points_
Whether or not points should be projected to the plane, or left in the original 3D space.
Definition: organized_multi_plane_segmentation.h:299
pcl::PlanarRegion
PlanarRegion represents a set of points that lie in a plane.
Definition: planar_region.h:51
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PlaneComparatorConstPtr
typename PlaneComparator::ConstPtr PlaneComparatorConstPtr
Definition: organized_multi_plane_segmentation.h:85
pcl::PlaneRefinementComparator::ConstPtr
shared_ptr< const PlaneRefinementComparator< PointT, PointNT, PointLT > > ConstPtr
Definition: plane_refinement_comparator.h:69
pcl::PlaneRefinementComparator::Ptr
shared_ptr< PlaneRefinementComparator< PointT, PointNT, PointLT > > Ptr
Definition: plane_refinement_comparator.h:68
pcl::OrganizedMultiPlaneSegmentation::getAngularThreshold
double getAngularThreshold() const
Get the angular threshold in radians for difference in normal direction between neighboring points,...
Definition: organized_multi_plane_segmentation.h:152
pcl::OrganizedMultiPlaneSegmentation::setMaximumCurvature
void setMaximumCurvature(double maximum_curvature)
Set the maximum curvature allowed for a planar region.
Definition: organized_multi_plane_segmentation.h:177
pcl::OrganizedMultiPlaneSegmentation::angular_threshold_
double angular_threshold_
The tolerance in radians for difference in normal direction between neighboring points,...
Definition: organized_multi_plane_segmentation.h:290
pcl::PointCloud::Ptr
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PlaneRefinementComparatorPtr
typename PlaneRefinementComparator::Ptr PlaneRefinementComparatorPtr
Definition: organized_multi_plane_segmentation.h:88
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PlaneRefinementComparatorConstPtr
typename PlaneRefinementComparator::ConstPtr PlaneRefinementComparatorConstPtr
Definition: organized_multi_plane_segmentation.h:89
pcl::OrganizedMultiPlaneSegmentation::setProjectPoints
void setProjectPoints(bool project_points)
Set whether or not to project boundary points to the plane, or leave them in the original 3D space.
Definition: organized_multi_plane_segmentation.h:211
pcl::PointCloud::ConstPtr
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:414
pcl::OrganizedMultiPlaneSegmentation::normals_
PointCloudNConstPtr normals_
A pointer to the input normals.
Definition: organized_multi_plane_segmentation.h:284
pcl::PlaneCoefficientComparator::ConstPtr
shared_ptr< const PlaneCoefficientComparator< PointT, PointNT > > ConstPtr
Definition: plane_coefficient_comparator.h:66
pcl::PlaneRefinementComparator
PlaneRefinementComparator is a Comparator that operates on plane coefficients, for use in planar segm...
Definition: plane_refinement_comparator.h:54
pcl::OrganizedMultiPlaneSegmentation< pcl::PointXYZRGBA, pcl::Normal, pcl::Label >::PointCloudLConstPtr
typename PointCloudL::ConstPtr PointCloudLConstPtr
Definition: organized_multi_plane_segmentation.h:81
pcl::OrganizedMultiPlaneSegmentation::distance_threshold_
double distance_threshold_
The tolerance in meters for difference in perpendicular distance (d component of plane equation) to t...
Definition: organized_multi_plane_segmentation.h:293
pcl::OrganizedMultiPlaneSegmentation::getMaximumCurvature
double getMaximumCurvature() const
Get the maximum curvature allowed for a planar region.
Definition: organized_multi_plane_segmentation.h:184
pcl::OrganizedMultiPlaneSegmentation::setDistanceThreshold
void setDistanceThreshold(double distance_threshold)
Set the tolerance in meters for difference in perpendicular distance (d component of plane equation) ...
Definition: organized_multi_plane_segmentation.h:161
pcl::PlaneCoefficientComparator
PlaneCoefficientComparator is a Comparator that operates on plane coefficients, for use in planar seg...
Definition: plane_coefficient_comparator.h:55