Point Cloud Library (PCL)  1.7.1
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_ */
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors...
boost::shared_ptr< Feature< PointInT, PointOutT > > Ptr
Definition: feature.h:113
PointCloud represents the base class in PCL for storing collections of 3D points. ...
pcl::PointCloud< PointFeature >::Ptr FeatureCloudPtr
std::vector< float > getScalesVector()
Method for getting the scale parameters vector.
boost::shared_ptr< MultiscaleFeaturePersistence< PointSource, PointFeature > > Ptr
void determinePersistentFeatures(FeatureCloud &output_features, boost::shared_ptr< std::vector< int > > &output_indices)
Central function that computes the persistent features.
NormType getDistanceMetric()
Returns the distance metric that is currently used to calculate the difference between feature vector...
FeatureEstimatorPtr getFeatureEstimator()
Getter method for the feature estimator.
void setAlpha(float alpha)
Sets the alpha parameter.
Generic class for extracting the persistent features from an input point cloud It can be given any Fe...
void setDistanceMetric(NormType distance_metric)
Method for setting the distance metric that will be used for computing the difference between feature...
NormType
Enum that defines all the types of norms available.
Definition: norms.h:55
float getAlpha()
Get the value of the alpha parameter.
PCL base class.
Definition: pcl_base.h:68
boost::shared_ptr< const pcl::PointRepresentation< PointFeature > > FeatureRepresentationConstPtr
void setScalesVector(std::vector< float > &scale_values)
Method for setting the scale parameters for the algorithm.
pcl::Feature< PointSource, PointFeature >::Ptr FeatureEstimatorPtr
boost::shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:428
boost::shared_ptr< const MultiscaleFeaturePersistence< PointSource, PointFeature > > ConstPtr
void setFeatureEstimator(FeatureEstimatorPtr feature_estimator)
Setter method for the feature estimator.
FeatureRepresentationConstPtr const getPointRepresentation()
Get a pointer to the feature representation used when converting features into k-D vectors...
virtual ~MultiscaleFeaturePersistence()
Empty destructor.
pcl::PointCloud< PointFeature > FeatureCloud
void computeFeaturesAtAllScales()
Method that calls computeFeatureAtScale () for each scale parameter.