Point Cloud Library (PCL) 1.14.0
Loading...
Searching...
No Matches
conditional_euclidean_clustering.h
1/*
2 * Software License Agreement (BSD License)
3 *
4 * Point Cloud Library (PCL) - www.pointclouds.org
5 * Copyright (c) 2010-2011, Willow Garage, Inc.
6 *
7 * All rights reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * * Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * * Redistributions in binary form must reproduce the above
16 * copyright notice, this list of conditions and the following
17 * disclaimer in the documentation and/or other materials provided
18 * with the distribution.
19 * * Neither the name of the copyright holder(s) nor the names of its
20 * contributors may be used to endorse or promote products derived
21 * from this software without specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 * POSSIBILITY OF SUCH DAMAGE.
35 *
36 */
37
38#pragma once
39
40#include <pcl/memory.h>
41#include <pcl/pcl_base.h>
42#include <pcl/pcl_macros.h>
43#include <pcl/console/print.h> // for PCL_WARN
44#include <pcl/search/search.h> // for Search
45
46#include <functional>
47
48namespace pcl
49{
50 using IndicesClusters = std::vector<pcl::PointIndices>;
51 using IndicesClustersPtr = shared_ptr<std::vector<pcl::PointIndices> >;
52
53 /** \brief @b ConditionalEuclideanClustering performs segmentation based on Euclidean distance and a user-defined clustering condition.
54 * \details The condition that need to hold is currently passed using a function pointer.
55 * For more information check the documentation of setConditionFunction() or the usage example below:
56 * \code
57 * bool
58 * enforceIntensitySimilarity (const pcl::PointXYZI& point_a, const pcl::PointXYZI& point_b, float squared_distance)
59 * {
60 * if (std::abs (point_a.intensity - point_b.intensity) < 0.1f)
61 * return (true);
62 * else
63 * return (false);
64 * }
65 * // ...
66 * // Somewhere down to the main code
67 * // ...
68 * pcl::ConditionalEuclideanClustering<pcl::PointXYZI> cec (true);
69 * cec.setInputCloud (cloud_in);
70 * cec.setConditionFunction (&enforceIntensitySimilarity);
71 * // Points within this distance from one another are going to need to validate the enforceIntensitySimilarity function to be part of the same cluster:
72 * cec.setClusterTolerance (0.09f);
73 * // Size constraints for the clusters:
74 * cec.setMinClusterSize (5);
75 * cec.setMaxClusterSize (30);
76 * // The resulting clusters (an array of pointindices):
77 * cec.segment (*clusters);
78 * // The clusters that are too small or too large in size can also be extracted separately:
79 * cec.getRemovedClusters (small_clusters, large_clusters);
80 * \endcode
81 * \author Frits Florentinus
82 * \ingroup segmentation
83 */
84 template<typename PointT>
86 {
87 protected:
89
94
95 public:
96 /** \brief Constructor.
97 * \param[in] extract_removed_clusters Set to true if you want to be able to extract the clusters that are too large or too small (default = false)
98 */
99 ConditionalEuclideanClustering (bool extract_removed_clusters = false) :
100 searcher_ (),
101 condition_function_ (),
102 extract_removed_clusters_ (extract_removed_clusters),
103 small_clusters_ (new pcl::IndicesClusters),
104 large_clusters_ (new pcl::IndicesClusters)
105 {
106 }
107
108 /** \brief Provide a pointer to the search object.
109 * \param[in] tree a pointer to the spatial search object.
110 */
111 inline void
113 {
114 searcher_ = tree;
115 }
116
117 /** \brief Get a pointer to the search method used.
118 */
119 inline const SearcherPtr&
121 {
122 return searcher_;
123 }
124
125 /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
126 * \details Any two points within a certain distance from one another will need to evaluate this condition in order to be made part of the same cluster.
127 * The distance can be set using setClusterTolerance().
128 * <br>
129 * Note that for a point to be part of a cluster, the condition only needs to hold for at least 1 point pair.
130 * To clarify, the following statement is false:
131 * Any two points within a cluster always evaluate this condition function to true.
132 * <br><br>
133 * The input arguments of the condition function are:
134 * <ul>
135 * <li>PointT The first point of the point pair</li>
136 * <li>PointT The second point of the point pair</li>
137 * <li>float The squared distance between the points</li>
138 * </ul>
139 * The output argument is a boolean, returning true will merge the second point into the cluster of the first point.
140 * \param[in] condition_function The condition function that needs to hold for clustering
141 */
142 inline void
143 setConditionFunction (bool (*condition_function) (const PointT&, const PointT&, float))
144 {
145 condition_function_ = condition_function;
146 }
147
148 /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
149 * This is an overloaded function provided for convenience. See the documentation for setConditionFunction(). */
150 inline void
151 setConditionFunction (std::function<bool (const PointT&, const PointT&, float)> condition_function)
152 {
153 condition_function_ = condition_function;
154 }
155
156 /** \brief Set the spatial tolerance for new cluster candidates.
157 * \details Any two points within this distance from one another will need to evaluate a certain condition in order to be made part of the same cluster.
158 * The condition can be set using setConditionFunction().
159 * \param[in] cluster_tolerance The distance to scan for cluster candidates (default = 0.0)
160 */
161 inline void
162 setClusterTolerance (float cluster_tolerance)
163 {
164 cluster_tolerance_ = cluster_tolerance;
165 }
166
167 /** \brief Get the spatial tolerance for new cluster candidates.*/
168 inline float
170 {
171 return (cluster_tolerance_);
172 }
173
174 /** \brief Set the minimum number of points that a cluster needs to contain in order to be considered valid.
175 * \param[in] min_cluster_size The minimum cluster size (default = 1)
176 */
177 inline void
178 setMinClusterSize (int min_cluster_size)
179 {
180 min_cluster_size_ = min_cluster_size;
181 }
182
183 /** \brief Get the minimum number of points that a cluster needs to contain in order to be considered valid.*/
184 inline int
186 {
187 return (min_cluster_size_);
188 }
189
190 /** \brief Set the maximum number of points that a cluster needs to contain in order to be considered valid.
191 * \param[in] max_cluster_size The maximum cluster size (default = unlimited)
192 */
193 inline void
194 setMaxClusterSize (int max_cluster_size)
195 {
196 max_cluster_size_ = max_cluster_size;
197 }
198
199 /** \brief Get the maximum number of points that a cluster needs to contain in order to be considered valid.*/
200 inline int
202 {
203 return (max_cluster_size_);
204 }
205
206 /** \brief Segment the input into separate clusters.
207 * \details The input can be set using setInputCloud() and setIndices().
208 * <br>
209 * The size constraints for the resulting clusters can be set using setMinClusterSize() and setMaxClusterSize().
210 * <br>
211 * The region growing parameters can be set using setConditionFunction() and setClusterTolerance().
212 * <br>
213 * \param[out] clusters The resultant set of indices, indexing the points of the input cloud that correspond to the clusters
214 */
215 void
216 segment (IndicesClusters &clusters);
217
218 /** \brief Get the clusters that are invalidated due to size constraints.
219 * \note The constructor of this class needs to be initialized with true, and the segment method needs to have been called prior to using this method.
220 * \param[out] small_clusters The resultant clusters that contain less than min_cluster_size points
221 * \param[out] large_clusters The resultant clusters that contain more than max_cluster_size points
222 */
223 inline void
225 {
226 if (!extract_removed_clusters_)
227 {
228 PCL_WARN("[pcl::ConditionalEuclideanClustering::getRemovedClusters] You need to set extract_removed_clusters to true (in this class' constructor) if you want to use this functionality.\n");
229 return;
230 }
231 small_clusters = small_clusters_;
232 large_clusters = large_clusters_;
233 }
234
235 private:
236 /** \brief A pointer to the spatial search object */
237 SearcherPtr searcher_{nullptr};
238
239 /** \brief The condition function that needs to hold for clustering */
240 std::function<bool (const PointT&, const PointT&, float)> condition_function_;
241
242 /** \brief The distance to scan for cluster candidates (default = 0.0) */
243 float cluster_tolerance_{0.0f};
244
245 /** \brief The minimum cluster size (default = 1) */
246 int min_cluster_size_{1};
247
248 /** \brief The maximum cluster size (default = unlimited) */
249 int max_cluster_size_{std::numeric_limits<int>::max ()};
250
251 /** \brief Set to true if you want to be able to extract the clusters that are too large or too small (default = false) */
252 bool extract_removed_clusters_;
253
254 /** \brief The resultant clusters that contain less than min_cluster_size points */
255 pcl::IndicesClustersPtr small_clusters_{nullptr};
256
257 /** \brief The resultant clusters that contain more than max_cluster_size points */
258 pcl::IndicesClustersPtr large_clusters_{nullptr};
259
260 public:
262 };
263}
264
265#ifdef PCL_NO_PRECOMPILE
266#include <pcl/segmentation/impl/conditional_euclidean_clustering.hpp>
267#endif
ConditionalEuclideanClustering performs segmentation based on Euclidean distance and a user-defined c...
int getMaxClusterSize()
Get the maximum number of points that a cluster needs to contain in order to be considered valid.
void setMinClusterSize(int min_cluster_size)
Set the minimum number of points that a cluster needs to contain in order to be considered valid.
void setSearchMethod(const SearcherPtr &tree)
Provide a pointer to the search object.
const SearcherPtr & getSearchMethod() const
Get a pointer to the search method used.
void setConditionFunction(std::function< bool(const PointT &, const PointT &, float)> condition_function)
Set the condition that needs to hold for neighboring points to be considered part of the same cluster...
typename pcl::search::Search< PointT >::Ptr SearcherPtr
float getClusterTolerance()
Get the spatial tolerance for new cluster candidates.
void setConditionFunction(bool(*condition_function)(const PointT &, const PointT &, float))
Set the condition that needs to hold for neighboring points to be considered part of the same cluster...
void segment(IndicesClusters &clusters)
Segment the input into separate clusters.
void setMaxClusterSize(int max_cluster_size)
Set the maximum number of points that a cluster needs to contain in order to be considered valid.
void setClusterTolerance(float cluster_tolerance)
Set the spatial tolerance for new cluster candidates.
int getMinClusterSize()
Get the minimum number of points that a cluster needs to contain in order to be considered valid.
void getRemovedClusters(IndicesClustersPtr &small_clusters, IndicesClustersPtr &large_clusters)
Get the clusters that are invalidated due to size constraints.
ConditionalEuclideanClustering(bool extract_removed_clusters=false)
Constructor.
PCL base class.
Definition pcl_base.h:70
PointCloudConstPtr input_
The input point cloud dataset.
Definition pcl_base.h:147
IndicesPtr indices_
A pointer to the vector of point indices to use.
Definition pcl_base.h:150
bool initCompute()
This method should get called before starting the actual computation.
Definition pcl_base.hpp:138
bool deinitCompute()
This method should get called after finishing the actual computation.
Definition pcl_base.hpp:175
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition search.h:81
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition memory.h:63
Defines functions, macros and traits for allocating and using memory.
shared_ptr< std::vector< pcl::PointIndices > > IndicesClustersPtr
std::vector< pcl::PointIndices > IndicesClusters
Defines all the PCL and non-PCL macros used.
A point structure representing Euclidean xyz coordinates, and the RGB color.