Point Cloud Library (PCL)  1.7.1
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 #ifndef PCL_REGION_GROWING_H_
41 #define PCL_REGION_GROWING_H_
42 
43 #include <pcl/pcl_base.h>
44 #include <pcl/search/search.h>
45 #include <pcl/point_cloud.h>
46 #include <pcl/point_types.h>
47 #include <list>
48 #include <math.h>
49 #include <time.h>
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  typedef typename KdTree::Ptr KdTreePtr;
68  typedef typename Normal::Ptr NormalPtr;
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  virtual
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] search search method to use
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  * \param[out] clusters clusters that were obtained during the segmentation process.
276  * Each cluster is an array of point indices.
277  */
278  void
279  assembleRegions ();
280 
281  protected:
282 
283  /** \brief Stores the minimum number of points that a cluster needs to contain in order to be considered valid. */
285 
286  /** \brief Stores the maximum number of points that a cluster needs to contain in order to be considered valid. */
288 
289  /** \brief Flag that signalizes if the smoothness constraint will be used. */
291 
292  /** \brief If set to true then curvature test will be done during segmentation. */
294 
295  /** \brief If set to true then residual test will be done during segmentation. */
297 
298  /** \brief Thershold used for testing the smoothness between points. */
300 
301  /** \brief Thershold used in residual test. */
303 
304  /** \brief Thershold used in curvature test. */
306 
307  /** \brief Number of neighbours to find. */
308  unsigned int neighbour_number_;
309 
310  /** \brief Serch method that will be used for KNN. */
312 
313  /** \brief Contains normals of the points that will be segmented. */
315 
316  /** \brief Contains neighbours of each point. */
317  std::vector<std::vector<int> > point_neighbours_;
318 
319  /** \brief Point labels that tells to which segment each point belongs. */
320  std::vector<int> point_labels_;
321 
322  /** \brief If set to true then normal/smoothness test will be done during segmentation.
323  * It is always set to true for the usual region growing algorithm. It is used for turning on/off the test
324  * for smoothness in the child class RegionGrowingRGB.*/
326 
327  /** \brief Tells how much points each segment contains. Used for reserving memory. */
328  std::vector<int> num_pts_in_segment_;
329 
330  /** \brief After the segmentation it will contain the segments. */
331  std::vector <pcl::PointIndices> clusters_;
332 
333  /** \brief Stores the number of segments. */
335 
336  public:
337  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
338  };
339 
340  /** \brief This function is used as a comparator for sorting. */
341  inline bool
342  comparePair (std::pair<float, int> i, std::pair<float, int> j)
343  {
344  return (i.first < j.first);
345  }
346 }
347 
348 #ifdef PCL_NO_PRECOMPILE
349 #include <pcl/segmentation/impl/region_growing.hpp>
350 #endif
351 
352 #endif