Point Cloud Library (PCL)  1.14.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 #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
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors...
void setTargetDimensionRange(std::vector< std::pair< float, float >> &dimension_range_target)
Method to set the target dimension range parameter.
shared_ptr< const PyramidFeatureHistogram< PointFeature >> ConstPtr
shared_ptr< const pcl::PointRepresentation< PointFeature >> FeatureRepresentationConstPtr
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.
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:69
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...
void setInputDimensionRange(std::vector< std::pair< float, float >> &dimension_range_input)
Method for setting the input dimension range parameter.
std::vector< std::pair< float, float > > getTargetDimensionRange()
Method for retrieving the target dimension range vector.
shared_ptr< PyramidFeatureHistogram< PointFeature >> Ptr