Point Cloud Library (PCL) 1.12.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 cluster_tolerance_ (0.0f),
103 min_cluster_size_ (1),
104 max_cluster_size_ (std::numeric_limits<int>::max ()),
105 extract_removed_clusters_ (extract_removed_clusters),
106 small_clusters_ (new pcl::IndicesClusters),
107 large_clusters_ (new pcl::IndicesClusters)
108 {
109 }
110
111 /** \brief Provide a pointer to the search object.
112 * \param[in] tree a pointer to the spatial search object.
113 */
114 inline void
116 {
117 searcher_ = tree;
118 }
119
120 /** \brief Get a pointer to the search method used.
121 */
122 inline const SearcherPtr&
124 {
125 return searcher_;
126 }
127
128 /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
129 * \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.
130 * The distance can be set using setClusterTolerance().
131 * <br>
132 * Note that for a point to be part of a cluster, the condition only needs to hold for at least 1 point pair.
133 * To clarify, the following statement is false:
134 * Any two points within a cluster always evaluate this condition function to true.
135 * <br><br>
136 * The input arguments of the condition function are:
137 * <ul>
138 * <li>PointT The first point of the point pair</li>
139 * <li>PointT The second point of the point pair</li>
140 * <li>float The squared distance between the points</li>
141 * </ul>
142 * The output argument is a boolean, returning true will merge the second point into the cluster of the first point.
143 * \param[in] condition_function The condition function that needs to hold for clustering
144 */
145 inline void
146 setConditionFunction (bool (*condition_function) (const PointT&, const PointT&, float))
147 {
148 condition_function_ = condition_function;
149 }
150
151 /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
152 * This is an overloaded function provided for convenience. See the documentation for setConditionFunction(). */
153 inline void
154 setConditionFunction (std::function<bool (const PointT&, const PointT&, float)> condition_function)
155 {
156 condition_function_ = condition_function;
157 }
158
159 /** \brief Set the spatial tolerance for new cluster candidates.
160 * \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.
161 * The condition can be set using setConditionFunction().
162 * \param[in] cluster_tolerance The distance to scan for cluster candidates (default = 0.0)
163 */
164 inline void
165 setClusterTolerance (float cluster_tolerance)
166 {
167 cluster_tolerance_ = cluster_tolerance;
168 }
169
170 /** \brief Get the spatial tolerance for new cluster candidates.*/
171 inline float
173 {
174 return (cluster_tolerance_);
175 }
176
177 /** \brief Set the minimum number of points that a cluster needs to contain in order to be considered valid.
178 * \param[in] min_cluster_size The minimum cluster size (default = 1)
179 */
180 inline void
181 setMinClusterSize (int min_cluster_size)
182 {
183 min_cluster_size_ = min_cluster_size;
184 }
185
186 /** \brief Get the minimum number of points that a cluster needs to contain in order to be considered valid.*/
187 inline int
189 {
190 return (min_cluster_size_);
191 }
192
193 /** \brief Set the maximum number of points that a cluster needs to contain in order to be considered valid.
194 * \param[in] max_cluster_size The maximum cluster size (default = unlimited)
195 */
196 inline void
197 setMaxClusterSize (int max_cluster_size)
198 {
199 max_cluster_size_ = max_cluster_size;
200 }
201
202 /** \brief Get the maximum number of points that a cluster needs to contain in order to be considered valid.*/
203 inline int
205 {
206 return (max_cluster_size_);
207 }
208
209 /** \brief Segment the input into separate clusters.
210 * \details The input can be set using setInputCloud() and setIndices().
211 * <br>
212 * The size constraints for the resulting clusters can be set using setMinClusterSize() and setMaxClusterSize().
213 * <br>
214 * The region growing parameters can be set using setConditionFunction() and setClusterTolerance().
215 * <br>
216 * \param[out] clusters The resultant set of indices, indexing the points of the input cloud that correspond to the clusters
217 */
218 void
219 segment (IndicesClusters &clusters);
220
221 /** \brief Get the clusters that are invalidated due to size constraints.
222 * \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.
223 * \param[out] small_clusters The resultant clusters that contain less than min_cluster_size points
224 * \param[out] large_clusters The resultant clusters that contain more than max_cluster_size points
225 */
226 inline void
228 {
229 if (!extract_removed_clusters_)
230 {
231 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");
232 return;
233 }
234 small_clusters = small_clusters_;
235 large_clusters = large_clusters_;
236 }
237
238 private:
239 /** \brief A pointer to the spatial search object */
240 SearcherPtr searcher_;
241
242 /** \brief The condition function that needs to hold for clustering */
243 std::function<bool (const PointT&, const PointT&, float)> condition_function_;
244
245 /** \brief The distance to scan for cluster candidates (default = 0.0) */
246 float cluster_tolerance_;
247
248 /** \brief The minimum cluster size (default = 1) */
249 int min_cluster_size_;
250
251 /** \brief The maximum cluster size (default = unlimited) */
252 int max_cluster_size_;
253
254 /** \brief Set to true if you want to be able to extract the clusters that are too large or too small (default = false) */
255 bool extract_removed_clusters_;
256
257 /** \brief The resultant clusters that contain less than min_cluster_size points */
258 pcl::IndicesClustersPtr small_clusters_;
259
260 /** \brief The resultant clusters that contain more than max_cluster_size points */
261 pcl::IndicesClustersPtr large_clusters_;
262
263 public:
265 };
266}
267
268#ifdef PCL_NO_PRECOMPILE
269#include <pcl/segmentation/impl/conditional_euclidean_clustering.hpp>
270#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:174
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.