Point Cloud Library (PCL)  1.9.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 similarity 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
127  comparePyramidFeatureHistograms (const PyramidFeatureHistogramPtr &pyramid_a,
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_
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors...
boost::shared_ptr< PyramidFeatureHistogram< PointFeature > > Ptr
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
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 ...
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 > > getInputDimensionRange()
Method for retrieving the input dimension range vector.
FeatureRepresentationConstPtr const getPointRepresentation()
Get a pointer to the feature representation used when converting features into k-D vectors...
PCL base class.
Definition: pcl_base.h:68
Class that compares two sets of features by using a multiscale representation of the features inside ...
PyramidFeatureHistogram()
Empty constructor that instantiates the feature representation variable.
bool isComputed()
Checks whether the pyramid histogram has been computed.
void compute()
The central method for inserting the feature set inside the pyramid and obtaining the complete pyrami...
boost::shared_ptr< const pcl::PointRepresentation< PointFeature > > FeatureRepresentationConstPtr
std::vector< std::pair< float, float > > getTargetDimensionRange()
Method for retrieving the target dimension range vector.
void setInputDimensionRange(std::vector< std::pair< float, float > > &dimension_range_input)
Method for setting the input dimension range parameter.