Point Cloud Library (PCL) 1.12.0
Loading...
Searching...
No Matches
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
46namespace 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 */
67template <typename PointFeature>
68class PyramidFeatureHistogram : public PCLBase<PointFeature> {
69public:
70 using PCLBase<PointFeature>::input_;
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. */
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
155private:
156 std::size_t nr_dimensions, nr_levels, nr_features;
157 std::vector<std::pair<float, float>> dimension_range_input_, dimension_range_target_;
158 FeatureRepresentationConstPtr feature_representation_;
159 bool is_computed_;
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() {}
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
PointCloudConstPtr input_
The input point cloud dataset.
Definition pcl_base.h:147
Class that compares two sets of features by using a multiscale representation of the features inside ...
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.
void compute()
The central method for inserting the feature set inside the pyramid and obtaining the complete pyrami...
void setTargetDimensionRange(std::vector< std::pair< float, float > > &dimension_range_target)
Method to set the target dimension range parameter.
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 > > getTargetDimensionRange()
Method for retrieving the target dimension range vector.
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
shared_ptr< const pcl::PointRepresentation< PointFeature > > FeatureRepresentationConstPtr
std::vector< std::pair< float, float > > getInputDimensionRange()
Method for retrieving the input dimension range vector.