Point Cloud Library (PCL)  1.9.1-dev
statistical_outlier_removal.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2012, 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  * $Id$
37  *
38  */
39 
40 #pragma once
41 
42 #include <pcl/filters/filter_indices.h>
43 #include <pcl/search/pcl_search.h>
44 
45 namespace pcl
46 {
47  /** \brief @b StatisticalOutlierRemoval uses point neighborhood statistics to filter outlier data.
48  * \details The algorithm iterates through the entire input twice:
49  * During the first iteration it will compute the average distance that each point has to its nearest k neighbors.
50  * The value of k can be set using setMeanK().
51  * Next, the mean and standard deviation of all these distances are computed in order to determine a distance threshold.
52  * The distance threshold will be equal to: mean + stddev_mult * stddev.
53  * The multiplier for the standard deviation can be set using setStddevMulThresh().
54  * During the next iteration the points will be classified as inlier or outlier if their average neighbor distance is below or above this threshold respectively.
55  * <br>
56  * The neighbors found for each query point will be found amongst ALL points of setInputCloud(), not just those indexed by setIndices().
57  * The setIndices() method only indexes the points that will be iterated through as search query points.
58  * <br><br>
59  * For more information:
60  * - R. B. Rusu, Z. C. Marton, N. Blodow, M. Dolha, and M. Beetz.
61  * Towards 3D Point Cloud Based Object Maps for Household Environments
62  * Robotics and Autonomous Systems Journal (Special Issue on Semantic Knowledge), 2008.
63  * <br><br>
64  * Usage example:
65  * \code
66  * pcl::StatisticalOutlierRemoval<PointType> sorfilter (true); // Initializing with true will allow us to extract the removed indices
67  * sorfilter.setInputCloud (cloud_in);
68  * sorfilter.setMeanK (8);
69  * sorfilter.setStddevMulThresh (1.0);
70  * sorfilter.filter (*cloud_out);
71  * // The resulting cloud_out contains all points of cloud_in that have an average distance to their 8 nearest neighbors that is below the computed threshold
72  * // Using a standard deviation multiplier of 1.0 and assuming the average distances are normally distributed there is a 84.1% chance that a point will be an inlier
73  * indices_rem = sorfilter.getRemovedIndices ();
74  * // The indices_rem array indexes all points of cloud_in that are outliers
75  * \endcode
76  * \author Radu Bogdan Rusu
77  * \ingroup filters
78  */
79  template<typename PointT>
81  {
82  protected:
84  typedef typename PointCloud::Ptr PointCloudPtr;
87 
88  public:
89 
90  typedef boost::shared_ptr< StatisticalOutlierRemoval<PointT> > Ptr;
91  typedef boost::shared_ptr< const StatisticalOutlierRemoval<PointT> > ConstPtr;
92 
93 
94  /** \brief Constructor.
95  * \param[in] extract_removed_indices Set to true if you want to be able to extract the indices of points being removed (default = false).
96  */
97  StatisticalOutlierRemoval (bool extract_removed_indices = false) :
98  FilterIndices<PointT>::FilterIndices (extract_removed_indices),
99  searcher_ (),
100  mean_k_ (1),
101  std_mul_ (0.0)
102  {
103  filter_name_ = "StatisticalOutlierRemoval";
104  }
105 
106  /** \brief Set the number of nearest neighbors to use for mean distance estimation.
107  * \param[in] nr_k The number of points to use for mean distance estimation.
108  */
109  inline void
110  setMeanK (int nr_k)
111  {
112  mean_k_ = nr_k;
113  }
114 
115  /** \brief Get the number of nearest neighbors to use for mean distance estimation.
116  * \return The number of points to use for mean distance estimation.
117  */
118  inline int
120  {
121  return (mean_k_);
122  }
123 
124  /** \brief Set the standard deviation multiplier for the distance threshold calculation.
125  * \details The distance threshold will be equal to: mean + stddev_mult * stddev.
126  * Points will be classified as inlier or outlier if their average neighbor distance is below or above this threshold respectively.
127  * \param[in] stddev_mult The standard deviation multiplier.
128  */
129  inline void
130  setStddevMulThresh (double stddev_mult)
131  {
132  std_mul_ = stddev_mult;
133  }
134 
135  /** \brief Get the standard deviation multiplier for the distance threshold calculation.
136  * \details The distance threshold will be equal to: mean + stddev_mult * stddev.
137  * Points will be classified as inlier or outlier if their average neighbor distance is below or above this threshold respectively.
138  */
139  inline double
141  {
142  return (std_mul_);
143  }
144 
145  protected:
155 
156  /** \brief Filtered results are stored in a separate point cloud.
157  * \param[out] output The resultant point cloud.
158  */
159  void
160  applyFilter (PointCloud &output) override;
161 
162  /** \brief Filtered results are indexed by an indices array.
163  * \param[out] indices The resultant indices.
164  */
165  void
166  applyFilter (std::vector<int> &indices) override
167  {
168  applyFilterIndices (indices);
169  }
170 
171  /** \brief Filtered results are indexed by an indices array.
172  * \param[out] indices The resultant indices.
173  */
174  void
175  applyFilterIndices (std::vector<int> &indices);
176 
177  private:
178  /** \brief A pointer to the spatial search object. */
179  SearcherPtr searcher_;
180 
181  /** \brief The number of points to use for mean distance estimation. */
182  int mean_k_;
183 
184  /** \brief Standard deviations threshold (i.e., points outside of
185  * \f$ \mu \pm \sigma \cdot std\_mul \f$ will be marked as outliers). */
186  double std_mul_;
187  };
188 
189  /** \brief @b StatisticalOutlierRemoval uses point neighborhood statistics to filter outlier data. For more
190  * information check:
191  * - R. B. Rusu, Z. C. Marton, N. Blodow, M. Dolha, and M. Beetz.
192  * Towards 3D Point Cloud Based Object Maps for Household Environments
193  * Robotics and Autonomous Systems Journal (Special Issue on Semantic Knowledge), 2008.
194  *
195  * \note setFilterFieldName (), setFilterLimits (), and setFilterLimitNegative () are ignored.
196  * \author Radu Bogdan Rusu
197  * \ingroup filters
198  */
199  template<>
200  class PCL_EXPORTS StatisticalOutlierRemoval<pcl::PCLPointCloud2> : public FilterIndices<pcl::PCLPointCloud2>
201  {
204 
207 
209  typedef pcl::search::Search<pcl::PointXYZ>::Ptr KdTreePtr;
210 
214 
215  public:
216  /** \brief Empty constructor. */
217  StatisticalOutlierRemoval (bool extract_removed_indices = false) :
218  FilterIndices<pcl::PCLPointCloud2>::FilterIndices (extract_removed_indices), mean_k_ (2),
219  std_mul_ (0.0), tree_ ()
220  {
221  filter_name_ = "StatisticalOutlierRemoval";
222  }
223 
224  /** \brief Set the number of points (k) to use for mean distance estimation
225  * \param nr_k the number of points to use for mean distance estimation
226  */
227  inline void
228  setMeanK (int nr_k)
229  {
230  mean_k_ = nr_k;
231  }
232 
233  /** \brief Get the number of points to use for mean distance estimation. */
234  inline int
236  {
237  return (mean_k_);
238  }
239 
240  /** \brief Set the standard deviation multiplier threshold. All points outside the
241  * \f[ \mu \pm \sigma \cdot std\_mul \f]
242  * will be considered outliers, where \f$ \mu \f$ is the estimated mean,
243  * and \f$ \sigma \f$ is the standard deviation.
244  * \param std_mul the standard deviation multiplier threshold
245  */
246  inline void
247  setStddevMulThresh (double std_mul)
248  {
249  std_mul_ = std_mul;
250  }
251 
252  /** \brief Get the standard deviation multiplier threshold as set by the user. */
253  inline double
255  {
256  return (std_mul_);
257  }
258 
259  protected:
260  /** \brief The number of points to use for mean distance estimation. */
261  int mean_k_;
262 
263  /** \brief Standard deviations threshold (i.e., points outside of
264  * \f$ \mu \pm \sigma \cdot std\_mul \f$ will be marked as outliers).
265  */
266  double std_mul_;
267 
268  /** \brief A pointer to the spatial search object. */
269  KdTreePtr tree_;
270 
271  void
272  applyFilter (std::vector<int> &indices) override;
273 
274  void
275  applyFilter (PCLPointCloud2 &output) override;
276 
277  /**
278  * \brief Compute the statistical values used in both applyFilter methods.
279  *
280  * This method tries to avoid duplicate code.
281  */
282  virtual void
283  generateStatistics (double& mean, double& variance, double& stddev, std::vector<float>& distances);
284  };
285 }
286 
287 #ifdef PCL_NO_PRECOMPILE
288 #include <pcl/filters/impl/statistical_outlier_removal.hpp>
289 #endif
void setMeanK(int nr_k)
Set the number of points (k) to use for mean distance estimation.
void setStddevMulThresh(double std_mul)
Set the standard deviation multiplier threshold.
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:44
int getMeanK()
Get the number of nearest neighbors to use for mean distance estimation.
double getStddevMulThresh()
Get the standard deviation multiplier threshold as set by the user.
void applyFilterIndices(std::vector< int > &indices)
Filtered results are indexed by an indices array.
void setStddevMulThresh(double stddev_mult)
Set the standard deviation multiplier for the distance threshold calculation.
boost::shared_ptr< ::pcl::PCLPointCloud2 const > PCLPointCloud2ConstPtr
void applyFilter(PointCloud &output) override
Filtered results are stored in a separate point cloud.
void setMeanK(int nr_k)
Set the number of nearest neighbors to use for mean distance estimation.
boost::shared_ptr< ::pcl::PCLPointCloud2 > Ptr
pcl::search::Search< PointT >::Ptr SearcherPtr
boost::shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:427
double getStddevMulThresh()
Get the standard deviation multiplier for the distance threshold calculation.
FilterIndices represents the base class for filters that are about binary point removal.
StatisticalOutlierRemoval uses point neighborhood statistics to filter outlier data.
boost::shared_ptr< StatisticalOutlierRemoval< PointT > > Ptr
StatisticalOutlierRemoval(bool extract_removed_indices=false)
Constructor.
Filter represents the base filter class.
Definition: filter.h:83
boost::shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:80
StatisticalOutlierRemoval(bool extract_removed_indices=false)
Empty constructor.
PCL base class.
Definition: pcl_base.h:68
double std_mul_
Standard deviations threshold (i.e., points outside of will be marked as outliers).
boost::shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:428
boost::shared_ptr< ::pcl::PCLPointCloud2 const > ConstPtr
PointCloud represents the base class in PCL for storing collections of 3D points. ...
boost::shared_ptr< ::pcl::PCLPointCloud2 > PCLPointCloud2Ptr
int getMeanK()
Get the number of points to use for mean distance estimation.
KdTreePtr tree_
A pointer to the spatial search object.
boost::shared_ptr< const StatisticalOutlierRemoval< PointT > > ConstPtr
void applyFilter(std::vector< int > &indices) override
Filtered results are indexed by an indices array.
std::string filter_name_
The filter name.
Definition: filter.h:165
A point structure representing Euclidean xyz coordinates, and the RGB color.
FilterIndices< PointT >::PointCloud PointCloud
int mean_k_
The number of points to use for mean distance estimation.