Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/filters/include/pcl/filters/pyramid.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2012-, Open Perception.
00006  *
00007  *  All rights reserved.
00008  *
00009  *  Redistribution and use in source and binary forms, with or without
00010  *  modification, are permitted provided that the following conditions
00011  *  are met:
00012  *
00013  *   * Redistributions of source code must retain the above copyright
00014  *     notice, this list of conditions and the following disclaimer.
00015  *   * Redistributions in binary form must reproduce the above
00016  *     copyright notice, this list of conditions and the following
00017  *     disclaimer in the documentation and/or other materials provided
00018  *     with the distribution.
00019  *   * Neither the name of the copyright holder(s) nor the names of its
00020  *     contributors may be used to endorse or promote products derived
00021  *     from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00027  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034  *  POSSIBILITY OF SUCH DAMAGE.
00035  *
00036  * $Id$
00037  *
00038  */
00039 
00040 #ifndef PCL_FILTERS_PYRAMID_H_
00041 #define PCL_FILTERS_PYRAMID_H_
00042 
00043 #include <pcl/common/point_operators.h>
00044 #include <pcl/point_cloud.h>
00045 #include <pcl/pcl_config.h>
00046 
00047 namespace pcl
00048 {
00049   namespace filters
00050   {
00051     /** Pyramid constructs a multi-scale representation of an organised point cloud.
00052       * It is an iterative smoothing subsampling algorithm.
00053       * The subsampling is fixed to 2. Two smoothing kernels may be used:
00054       * - [1/16 1/4 3/8 1/4 1/16] slower but produces finer result;
00055       * - [1/4 1/2 1/2] the more conventional binomial kernel which is faster.
00056       * We use a memory efficient algorithm so the convolving and subsampling are combined in a 
00057       * single step.
00058       *
00059       * \author Nizar Sallem
00060       */
00061     template <typename PointT>
00062     class Pyramid
00063     {
00064       public:
00065         typedef typename PointCloud<PointT>::Ptr PointCloudPtr;
00066         typedef typename PointCloud<PointT>::ConstPtr PointCloudConstPtr;
00067         typedef boost::shared_ptr< Pyramid<PointT> > Ptr;
00068         typedef boost::shared_ptr< const Pyramid<PointT> > ConstPtr;
00069  
00070         Pyramid (int levels = 4)
00071           : levels_ (levels)
00072           , large_ (false)
00073           , threshold_ (0.01)
00074           , threads_ (0)
00075         {
00076           name_ = "Pyramid";
00077         }
00078       
00079         /** \brief Provide a pointer to the input dataset
00080           * \param cloud the const boost shared pointer to a PointCloud message
00081           */
00082         inline void 
00083         setInputCloud (const PointCloudConstPtr &cloud) { input_ = cloud; }
00084 
00085         /** \brief Get a pointer to the input point cloud dataset. */
00086         inline PointCloudConstPtr const 
00087         getInputCloud () { return (input_); }
00088       
00089         /** \brief Set the number of pyramid levels
00090           * \param levels desired number of pyramid levels
00091           */
00092         inline void
00093         setNumberOfLevels (int levels) { levels_ = levels; }
00094       
00095         /// \brief \return the number of pyramid levels
00096         inline int
00097         getNumberOfLevels () const { return (levels_); }
00098 
00099         /** \brief Initialize the scheduler and set the number of threads to use.
00100           * \param nr_threads the number of hardware threads to use (0 sets the value back to automatic).
00101           */
00102         inline void
00103         setNumberOfThreads (unsigned int nr_threads = 0) { threads_ = nr_threads; }
00104 
00105         /** \brief Choose a larger smoothing kernel for enhanced smoothing.
00106           * \param large if true large smoothng kernel will be used.
00107           */
00108         inline void
00109         setLargeSmoothingKernel (bool large) { large_ = large; }
00110       
00111         /** Only points such us distance (center,point) < threshold are accounted for to prevent
00112           * ghost points.
00113           * Default value is 0.01, to disable set to std::numeric<float>::infinity ().
00114           * \param[in] threshold maximum allowed distance between center and neighbor.
00115           */
00116         inline void
00117         setDistanceThreshold (float threshold) { threshold_ = threshold; }
00118 
00119         /// \return the distance threshold
00120         inline float
00121         getDistanceThreshold () const { return (threshold_); }
00122 
00123         /** \brief compute the pyramid levels.
00124           * \param[out] output the constructed pyramid. It is resized to the number of levels.
00125           * \remark input_ is copied to output[0] for consistency reasons.
00126           */
00127         void
00128         compute (std::vector<PointCloudPtr>& output);
00129 
00130         inline const std::string&
00131         getClassName () const { return (name_); }
00132       
00133       private:
00134 
00135         /// \brief init computation
00136         bool 
00137         initCompute ();
00138 
00139         /** \brief nullify a point 
00140           * \param[in][out] p point to nullify
00141           */
00142         inline void
00143         nullify (PointT& p) const
00144         {
00145           p.x = p.y = p.z = std::numeric_limits<float>::quiet_NaN ();
00146         }
00147 
00148         /// \brief The input point cloud dataset.
00149         PointCloudConstPtr input_;
00150         /// \brief number of pyramid levels
00151         int levels_;
00152         /// \brief use large smoothing kernel
00153         bool large_;
00154         /// \brief filter name
00155         std::string name_;
00156         /// \brief smoothing kernel
00157         Eigen::MatrixXf kernel_;
00158         /// Threshold distance between adjacent points
00159         float threshold_;
00160         /// \brief number of threads
00161         unsigned int threads_;
00162 
00163       public:
00164         EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00165     };
00166   }
00167 }
00168 
00169 #endif