Point Cloud Library (PCL)  1.7.0
shot.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2011, Willow Garage, Inc.
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  *
38  */
39 
40 #ifndef PCL_SHOT_H_
41 #define PCL_SHOT_H_
42 
43 #include <pcl/point_types.h>
44 #include <pcl/features/feature.h>
45 
46 namespace pcl
47 {
48  /** \brief SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for
49  * a given point cloud dataset containing points and normals.
50  *
51  * The suggested PointOutT is pcl::SHOT352.
52  *
53  * \note If you use this code in any academic work, please cite:
54  *
55  * - F. Tombari, S. Salti, L. Di Stefano
56  * Unique Signatures of Histograms for Local Surface Description.
57  * In Proceedings of the 11th European Conference on Computer Vision (ECCV),
58  * Heraklion, Greece, September 5-11 2010.
59  * - F. Tombari, S. Salti, L. Di Stefano
60  * A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
61  * In Proceedings of the 18th International Conference on Image Processing (ICIP),
62  * Brussels, Belgium, September 11-14 2011.
63  *
64  * \author Samuele Salti, Federico Tombari
65  * \ingroup features
66  */
67  template <typename PointInT, typename PointNT, typename PointOutT, typename PointRFT = pcl::ReferenceFrame>
68  class SHOTEstimationBase : public FeatureFromNormals<PointInT, PointNT, PointOutT>,
69  public FeatureWithLocalReferenceFrames<PointInT, PointRFT>
70  {
71  public:
72  typedef boost::shared_ptr<SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
73  typedef boost::shared_ptr<const SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
85 
87 
88  protected:
89  /** \brief Empty constructor.
90  * \param[in] nr_shape_bins the number of bins in the shape histogram
91  */
92  SHOTEstimationBase (int nr_shape_bins = 10) :
93  nr_shape_bins_ (nr_shape_bins),
94  shot_ (), lrf_radius_ (0),
95  sqradius_ (0), radius3_4_ (0), radius1_4_ (0), radius1_2_ (0),
96  nr_grid_sector_ (32),
97  maxAngularSectors_ (28),
98  descLength_ (0)
99  {
100  feature_name_ = "SHOTEstimation";
101  };
102 
103 
104  public:
105 
106  /** \brief Empty destructor */
107  virtual ~SHOTEstimationBase () {}
108 
109  /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
110  * \param[in] index the index of the point in indices_
111  * \param[in] indices the k-neighborhood point indices in surface_
112  * \param[in] sqr_dists the k-neighborhood point distances in surface_
113  * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
114  */
115  virtual void
116  computePointSHOT (const int index,
117  const std::vector<int> &indices,
118  const std::vector<float> &sqr_dists,
119  Eigen::VectorXf &shot) = 0;
120 
121  /** \brief Set the radius used for local reference frame estimation if the frames are not set by the user */
122  virtual void
123  setLRFRadius (float radius) { lrf_radius_ = radius; }
124 
125  /** \brief Get the radius used for local reference frame estimation */
126  virtual float
127  getLRFRadius () const { return lrf_radius_; }
128 
129  protected:
130 
131  /** \brief This method should get called before starting the actual computation. */
132  virtual bool
133  initCompute ();
134 
135  /** \brief Quadrilinear interpolation used when color and shape descriptions are NOT activated simultaneously
136  *
137  * \param[in] indices the neighborhood point indices
138  * \param[in] sqr_dists the neighborhood point distances
139  * \param[in] index the index of the point in indices_
140  * \param[out] binDistance the resultant distance shape histogram
141  * \param[in] nr_bins the number of bins in the shape histogram
142  * \param[out] shot the resultant SHOT histogram
143  */
144  void
145  interpolateSingleChannel (const std::vector<int> &indices,
146  const std::vector<float> &sqr_dists,
147  const int index,
148  std::vector<double> &binDistance,
149  const int nr_bins,
150  Eigen::VectorXf &shot);
151 
152  /** \brief Normalize the SHOT histogram.
153  * \param[in,out] shot the SHOT histogram
154  * \param[in] desc_length the length of the histogram
155  */
156  void
157  normalizeHistogram (Eigen::VectorXf &shot, int desc_length);
158 
159 
160  /** \brief Create a binned distance shape histogram
161  * \param[in] index the index of the point in indices_
162  * \param[in] indices the k-neighborhood point indices in surface_
163  * \param[in] sqr_dists the k-neighborhood point distances in surface_
164  * \param[out] bin_distance_shape the resultant histogram
165  */
166  void
167  createBinDistanceShape (int index, const std::vector<int> &indices,
168  std::vector<double> &bin_distance_shape);
169 
170  /** \brief The number of bins in each shape histogram. */
172 
173  /** \brief Placeholder for a point's SHOT. */
174  Eigen::VectorXf shot_;
175 
176  /** \brief The radius used for the LRF computation */
177  float lrf_radius_;
178 
179  /** \brief The squared search radius. */
180  double sqradius_;
181 
182  /** \brief 3/4 of the search radius. */
183  double radius3_4_;
184 
185  /** \brief 1/4 of the search radius. */
186  double radius1_4_;
187 
188  /** \brief 1/2 of the search radius. */
189  double radius1_2_;
190 
191  /** \brief Number of azimuthal sectors. */
192  const int nr_grid_sector_;
193 
194  /** \brief ... */
196 
197  /** \brief One SHOT length. */
199  };
200 
201  /** \brief SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for
202  * a given point cloud dataset containing points and normals.
203  *
204  * The suggested PointOutT is pcl::SHOT352
205  *
206  * \note If you use this code in any academic work, please cite:
207  *
208  * - F. Tombari, S. Salti, L. Di Stefano
209  * Unique Signatures of Histograms for Local Surface Description.
210  * In Proceedings of the 11th European Conference on Computer Vision (ECCV),
211  * Heraklion, Greece, September 5-11 2010.
212  * - F. Tombari, S. Salti, L. Di Stefano
213  * A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
214  * In Proceedings of the 18th International Conference on Image Processing (ICIP),
215  * Brussels, Belgium, September 11-14 2011.
216  *
217  * \author Samuele Salti, Federico Tombari
218  * \ingroup features
219  */
220  template <typename PointInT, typename PointNT, typename PointOutT = pcl::SHOT352, typename PointRFT = pcl::ReferenceFrame>
221  class SHOTEstimation : public SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>
222  {
223  public:
224  typedef boost::shared_ptr<SHOTEstimation<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
225  typedef boost::shared_ptr<const SHOTEstimation<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
246 
248 
249  /** \brief Empty constructor. */
250  SHOTEstimation () : SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> (10)
251  {
252  feature_name_ = "SHOTEstimation";
253  };
254 
255  /** \brief Empty destructor */
256  virtual ~SHOTEstimation () {}
257 
258  /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
259  * \param[in] index the index of the point in indices_
260  * \param[in] indices the k-neighborhood point indices in surface_
261  * \param[in] sqr_dists the k-neighborhood point distances in surface_
262  * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
263  */
264  virtual void
265  computePointSHOT (const int index,
266  const std::vector<int> &indices,
267  const std::vector<float> &sqr_dists,
268  Eigen::VectorXf &shot);
269  protected:
270  /** \brief Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by
271  * <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
272  * setSearchMethod ()
273  * \param output the resultant point cloud model dataset that contains the SHOT feature estimates
274  */
275  void
277  };
278 
279  /** \brief SHOTColorEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for a given point cloud dataset
280  * containing points, normals and colors.
281  *
282  * The suggested PointOutT is pcl::SHOT1344
283  *
284  * \note If you use this code in any academic work, please cite:
285  *
286  * - F. Tombari, S. Salti, L. Di Stefano
287  * Unique Signatures of Histograms for Local Surface Description.
288  * In Proceedings of the 11th European Conference on Computer Vision (ECCV),
289  * Heraklion, Greece, September 5-11 2010.
290  * - F. Tombari, S. Salti, L. Di Stefano
291  * A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
292  * In Proceedings of the 18th International Conference on Image Processing (ICIP),
293  * Brussels, Belgium, September 11-14 2011.
294  *
295  * \author Samuele Salti, Federico Tombari
296  * \ingroup features
297  */
298  template <typename PointInT, typename PointNT, typename PointOutT = pcl::SHOT1344, typename PointRFT = pcl::ReferenceFrame>
299  class SHOTColorEstimation : public SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>
300  {
301  public:
302  typedef boost::shared_ptr<SHOTColorEstimation<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
303  typedef boost::shared_ptr<const SHOTColorEstimation<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
324 
326 
327  /** \brief Empty constructor.
328  * \param[in] describe_shape
329  * \param[in] describe_color
330  */
331  SHOTColorEstimation (bool describe_shape = true,
332  bool describe_color = true)
333  : SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> (10),
334  b_describe_shape_ (describe_shape),
335  b_describe_color_ (describe_color),
336  nr_color_bins_ (30)
337  {
338  feature_name_ = "SHOTColorEstimation";
339  };
340 
341  /** \brief Empty destructor */
342  virtual ~SHOTColorEstimation () {}
343 
344  /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
345  * \param[in] index the index of the point in indices_
346  * \param[in] indices the k-neighborhood point indices in surface_
347  * \param[in] sqr_dists the k-neighborhood point distances in surface_
348  * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
349  */
350  virtual void
351  computePointSHOT (const int index,
352  const std::vector<int> &indices,
353  const std::vector<float> &sqr_dists,
354  Eigen::VectorXf &shot);
355  protected:
356  /** \brief Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by
357  * <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
358  * setSearchMethod ()
359  * \param output the resultant point cloud model dataset that contains the SHOT feature estimates
360  */
361  void
363 
364  /** \brief Quadrilinear interpolation; used when color and shape descriptions are both activated
365  * \param[in] indices the neighborhood point indices
366  * \param[in] sqr_dists the neighborhood point distances
367  * \param[in] index the index of the point in indices_
368  * \param[out] binDistanceShape the resultant distance shape histogram
369  * \param[out] binDistanceColor the resultant color shape histogram
370  * \param[in] nr_bins_shape the number of bins in the shape histogram
371  * \param[in] nr_bins_color the number of bins in the color histogram
372  * \param[out] shot the resultant SHOT histogram
373  */
374  void
375  interpolateDoubleChannel (const std::vector<int> &indices,
376  const std::vector<float> &sqr_dists,
377  const int index,
378  std::vector<double> &binDistanceShape,
379  std::vector<double> &binDistanceColor,
380  const int nr_bins_shape,
381  const int nr_bins_color,
382  Eigen::VectorXf &shot);
383 
384  /** \brief Compute shape descriptor. */
386 
387  /** \brief Compute color descriptor. */
389 
390  /** \brief The number of bins in each color histogram. */
392 
393  public:
394  /** \brief Converts RGB triplets to CIELab space.
395  * \param[in] R the red channel
396  * \param[in] G the green channel
397  * \param[in] B the blue channel
398  * \param[out] L the lightness
399  * \param[out] A the first color-opponent dimension
400  * \param[out] B2 the second color-opponent dimension
401  */
402  static void
403  RGB2CIELAB (unsigned char R, unsigned char G, unsigned char B, float &L, float &A, float &B2);
404 
405  static float sRGB_LUT[256];
406  static float sXYZ_LUT[4000];
407  };
408 }
409 
410 #ifdef PCL_NO_PRECOMPILE
411 #include <pcl/features/impl/shot.hpp>
412 #endif
413 
414 #endif //#ifndef PCL_SHOT_H_
boost::shared_ptr< const SHOTColorEstimation< PointInT, PointNT, PointOutT, PointRFT > > ConstPtr
Definition: shot.h:303
Feature< PointInT, PointOutT >::PointCloudIn PointCloudIn
Definition: shot.h:247
virtual float getLRFRadius() const
Get the radius used for local reference frame estimation.
Definition: shot.h:127
double sqradius_
The squared search radius.
Definition: shot.h:180
SHOTColorEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for a giv...
Definition: shot.h:299
static float sXYZ_LUT[4000]
Definition: shot.h:406
Feature< PointInT, PointOutT >::PointCloudIn PointCloudIn
Definition: shot.h:325
void computeFeature(pcl::PointCloud< PointOutT > &output)
Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by ...
Definition: shot.hpp:830
SHOTEstimation()
Empty constructor.
Definition: shot.h:250
std::string feature_name_
The feature name.
Definition: feature.h:222
void interpolateSingleChannel(const std::vector< int > &indices, const std::vector< float > &sqr_dists, const int index, std::vector< double > &binDistance, const int nr_bins, Eigen::VectorXf &shot)
Quadrilinear interpolation used when color and shape descriptions are NOT activated simultaneously...
Definition: shot.hpp:255
static void RGB2CIELAB(unsigned char R, unsigned char G, unsigned char B, float &L, float &A, float &B2)
Converts RGB triplets to CIELab space.
Definition: shot.hpp:97
double radius1_2_
1/2 of the search radius.
Definition: shot.h:189
virtual void setLRFRadius(float radius)
Set the radius used for local reference frame estimation if the frames are not set by the user...
Definition: shot.h:123
void computeFeature(pcl::PointCloud< PointOutT > &output)
Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by ...
Definition: shot.hpp:764
virtual void computePointSHOT(const int index, const std::vector< int > &indices, const std::vector< float > &sqr_dists, Eigen::VectorXf &shot)=0
Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with no...
float lrf_radius_
The radius used for the LRF computation.
Definition: shot.h:177
virtual bool initCompute()
This method should get called before starting the actual computation.
Definition: shot.hpp:158
virtual ~SHOTEstimationBase()
Empty destructor.
Definition: shot.h:107
int descLength_
One SHOT length.
Definition: shot.h:198
virtual ~SHOTColorEstimation()
Empty destructor.
Definition: shot.h:342
SHOTColorEstimation(bool describe_shape=true, bool describe_color=true)
Empty constructor.
Definition: shot.h:331
const int maxAngularSectors_
...
Definition: shot.h:195
SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for a given po...
Definition: shot.h:221
const int nr_grid_sector_
Number of azimuthal sectors.
Definition: shot.h:192
virtual ~SHOTEstimation()
Empty destructor.
Definition: shot.h:256
Feature< PointInT, PointOutT >::PointCloudIn PointCloudIn
Definition: shot.h:86
int nr_color_bins_
The number of bins in each color histogram.
Definition: shot.h:391
boost::shared_ptr< const SHOTEstimation< PointInT, PointNT, PointOutT, PointRFT > > ConstPtr
Definition: shot.h:225
int nr_shape_bins_
The number of bins in each shape histogram.
Definition: shot.h:171
Eigen::VectorXf shot_
Placeholder for a point&#39;s SHOT.
Definition: shot.h:174
void createBinDistanceShape(int index, const std::vector< int > &indices, std::vector< double > &bin_distance_shape)
Create a binned distance shape histogram.
Definition: shot.hpp:194
boost::shared_ptr< SHOTColorEstimation< PointInT, PointNT, PointOutT, PointRFT > > Ptr
Definition: shot.h:302
static float sRGB_LUT[256]
Definition: shot.h:405
virtual void computePointSHOT(const int index, const std::vector< int > &indices, const std::vector< float > &sqr_dists, Eigen::VectorXf &shot)
Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with no...
Definition: shot.hpp:646
void normalizeHistogram(Eigen::VectorXf &shot, int desc_length)
Normalize the SHOT histogram.
Definition: shot.hpp:238
double radius1_4_
1/4 of the search radius.
Definition: shot.h:186
SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for a given po...
Definition: shot.h:68
boost::shared_ptr< SHOTEstimationBase< PointInT, PointNT, PointOutT, PointRFT > > Ptr
Definition: shot.h:72
boost::shared_ptr< const SHOTEstimationBase< PointInT, PointNT, PointOutT, PointRFT > > ConstPtr
Definition: shot.h:73
double radius3_4_
3/4 of the search radius.
Definition: shot.h:183
Feature represents the base feature class.
Definition: feature.h:105
bool b_describe_color_
Compute color descriptor.
Definition: shot.h:388
FeatureWithLocalReferenceFrames provides a public interface for descriptor extractor classes which ne...
Definition: feature.h:447
boost::shared_ptr< SHOTEstimation< PointInT, PointNT, PointOutT, PointRFT > > Ptr
Definition: shot.h:224
SHOTEstimationBase(int nr_shape_bins=10)
Empty constructor.
Definition: shot.h:92
Definition: norms.h:55
void interpolateDoubleChannel(const std::vector< int > &indices, const std::vector< float > &sqr_dists, const int index, std::vector< double > &binDistanceShape, std::vector< double > &binDistanceColor, const int nr_bins_shape, const int nr_bins_color, Eigen::VectorXf &shot)
Quadrilinear interpolation; used when color and shape descriptions are both activated.
Definition: shot.hpp:430
virtual void computePointSHOT(const int index, const std::vector< int > &indices, const std::vector< float > &sqr_dists, Eigen::VectorXf &shot)
Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with no...
Definition: shot.hpp:734
bool b_describe_shape_
Compute shape descriptor.
Definition: shot.h:385