Point Cloud Library (PCL)  1.12.0
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 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