Point Cloud Library (PCL)  1.11.0
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  /**
49  * \brief Class that compares two sets of features by using a multiscale representation of the features inside a
50  * pyramid. Each level of the pyramid offers information about the similarity of the two feature sets.
51  * \note Works with any Point/Feature type which has a PointRepresentation implementation
52  * \note The only parameters it needs are the input dimension ranges and the output dimension ranges. The input
53  * dimension ranges represent the ranges in which each dimension of the feature vector lies. As described in the
54  * paper, a minimum inter-vector distance of sqrt(nr_dims)/2 is needed. As such, the target dimension range parameter
55  * is used in order to augment/reduce the range for each dimension in order to obtain the necessary minimal
56  * inter-vector distance and to add/subtract weight to/from certain dimensions of the feature vector.
57  *
58  * Follows the algorithm presented in the publication:
59  * Grauman, K. & Darrell, T.
60  * The Pyramid Match Kernel: Discriminative Classification with Sets of Image Features
61  * Tenth IEEE International Conference on Computer Vision ICCV05 Volume 1
62  * October 2005
63  *
64  * \author Alexandru-Eugen Ichim
65  */
66  template <typename PointFeature>
67  class PyramidFeatureHistogram : public PCLBase<PointFeature>
68  {
69  public:
71 
72  using Ptr = shared_ptr<PyramidFeatureHistogram<PointFeature> >;
73  using ConstPtr = shared_ptr<const PyramidFeatureHistogram<PointFeature>>;
75  using FeatureRepresentationConstPtr = shared_ptr<const pcl::PointRepresentation<PointFeature> >;
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
128  const PyramidFeatureHistogramPtr &pyramid_b);
129 
130 
131  private:
132  std::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<std::size_t> &access,
159  std::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  std::size_t &level);
168 
169  /** \brief Structure for representing a single pyramid histogram level */
170  struct PyramidFeatureHistogramLevel
171  {
172  PyramidFeatureHistogramLevel ()
173  {
174  }
175 
176  PyramidFeatureHistogramLevel (std::vector<std::size_t> &a_bins_per_dimension, std::vector<float> &a_bin_step) :
177  bins_per_dimension (a_bins_per_dimension),
178  bin_step (a_bin_step)
179  {
180  initializeHistogramLevel ();
181  }
182 
183  void
184  initializeHistogramLevel ();
185 
186  std::vector<unsigned int> hist;
187  std::vector<std::size_t> bins_per_dimension;
188  std::vector<float> bin_step;
189  };
190  std::vector<PyramidFeatureHistogramLevel> hist_levels;
191  };
192 }
193 
194 #ifdef PCL_NO_PRECOMPILE
195 #include <pcl/registration/impl/pyramid_feature_matching.hpp>
196 #endif
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
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: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...
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.