Point Cloud Library (PCL)  1.9.1
convolution_3d.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_CONVOLUTION_3D_H
41 #define PCL_FILTERS_CONVOLUTION_3D_H
42 
43 #include <pcl/pcl_base.h>
44 #include <pcl/filters/boost.h>
45 #include <pcl/search/pcl_search.h>
46 
47 namespace pcl
48 {
49  namespace filters
50  {
51  /** \brief Class ConvolvingKernel base class for all convolving kernels
52  * \ingroup filters
53  */
54  template<typename PointInT, typename PointOutT>
56  {
57  public:
58  typedef boost::shared_ptr<ConvolvingKernel<PointInT, PointOutT> > Ptr;
59  typedef boost::shared_ptr<const ConvolvingKernel<PointInT, PointOutT> > ConstPtr;
60 
62 
63  /// \brief empty constructor
65 
66  /// \brief empty destructor
67  virtual ~ConvolvingKernel () {}
68 
69  /** \brief Set input cloud
70  * \param[in] input source point cloud
71  */
72  void
73  setInputCloud (const PointCloudInConstPtr& input) { input_ = input; }
74 
75  /** \brief Convolve point at the center of this local information
76  * \param[in] indices indices of the point in the source point cloud
77  * \param[in] distances euclidean distance squared from the query point
78  * \return the convolved point
79  */
80  virtual PointOutT
81  operator() (const std::vector<int>& indices, const std::vector<float>& distances) = 0;
82 
83  /** \brief Must call this method before doing any computation
84  * \note make sure to override this with at least
85  * \code
86  * bool initCompute ()
87  * {
88  * return (true);
89  * }
90  * \endcode
91  * in your kernel interface, else you are going nowhere!
92  */
93  virtual bool
94  initCompute () { return false; }
95 
96  /** \brief Utility function that annihilates a point making it fail the \ref pcl::isFinite test
97  * \param p point to annihilate
98  */
99  static void
100  makeInfinite (PointOutT& p)
101  {
102  p.x = p.y = p.z = std::numeric_limits<float>::quiet_NaN ();
103  }
104 
105  protected:
106  /// source cloud
108  };
109 
110  /** \brief Gaussian kernel implementation interface
111  * Use this as implementation reference
112  * \ingroup filters
113  */
114  template<typename PointInT, typename PointOutT>
115  class GaussianKernel : public ConvolvingKernel <PointInT, PointOutT>
116  {
117  public:
122  typedef boost::shared_ptr<GaussianKernel<PointInT, PointOutT> > Ptr;
123  typedef boost::shared_ptr<GaussianKernel<PointInT, PointOutT> > ConstPtr;
124 
125  /** Default constructor */
127  : ConvolvingKernel <PointInT, PointOutT> ()
128  , sigma_ (0)
129  , threshold_ (std::numeric_limits<float>::infinity ())
130  {}
131 
132  virtual ~GaussianKernel () {}
133 
134  /** Set the sigma parameter of the Gaussian
135  * \param[in] sigma
136  */
137  inline void
138  setSigma (float sigma) { sigma_ = sigma; }
139 
140  /** Set the distance threshold relative to a sigma factor i.e. points such as
141  * ||pi - q|| > sigma_coefficient^2 * sigma^2 are not considered.
142  */
143  inline void
144  setThresholdRelativeToSigma (float sigma_coefficient)
145  {
146  sigma_coefficient_.reset (sigma_coefficient);
147  }
148 
149  /** Set the distance threshold such as pi, ||pi - q|| > threshold are not considered. */
150  inline void
151  setThreshold (float threshold) { threshold_ = threshold; }
152 
153  /** Must call this method before doing any computation */
154  bool initCompute ();
155 
156  virtual PointOutT
157  operator() (const std::vector<int>& indices, const std::vector<float>& distances);
158 
159  protected:
160  float sigma_;
161  float sigma_sqr_;
162  float threshold_;
163  boost::optional<float> sigma_coefficient_;
164  };
165 
166  /** \brief Gaussian kernel implementation interface with RGB channel handling
167  * Use this as implementation reference
168  * \ingroup filters
169  */
170  template<typename PointInT, typename PointOutT>
171  class GaussianKernelRGB : public GaussianKernel <PointInT, PointOutT>
172  {
173  public:
180  typedef boost::shared_ptr<GaussianKernelRGB<PointInT, PointOutT> > Ptr;
181  typedef boost::shared_ptr<GaussianKernelRGB<PointInT, PointOutT> > ConstPtr;
182 
183  /** Default constructor */
185  : GaussianKernel <PointInT, PointOutT> ()
186  {}
187 
189 
190  PointOutT
191  operator() (const std::vector<int>& indices, const std::vector<float>& distances);
192  };
193 
194  /** Convolution3D handles the non organized case where width and height are unknown or if you
195  * are only interested in convolving based on local neighborhood information.
196  * The convolving kernel MUST be a radial symmetric and implement \ref ConvolvingKernel
197  * interface.
198  */
199  template <typename PointIn, typename PointOut, typename KernelT>
200  class Convolution3D : public pcl::PCLBase <PointIn>
201  {
202  public:
208  typedef boost::shared_ptr<Convolution3D<PointIn, PointOut, KernelT> > Ptr;
209  typedef boost::shared_ptr<Convolution3D<PointIn, PointOut, KernelT> > ConstPtr;
210 
213 
214  /** \brief Constructor */
215  Convolution3D ();
216 
217  /** \brief Empty destructor */
219 
220  /** \brief Initialize the scheduler and set the number of threads to use.
221  * \param nr_threads the number of hardware threads to use (0 sets the value back to automatic)
222  */
223  inline void
224  setNumberOfThreads (unsigned int nr_threads = 0) { threads_ = nr_threads; }
225 
226  /** \brief Set convolving kernel
227  * \param[in] kernel convolving element
228  */
229  inline void
230  setKernel (const KernelT& kernel) { kernel_ = kernel; }
231 
232  /** \brief Provide a pointer to the input dataset that we need to estimate features at every point for.
233  * \param cloud the const boost shared pointer to a PointCloud message
234  */
235  inline void
236  setSearchSurface (const PointCloudInConstPtr &cloud) { surface_ = cloud; }
237 
238  /** \brief Get a pointer to the surface point cloud dataset. */
239  inline PointCloudInConstPtr
240  getSearchSurface () { return (surface_); }
241 
242  /** \brief Provide a pointer to the search object.
243  * \param tree a pointer to the spatial search object.
244  */
245  inline void
246  setSearchMethod (const KdTreePtr &tree) { tree_ = tree; }
247 
248  /** \brief Get a pointer to the search method used. */
249  inline KdTreePtr
250  getSearchMethod () { return (tree_); }
251 
252  /** \brief Set the sphere radius that is to be used for determining the nearest neighbors
253  * \param radius the sphere radius used as the maximum distance to consider a point a neighbor
254  */
255  inline void
256  setRadiusSearch (double radius) { search_radius_ = radius; }
257 
258  /** \brief Get the sphere radius used for determining the neighbors. */
259  inline double
261 
262  /** Convolve point cloud.
263  * \param[out] output the convolved cloud
264  */
265  void
266  convolve (PointCloudOut& output);
267 
268  protected:
269  /** \brief initialize computation */
270  bool initCompute ();
271 
272  /** \brief An input point cloud describing the surface that is to be used for nearest neighbors estimation. */
274 
275  /** \brief A pointer to the spatial search object. */
277 
278  /** \brief The nearest neighbors search radius for each point. */
280 
281  /** \brief number of threads */
282  unsigned int threads_;
283 
284  /** \brief convlving kernel */
285  KernelT kernel_;
286  };
287  }
288 }
289 
290 #include <pcl/filters/impl/convolution_3d.hpp>
291 
292 #endif // PCL_FILTERS_CONVOLUTION_3D_H
pcl::filters::GaussianKernelRGB::GaussianKernelRGB
GaussianKernelRGB()
Default constructor.
Definition: convolution_3d.h:184
pcl::search::Search< PointIn >
pcl
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
pcl::filters::Convolution3D::setSearchSurface
void setSearchSurface(const PointCloudInConstPtr &cloud)
Provide a pointer to the input dataset that we need to estimate features at every point for.
Definition: convolution_3d.h:236
pcl::filters::Convolution3D::ConstPtr
boost::shared_ptr< Convolution3D< PointIn, PointOut, KernelT > > ConstPtr
Definition: convolution_3d.h:209
pcl::filters::Convolution3D::PointCloudIn
pcl::PointCloud< PointIn > PointCloudIn
Definition: convolution_3d.h:203
pcl::search::Search::Ptr
boost::shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:81
pcl::filters::Convolution3D::tree_
KdTreePtr tree_
A pointer to the spatial search object.
Definition: convolution_3d.h:276
pcl::filters::ConvolvingKernel::initCompute
virtual bool initCompute()
Must call this method before doing any computation.
Definition: convolution_3d.h:94
pcl::filters::Convolution3D::KdTree
pcl::search::Search< PointIn > KdTree
Definition: convolution_3d.h:205
pcl::filters::GaussianKernel::operator()
virtual PointOutT operator()(const std::vector< int > &indices, const std::vector< float > &distances)
Convolve point at the center of this local information.
Definition: convolution_3d.hpp:101
pcl::filters::GaussianKernel::setSigma
void setSigma(float sigma)
Set the sigma parameter of the Gaussian.
Definition: convolution_3d.h:138
pcl::filters::GaussianKernelRGB::~GaussianKernelRGB
~GaussianKernelRGB()
Definition: convolution_3d.h:188
pcl::filters::ConvolvingKernel::input_
PointCloudInConstPtr input_
source cloud
Definition: convolution_3d.h:107
pcl::filters::ConvolvingKernel::makeInfinite
static void makeInfinite(PointOutT &p)
Utility function that annihilates a point making it fail the pcl::isFinite test.
Definition: convolution_3d.h:100
pcl::filters::ConvolvingKernel::PointCloudInConstPtr
PointCloud< PointInT >::ConstPtr PointCloudInConstPtr
Definition: convolution_3d.h:61
pcl::filters::GaussianKernel::GaussianKernel
GaussianKernel()
Default constructor.
Definition: convolution_3d.h:126
pcl::filters::GaussianKernel::sigma_coefficient_
boost::optional< float > sigma_coefficient_
Definition: convolution_3d.h:163
pcl::filters::GaussianKernel::setThresholdRelativeToSigma
void setThresholdRelativeToSigma(float sigma_coefficient)
Set the distance threshold relative to a sigma factor i.e.
Definition: convolution_3d.h:144
pcl::filters::Convolution3D::setRadiusSearch
void setRadiusSearch(double radius)
Set the sphere radius that is to be used for determining the nearest neighbors.
Definition: convolution_3d.h:256
pcl::filters::Convolution3D::setSearchMethod
void setSearchMethod(const KdTreePtr &tree)
Provide a pointer to the search object.
Definition: convolution_3d.h:246
pcl::filters::Convolution3D::search_radius_
double search_radius_
The nearest neighbors search radius for each point.
Definition: convolution_3d.h:279
pcl::PCLBase
PCL base class.
Definition: pcl_base.h:68
pcl::filters::Convolution3D::convolve
void convolve(PointCloudOut &output)
Convolve point cloud.
Definition: convolution_3d.hpp:226
pcl::PointCloud
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: projection_matrix.h:53
pcl::filters::GaussianKernel::threshold_
float threshold_
Definition: convolution_3d.h:162
pcl::filters::ConvolvingKernel::ConvolvingKernel
ConvolvingKernel()
empty constructor
Definition: convolution_3d.h:64
pcl::filters::Convolution3D::getSearchMethod
KdTreePtr getSearchMethod()
Get a pointer to the search method used.
Definition: convolution_3d.h:250
pcl::filters::Convolution3D::initCompute
bool initCompute()
initialize computation
Definition: convolution_3d.hpp:180
pcl::filters::GaussianKernelRGB::operator()
PointOutT operator()(const std::vector< int > &indices, const std::vector< float > &distances)
Convolve point at the center of this local information.
Definition: convolution_3d.hpp:130
pcl::filters::Convolution3D::PointCloudOut
pcl::PointCloud< PointOut > PointCloudOut
Definition: convolution_3d.h:207
pcl::filters::Convolution3D::PointCloudInConstPtr
PointCloudIn::ConstPtr PointCloudInConstPtr
Definition: convolution_3d.h:204
pcl::filters::Convolution3D
Convolution3D handles the non organized case where width and height are unknown or if you are only in...
Definition: convolution_3d.h:200
pcl::filters::ConvolvingKernel::setInputCloud
void setInputCloud(const PointCloudInConstPtr &input)
Set input cloud.
Definition: convolution_3d.h:73
pcl::filters::Convolution3D::Convolution3D
Convolution3D()
Constructor.
Definition: convolution_3d.hpp:171
pcl::filters::Convolution3D::Ptr
boost::shared_ptr< Convolution3D< PointIn, PointOut, KernelT > > Ptr
Definition: convolution_3d.h:208
pcl::filters::GaussianKernelRGB::ConstPtr
boost::shared_ptr< GaussianKernelRGB< PointInT, PointOutT > > ConstPtr
Definition: convolution_3d.h:181
pcl::filters::Convolution3D::setKernel
void setKernel(const KernelT &kernel)
Set convolving kernel.
Definition: convolution_3d.h:230
pcl::filters::GaussianKernelRGB::Ptr
boost::shared_ptr< GaussianKernelRGB< PointInT, PointOutT > > Ptr
Definition: convolution_3d.h:180
pcl::filters::ConvolvingKernel::ConstPtr
boost::shared_ptr< const ConvolvingKernel< PointInT, PointOutT > > ConstPtr
Definition: convolution_3d.h:59
pcl::filters::GaussianKernel::setThreshold
void setThreshold(float threshold)
Set the distance threshold such as pi, ||pi - q|| > threshold are not considered.
Definition: convolution_3d.h:151
pcl::filters::Convolution3D::getSearchSurface
PointCloudInConstPtr getSearchSurface()
Get a pointer to the surface point cloud dataset.
Definition: convolution_3d.h:240
pcl::filters::Convolution3D::~Convolution3D
~Convolution3D()
Empty destructor.
Definition: convolution_3d.h:218
pcl::filters::Convolution3D::surface_
PointCloudInConstPtr surface_
An input point cloud describing the surface that is to be used for nearest neighbors estimation.
Definition: convolution_3d.h:273
pcl::filters::GaussianKernel::Ptr
boost::shared_ptr< GaussianKernel< PointInT, PointOutT > > Ptr
Definition: convolution_3d.h:122
pcl::filters::GaussianKernel::ConstPtr
boost::shared_ptr< GaussianKernel< PointInT, PointOutT > > ConstPtr
Definition: convolution_3d.h:123
std
Definition: multi_grid_octree_data.hpp:45
pcl::PointCloud::ConstPtr
boost::shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:429
pcl::filters::GaussianKernel::initCompute
bool initCompute()
Must call this method before doing any computation.
Definition: convolution_3d.hpp:76
pcl::filters::ConvolvingKernel
Class ConvolvingKernel base class for all convolving kernels.
Definition: convolution_3d.h:55
pcl::filters::Convolution3D::KdTreePtr
pcl::search::Search< PointIn >::Ptr KdTreePtr
Definition: convolution_3d.h:206
pcl::filters::Convolution3D::getRadiusSearch
double getRadiusSearch()
Get the sphere radius used for determining the neighbors.
Definition: convolution_3d.h:260
pcl::filters::ConvolvingKernel::operator()
virtual PointOutT operator()(const std::vector< int > &indices, const std::vector< float > &distances)=0
Convolve point at the center of this local information.
pcl::filters::ConvolvingKernel::Ptr
boost::shared_ptr< ConvolvingKernel< PointInT, PointOutT > > Ptr
Definition: convolution_3d.h:58
pcl::filters::Convolution3D::threads_
unsigned int threads_
number of threads
Definition: convolution_3d.h:282
pcl::filters::GaussianKernel::sigma_
float sigma_
Definition: convolution_3d.h:160
pcl::filters::Convolution3D::setNumberOfThreads
void setNumberOfThreads(unsigned int nr_threads=0)
Initialize the scheduler and set the number of threads to use.
Definition: convolution_3d.h:224
pcl::filters::ConvolvingKernel::~ConvolvingKernel
virtual ~ConvolvingKernel()
empty destructor
Definition: convolution_3d.h:67
pcl::kernel
Definition: kernel.h:45
pcl::filters::GaussianKernel::sigma_sqr_
float sigma_sqr_
Definition: convolution_3d.h:161
pcl::filters::GaussianKernel::~GaussianKernel
virtual ~GaussianKernel()
Definition: convolution_3d.h:132
pcl::filters::Convolution3D::kernel_
KernelT kernel_
convlving kernel
Definition: convolution_3d.h:285
pcl::filters::GaussianKernelRGB
Gaussian kernel implementation interface with RGB channel handling Use this as implementation referen...
Definition: convolution_3d.h:171
pcl::filters::GaussianKernel
Gaussian kernel implementation interface Use this as implementation reference.
Definition: convolution_3d.h:115