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