Point Cloud Library (PCL)  1.11.1
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/search/pcl_search.h>
44 
45 #include <functional>
46 
47 namespace pcl
48 {
49  using IndicesClusters = std::vector<pcl::PointIndices>;
50  using IndicesClustersPtr = shared_ptr<std::vector<pcl::PointIndices> >;
51 
52  /** \brief @b ConditionalEuclideanClustering performs segmentation based on Euclidean distance and a user-defined clustering condition.
53  * \details The condition that need to hold is currently passed using a function pointer.
54  * For more information check the documentation of setConditionFunction() or the usage example below:
55  * \code
56  * bool
57  * enforceIntensitySimilarity (const pcl::PointXYZI& point_a, const pcl::PointXYZI& point_b, float squared_distance)
58  * {
59  * if (std::abs (point_a.intensity - point_b.intensity) < 0.1f)
60  * return (true);
61  * else
62  * return (false);
63  * }
64  * // ...
65  * // Somewhere down to the main code
66  * // ...
67  * pcl::ConditionalEuclideanClustering<pcl::PointXYZI> cec (true);
68  * cec.setInputCloud (cloud_in);
69  * cec.setConditionFunction (&enforceIntensitySimilarity);
70  * // Points within this distance from one another are going to need to validate the enforceIntensitySimilarity function to be part of the same cluster:
71  * cec.setClusterTolerance (0.09f);
72  * // Size constraints for the clusters:
73  * cec.setMinClusterSize (5);
74  * cec.setMaxClusterSize (30);
75  * // The resulting clusters (an array of pointindices):
76  * cec.segment (*clusters);
77  * // The clusters that are too small or too large in size can also be extracted separately:
78  * cec.getRemovedClusters (small_clusters, large_clusters);
79  * \endcode
80  * \author Frits Florentinus
81  * \ingroup segmentation
82  */
83  template<typename PointT>
84  class ConditionalEuclideanClustering : public PCLBase<PointT>
85  {
86  protected:
88 
93 
94  public:
95  /** \brief Constructor.
96  * \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)
97  */
98  ConditionalEuclideanClustering (bool extract_removed_clusters = false) :
99  searcher_ (),
100  condition_function_ (),
101  cluster_tolerance_ (0.0f),
102  min_cluster_size_ (1),
103  max_cluster_size_ (std::numeric_limits<int>::max ()),
104  extract_removed_clusters_ (extract_removed_clusters),
105  small_clusters_ (new pcl::IndicesClusters),
106  large_clusters_ (new pcl::IndicesClusters)
107  {
108  }
109 
110  /** \brief Provide a pointer to the search object.
111  * \param[in] tree a pointer to the spatial search object.
112  */
113  inline void
115  {
116  searcher_ = tree;
117  }
118 
119  /** \brief Get a pointer to the search method used.
120  */
121  inline const SearcherPtr&
123  {
124  return searcher_;
125  }
126 
127  /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
128  * \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.
129  * The distance can be set using setClusterTolerance().
130  * <br>
131  * Note that for a point to be part of a cluster, the condition only needs to hold for at least 1 point pair.
132  * To clarify, the following statement is false:
133  * Any two points within a cluster always evaluate this condition function to true.
134  * <br><br>
135  * The input arguments of the condition function are:
136  * <ul>
137  * <li>PointT The first point of the point pair</li>
138  * <li>PointT The second point of the point pair</li>
139  * <li>float The squared distance between the points</li>
140  * </ul>
141  * The output argument is a boolean, returning true will merge the second point into the cluster of the first point.
142  * \param[in] condition_function The condition function that needs to hold for clustering
143  */
144  inline void
145  setConditionFunction (bool (*condition_function) (const PointT&, const PointT&, float))
146  {
147  condition_function_ = condition_function;
148  }
149 
150  /** \brief Set the condition that needs to hold for neighboring points to be considered part of the same cluster.
151  * This is an overloaded function provided for convenience. See the documentation for setConditionFunction(). */
152  inline void
153  setConditionFunction (std::function<bool (const PointT&, const PointT&, float)> condition_function)
154  {
155  condition_function_ = condition_function;
156  }
157 
158  /** \brief Set the spatial tolerance for new cluster candidates.
159  * \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.
160  * The condition can be set using setConditionFunction().
161  * \param[in] cluster_tolerance The distance to scan for cluster candidates (default = 0.0)
162  */
163  inline void
164  setClusterTolerance (float cluster_tolerance)
165  {
166  cluster_tolerance_ = cluster_tolerance;
167  }
168 
169  /** \brief Get the spatial tolerance for new cluster candidates.*/
170  inline float
172  {
173  return (cluster_tolerance_);
174  }
175 
176  /** \brief Set the minimum number of points that a cluster needs to contain in order to be considered valid.
177  * \param[in] min_cluster_size The minimum cluster size (default = 1)
178  */
179  inline void
180  setMinClusterSize (int min_cluster_size)
181  {
182  min_cluster_size_ = min_cluster_size;
183  }
184 
185  /** \brief Get the minimum number of points that a cluster needs to contain in order to be considered valid.*/
186  inline int
188  {
189  return (min_cluster_size_);
190  }
191 
192  /** \brief Set the maximum number of points that a cluster needs to contain in order to be considered valid.
193  * \param[in] max_cluster_size The maximum cluster size (default = unlimited)
194  */
195  inline void
196  setMaxClusterSize (int max_cluster_size)
197  {
198  max_cluster_size_ = max_cluster_size;
199  }
200 
201  /** \brief Get the maximum number of points that a cluster needs to contain in order to be considered valid.*/
202  inline int
204  {
205  return (max_cluster_size_);
206  }
207 
208  /** \brief Segment the input into separate clusters.
209  * \details The input can be set using setInputCloud() and setIndices().
210  * <br>
211  * The size constraints for the resulting clusters can be set using setMinClusterSize() and setMaxClusterSize().
212  * <br>
213  * The region growing parameters can be set using setConditionFunction() and setClusterTolerance().
214  * <br>
215  * \param[out] clusters The resultant set of indices, indexing the points of the input cloud that correspond to the clusters
216  */
217  void
218  segment (IndicesClusters &clusters);
219 
220  /** \brief Get the clusters that are invalidated due to size constraints.
221  * \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.
222  * \param[out] small_clusters The resultant clusters that contain less than min_cluster_size points
223  * \param[out] large_clusters The resultant clusters that contain more than max_cluster_size points
224  */
225  inline void
226  getRemovedClusters (IndicesClustersPtr &small_clusters, IndicesClustersPtr &large_clusters)
227  {
228  if (!extract_removed_clusters_)
229  {
230  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");
231  return;
232  }
233  small_clusters = small_clusters_;
234  large_clusters = large_clusters_;
235  }
236 
237  private:
238  /** \brief A pointer to the spatial search object */
239  SearcherPtr searcher_;
240 
241  /** \brief The condition function that needs to hold for clustering */
242  std::function<bool (const PointT&, const PointT&, float)> condition_function_;
243 
244  /** \brief The distance to scan for cluster candidates (default = 0.0) */
245  float cluster_tolerance_;
246 
247  /** \brief The minimum cluster size (default = 1) */
248  int min_cluster_size_;
249 
250  /** \brief The maximum cluster size (default = unlimited) */
251  int max_cluster_size_;
252 
253  /** \brief Set to true if you want to be able to extract the clusters that are too large or too small (default = false) */
254  bool extract_removed_clusters_;
255 
256  /** \brief The resultant clusters that contain less than min_cluster_size points */
257  pcl::IndicesClustersPtr small_clusters_;
258 
259  /** \brief The resultant clusters that contain more than max_cluster_size points */
260  pcl::IndicesClustersPtr large_clusters_;
261 
262  public:
264  };
265 }
266 
267 #ifdef PCL_NO_PRECOMPILE
268 #include <pcl/segmentation/impl/conditional_euclidean_clustering.hpp>
269 #endif
pcl::ConditionalEuclideanClustering::setConditionFunction
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...
Definition: conditional_euclidean_clustering.h:145
pcl_macros.h
Defines all the PCL and non-PCL macros used.
pcl
Definition: convolution.h:46
pcl::ConditionalEuclideanClustering::getMinClusterSize
int getMinClusterSize()
Get the minimum number of points that a cluster needs to contain in order to be considered valid.
Definition: conditional_euclidean_clustering.h:187
pcl::ConditionalEuclideanClustering::getClusterTolerance
float getClusterTolerance()
Get the spatial tolerance for new cluster candidates.
Definition: conditional_euclidean_clustering.h:171
pcl::ConditionalEuclideanClustering::ConditionalEuclideanClustering
ConditionalEuclideanClustering(bool extract_removed_clusters=false)
Constructor.
Definition: conditional_euclidean_clustering.h:98
pcl::ConditionalEuclideanClustering::setConditionFunction
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...
Definition: conditional_euclidean_clustering.h:153
pcl::PCLBase
PCL base class.
Definition: pcl_base.h:73
pcl::IndicesClusters
std::vector< pcl::PointIndices > IndicesClusters
Definition: conditional_euclidean_clustering.h:49
pcl::PointXYZRGB
A point structure representing Euclidean xyz coordinates, and the RGB color.
Definition: point_types.hpp:629
pcl::ConditionalEuclideanClustering
ConditionalEuclideanClustering performs segmentation based on Euclidean distance and a user-defined c...
Definition: conditional_euclidean_clustering.h:85
pcl::ConditionalEuclideanClustering::getSearchMethod
const SearcherPtr & getSearchMethod() const
Get a pointer to the search method used.
Definition: conditional_euclidean_clustering.h:122
pcl::ConditionalEuclideanClustering::setSearchMethod
void setSearchMethod(const SearcherPtr &tree)
Provide a pointer to the search object.
Definition: conditional_euclidean_clustering.h:114
pcl::ConditionalEuclideanClustering::setMinClusterSize
void setMinClusterSize(int min_cluster_size)
Set the minimum number of points that a cluster needs to contain in order to be considered valid.
Definition: conditional_euclidean_clustering.h:180
pcl::search::Search::Ptr
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:81
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::ConditionalEuclideanClustering::segment
void segment(IndicesClusters &clusters)
Segment the input into separate clusters.
Definition: conditional_euclidean_clustering.hpp:43
pcl::ConditionalEuclideanClustering::getMaxClusterSize
int getMaxClusterSize()
Get the maximum number of points that a cluster needs to contain in order to be considered valid.
Definition: conditional_euclidean_clustering.h:203
pcl::IndicesClustersPtr
shared_ptr< std::vector< pcl::PointIndices > > IndicesClustersPtr
Definition: conditional_euclidean_clustering.h:50
pcl::ConditionalEuclideanClustering::SearcherPtr
typename pcl::search::Search< PointT >::Ptr SearcherPtr
Definition: conditional_euclidean_clustering.h:87
pcl::ConditionalEuclideanClustering::setMaxClusterSize
void setMaxClusterSize(int max_cluster_size)
Set the maximum number of points that a cluster needs to contain in order to be considered valid.
Definition: conditional_euclidean_clustering.h:196
pcl::ConditionalEuclideanClustering::getRemovedClusters
void getRemovedClusters(IndicesClustersPtr &small_clusters, IndicesClustersPtr &large_clusters)
Get the clusters that are invalidated due to size constraints.
Definition: conditional_euclidean_clustering.h:226
pcl::ConditionalEuclideanClustering::setClusterTolerance
void setClusterTolerance(float cluster_tolerance)
Set the spatial tolerance for new cluster candidates.
Definition: conditional_euclidean_clustering.h:164
memory.h
Defines functions, macros and traits for allocating and using memory.