Point Cloud Library (PCL)  1.11.1
region_growing_rgb.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/memory.h>
43 #include <pcl/pcl_macros.h>
44 #include <pcl/segmentation/region_growing.h>
45 
46 namespace pcl
47 {
48  /** \brief
49  * Implements the well known Region Growing algorithm used for segmentation based on color of points.
50  * Description can be found in the article
51  * "Color-based segmentation of point clouds"
52  * by Qingming Zhan, Yubin Liang, Yinghui Xiao
53  */
54  template <typename PointT, typename NormalT = pcl::Normal>
55  class PCL_EXPORTS RegionGrowingRGB : public RegionGrowing<PointT, NormalT>
56  {
57  public:
58 
82 
83  public:
84 
85  /** \brief Constructor that sets default values for member variables. */
87 
88  /** \brief Destructor that frees memory. */
89 
90  ~RegionGrowingRGB ();
91 
92  /** \brief Returns the color threshold value used for testing if points belong to the same region. */
93  float
94  getPointColorThreshold () const;
95 
96  /** \brief This method specifies the threshold value for color test between the points.
97  * This kind of testing is made at the first stage of the algorithm(region growing).
98  * If the difference between points color is less than threshold value, then they are considered
99  * to be in the same region.
100  * \param[in] thresh new threshold value for color test
101  */
102  void
103  setPointColorThreshold (float thresh);
104 
105  /** \brief Returns the color threshold value used for testing if regions can be merged. */
106  float
107  getRegionColorThreshold () const;
108 
109  /** \brief This method specifies the threshold value for color test between the regions.
110  * This kind of testing is made at the second stage of the algorithm(region merging).
111  * If the difference between segments color is less than threshold value, then they are merged together.
112  * \param[in] thresh new threshold value for color test
113  */
114  void
115  setRegionColorThreshold (float thresh);
116 
117  /** \brief Returns the distance threshold. If the distance between two points is less or equal to
118  * distance threshold value, then those points assumed to be neighbouring points.
119  */
120  float
121  getDistanceThreshold () const;
122 
123  /** \brief Allows to set distance threshold.
124  * \param[in] thresh new threshold value for neighbour test
125  */
126  void
127  setDistanceThreshold (float thresh);
128 
129  /** \brief Returns the number of nearest neighbours used for searching K nearest segments.
130  * Note that here it refers to the segments(not the points).
131  */
132  unsigned int
133  getNumberOfRegionNeighbours () const;
134 
135  /** \brief This method allows to set the number of neighbours that is used for finding
136  * neighbouring segments. Neighbouring segments are needed for the merging process.
137  * \param[in] nghbr_number the number of neighbouring segments to find
138  */
139  void
140  setNumberOfRegionNeighbours (unsigned int nghbr_number);
141 
142  /** \brief Returns the flag that signalize if the smoothness test is turned on/off. */
143  bool
144  getNormalTestFlag () const;
145 
146  /** \brief
147  * Allows to turn on/off the smoothness test.
148  * \param[in] value new value for normal/smoothness test. If set to true then the test will be turned on
149  */
150  void
151  setNormalTestFlag (bool value);
152 
153  /** \brief Allows to turn on/off the curvature test.
154  * \param[in] value new value for curvature test. If set to true then the test will be turned on
155  */
156  void
157  setCurvatureTestFlag (bool value) override;
158 
159  /** \brief
160  * Allows to turn on/off the residual test.
161  * \param[in] value new value for residual test. If set to true then the test will be turned on
162  */
163  void
164  setResidualTestFlag (bool value) override;
165 
166  /** \brief This method launches the segmentation algorithm and returns the clusters that were
167  * obtained during the segmentation.
168  * \param[out] clusters clusters that were obtained. Each cluster is an array of point indices.
169  */
170  void
171  extract (std::vector <pcl::PointIndices>& clusters) override;
172 
173  /** \brief For a given point this function builds a segment to which it belongs and returns this segment.
174  * \param[in] index index of the initial point which will be the seed for growing a segment.
175  * \param cluster
176  */
177  void
178  getSegmentFromPoint (int index, pcl::PointIndices& cluster) override;
179 
180  protected:
181 
182  /** \brief This method simply checks if it is possible to execute the segmentation algorithm with
183  * the current settings. If it is possible then it returns true.
184  */
185  bool
186  prepareForSegmentation () override;
187 
188  /** \brief This method finds KNN for each point and saves them to the array
189  * because the algorithm needs to find KNN a few times.
190  */
191  void
192  findPointNeighbours () override;
193 
194  /** \brief This method simply calls the findRegionsKNN for each segment and
195  * saves the results for later use.
196  */
197  void
198  findSegmentNeighbours ();
199 
200  /** \brief This method finds K nearest neighbours of the given segment.
201  * \param[in] index index of the segment for which neighbours will be found
202  * \param[in] nghbr_number the number of neighbours to find
203  * \param[out] nghbrs the array of indices of the neighbours that were found
204  * \param[out] dist the array of distances to the corresponding neighbours
205  */
206  void
207  findRegionsKNN (int index, int nghbr_number, std::vector<int>& nghbrs, std::vector<float>& dist);
208 
209  /** \brief This function implements the merging algorithm described in the article
210  * "Color-based segmentation of point clouds"
211  * by Qingming Zhan, Yubin Liang, Yinghui Xiao
212  */
213  void
214  applyRegionMergingAlgorithm ();
215 
216  /** \brief This method calculates the colorimetrical difference between two points.
217  * In this case it simply returns the euclidean distance between two colors.
218  * \param[in] first_color the color of the first point
219  * \param[in] second_color the color of the second point
220  */
221  float
222  calculateColorimetricalDifference (std::vector<unsigned int>& first_color, std::vector<unsigned int>& second_color) const;
223 
224  /** \brief This method assembles the array containing neighbours of each homogeneous region.
225  * Homogeneous region is the union of some segments. This array is used when the regions
226  * with a few points need to be merged with the neighbouring region.
227  * \param[out] neighbours_out vector of lists of neighbours for every homogeneous region
228  * \param[in] regions_in vector of lists, each list contains indices of segments that belong
229  * to the corresponding homogeneous region.
230  */
231  void
232  findRegionNeighbours (std::vector< std::vector< std::pair<float, int> > >& neighbours_out, std::vector< std::vector<int> >& regions_in);
233 
234  /** \brief This function simply assembles the regions from list of point labels.
235  * \param[in] num_pts_in_region for each final region it stores the corresponding number of points in it
236  * \param[in] num_regions number of regions to assemble
237  */
238  void
239  assembleRegions (std::vector<unsigned int>& num_pts_in_region, int num_regions);
240 
241  /** \brief This function is checking if the point with index 'nghbr' belongs to the segment.
242  * If so, then it returns true. It also checks if this point can serve as the seed.
243  * \param[in] initial_seed index of the initial point that was passed to the growRegion() function
244  * \param[in] point index of the current seed point
245  * \param[in] nghbr index of the point that is neighbour of the current seed
246  * \param[out] is_a_seed this value is set to true if the point with index 'nghbr' can serve as the seed
247  */
248  bool
249  validatePoint (int initial_seed, int point, int nghbr, bool& is_a_seed) const override;
250 
251  protected:
252 
253  /** \brief Thershold used in color test for points. */
255 
256  /** \brief Thershold used in color test for regions. */
258 
259  /** \brief Threshold that tells which points we need to assume neighbouring. */
261 
262  /** \brief Number of neighbouring segments to find. */
264 
265  /** \brief Stores distances for the point neighbours from point_neighbours_ */
266  std::vector< std::vector<float> > point_distances_;
267 
268  /** \brief Stores the neighboures for the corresponding segments. */
269  std::vector< std::vector<int> > segment_neighbours_;
270 
271  /** \brief Stores distances for the segment neighbours from segment_neighbours_ */
272  std::vector< std::vector<float> > segment_distances_;
273 
274  /** \brief Stores new indices for segments that were obtained at the region growing stage. */
275  std::vector<int> segment_labels_;
276 
277  public:
279  };
280 }
281 
282 #ifdef PCL_NO_PRECOMPILE
283 #include <pcl/segmentation/impl/region_growing_rgb.hpp>
284 #endif
float distance_threshold_
Threshold that tells which points we need to assume neighbouring.
Defines functions, macros and traits for allocating and using memory.
std::vector< std::vector< float > > segment_distances_
Stores distances for the segment neighbours from segment_neighbours_.
Implements the well known Region Growing algorithm used for segmentation based on color of points...
unsigned int region_neighbour_number_
Number of neighbouring segments to find.
std::vector< std::vector< float > > point_distances_
Stores distances for the point neighbours from point_neighbours_.
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: memory.h:63
Implements the well known Region Growing algorithm used for segmentation.
std::vector< std::vector< int > > segment_neighbours_
Stores the neighboures for the corresponding segments.
std::vector< int > segment_labels_
Stores new indices for segments that were obtained at the region growing stage.
float color_r2r_threshold_
Thershold used in color test for regions.
float color_p2p_threshold_
Thershold used in color test for points.
#define PCL_EXPORTS
Definition: pcl_macros.h:328
Defines all the PCL and non-PCL macros used.