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