Point Cloud Library (PCL)  1.14.1-dev
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 #pragma once
42 
43 #include <pcl/pcl_base.h>
44 #include <pcl/point_representation.h>
45 
46 namespace pcl {
47 /**
48  * \brief Class that compares two sets of features by using a multiscale representation
49  * of the features inside a pyramid. Each level of the pyramid offers information about
50  * the similarity of the two feature sets. \note Works with any Point/Feature type which
51  * has a PointRepresentation implementation \note The only parameters it needs are the
52  * input dimension ranges and the output dimension ranges. The input dimension ranges
53  * represent the ranges in which each dimension of the feature vector lies. As described
54  * in the paper, a minimum inter-vector distance of sqrt(nr_dims)/2 is needed. As such,
55  * the target dimension range parameter is used in order to augment/reduce the range for
56  * each dimension in order to obtain the necessary minimal inter-vector distance and to
57  * 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
62  * Features 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 public:
71 
72  using Ptr = shared_ptr<PyramidFeatureHistogram<PointFeature>>;
73  using ConstPtr = shared_ptr<const PyramidFeatureHistogram<PointFeature>>;
76  shared_ptr<const pcl::PointRepresentation<PointFeature>>;
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
83  * this parameter.
84  */
85  inline void
86  setInputDimensionRange(std::vector<std::pair<float, float>>& dimension_range_input)
87  {
88  dimension_range_input_ = dimension_range_input;
89  }
90 
91  /** \brief Method for retrieving the input dimension range vector */
92  inline std::vector<std::pair<float, float>>
94  {
95  return dimension_range_input_;
96  }
97 
98  /** \brief Method to set the target dimension range parameter.
99  * \note Please check the PyramidHistogram class description for more details about
100  * this parameter.
101  */
102  inline void
103  setTargetDimensionRange(std::vector<std::pair<float, float>>& dimension_range_target)
104  {
105  dimension_range_target_ = dimension_range_target;
106  }
107 
108  /** \brief Method for retrieving the target dimension range vector */
109  inline std::vector<std::pair<float, float>>
111  {
112  return dimension_range_target_;
113  }
114 
115  /** \brief Provide a pointer to the feature representation to use to convert features
116  * to k-D vectors. \param feature_representation the const boost shared pointer to a
117  * PointRepresentation
118  */
119  inline void
121  {
122  feature_representation_ = feature_representation;
123  }
124 
125  /** \brief Get a pointer to the feature representation used when converting features
126  * into k-D vectors. */
127  inline FeatureRepresentationConstPtr const
129  {
130  return feature_representation_;
131  }
132 
133  /** \brief The central method for inserting the feature set inside the pyramid and
134  * obtaining the complete pyramid */
135  void
136  compute();
137 
138  /** \brief Checks whether the pyramid histogram has been computed */
139  inline bool
141  {
142  return is_computed_;
143  }
144 
145  /** \brief Static method for comparing two pyramid histograms that returns a floating
146  * point value between 0 and 1, representing the similarity between the feature sets
147  * on which the two pyramid histograms are based. \param pyramid_a Pointer to the
148  * first pyramid to be compared (needs to be computed already). \param pyramid_b
149  * Pointer to the second pyramid to be compared (needs to be computed already).
150  */
151  static float
153  const PyramidFeatureHistogramPtr& pyramid_b);
154 
155 private:
156  std::size_t nr_dimensions{0}, nr_levels{0}, nr_features{0};
157  std::vector<std::pair<float, float>> dimension_range_input_, dimension_range_target_;
158  FeatureRepresentationConstPtr feature_representation_;
159  bool is_computed_{false};
160 
161  /** \brief Checks for input inconsistencies and initializes the underlying data
162  * structures */
163  bool
164  initializeHistogram();
165 
166  /** \brief Converts a feature in templated form to an STL vector. This is the point
167  * where the conversion from the input dimension range to the target dimension range
168  * is done.
169  */
170  void
171  convertFeatureToVector(const PointFeature& feature,
172  std::vector<float>& feature_vector);
173 
174  /** \brief Adds a feature vector to its corresponding bin at each level in the pyramid
175  */
176  void
177  addFeature(std::vector<float>& feature);
178 
179  /** \brief Access the pyramid bin given the position of the bin at the given pyramid
180  * level and the pyramid level \param access index of the bin at the respective level
181  * \param level the level in the pyramid
182  */
183  inline unsigned int&
184  at(std::vector<std::size_t>& access, std::size_t& level);
185 
186  /** \brief Access the pyramid bin given a feature vector and the pyramid level
187  * \param feature the feature in vectorized form
188  * \param level the level in the pyramid
189  */
190  inline unsigned int&
191  at(std::vector<float>& feature, std::size_t& level);
192 
193  /** \brief Structure for representing a single pyramid histogram level */
194  struct PyramidFeatureHistogramLevel {
195  PyramidFeatureHistogramLevel() = default;
196 
197  PyramidFeatureHistogramLevel(std::vector<std::size_t>& a_bins_per_dimension,
198  std::vector<float>& a_bin_step)
199  : bins_per_dimension(a_bins_per_dimension), bin_step(a_bin_step)
200  {
201  initializeHistogramLevel();
202  }
203 
204  void
205  initializeHistogramLevel();
206 
207  std::vector<unsigned int> hist;
208  std::vector<std::size_t> bins_per_dimension;
209  std::vector<float> bin_step;
210  };
211  std::vector<PyramidFeatureHistogramLevel> hist_levels;
212 };
213 } // namespace pcl
214 
215 #ifdef PCL_NO_PRECOMPILE
216 #include <pcl/registration/impl/pyramid_feature_matching.hpp>
217 #endif
PCL base class.
Definition: pcl_base.h:70
Class that compares two sets of features by using a multiscale representation of the features inside ...
void setTargetDimensionRange(std::vector< std::pair< float, float >> &dimension_range_target)
Method to set the target dimension range parameter.
void setInputDimensionRange(std::vector< std::pair< float, float >> &dimension_range_input)
Method for setting the input dimension range parameter.
shared_ptr< const pcl::PointRepresentation< PointFeature > > FeatureRepresentationConstPtr
FeatureRepresentationConstPtr const getPointRepresentation()
Get a pointer to the feature representation used when converting features into k-D vectors.
void compute()
The central method for inserting the feature set inside the pyramid and obtaining the complete pyrami...
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 ...
bool isComputed()
Checks whether the pyramid histogram has been computed.
PyramidFeatureHistogram()
Empty constructor that instantiates the feature representation variable.
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors.
shared_ptr< const PyramidFeatureHistogram< PointFeature > > ConstPtr
shared_ptr< PyramidFeatureHistogram< PointFeature > > Ptr
std::vector< std::pair< float, float > > getTargetDimensionRange()
Method for retrieving the target dimension range vector.
std::vector< std::pair< float, float > > getInputDimensionRange()
Method for retrieving the input dimension range vector.