Point Cloud Library (PCL)  1.10.0-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:
72 
74 
75  /** \brief Empty constructor */
77 
78  /** \brief Empty destructor */
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  shared_ptr<std::vector<int> > &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
FeatureRepresentationConstPtr const getPointRepresentation()
Get a pointer to the feature representation used when converting features into k-D vectors...
void determinePersistentFeatures(FeatureCloud &output_features, shared_ptr< std::vector< int > > &output_indices)
Central function that computes the persistent features.
void setScalesVector(std::vector< float > &scale_values)
Method for setting the scale parameters for the algorithm.
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:415
FeatureEstimatorPtr getFeatureEstimator()
Getter method for the feature estimator.
shared_ptr< MultiscaleFeaturePersistence< PointSource, PointFeature > > Ptr
std::vector< float > getScalesVector()
Method for getting the scale parameters vector.
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
void setPointRepresentation(const FeatureRepresentationConstPtr &feature_representation)
Provide a pointer to the feature representation to use to convert features to k-D vectors...
NormType
Enum that defines all the types of norms available.
Definition: norms.h:54
void setDistanceMetric(NormType distance_metric)
Method for setting the distance metric that will be used for computing the difference between feature...
void computeFeaturesAtAllScales()
Method that calls computeFeatureAtScale () for each scale parameter.
void setFeatureEstimator(FeatureEstimatorPtr feature_estimator)
Setter method for the feature estimator.
shared_ptr< const PointRepresentation< PointT > > ConstPtr
typename pcl::Feature< PointSource, PointFeature >::Ptr FeatureEstimatorPtr
PCL base class.
Definition: pcl_base.h:69
Define standard C methods to calculate different norms.
PointCloud represents the base class in PCL for storing collections of 3D points. ...
shared_ptr< const MultiscaleFeaturePersistence< PointSource, PointFeature > > ConstPtr
Generic class for extracting the persistent features from an input point cloud It can be given any Fe...
typename pcl::PointCloud< PointFeature >::Ptr FeatureCloudPtr
float getAlpha()
Get the value of the alpha parameter.
NormType getDistanceMetric()
Returns the distance metric that is currently used to calculate the difference between feature vector...
boost::shared_ptr< T > shared_ptr
Alias for boost::shared_ptr.
Definition: pcl_macros.h:90
void setAlpha(float alpha)
Sets the alpha parameter.
typename pcl::PointRepresentation< PointFeature >::ConstPtr FeatureRepresentationConstPtr
shared_ptr< Feature< PointInT, PointOutT > > Ptr
Definition: feature.h:113