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() = default;
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  /** Set the sigma parameter of the Gaussian
131  * \param[in] sigma
132  */
133  inline void
134  setSigma (float sigma) { sigma_ = sigma; }
135 
136  /** Set the distance threshold relative to a sigma factor i.e. points such as
137  * ||pi - q|| > sigma_coefficient^2 * sigma^2 are not considered.
138  */
139  inline void
140  setThresholdRelativeToSigma (float sigma_coefficient)
141  {
142  sigma_coefficient_.reset (sigma_coefficient);
143  }
144 
145  /** Set the distance threshold such as pi, ||pi - q|| > threshold are not considered. */
146  inline void
147  setThreshold (float threshold) { threshold_ = threshold; }
148 
149  /** Must call this method before doing any computation */
150  bool initCompute ();
151 
152  virtual PointOutT
153  operator() (const Indices& indices, const std::vector<float>& distances);
154 
155  protected:
156  float sigma_;
157  float sigma_sqr_;
158  float threshold_;
159  boost::optional<float> sigma_coefficient_;
160  };
161 
162  /** \brief Gaussian kernel implementation interface with RGB channel handling
163  * Use this as implementation reference
164  * \ingroup filters
165  */
166  template<typename PointInT, typename PointOutT>
167  class GaussianKernelRGB : public GaussianKernel <PointInT, PointOutT>
168  {
169  public:
176  using Ptr = shared_ptr<GaussianKernelRGB<PointInT, PointOutT> >;
177  using ConstPtr = shared_ptr<GaussianKernelRGB<PointInT, PointOutT> >;
178 
179  /** Default constructor */
181  : GaussianKernel <PointInT, PointOutT> ()
182  {}
183 
184  PointOutT
185  operator() (const Indices& indices, const std::vector<float>& distances);
186  };
187 
188  /** Convolution3D handles the non organized case where width and height are unknown or if you
189  * are only interested in convolving based on local neighborhood information.
190  * The convolving kernel MUST be a radial symmetric and implement \ref ConvolvingKernel
191  * interface.
192  */
193  template <typename PointIn, typename PointOut, typename KernelT>
194  class Convolution3D : public pcl::PCLBase <PointIn>
195  {
196  public:
200  using KdTreePtr = typename KdTree::Ptr;
202  using Ptr = shared_ptr<Convolution3D<PointIn, PointOut, KernelT> >;
203  using ConstPtr = shared_ptr<Convolution3D<PointIn, PointOut, KernelT> >;
204 
207 
208  /** \brief Constructor */
209  Convolution3D ();
210 
211  /** \brief Initialize the scheduler and set the number of threads to use.
212  * \param nr_threads the number of hardware threads to use (0 sets the value back to automatic)
213  */
214  inline void
215  setNumberOfThreads (unsigned int nr_threads = 0) { threads_ = nr_threads; }
216 
217  /** \brief Set convolving kernel
218  * \param[in] kernel convolving element
219  */
220  inline void
221  setKernel (const KernelT& kernel) { kernel_ = kernel; }
222 
223  /** \brief Provide a pointer to the input dataset that we need to estimate features at every point for.
224  * \param cloud the const boost shared pointer to a PointCloud message
225  */
226  inline void
227  setSearchSurface (const PointCloudInConstPtr &cloud) { surface_ = cloud; }
228 
229  /** \brief Get a pointer to the surface point cloud dataset. */
230  inline PointCloudInConstPtr
231  getSearchSurface () { return (surface_); }
232 
233  /** \brief Provide a pointer to the search object.
234  * \param tree a pointer to the spatial search object.
235  */
236  inline void
237  setSearchMethod (const KdTreePtr &tree) { tree_ = tree; }
238 
239  /** \brief Get a pointer to the search method used. */
240  inline KdTreePtr
241  getSearchMethod () { return (tree_); }
242 
243  /** \brief Set the sphere radius that is to be used for determining the nearest neighbors
244  * \param radius the sphere radius used as the maximum distance to consider a point a neighbor
245  */
246  inline void
247  setRadiusSearch (double radius) { search_radius_ = radius; }
248 
249  /** \brief Get the sphere radius used for determining the neighbors. */
250  inline double
252 
253  /** Convolve point cloud.
254  * \param[out] output the convolved cloud
255  */
256  void
257  convolve (PointCloudOut& output);
258 
259  protected:
260  /** \brief initialize computation */
261  bool initCompute ();
262 
263  /** \brief An input point cloud describing the surface that is to be used for nearest neighbors estimation. */
265 
266  /** \brief A pointer to the spatial search object. */
268 
269  /** \brief The nearest neighbors search radius for each point. */
271 
272  /** \brief number of threads */
273  unsigned int threads_;
274 
275  /** \brief convlving kernel */
276  KernelT kernel_;
277  };
278  }
279 }
280 
281 #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.
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
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 ~ConvolvingKernel()=default
empty destructor
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