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