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