Point Cloud Library (PCL)  1.7.1
pyramid_feature_matching.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Copyright (c) 2011, Alexandru-Eugen Ichim
5  * Willow Garage, Inc
6  * Copyright (c) 2012-, Open Perception, Inc.
7  *
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  *
14  * * Redistributions of source code must retain the above copyright
15  * notice, this list of conditions and the following disclaimer.
16  * * Redistributions in binary form must reproduce the above
17  * copyright notice, this list of conditions and the following
18  * disclaimer in the documentation and/or other materials provided
19  * with the distribution.
20  * * Neither the name of the copyright holder(s) nor the names of its
21  * contributors may be used to endorse or promote products derived
22  * from this software without specific prior written permission.
23  *
24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
30  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35  * POSSIBILITY OF SUCH DAMAGE.
36  *
37  * $Id$
38  *
39  */
40 
41 #ifndef PCL_PYRAMID_FEATURE_MATCHING_H_
42 #define PCL_PYRAMID_FEATURE_MATCHING_H_
43 
44 #include <pcl/pcl_base.h>
45 #include <pcl/point_representation.h>
46 
47 namespace pcl
48 {
49  /**
50  * \brief Class that compares two sets of features by using a multiscale representation of the features inside a
51  * pyramid. Each level of the pyramid offers information about the similarity of the two feature sets.
52  * \note Works with any Point/Feature type which has a PointRepresentation implementation
53  * \note The only parameters it needs are the input dimension ranges and the output dimension ranges. The input
54  * dimension ranges represent the ranges in which each dimension of the feature vector lies. As described in the
55  * paper, a minimum inter-vector distance of sqrt(nr_dims)/2 is needed. As such, the target dimension range parameter
56  * is used in order to augment/reduce the range for each dimension in order to obtain the necessary minimal
57  * inter-vector distance and to add/subtract weight to/from certain dimensions of the feature vector.
58  *
59  * Follows the algorithm presented in the publication:
60  * Grauman, K. & Darrell, T.
61  * The Pyramid Match Kernel: Discriminative Classification with Sets of Image Features
62  * Tenth IEEE International Conference on Computer Vision ICCV05 Volume 1
63  * October 2005
64  *
65  * \author Alexandru-Eugen Ichim
66  */
67  template <typename PointFeature>
68  class PyramidFeatureHistogram : public PCLBase<PointFeature>
69  {
70  public:
72 
73  typedef boost::shared_ptr<PyramidFeatureHistogram<PointFeature> > Ptr;
75  typedef boost::shared_ptr<const pcl::PointRepresentation<PointFeature> > FeatureRepresentationConstPtr;
76 
77 
78  /** \brief Empty constructor that instantiates the feature representation variable */
80 
81  /** \brief Method for setting the input dimension range parameter.
82  * \note Please check the PyramidHistogram class description for more details about this parameter.
83  */
84  inline void
85  setInputDimensionRange (std::vector<std::pair<float, float> > &dimension_range_input)
86  { dimension_range_input_ = dimension_range_input; }
87 
88  /** \brief Method for retrieving the input dimension range vector */
89  inline std::vector<std::pair<float, float> >
90  getInputDimensionRange () { return dimension_range_input_; }
91 
92  /** \brief Method to set the target dimension range parameter.
93  * \note Please check the PyramidHistogram class description for more details about this parameter.
94  */
95  inline void
96  setTargetDimensionRange (std::vector<std::pair<float, float> > &dimension_range_target)
97  { dimension_range_target_ = dimension_range_target; }
98 
99  /** \brief Method for retrieving the target dimension range vector */
100  inline std::vector<std::pair<float, float> >
101  getTargetDimensionRange () { return dimension_range_target_; }
102 
103  /** \brief Provide a pointer to the feature representation to use to convert features to k-D vectors.
104  * \param feature_representation the const boost shared pointer to a PointRepresentation
105  */
106  inline void
107  setPointRepresentation (const FeatureRepresentationConstPtr& feature_representation) { feature_representation_ = feature_representation; }
108 
109  /** \brief Get a pointer to the feature representation used when converting features into k-D vectors. */
110  inline FeatureRepresentationConstPtr const
111  getPointRepresentation () { return feature_representation_; }
112 
113  /** \brief The central method for inserting the feature set inside the pyramid and obtaining the complete pyramid */
114  void
115  compute ();
116 
117  /** \brief Checks whether the pyramid histogram has been computed */
118  inline bool
119  isComputed () { return is_computed_; }
120 
121  /** \brief Static method for comparing two pyramid histograms that returns a floating point value between 0 and 1,
122  * representing the similiarity between the feature sets on which the two pyramid histograms are based.
123  * \param pyramid_a Pointer to the first pyramid to be compared (needs to be computed already).
124  * \param pyramid_b Pointer to the second pyramid to be compared (needs to be computed already).
125  */
126  static float
128  const PyramidFeatureHistogramPtr &pyramid_b);
129 
130 
131  private:
132  size_t nr_dimensions, nr_levels, nr_features;
133  std::vector<std::pair<float, float> > dimension_range_input_, dimension_range_target_;
134  FeatureRepresentationConstPtr feature_representation_;
135  bool is_computed_;
136 
137  /** \brief Checks for input inconsistencies and initializes the underlying data structures */
138  bool
139  initializeHistogram ();
140 
141  /** \brief Converts a feature in templated form to an STL vector. This is the point where the conversion from the
142  * input dimension range to the target dimension range is done.
143  */
144  void
145  convertFeatureToVector (const PointFeature &feature,
146  std::vector<float> &feature_vector);
147 
148  /** \brief Adds a feature vector to its corresponding bin at each level in the pyramid */
149  void
150  addFeature (std::vector<float> &feature);
151 
152  /** \brief Access the pyramid bin given the position of the bin at the given pyramid level
153  * and the pyramid level
154  * \param access index of the bin at the respective level
155  * \param level the level in the pyramid
156  */
157  inline unsigned int&
158  at (std::vector<size_t> &access,
159  size_t &level);
160 
161  /** \brief Access the pyramid bin given a feature vector and the pyramid level
162  * \param feature the feature in vectorized form
163  * \param level the level in the pyramid
164  */
165  inline unsigned int&
166  at (std::vector<float> &feature,
167  size_t &level);
168 
169  /** \brief Structure for representing a single pyramid histogram level */
170  struct PyramidFeatureHistogramLevel
171  {
172  PyramidFeatureHistogramLevel () :
173  hist (),
174  bins_per_dimension (),
175  bin_step ()
176  {
177  }
178 
179  PyramidFeatureHistogramLevel (std::vector<size_t> &a_bins_per_dimension, std::vector<float> &a_bin_step) :
180  hist (),
181  bins_per_dimension (a_bins_per_dimension),
182  bin_step (a_bin_step)
183  {
184  initializeHistogramLevel ();
185  }
186 
187  void
188  initializeHistogramLevel ();
189 
190  std::vector<unsigned int> hist;
191  std::vector<size_t> bins_per_dimension;
192  std::vector<float> bin_step;
193  };
194  std::vector<PyramidFeatureHistogramLevel> hist_levels;
195  };
196 }
197 
198 #ifdef PCL_NO_PRECOMPILE
199 #include <pcl/registration/impl/pyramid_feature_matching.hpp>
200 #endif
201 
202 #endif // PCL_PYRAMID_FEATURE_MATCHING_H_
Class that compares two sets of features by using a multiscale representation of the features inside ...
void compute()
The central method for inserting the feature set inside the pyramid and obtaining the complete pyrami...
boost::shared_ptr< PyramidFeatureHistogram< PointFeature > > Ptr
PCL base class.
Definition: pcl_base.h:68
void setTargetDimensionRange(std::vector< std::pair< float, float > > &dimension_range_target)
Method to set the target dimension range parameter.
std::vector< std::pair< float, float > > getTargetDimensionRange()
Method for retrieving the target dimension range vector.
PyramidFeatureHistogram()
Empty constructor that instantiates the feature representation variable.
bool isComputed()
Checks whether the pyramid histogram has been computed.
boost::shared_ptr< const pcl::PointRepresentation< PointFeature > > FeatureRepresentationConstPtr
void setInputDimensionRange(std::vector< std::pair< float, float > > &dimension_range_input)
Method for setting the input dimension range parameter.
FeatureRepresentationConstPtr const getPointRepresentation()
Get a pointer to the feature representation used when converting features into k-D vectors...
static float comparePyramidFeatureHistograms(const PyramidFeatureHistogramPtr &pyramid_a, const PyramidFeatureHistogramPtr &pyramid_b)
Static method for comparing two pyramid histograms that returns a floating point value between 0 and ...
std::vector< std::pair< float, float > > getInputDimensionRange()
Method for retrieving the input dimension range vector.
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors...