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