Point Cloud Library (PCL)  1.11.0-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  using Ptr = shared_ptr<ConvolvingKernel<PointInT, PointOutT> >;
58  using ConstPtr = shared_ptr<const ConvolvingKernel<PointInT, PointOutT> >;
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
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  using Ptr = shared_ptr<GaussianKernel<PointInT, PointOutT> >;
122  using ConstPtr = shared_ptr<GaussianKernel<PointInT, PointOutT> >;
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  using Ptr = shared_ptr<GaussianKernelRGB<PointInT, PointOutT> >;
180  using ConstPtr = shared_ptr<GaussianKernelRGB<PointInT, PointOutT> >;
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  using KdTreePtr = typename KdTree::Ptr;
207  using Ptr = shared_ptr<Convolution3D<PointIn, PointOut, KernelT> >;
208  using ConstPtr = shared_ptr<Convolution3D<PointIn, PointOut, KernelT> >;
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
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. */
273 
274  /** \brief A pointer to the spatial search object. */
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::filters::GaussianKernelRGB::GaussianKernelRGB
GaussianKernelRGB()
Default constructor.
Definition: convolution_3d.h:183
pcl::search::Search
Generic search class.
Definition: search.h:74
pcl
Definition: convolution.h:46
pcl::filters::Convolution3D::Ptr
shared_ptr< Convolution3D< PointIn, PointOut, KernelT > > Ptr
Definition: convolution_3d.h:207
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:235
pcl::filters::Convolution3D::tree_
KdTreePtr tree_
A pointer to the spatial search object.
Definition: convolution_3d.h:275
pcl::filters::ConvolvingKernel::initCompute
virtual bool initCompute()
Must call this method before doing any computation.
Definition: convolution_3d.h:93
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:105
pcl::filters::GaussianKernel::setSigma
void setSigma(float sigma)
Set the sigma parameter of the Gaussian.
Definition: convolution_3d.h:137
pcl::filters::GaussianKernelRGB::~GaussianKernelRGB
~GaussianKernelRGB()
Definition: convolution_3d.h:187
pcl::filters::ConvolvingKernel::ConstPtr
shared_ptr< const ConvolvingKernel< PointInT, PointOutT > > ConstPtr
Definition: convolution_3d.h:58
pcl::filters::ConvolvingKernel::input_
PointCloudInConstPtr input_
source cloud
Definition: convolution_3d.h:106
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:99
pcl::filters::GaussianKernel::GaussianKernel
GaussianKernel()
Default constructor.
Definition: convolution_3d.h:125
pcl::filters::GaussianKernel::sigma_coefficient_
boost::optional< float > sigma_coefficient_
Definition: convolution_3d.h:162
pcl::filters::GaussianKernel::setThresholdRelativeToSigma
void setThresholdRelativeToSigma(float sigma_coefficient)
Set the distance threshold relative to a sigma factor i.e.
Definition: convolution_3d.h:143
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:255
pcl::filters::Convolution3D::setSearchMethod
void setSearchMethod(const KdTreePtr &tree)
Provide a pointer to the search object.
Definition: convolution_3d.h:245
pcl::filters::Convolution3D::search_radius_
double search_radius_
The nearest neighbors search radius for each point.
Definition: convolution_3d.h:278
pcl::PCLBase
PCL base class.
Definition: pcl_base.h:72
pcl::filters::Convolution3D::convolve
void convolve(PointCloudOut &output)
Convolve point cloud.
Definition: convolution_3d.hpp:230
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:161
pcl::filters::ConvolvingKernel::ConvolvingKernel
ConvolvingKernel()
empty constructor
Definition: convolution_3d.h:63
pcl::filters::Convolution3D::getSearchMethod
KdTreePtr getSearchMethod()
Get a pointer to the search method used.
Definition: convolution_3d.h:249
pcl::filters::Convolution3D::initCompute
bool initCompute()
initialize computation
Definition: convolution_3d.hpp:184
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:134
pcl::filters::ConvolvingKernel::PointCloudInConstPtr
typename PointCloud< PointInT >::ConstPtr PointCloudInConstPtr
Definition: convolution_3d.h:60
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:199
pcl::filters::ConvolvingKernel::setInputCloud
void setInputCloud(const PointCloudInConstPtr &input)
Set input cloud.
Definition: convolution_3d.h:72
pcl::filters::Convolution3D::Convolution3D
Convolution3D()
Constructor.
Definition: convolution_3d.hpp:175
pcl::filters::Convolution3D::setKernel
void setKernel(const KernelT &kernel)
Set convolving kernel.
Definition: convolution_3d.h:229
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:150
pcl::filters::Convolution3D::PointCloudInConstPtr
typename PointCloudIn::ConstPtr PointCloudInConstPtr
Definition: convolution_3d.h:203
pcl::search::Search::Ptr
shared_ptr< pcl::search::Search< PointT > > Ptr
Definition: search.h:81
pcl::filters::Convolution3D::getSearchSurface
PointCloudInConstPtr getSearchSurface()
Get a pointer to the surface point cloud dataset.
Definition: convolution_3d.h:239
pcl::filters::Convolution3D::~Convolution3D
~Convolution3D()
Empty destructor.
Definition: convolution_3d.h:217
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:272
pcl::filters::ConvolvingKernel::Ptr
shared_ptr< ConvolvingKernel< PointInT, PointOutT > > Ptr
Definition: convolution_3d.h:57
pcl::filters::Convolution3D::ConstPtr
shared_ptr< Convolution3D< PointIn, PointOut, KernelT > > ConstPtr
Definition: convolution_3d.h:208
pcl::filters::Convolution3D::KdTreePtr
typename KdTree::Ptr KdTreePtr
Definition: convolution_3d.h:205
pcl::filters::Convolution3D::PointCloudOut
pcl::PointCloud< PointOut > PointCloudOut
Definition: convolution_3d.h:206
pcl::filters::GaussianKernel::initCompute
bool initCompute()
Must call this method before doing any computation.
Definition: convolution_3d.hpp:80
pcl::filters::ConvolvingKernel
Class ConvolvingKernel base class for all convolving kernels.
Definition: convolution_3d.h:54
pcl::PointCloud::ConstPtr
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:430
pcl::filters::Convolution3D::getRadiusSearch
double getRadiusSearch()
Get the sphere radius used for determining the neighbors.
Definition: convolution_3d.h:259
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::Convolution3D::threads_
unsigned int threads_
number of threads
Definition: convolution_3d.h:281
pcl::filters::GaussianKernel::sigma_
float sigma_
Definition: convolution_3d.h:159
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:223
pcl::filters::ConvolvingKernel::~ConvolvingKernel
virtual ~ConvolvingKernel()
empty destructor
Definition: convolution_3d.h:66
pcl::kernel
Definition: kernel.h:46
pcl::filters::GaussianKernel::sigma_sqr_
float sigma_sqr_
Definition: convolution_3d.h:160
pcl::filters::GaussianKernel::~GaussianKernel
virtual ~GaussianKernel()
Definition: convolution_3d.h:131
pcl::filters::Convolution3D::kernel_
KernelT kernel_
convlving kernel
Definition: convolution_3d.h:284
pcl::filters::GaussianKernelRGB
Gaussian kernel implementation interface with RGB channel handling Use this as implementation referen...
Definition: convolution_3d.h:170
pcl::filters::GaussianKernel
Gaussian kernel implementation interface Use this as implementation reference.
Definition: convolution_3d.h:114