Point Cloud Library (PCL)  1.12.1-dev
multiscale_feature_persistence.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2011, Alexandru-Eugen Ichim
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 #pragma once
41 
42 #include <pcl/pcl_base.h>
43 #include <pcl/features/feature.h>
44 #include <pcl/point_representation.h>
45 #include <pcl/common/norms.h>
46 #include <list>
47 
48 namespace pcl
49 {
50  /** \brief Generic class for extracting the persistent features from an input point cloud
51  * It can be given any Feature estimator instance and will compute the features of the input
52  * over a multiscale representation of the cloud and output the unique ones over those scales.
53  *
54  * Please refer to the following publication for more details:
55  * Radu Bogdan Rusu, Zoltan Csaba Marton, Nico Blodow, and Michael Beetz
56  * Persistent Point Feature Histograms for 3D Point Clouds
57  * Proceedings of the 10th International Conference on Intelligent Autonomous Systems (IAS-10)
58  * 2008, Baden-Baden, Germany
59  *
60  * \author Alexandru-Eugen Ichim
61  */
62  template <typename PointSource, typename PointFeature>
63  class MultiscaleFeaturePersistence : public PCLBase<PointSource>
64  {
65  public:
66  using Ptr = shared_ptr<MultiscaleFeaturePersistence<PointSource, PointFeature> >;
67  using ConstPtr = shared_ptr<const MultiscaleFeaturePersistence<PointSource, PointFeature> >;
72 
74 
75  /** \brief Empty constructor */
77 
78  /** \brief Empty destructor */
79  ~MultiscaleFeaturePersistence () override = default;
80 
81  /** \brief Method that calls computeFeatureAtScale () for each scale parameter */
82  void
84 
85  /** \brief Central function that computes the persistent features
86  * \param output_features a cloud containing the persistent features
87  * \param output_indices vector containing the indices of the points in the input cloud
88  * that have persistent features, under a one-to-one correspondence with the output_features cloud
89  */
90  void
91  determinePersistentFeatures (FeatureCloud &output_features,
92  pcl::IndicesPtr &output_indices);
93 
94  /** \brief Method for setting the scale parameters for the algorithm
95  * \param scale_values vector of scales to determine the characteristic of each scaling step
96  */
97  inline void
98  setScalesVector (std::vector<float> &scale_values) { scale_values_ = scale_values; }
99 
100  /** \brief Method for getting the scale parameters vector */
101  inline std::vector<float>
102  getScalesVector () { return scale_values_; }
103 
104  /** \brief Setter method for the feature estimator
105  * \param feature_estimator pointer to the feature estimator instance that will be used
106  * \note the feature estimator instance should already have the input data given beforehand
107  * and everything set, ready to be given the compute () command
108  */
109  inline void
110  setFeatureEstimator (FeatureEstimatorPtr feature_estimator) { feature_estimator_ = feature_estimator; };
111 
112  /** \brief Getter method for the feature estimator */
113  inline FeatureEstimatorPtr
114  getFeatureEstimator () { return feature_estimator_; }
115 
116  /** \brief Provide a pointer to the feature representation to use to convert features to k-D vectors.
117  * \param feature_representation the const boost shared pointer to a PointRepresentation
118  */
119  inline void
120  setPointRepresentation (const FeatureRepresentationConstPtr& feature_representation) { feature_representation_ = feature_representation; }
121 
122  /** \brief Get a pointer to the feature representation used when converting features into k-D vectors. */
123  inline FeatureRepresentationConstPtr const
124  getPointRepresentation () { return feature_representation_; }
125 
126  /** \brief Sets the alpha parameter
127  * \param alpha value to replace the current alpha with
128  */
129  inline void
130  setAlpha (float alpha) { alpha_ = alpha; }
131 
132  /** \brief Get the value of the alpha parameter */
133  inline float
134  getAlpha () { return alpha_; }
135 
136  /** \brief Method for setting the distance metric that will be used for computing the difference between feature vectors
137  * \param distance_metric the new distance metric chosen from the NormType enum
138  */
139  inline void
140  setDistanceMetric (NormType distance_metric) { distance_metric_ = distance_metric; }
141 
142  /** \brief Returns the distance metric that is currently used to calculate the difference between feature vectors */
143  inline NormType
144  getDistanceMetric () { return distance_metric_; }
145 
146 
147  private:
148  /** \brief Checks if all the necessary input was given and the computations can successfully start */
149  bool
150  initCompute ();
151 
152 
153  /** \brief Method to compute the features for the point cloud at the given scale */
154  virtual void
155  computeFeatureAtScale (float &scale,
156  FeatureCloudPtr &features);
157 
158 
159  /** \brief Function that calculates the scalar difference between two features
160  * \return the difference as a floating point type
161  */
162  float
163  distanceBetweenFeatures (const std::vector<float> &a,
164  const std::vector<float> &b);
165 
166  /** \brief Method that averages all the features at all scales in order to obtain the global mean feature;
167  * this value is stored in the mean_feature field
168  */
169  void
170  calculateMeanFeature ();
171 
172  /** \brief Selects the so-called 'unique' features from the cloud of features at each level.
173  * These features are the ones that fall outside the standard deviation * alpha_
174  */
175  void
176  extractUniqueFeatures ();
177 
178 
179  /** \brief The general parameter for determining each scale level */
180  std::vector<float> scale_values_;
181 
182  /** \brief Parameter that determines if a feature is to be considered unique or not */
183  float alpha_;
184 
185  /** \brief Parameter that determines which distance metric is to be usedto calculate the difference between feature vectors */
186  NormType distance_metric_;
187 
188  /** \brief the feature estimator that will be used to determine the feature set at each scale level */
189  FeatureEstimatorPtr feature_estimator_;
190 
191  std::vector<FeatureCloudPtr> features_at_scale_;
192  std::vector<std::vector<std::vector<float> > > features_at_scale_vectorized_;
193  std::vector<float> mean_feature_;
194  FeatureRepresentationConstPtr feature_representation_;
195 
196  /** \brief Two structures in which to hold the results of the unique feature extraction process.
197  * They are superfluous with respect to each other, but improve the time performance of the algorithm
198  */
199  std::vector<std::list<std::size_t> > unique_features_indices_;
200  std::vector<std::vector<bool> > unique_features_table_;
201  };
202 }
203 
204 #ifdef PCL_NO_PRECOMPILE
205 #include <pcl/features/impl/multiscale_feature_persistence.hpp>
206 #endif
shared_ptr< Feature< PointInT, PointOutT > > Ptr
Definition: feature.h:114
Generic class for extracting the persistent features from an input point cloud It can be given any Fe...
std::vector< float > getScalesVector()
Method for getting the scale parameters vector.
void setFeatureEstimator(FeatureEstimatorPtr feature_estimator)
Setter method for the feature estimator.
shared_ptr< const MultiscaleFeaturePersistence< PointSource, PointFeature > > ConstPtr
void determinePersistentFeatures(FeatureCloud &output_features, pcl::IndicesPtr &output_indices)
Central function that computes the persistent features.
typename pcl::Feature< PointSource, PointFeature >::Ptr FeatureEstimatorPtr
FeatureEstimatorPtr getFeatureEstimator()
Getter method for the feature estimator.
void setAlpha(float alpha)
Sets the alpha parameter.
void setDistanceMetric(NormType distance_metric)
Method for setting the distance metric that will be used for computing the difference between feature...
void setScalesVector(std::vector< float > &scale_values)
Method for setting the scale parameters for the algorithm.
void computeFeaturesAtAllScales()
Method that calls computeFeatureAtScale () for each scale parameter.
NormType getDistanceMetric()
Returns the distance metric that is currently used to calculate the difference between feature vector...
typename pcl::PointRepresentation< PointFeature >::ConstPtr FeatureRepresentationConstPtr
float getAlpha()
Get the value of the alpha parameter.
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors.
~MultiscaleFeaturePersistence() override=default
Empty destructor.
typename pcl::PointCloud< PointFeature >::Ptr FeatureCloudPtr
shared_ptr< MultiscaleFeaturePersistence< PointSource, PointFeature > > Ptr
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:70
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
shared_ptr< const PointRepresentation< PointT > > ConstPtr
NormType
Enum that defines all the types of norms available.
Definition: norms.h:54
shared_ptr< Indices > IndicesPtr
Definition: pcl_base.h:58
Define standard C methods to calculate different norms.