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