Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/features/include/pcl/features/multiscale_feature_persistence.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2011, Alexandru-Eugen Ichim
00006  *  Copyright (c) 2012-, Open Perception, Inc.
00007  *
00008  *  All rights reserved.
00009  *
00010  *  Redistribution and use in source and binary forms, with or without
00011  *  modification, are permitted provided that the following conditions
00012  *  are met:
00013  *
00014  *   * Redistributions of source code must retain the above copyright
00015  *     notice, this list of conditions and the following disclaimer.
00016  *   * Redistributions in binary form must reproduce the above
00017  *     copyright notice, this list of conditions and the following
00018  *     disclaimer in the documentation and/or other materials provided
00019  *     with the distribution.
00020  *   * Neither the name of the copyright holder(s) nor the names of its
00021  *     contributors may be used to endorse or promote products derived
00022  *     from this software without specific prior written permission.
00023  *
00024  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00025  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00026  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00027  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00028  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00029  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00030  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00031  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00032  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00033  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00034  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035  *  POSSIBILITY OF SUCH DAMAGE.
00036  *
00037  *  $Id$
00038  */
00039 
00040 #ifndef PCL_MULTISCALE_FEATURE_PERSISTENCE_H_
00041 #define PCL_MULTISCALE_FEATURE_PERSISTENCE_H_
00042 
00043 #include <pcl/pcl_base.h>
00044 #include <pcl/features/feature.h>
00045 #include <pcl/point_representation.h>
00046 #include <pcl/common/norms.h>
00047 #include <list>
00048 
00049 namespace pcl
00050 {
00051   /** \brief Generic class for extracting the persistent features from an input point cloud
00052    * It can be given any Feature estimator instance and will compute the features of the input
00053    * over a multiscale representation of the cloud and output the unique ones over those scales.
00054    *
00055    * Please refer to the following publication for more details:
00056    *    Radu Bogdan Rusu, Zoltan Csaba Marton, Nico Blodow, and Michael Beetz
00057    *    Persistent Point Feature Histograms for 3D Point Clouds
00058    *    Proceedings of the 10th International Conference on Intelligent Autonomous Systems (IAS-10)
00059    *    2008, Baden-Baden, Germany
00060    *
00061    * \author Alexandru-Eugen Ichim
00062    */
00063   template <typename PointSource, typename PointFeature>
00064   class MultiscaleFeaturePersistence : public PCLBase<PointSource>
00065   {
00066     public:
00067       typedef boost::shared_ptr<MultiscaleFeaturePersistence<PointSource, PointFeature> > Ptr;
00068       typedef boost::shared_ptr<const MultiscaleFeaturePersistence<PointSource, PointFeature> > ConstPtr;
00069       typedef pcl::PointCloud<PointFeature> FeatureCloud;
00070       typedef typename pcl::PointCloud<PointFeature>::Ptr FeatureCloudPtr;
00071       typedef typename pcl::Feature<PointSource, PointFeature>::Ptr FeatureEstimatorPtr;
00072       typedef boost::shared_ptr<const pcl::PointRepresentation <PointFeature> > FeatureRepresentationConstPtr;
00073 
00074       using pcl::PCLBase<PointSource>::input_;
00075 
00076       /** \brief Empty constructor */
00077       MultiscaleFeaturePersistence ();
00078       
00079       /** \brief Empty destructor */
00080       virtual ~MultiscaleFeaturePersistence () {}
00081 
00082       /** \brief Method that calls computeFeatureAtScale () for each scale parameter */
00083       void
00084       computeFeaturesAtAllScales ();
00085 
00086       /** \brief Central function that computes the persistent features
00087        * \param output_features a cloud containing the persistent features
00088        * \param output_indices vector containing the indices of the points in the input cloud
00089        * that have persistent features, under a one-to-one correspondence with the output_features cloud
00090        */
00091       void
00092       determinePersistentFeatures (FeatureCloud &output_features,
00093                                    boost::shared_ptr<std::vector<int> > &output_indices);
00094 
00095       /** \brief Method for setting the scale parameters for the algorithm
00096        * \param scale_values vector of scales to determine the characteristic of each scaling step
00097        */
00098       inline void
00099       setScalesVector (std::vector<float> &scale_values) { scale_values_ = scale_values; }
00100 
00101       /** \brief Method for getting the scale parameters vector */
00102       inline std::vector<float>
00103       getScalesVector () { return scale_values_; }
00104 
00105       /** \brief Setter method for the feature estimator
00106        * \param feature_estimator pointer to the feature estimator instance that will be used
00107        * \note the feature estimator instance should already have the input data given beforehand
00108        * and everything set, ready to be given the compute () command
00109        */
00110       inline void
00111       setFeatureEstimator (FeatureEstimatorPtr feature_estimator) { feature_estimator_ = feature_estimator; };
00112 
00113       /** \brief Getter method for the feature estimator */
00114       inline FeatureEstimatorPtr
00115       getFeatureEstimator () { return feature_estimator_; }
00116 
00117       /** \brief Provide a pointer to the feature representation to use to convert features to k-D vectors.
00118        * \param feature_representation the const boost shared pointer to a PointRepresentation
00119        */
00120       inline void
00121       setPointRepresentation (const FeatureRepresentationConstPtr& feature_representation) { feature_representation_ = feature_representation; }
00122 
00123       /** \brief Get a pointer to the feature representation used when converting features into k-D vectors. */
00124       inline FeatureRepresentationConstPtr const
00125       getPointRepresentation () { return feature_representation_; }
00126 
00127       /** \brief Sets the alpha parameter
00128        * \param alpha value to replace the current alpha with
00129        */
00130       inline void
00131       setAlpha (float alpha) { alpha_ = alpha; }
00132 
00133       /** \brief Get the value of the alpha parameter */
00134       inline float
00135       getAlpha () { return alpha_; }
00136 
00137       /** \brief Method for setting the distance metric that will be used for computing the difference between feature vectors
00138        * \param distance_metric the new distance metric chosen from the NormType enum
00139        */
00140       inline void
00141       setDistanceMetric (NormType distance_metric) { distance_metric_ = distance_metric; }
00142 
00143       /** \brief Returns the distance metric that is currently used to calculate the difference between feature vectors */
00144       inline NormType
00145       getDistanceMetric () { return distance_metric_; }
00146 
00147 
00148     private:
00149       /** \brief Checks if all the necessary input was given and the computations can successfully start */
00150       bool
00151       initCompute ();
00152 
00153 
00154       /** \brief Method to compute the features for the point cloud at the given scale */
00155       virtual void
00156       computeFeatureAtScale (float &scale,
00157                              FeatureCloudPtr &features);
00158 
00159 
00160       /** \brief Function that calculates the scalar difference between two features
00161        * \return the difference as a floating point type
00162        */
00163       float
00164       distanceBetweenFeatures (const std::vector<float> &a,
00165                                const std::vector<float> &b);
00166 
00167       /** \brief Method that averages all the features at all scales in order to obtain the global mean feature;
00168        * this value is stored in the mean_feature field
00169        */
00170       void
00171       calculateMeanFeature ();
00172 
00173       /** \brief Selects the so-called 'unique' features from the cloud of features at each level.
00174        * These features are the ones that fall outside the standard deviation * alpha_
00175        */
00176       void
00177       extractUniqueFeatures ();
00178 
00179 
00180       /** \brief The general parameter for determining each scale level */
00181       std::vector<float> scale_values_;
00182 
00183       /** \brief Parameter that determines if a feature is to be considered unique or not */
00184       float alpha_;
00185 
00186       /** \brief Parameter that determines which distance metric is to be usedto calculate the difference between feature vectors */
00187       NormType distance_metric_;
00188 
00189       /** \brief the feature estimator that will be used to determine the feature set at each scale level */
00190       FeatureEstimatorPtr feature_estimator_;
00191 
00192       std::vector<FeatureCloudPtr> features_at_scale_;
00193       std::vector<std::vector<std::vector<float> > > features_at_scale_vectorized_;
00194       std::vector<float> mean_feature_;
00195       FeatureRepresentationConstPtr feature_representation_;
00196 
00197       /** \brief Two structures in which to hold the results of the unique feature extraction process.
00198        * They are superfluous with respect to each other, but improve the time performance of the algorithm
00199        */
00200       std::vector<std::list<size_t> > unique_features_indices_;
00201       std::vector<std::vector<bool> > unique_features_table_;
00202   };
00203 }
00204 
00205 #ifdef PCL_NO_PRECOMPILE
00206 #include <pcl/features/impl/multiscale_feature_persistence.hpp>
00207 #endif
00208 
00209 #endif /* PCL_MULTISCALE_FEATURE_PERSISTENCE_H_ */