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