Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/registration/include/pcl/registration/pyramid_feature_matching.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Copyright (c) 2011, Alexandru-Eugen Ichim
00005  *                      Willow Garage, Inc
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 
00041 #ifndef PCL_PYRAMID_FEATURE_MATCHING_H_
00042 #define PCL_PYRAMID_FEATURE_MATCHING_H_
00043 
00044 #include <pcl/pcl_base.h>
00045 #include <pcl/point_representation.h>
00046 
00047 namespace pcl
00048 {
00049   /**
00050    * \brief Class that compares two sets of features by using a multiscale representation of the features inside a
00051    * pyramid. Each level of the pyramid offers information about the similarity of the two feature sets.
00052    * \note Works with any Point/Feature type which has a PointRepresentation implementation
00053    * \note The only parameters it needs are the input dimension ranges and the output dimension ranges. The input
00054    * dimension ranges represent the ranges in which each dimension of the feature vector lies. As described in the
00055    * paper, a minimum inter-vector distance of sqrt(nr_dims)/2 is needed. As such, the target dimension range parameter
00056    * is used in order to augment/reduce the range for each dimension in order to obtain the necessary minimal
00057    * inter-vector distance and to add/subtract weight to/from certain dimensions of the feature vector.
00058    *
00059    * Follows the algorithm presented in the publication:
00060    *    Grauman, K. & Darrell, T.
00061    *    The Pyramid Match Kernel: Discriminative Classification with Sets of Image Features
00062    *    Tenth IEEE International Conference on Computer Vision ICCV05 Volume 1
00063    *    October 2005
00064    *
00065    * \author Alexandru-Eugen Ichim
00066    */
00067   template <typename PointFeature>
00068   class PyramidFeatureHistogram : public PCLBase<PointFeature>
00069   {
00070     public:
00071       using PCLBase<PointFeature>::input_;
00072 
00073       typedef boost::shared_ptr<PyramidFeatureHistogram<PointFeature> > Ptr;
00074       typedef Ptr PyramidFeatureHistogramPtr;
00075       typedef boost::shared_ptr<const pcl::PointRepresentation<PointFeature> > FeatureRepresentationConstPtr;
00076 
00077 
00078       /** \brief Empty constructor that instantiates the feature representation variable */
00079       PyramidFeatureHistogram ();
00080 
00081       /** \brief Method for setting the input dimension range parameter.
00082        * \note Please check the PyramidHistogram class description for more details about this parameter.
00083        */
00084       inline void
00085       setInputDimensionRange (std::vector<std::pair<float, float> > &dimension_range_input)
00086       { dimension_range_input_ = dimension_range_input; }
00087 
00088       /** \brief Method for retrieving the input dimension range vector */
00089       inline std::vector<std::pair<float, float> >
00090       getInputDimensionRange () { return dimension_range_input_; }
00091 
00092       /** \brief Method to set the target dimension range parameter.
00093        * \note Please check the PyramidHistogram class description for more details about this parameter.
00094        */
00095       inline void
00096       setTargetDimensionRange (std::vector<std::pair<float, float> > &dimension_range_target)
00097       { dimension_range_target_ = dimension_range_target; }
00098 
00099       /** \brief Method for retrieving the target dimension range vector */
00100       inline std::vector<std::pair<float, float> >
00101       getTargetDimensionRange () { return dimension_range_target_; }
00102 
00103       /** \brief Provide a pointer to the feature representation to use to convert features to k-D vectors.
00104        * \param feature_representation the const boost shared pointer to a PointRepresentation
00105        */
00106       inline void
00107       setPointRepresentation (const FeatureRepresentationConstPtr& feature_representation) { feature_representation_ = feature_representation; }
00108 
00109       /** \brief Get a pointer to the feature representation used when converting features into k-D vectors. */
00110       inline FeatureRepresentationConstPtr const
00111       getPointRepresentation () { return feature_representation_; }
00112 
00113       /** \brief The central method for inserting the feature set inside the pyramid and obtaining the complete pyramid */
00114       void
00115       compute ();
00116 
00117       /** \brief Checks whether the pyramid histogram has been computed */
00118       inline bool
00119       isComputed () { return is_computed_; }
00120 
00121       /** \brief Static method for comparing two pyramid histograms that returns a floating point value between 0 and 1,
00122        * representing the similiarity between the feature sets on which the two pyramid histograms are based.
00123        * \param pyramid_a Pointer to the first pyramid to be compared (needs to be computed already).
00124        * \param pyramid_b Pointer to the second pyramid to be compared (needs to be computed already).
00125        */
00126       static float
00127       comparePyramidFeatureHistograms (const PyramidFeatureHistogramPtr &pyramid_a,
00128                                        const PyramidFeatureHistogramPtr &pyramid_b);
00129 
00130 
00131     private:
00132       size_t nr_dimensions, nr_levels, nr_features;
00133       std::vector<std::pair<float, float> > dimension_range_input_, dimension_range_target_;
00134       FeatureRepresentationConstPtr feature_representation_;
00135       bool is_computed_;
00136 
00137       /** \brief Checks for input inconsistencies and initializes the underlying data structures */
00138       bool
00139       initializeHistogram ();
00140 
00141       /** \brief Converts a feature in templated form to an STL vector. This is the point where the conversion from the
00142        * input dimension range to the target dimension range is done.
00143        */
00144       void
00145       convertFeatureToVector (const PointFeature &feature,
00146                               std::vector<float> &feature_vector);
00147 
00148       /** \brief Adds a feature vector to its corresponding bin at each level in the pyramid */
00149       void
00150       addFeature (std::vector<float> &feature);
00151 
00152       /** \brief Access the pyramid bin given the position of the bin at the given pyramid level
00153        * and the pyramid level
00154        * \param access index of the bin at the respective level
00155        * \param level the level in the pyramid
00156        */
00157       inline unsigned int&
00158       at (std::vector<size_t> &access,
00159           size_t &level);
00160 
00161       /** \brief Access the pyramid bin given a feature vector and the pyramid level
00162        * \param feature the feature in vectorized form
00163        * \param level the level in the pyramid
00164        */
00165       inline unsigned int&
00166       at (std::vector<float> &feature,
00167           size_t &level);
00168 
00169       /** \brief Structure for representing a single pyramid histogram level */
00170       struct PyramidFeatureHistogramLevel
00171       {
00172         PyramidFeatureHistogramLevel () :
00173           hist (), 
00174           bins_per_dimension (),
00175           bin_step ()
00176         {
00177         }
00178 
00179         PyramidFeatureHistogramLevel (std::vector<size_t> &a_bins_per_dimension, std::vector<float> &a_bin_step) : 
00180           hist (), 
00181           bins_per_dimension (a_bins_per_dimension),
00182           bin_step (a_bin_step)
00183         {
00184           initializeHistogramLevel ();
00185         }
00186 
00187         void
00188         initializeHistogramLevel ();
00189 
00190         std::vector<unsigned int> hist;
00191         std::vector<size_t> bins_per_dimension;
00192         std::vector<float> bin_step;
00193       };
00194       std::vector<PyramidFeatureHistogramLevel> hist_levels;
00195   };
00196 }
00197 
00198 #ifdef PCL_NO_PRECOMPILE
00199 #include <pcl/registration/impl/pyramid_feature_matching.hpp>
00200 #endif
00201 
00202 #endif    // PCL_PYRAMID_FEATURE_MATCHING_H_