Point Cloud Library (PCL)  1.10.0-dev
region_growing.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  *
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * * Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  * * Redistributions in binary form must reproduce the above
15  * copyright notice, this list of conditions and the following
16  * disclaimer in the documentation and/or other materials provided
17  * with the distribution.
18  * * Neither the name of the copyright holder(s) nor the names of its
19  * contributors may be used to endorse or promote products derived
20  * from this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
25  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
26  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
27  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
30  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  *
35  * Author : Sergey Ushakov
36  * Email : mine_all_mine@bk.ru
37  *
38  */
39 
40 #pragma once
41 
42 #include <pcl/pcl_base.h>
43 #include <pcl/pcl_macros.h>
44 #include <pcl/search/search.h>
45 #include <pcl/point_cloud.h>
46 #include <pcl/point_types.h>
47 #include <list>
48 #include <cmath>
49 #include <ctime>
50 
51 namespace pcl
52 {
53  /** \brief
54  * Implements the well known Region Growing algorithm used for segmentation.
55  * Description can be found in the article
56  * "Segmentation of point clouds using smoothness constraint"
57  * by T. Rabbania, F. A. van den Heuvelb, G. Vosselmanc.
58  * In addition to residual test, the possibility to test curvature is added.
59  */
60  template <typename PointT, typename NormalT>
61  class PCL_EXPORTS RegionGrowing : public pcl::PCLBase<PointT>
62  {
63  public:
64 
66  using KdTreePtr = typename KdTree::Ptr;
68  using NormalPtr = typename Normal::Ptr;
70 
75 
76  public:
77 
78  /** \brief Constructor that sets default values for member variables. */
79  RegionGrowing ();
80 
81  /** \brief This destructor destroys the cloud, normals and search method used for
82  * finding KNN. In other words it frees memory.
83  */
84 
85  ~RegionGrowing ();
86 
87  /** \brief Get the minimum number of points that a cluster needs to contain in order to be considered valid. */
88  int
89  getMinClusterSize ();
90 
91  /** \brief Set the minimum number of points that a cluster needs to contain in order to be considered valid. */
92  void
93  setMinClusterSize (int min_cluster_size);
94 
95  /** \brief Get the maximum number of points that a cluster needs to contain in order to be considered valid. */
96  int
97  getMaxClusterSize ();
98 
99  /** \brief Set the maximum number of points that a cluster needs to contain in order to be considered valid. */
100  void
101  setMaxClusterSize (int max_cluster_size);
102 
103  /** \brief Returns the flag value. This flag signalizes which mode of algorithm will be used.
104  * If it is set to true than it will work as said in the article. This means that
105  * it will be testing the angle between normal of the current point and it's neighbours normal.
106  * Otherwise, it will be testing the angle between normal of the current point
107  * and normal of the initial point that was chosen for growing new segment.
108  */
109  bool
110  getSmoothModeFlag () const;
111 
112  /** \brief This function allows to turn on/off the smoothness constraint.
113  * \param[in] value new mode value, if set to true then the smooth version will be used.
114  */
115  void
116  setSmoothModeFlag (bool value);
117 
118  /** \brief Returns the flag that signalize if the curvature test is turned on/off. */
119  bool
120  getCurvatureTestFlag () const;
121 
122  /** \brief Allows to turn on/off the curvature test. Note that at least one test
123  * (residual or curvature) must be turned on. If you are turning curvature test off
124  * then residual test will be turned on automatically.
125  * \param[in] value new value for curvature test. If set to true then the test will be turned on
126  */
127  virtual void
128  setCurvatureTestFlag (bool value);
129 
130  /** \brief Returns the flag that signalize if the residual test is turned on/off. */
131  bool
132  getResidualTestFlag () const;
133 
134  /** \brief
135  * Allows to turn on/off the residual test. Note that at least one test
136  * (residual or curvature) must be turned on. If you are turning residual test off
137  * then curvature test will be turned on automatically.
138  * \param[in] value new value for residual test. If set to true then the test will be turned on
139  */
140  virtual void
141  setResidualTestFlag (bool value);
142 
143  /** \brief Returns smoothness threshold. */
144  float
145  getSmoothnessThreshold () const;
146 
147  /** \brief Allows to set smoothness threshold used for testing the points.
148  * \param[in] theta new threshold value for the angle between normals
149  */
150  void
151  setSmoothnessThreshold (float theta);
152 
153  /** \brief Returns residual threshold. */
154  float
155  getResidualThreshold () const;
156 
157  /** \brief Allows to set residual threshold used for testing the points.
158  * \param[in] residual new threshold value for residual testing
159  */
160  void
161  setResidualThreshold (float residual);
162 
163  /** \brief Returns curvature threshold. */
164  float
165  getCurvatureThreshold () const;
166 
167  /** \brief Allows to set curvature threshold used for testing the points.
168  * \param[in] curvature new threshold value for curvature testing
169  */
170  void
171  setCurvatureThreshold (float curvature);
172 
173  /** \brief Returns the number of nearest neighbours used for KNN. */
174  unsigned int
175  getNumberOfNeighbours () const;
176 
177  /** \brief Allows to set the number of neighbours. For more information check the article.
178  * \param[in] neighbour_number number of neighbours to use
179  */
180  void
181  setNumberOfNeighbours (unsigned int neighbour_number);
182 
183  /** \brief Returns the pointer to the search method that is used for KNN. */
184  KdTreePtr
185  getSearchMethod () const;
186 
187  /** \brief Allows to set search method that will be used for finding KNN.
188  * \param[in] tree pointer to a KdTree
189  */
190  void
191  setSearchMethod (const KdTreePtr& tree);
192 
193  /** \brief Returns normals. */
194  NormalPtr
195  getInputNormals () const;
196 
197  /** \brief This method sets the normals. They are needed for the algorithm, so if
198  * no normals will be set, the algorithm would not be able to segment the points.
199  * \param[in] norm normals that will be used in the algorithm
200  */
201  void
202  setInputNormals (const NormalPtr& norm);
203 
204  /** \brief This method launches the segmentation algorithm and returns the clusters that were
205  * obtained during the segmentation.
206  * \param[out] clusters clusters that were obtained. Each cluster is an array of point indices.
207  */
208  virtual void
209  extract (std::vector <pcl::PointIndices>& clusters);
210 
211  /** \brief For a given point this function builds a segment to which it belongs and returns this segment.
212  * \param[in] index index of the initial point which will be the seed for growing a segment.
213  * \param[out] cluster cluster to which the point belongs.
214  */
215  virtual void
216  getSegmentFromPoint (int index, pcl::PointIndices& cluster);
217 
218  /** \brief If the cloud was successfully segmented, then function
219  * returns colored cloud. Otherwise it returns an empty pointer.
220  * Points that belong to the same segment have the same color.
221  * But this function doesn't guarantee that different segments will have different
222  * color(it all depends on RNG). Points that were not listed in the indices array will have red color.
223  */
225  getColoredCloud ();
226 
227  /** \brief If the cloud was successfully segmented, then function
228  * returns colored cloud. Otherwise it returns an empty pointer.
229  * Points that belong to the same segment have the same color.
230  * But this function doesn't guarantee that different segments will have different
231  * color(it all depends on RNG). Points that were not listed in the indices array will have red color.
232  */
234  getColoredCloudRGBA ();
235 
236  protected:
237 
238  /** \brief This method simply checks if it is possible to execute the segmentation algorithm with
239  * the current settings. If it is possible then it returns true.
240  */
241  virtual bool
242  prepareForSegmentation ();
243 
244  /** \brief This method finds KNN for each point and saves them to the array
245  * because the algorithm needs to find KNN a few times.
246  */
247  virtual void
248  findPointNeighbours ();
249 
250  /** \brief This function implements the algorithm described in the article
251  * "Segmentation of point clouds using smoothness constraint"
252  * by T. Rabbania, F. A. van den Heuvelb, G. Vosselmanc.
253  */
254  void
255  applySmoothRegionGrowingAlgorithm ();
256 
257  /** \brief This method grows a segment for the given seed point. And returns the number of its points.
258  * \param[in] initial_seed index of the point that will serve as the seed point
259  * \param[in] segment_number indicates which number this segment will have
260  */
261  int
262  growRegion (int initial_seed, int segment_number);
263 
264  /** \brief This function is checking if the point with index 'nghbr' belongs to the segment.
265  * If so, then it returns true. It also checks if this point can serve as the seed.
266  * \param[in] initial_seed index of the initial point that was passed to the growRegion() function
267  * \param[in] point index of the current seed point
268  * \param[in] nghbr index of the point that is neighbour of the current seed
269  * \param[out] is_a_seed this value is set to true if the point with index 'nghbr' can serve as the seed
270  */
271  virtual bool
272  validatePoint (int initial_seed, int point, int nghbr, bool& is_a_seed) const;
273 
274  /** \brief This function simply assembles the regions from list of point labels.
275  * Each cluster is an array of point indices.
276  */
277  void
278  assembleRegions ();
279 
280  protected:
281 
282  /** \brief Stores the minimum number of points that a cluster needs to contain in order to be considered valid. */
284 
285  /** \brief Stores the maximum number of points that a cluster needs to contain in order to be considered valid. */
287 
288  /** \brief Flag that signalizes if the smoothness constraint will be used. */
290 
291  /** \brief If set to true then curvature test will be done during segmentation. */
293 
294  /** \brief If set to true then residual test will be done during segmentation. */
296 
297  /** \brief Thershold used for testing the smoothness between points. */
299 
300  /** \brief Thershold used in residual test. */
302 
303  /** \brief Thershold used in curvature test. */
305 
306  /** \brief Number of neighbours to find. */
307  unsigned int neighbour_number_;
308 
309  /** \brief Serch method that will be used for KNN. */
311 
312  /** \brief Contains normals of the points that will be segmented. */
314 
315  /** \brief Contains neighbours of each point. */
316  std::vector<std::vector<int> > point_neighbours_;
317 
318  /** \brief Point labels that tells to which segment each point belongs. */
319  std::vector<int> point_labels_;
320 
321  /** \brief If set to true then normal/smoothness test will be done during segmentation.
322  * It is always set to true for the usual region growing algorithm. It is used for turning on/off the test
323  * for smoothness in the child class RegionGrowingRGB.*/
325 
326  /** \brief Tells how much points each segment contains. Used for reserving memory. */
327  std::vector<int> num_pts_in_segment_;
328 
329  /** \brief After the segmentation it will contain the segments. */
330  std::vector <pcl::PointIndices> clusters_;
331 
332  /** \brief Stores the number of segments. */
334 
335  public:
337  };
338 
339  /** \brief This function is used as a comparator for sorting. */
340  inline bool
341  comparePair (std::pair<float, int> i, std::pair<float, int> j)
342  {
343  return (i.first < j.first);
344  }
345 }
346 
347 #ifdef PCL_NO_PRECOMPILE
348 #include <pcl/segmentation/impl/region_growing.hpp>
349 #endif
float theta_threshold_
Thershold used for testing the smoothness between points.
float residual_threshold_
Thershold used in residual test.
float curvature_threshold_
Thershold used in curvature test.
shared_ptr< PointCloud< NormalT > > Ptr
Definition: point_cloud.h:415
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
std::vector< int > num_pts_in_segment_
Tells how much points each segment contains.
unsigned int neighbour_number_
Number of neighbours to find.
bool residual_flag_
If set to true then residual test will be done during segmentation.
typename KdTree::Ptr KdTreePtr
int min_pts_per_cluster_
Stores the minimum number of points that a cluster needs to contain in order to be considered valid...
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: pcl_macros.h:371
shared_ptr< KdTree< PointT > > Ptr
Definition: kdtree.h:69
int number_of_segments_
Stores the number of segments.
NormalPtr normals_
Contains normals of the points that will be segmented.
int max_pts_per_cluster_
Stores the maximum number of points that a cluster needs to contain in order to be considered valid...
Implements the well known Region Growing algorithm used for segmentation.
bool comparePair(std::pair< float, int > i, std::pair< float, int > j)
This function is used as a comparator for sorting.
std::vector< pcl::PointIndices > clusters_
After the segmentation it will contain the segments.
Defines all the PCL implemented PointT point type structures.
PCL base class.
Definition: pcl_base.h:69
std::vector< int > point_labels_
Point labels that tells to which segment each point belongs.
bool smooth_mode_flag_
Flag that signalizes if the smoothness constraint will be used.
bool normal_flag_
If set to true then normal/smoothness test will be done during segmentation.
KdTreePtr search_
Serch method that will be used for KNN.
#define PCL_EXPORTS
Definition: pcl_macros.h:253
bool curvature_flag_
If set to true then curvature test will be done during segmentation.
typename Normal::Ptr NormalPtr
Defines all the PCL and non-PCL macros used.
std::vector< std::vector< int > > point_neighbours_
Contains neighbours of each point.
Generic search class.
Definition: search.h:73