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> >; 68 using FeatureCloud = pcl::PointCloud<PointFeature>; 69 using FeatureCloudPtr = typename pcl::PointCloud<PointFeature>::Ptr; 70 using FeatureEstimatorPtr = typename pcl::Feature<PointSource, PointFeature>::Ptr; 71 using FeatureRepresentationConstPtr = typename pcl::PointRepresentation<PointFeature>::ConstPtr; 72 73 using pcl::PCLBase<PointSource>::input_; 74 75 /** \brief Empty constructor */ 76 MultiscaleFeaturePersistence (); 77 78 /** \brief Empty destructor */ ~MultiscaleFeaturePersistence()79 ~MultiscaleFeaturePersistence () {} 80 81 /** \brief Method that calls computeFeatureAtScale () for each scale parameter */ 82 void 83 computeFeaturesAtAllScales (); 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 setScalesVector(std::vector<float> & scale_values)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> getScalesVector()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 setFeatureEstimator(FeatureEstimatorPtr feature_estimator)110 setFeatureEstimator (FeatureEstimatorPtr feature_estimator) { feature_estimator_ = feature_estimator; }; 111 112 /** \brief Getter method for the feature estimator */ 113 inline FeatureEstimatorPtr getFeatureEstimator()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 setPointRepresentation(const FeatureRepresentationConstPtr & feature_representation)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 getPointRepresentation()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 setAlpha(float alpha)130 setAlpha (float alpha) { alpha_ = alpha; } 131 132 /** \brief Get the value of the alpha parameter */ 133 inline float getAlpha()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 setDistanceMetric(NormType distance_metric)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 getDistanceMetric()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 207