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