Point Cloud Library (PCL)  1.13.1-dev
extract_labeled_clusters.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Copyright (c) 2011, Willow Garage, Inc.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * * Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * * Redistributions in binary form must reproduce the above
14  * copyright notice, this list of conditions and the following
15  * disclaimer in the documentation and/or other materials provided
16  * with the distribution.
17  * * Neither the name of the copyright holder(s) nor the names of its
18  * contributors may be used to endorse or promote products derived
19  * from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  */
35 
36 #pragma once
37 
38 #include <pcl/search/search.h>
39 #include <pcl/pcl_base.h>
40 
41 namespace pcl {
42 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
43 /** \brief Decompose a region of space into clusters based on the Euclidean distance
44  * between points
45  * \param[in] cloud the point cloud message
46  * \param[in] tree the spatial locator (e.g., kd-tree) used for nearest neighbors
47  * searching
48  * \note the tree has to be created as a spatial locator on \a cloud
49  * \param[in] tolerance the spatial cluster tolerance as a measure in L2 Euclidean space
50  * \param[out] labeled_clusters the resultant clusters containing point indices (as a
51  * vector of PointIndices)
52  * \param[in] min_pts_per_cluster minimum number of points that a cluster may contain
53  * (default: 1)
54  * \param[in] max_pts_per_cluster maximum number of points that a cluster may contain
55  * (default: max int)
56  * \param[in] max_label
57  * \ingroup segmentation
58  */
59 template <typename PointT>
60 PCL_DEPRECATED(1, 14, "Use of max_label is deprecated")
62  const PointCloud<PointT>& cloud,
63  const typename search::Search<PointT>::Ptr& tree,
64  float tolerance,
65  std::vector<std::vector<PointIndices>>& labeled_clusters,
66  unsigned int min_pts_per_cluster,
67  unsigned int max_pts_per_cluster,
68  unsigned int max_label);
69 
70 /** \brief Decompose a region of space into clusters based on the Euclidean distance
71  * between points
72  * \param[in] cloud the point cloud message
73  * \param[in] tree the spatial locator (e.g., kd-tree) used for nearest neighbors
74  * searching \note the tree has to be created as a spatial locator on \a cloud
75  * \param[in] tolerance the spatial cluster tolerance as a measure in L2 Euclidean space
76  * \param[out] labeled_clusters the resultant clusters containing point indices
77  * (as a vector of PointIndices)
78  * \param[in] min_pts_per_cluster minimum number of points that a cluster may contain
79  * (default: 1)
80  * \param[in] max_pts_per_cluster maximum number of points that a cluster may contain
81  * (default: max int)
82  * \ingroup segmentation
83  */
84 template <typename PointT>
85 void
87  const PointCloud<PointT>& cloud,
88  const typename search::Search<PointT>::Ptr& tree,
89  float tolerance,
90  std::vector<std::vector<PointIndices>>& labeled_clusters,
91  unsigned int min_pts_per_cluster = 1,
92  unsigned int max_pts_per_cluster = std::numeric_limits<unsigned int>::max());
93 
94 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
95 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
96 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
97 /** \brief @b LabeledEuclideanClusterExtraction represents a segmentation class for
98  * cluster extraction in an Euclidean sense, with label info. \author Koen Buys
99  * \ingroup segmentation
100  */
101 template <typename PointT>
104 
105 public:
107  using PointCloudPtr = typename PointCloud::Ptr;
109 
111  using KdTreePtr = typename KdTree::Ptr;
112 
115 
116  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
117  /** \brief Empty constructor. */
119  : tree_()
120  , cluster_tolerance_(0)
121  , min_pts_per_cluster_(1)
122  , max_pts_per_cluster_(std::numeric_limits<int>::max())
123  , max_label_(std::numeric_limits<int>::max()){};
124 
125  /** \brief Provide a pointer to the search object.
126  * \param[in] tree a pointer to the spatial search object.
127  */
128  inline void
130  {
131  tree_ = tree;
132  }
133 
134  /** \brief Get a pointer to the search method used. */
135  inline KdTreePtr
137  {
138  return (tree_);
139  }
140 
141  /** \brief Set the spatial cluster tolerance as a measure in the L2 Euclidean space
142  * \param[in] tolerance the spatial cluster tolerance as a measure in the L2 Euclidean
143  * space
144  */
145  inline void
146  setClusterTolerance(double tolerance)
147  {
148  cluster_tolerance_ = tolerance;
149  }
150 
151  /** \brief Get the spatial cluster tolerance as a measure in the L2 Euclidean space.
152  */
153  inline double
155  {
156  return (cluster_tolerance_);
157  }
158 
159  /** \brief Set the minimum number of points that a cluster needs to contain in order
160  * to be considered valid. \param[in] min_cluster_size the minimum cluster size
161  */
162  inline void
163  setMinClusterSize(int min_cluster_size)
164  {
165  min_pts_per_cluster_ = min_cluster_size;
166  }
167 
168  /** \brief Get the minimum number of points that a cluster needs to contain in order
169  * to be considered valid. */
170  inline int
172  {
173  return (min_pts_per_cluster_);
174  }
175 
176  /** \brief Set the maximum number of points that a cluster needs to contain in order
177  * to be considered valid. \param[in] max_cluster_size the maximum cluster size
178  */
179  inline void
180  setMaxClusterSize(int max_cluster_size)
181  {
182  max_pts_per_cluster_ = max_cluster_size;
183  }
184 
185  /** \brief Get the maximum number of points that a cluster needs to contain in order
186  * to be considered valid. */
187  inline int
189  {
190  return (max_pts_per_cluster_);
191  }
192 
193  /** \brief Set the maximum number of labels in the cloud.
194  * \param[in] max_label the maximum
195  */
196  PCL_DEPRECATED(1, 14, "Max label is being deprecated")
197  inline void
198  setMaxLabels(unsigned int max_label)
199  {
200  max_label_ = max_label;
201  }
202 
203  /** \brief Get the maximum number of labels */
204  PCL_DEPRECATED(1, 14, "Max label is being deprecated")
205  inline unsigned int
206  getMaxLabels() const
207  {
208  return (max_label_);
209  }
210 
211  /** \brief Cluster extraction in a PointCloud given by <setInputCloud (), setIndices
212  * ()> \param[out] labeled_clusters the resultant point clusters
213  */
214  void
215  extract(std::vector<std::vector<PointIndices>>& labeled_clusters);
216 
217 protected:
218  // Members derived from the base class
219  using BasePCLBase::deinitCompute;
220  using BasePCLBase::indices_;
221  using BasePCLBase::initCompute;
222  using BasePCLBase::input_;
223 
224  /** \brief A pointer to the spatial search object. */
226 
227  /** \brief The spatial cluster tolerance as a measure in the L2 Euclidean space. */
229 
230  /** \brief The minimum number of points that a cluster needs to contain in order to be
231  * considered valid (default = 1). */
233 
234  /** \brief The maximum number of points that a cluster needs to contain in order to be
235  * considered valid (default = MAXINT). */
237 
238  /** \brief The maximum number of labels we can find in this pointcloud (default =
239  * MAXINT)*/
240  unsigned int max_label_;
241 
242  /** \brief Class getName method. */
243  virtual std::string
244  getClassName() const
245  {
246  return ("LabeledEuclideanClusterExtraction");
247  }
248 };
249 
250 /** \brief Sort clusters method (for std::sort).
251  * \ingroup segmentation
252  */
253 inline bool
255 {
256  return (a.indices.size() < b.indices.size());
257 }
258 } // namespace pcl
259 
260 #ifdef PCL_NO_PRECOMPILE
261 #include <pcl/segmentation/impl/extract_labeled_clusters.hpp>
262 #endif
shared_ptr< KdTree< PointT > > Ptr
Definition: kdtree.h:68
LabeledEuclideanClusterExtraction represents a segmentation class for cluster extraction in an Euclid...
unsigned int max_label_
The maximum number of labels we can find in this pointcloud (default = MAXINT)
void setClusterTolerance(double tolerance)
Set the spatial cluster tolerance as a measure in the L2 Euclidean space.
KdTreePtr tree_
A pointer to the spatial search object.
double cluster_tolerance_
The spatial cluster tolerance as a measure in the L2 Euclidean space.
void setMinClusterSize(int min_cluster_size)
Set the minimum number of points that a cluster needs to contain in order to be considered valid.
int getMaxClusterSize() const
Get the maximum number of points that a cluster needs to contain in order to be considered valid.
int min_pts_per_cluster_
The minimum number of points that a cluster needs to contain in order to be considered valid (default...
double getClusterTolerance() const
Get the spatial cluster tolerance as a measure in the L2 Euclidean space.
virtual std::string getClassName() const
Class getName method.
KdTreePtr getSearchMethod() const
Get a pointer to the search method used.
int getMinClusterSize() const
Get the minimum number of points that a cluster needs to contain in order to be considered valid.
int max_pts_per_cluster_
The maximum number of points that a cluster needs to contain in order to be considered valid (default...
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 setSearchMethod(const KdTreePtr &tree)
Provide a pointer to the search object.
PCL base class.
Definition: pcl_base.h:70
typename PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:73
typename PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:74
PointIndices::ConstPtr PointIndicesConstPtr
Definition: pcl_base.h:77
PointIndices::Ptr PointIndicesPtr
Definition: pcl_base.h:76
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:414
Generic search class.
Definition: search.h:75
void extractLabeledEuclideanClusters(const PointCloud< PointT > &cloud, const typename search::Search< PointT >::Ptr &tree, float tolerance, std::vector< std::vector< PointIndices >> &labeled_clusters, unsigned int min_pts_per_cluster, unsigned int max_pts_per_cluster, unsigned int max_label)
Decompose a region of space into clusters based on the Euclidean distance between points.
bool compareLabeledPointClusters(const pcl::PointIndices &a, const pcl::PointIndices &b)
Sort clusters method (for std::sort).
#define PCL_DEPRECATED(Major, Minor, Message)
macro for compatibility across compilers and help remove old deprecated items for the Major....
Definition: pcl_macros.h:156
shared_ptr< ::pcl::PointIndices > Ptr
Definition: PointIndices.h:13
shared_ptr< const ::pcl::PointIndices > ConstPtr
Definition: PointIndices.h:14
A point structure representing Euclidean xyz coordinates, and the RGB color.