Point Cloud Library (PCL) 1.15.0
Loading...
Searching...
No Matches
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
46namespace 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
60 using RegionGrowing<PointT, NormalT>::input_;
61 using RegionGrowing<PointT, NormalT>::indices_;
62 using RegionGrowing<PointT, NormalT>::initCompute;
63 using RegionGrowing<PointT, NormalT>::deinitCompute;
64 using RegionGrowing<PointT, NormalT>::normals_;
65 using RegionGrowing<PointT, NormalT>::normal_flag_;
66 using RegionGrowing<PointT, NormalT>::curvature_flag_;
67 using RegionGrowing<PointT, NormalT>::residual_flag_;
68 using RegionGrowing<PointT, NormalT>::residual_threshold_;
69 using RegionGrowing<PointT, NormalT>::neighbour_number_;
70 using RegionGrowing<PointT, NormalT>::search_;
71 using RegionGrowing<PointT, NormalT>::min_pts_per_cluster_;
72 using RegionGrowing<PointT, NormalT>::max_pts_per_cluster_;
73 using RegionGrowing<PointT, NormalT>::smooth_mode_flag_;
74 using RegionGrowing<PointT, NormalT>::theta_threshold_;
75 using RegionGrowing<PointT, NormalT>::curvature_threshold_;
76 using RegionGrowing<PointT, NormalT>::point_neighbours_;
77 using RegionGrowing<PointT, NormalT>::point_labels_;
78 using RegionGrowing<PointT, NormalT>::num_pts_in_segment_;
79 using RegionGrowing<PointT, NormalT>::clusters_;
80 using RegionGrowing<PointT, NormalT>::number_of_segments_;
81 using RegionGrowing<PointT, NormalT>::applySmoothRegionGrowingAlgorithm;
82 using RegionGrowing<PointT, NormalT>::assembleRegions;
83
84 public:
85
86 /** \brief Constructor that sets default values for member variables. */
88
89 /** \brief Destructor that frees memory. */
90
91 ~RegionGrowingRGB () override;
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. */
255 float color_p2p_threshold_{1225.0f};
256
257 /** \brief Thershold used in color test for regions. */
258 float color_r2r_threshold_{10.0f};
259
260 /** \brief Threshold that tells which points we need to assume neighbouring. */
261 float distance_threshold_{0.05f};
262
263 /** \brief Number of neighbouring segments to find. */
264 unsigned int region_neighbour_number_{100};
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
Implements the well known Region Growing algorithm used for segmentation.
Implements the well known Region Growing algorithm used for segmentation based on color of points.
std::vector< std::vector< float > > point_distances_
Stores distances for the point neighbours from point_neighbours_.
std::vector< pcl::Indices > segment_neighbours_
Stores the neighboures for the corresponding segments.
std::vector< std::vector< float > > segment_distances_
Stores distances for the segment neighbours from segment_neighbours_.
std::vector< int > segment_labels_
Stores new indices for segments that were obtained at the region growing stage.
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition memory.h:86
Defines functions, macros and traits for allocating and using memory.
detail::int_type_t< detail::index_type_size, false > uindex_t
Type used for an unsigned index in PCL.
Definition types.h:120
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
IndicesAllocator<> Indices
Type used for indices in PCL.
Definition types.h:133
Defines all the PCL and non-PCL macros used.
A point structure representing normal coordinates and the surface curvature estimate.
A point structure representing Euclidean xyz coordinates, and the RGB color.