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