Point Cloud Library (PCL)  1.11.1-dev
gasd.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2016-, Open Perception, Inc.
6  * Copyright (c) 2016, Voxar Labs, CIn-UFPE / DEINFO-UFRPE
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 #pragma once
40 
41 #include <pcl/features/feature.h>
42 #include <pcl/point_cloud.h>
43 
44 namespace pcl
45 {
46  /// Different histogram interpolation methods
48  {
49  INTERP_NONE, ///< no interpolation
50  INTERP_TRILINEAR, ///< trilinear interpolation
51  INTERP_QUADRILINEAR ///< quadrilinear interpolation
52  };
53 
54  /** \brief GASDEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given
55  * point cloud dataset given XYZ data.
56  *
57  * The suggested PointOutT is pcl::GASDSignature512.
58  *
59  * \note If you use this code in any academic work, please cite:
60  *
61  * - J. Lima, V. Teichrieb.
62  * An Efficient Global Point Cloud Descriptor for Object Recognition and Pose Estimation.
63  * In Proceedings of the 29th SIBGRAPI - Conference on Graphics, Patterns and Images,
64  * Sao Jose dos Campos, Brazil, October 4-7 2016.
65  *
66  * \author Joao Paulo Lima
67  *
68  * Voxar Labs, Centro de Informatica, Universidade Federal de Pernambuco, Brazil
69  *
70  * Departamento de Estatistica e Informatica, Universidade Federal Rural de Pernambuco, Brazil
71  *
72  * \ingroup features
73  */
74  template <typename PointInT, typename PointOutT = GASDSignature512>
75  class GASDEstimation : public Feature<PointInT, PointOutT>
76  {
77  public:
80  using Ptr = shared_ptr<GASDEstimation<PointInT, PointOutT> >;
81  using ConstPtr = shared_ptr<const GASDEstimation<PointInT, PointOutT> >;
82 
83  /** \brief Constructor.
84  * \param[in] view_direction view direction
85  * \param[in] shape_half_grid_size shape half grid size
86  * \param[in] shape_hists_size shape histograms size
87  * \param[in] shape_interp shape histograms interpolation method
88  */
89  GASDEstimation (const Eigen::Vector3f &view_direction = Eigen::Vector3f (0.0f, 0.0f, 1.0f),
90  const std::size_t shape_half_grid_size = 4,
91  const std::size_t shape_hists_size = 1,
92  const HistogramInterpolationMethod shape_interp = INTERP_TRILINEAR) :
93  view_direction_ (view_direction),
94  shape_half_grid_size_ (shape_half_grid_size),
95  shape_hists_size_ (shape_hists_size),
96  shape_interp_ (shape_interp)
97  {
98  search_radius_ = 0;
99  k_ = 1;
100  feature_name_ = "GASDEstimation";
101  }
102 
103  /** \brief Set the view direction.
104  * \param[in] dir view direction
105  */
106  inline void
107  setViewDirection (const Eigen::Vector3f &dir)
108  {
109  view_direction_ = dir;
110  }
111 
112  /** \brief Set the shape half grid size.
113  * \param[in] shgs shape half grid size
114  */
115  inline void
116  setShapeHalfGridSize (const std::size_t shgs)
117  {
118  shape_half_grid_size_ = shgs;
119  }
120 
121  /** \brief Set the shape histograms size. If size is 1, then each histogram bin will store the number
122  * of points that belong to its correspondent cell in the 3D regular grid. If size > 1, then for each cell
123  * it will be computed a histogram of normalized distances between each sample and the cloud centroid
124  * \param[in] shs shape histograms size
125  */
126  inline void
127  setShapeHistsSize (const std::size_t shs)
128  {
129  shape_hists_size_ = shs;
130  }
131 
132  /** \brief Set the shape histograms interpolation method.
133  * \param[in] interp shape histograms interpolation method
134  */
135  inline void
137  {
138  shape_interp_ = interp;
139  }
140 
141  /**
142  * \brief Returns the transformation aligning the point cloud to the canonical coordinate system
143  */
144  const Eigen::Matrix4f&
145  getTransform () const
146  {
147  return transform_;
148  }
149 
150  /** \brief Overloaded computed method from pcl::Feature.
151  * \param[out] output the resultant point cloud model dataset containing the estimated feature
152  */
153  void
154  compute (PointCloudOut &output);
155 
156  protected:
163 
164  /** \brief Point cloud aligned to the canonical coordinate system. */
166 
167  /** \brief Normalization factor with respect to axis-aligned bounding cube centered on the origin. */
168  float max_coord_;
169 
170  /** \brief Normalized sample contribution with respect to the total number of points in the cloud. */
171  float hist_incr_;
172 
173  /** \brief Current position of output descriptor point cloud. */
174  std::size_t pos_;
175 
176  /** \brief add a sample to its respective histogram, optionally performing interpolation.
177  * \param[in] p histogram sample
178  * \param[in] max_coord normalization factor with respect to axis-aligned bounding cube centered on the origin
179  * \param[in] half_grid_size half size of the regular grid used to compute the descriptor
180  * \param[in] interp interpolation method to be used while computing the descriptor
181  * \param[in] hbin histogram bin
182  * \param[in] hist_incr normalization factor of sample contribution
183  * \param[in,out] hists updated histograms
184  */
185  void
186  addSampleToHistograms (const Eigen::Vector4f &p,
187  const float max_coord,
188  const std::size_t half_grid_size,
189  const HistogramInterpolationMethod interp,
190  const float hbin,
191  const float hist_incr,
192  std::vector<Eigen::VectorXf> &hists);
193 
194  /** \brief Estimate GASD descriptor
195  *
196  * \param[out] output the resultant point cloud model dataset containing the GASD feature
197  */
198  void
199  computeFeature (PointCloudOut &output) override;
200 
201  private:
202  /** \brief Transform that aligns the point cloud to the canonical coordinate system. */
203  Eigen::Matrix4f transform_;
204 
205  /** \brief Viewing direction, default value is (0, 0, 1). */
206  Eigen::Vector3f view_direction_;
207 
208  /** \brief Half size of the regular grid used to compute the shape descriptor. */
209  std::size_t shape_half_grid_size_;
210 
211  /** \brief Size of the histograms of normalized distances between each sample and the cloud centroid. */
212  std::size_t shape_hists_size_;
213 
214  /** \brief Interpolation method to be used while computing the shape descriptor. */
215  HistogramInterpolationMethod shape_interp_;
216 
217  /** \brief Estimates a reference frame for the point cloud and uses it to compute a transform that aligns the point cloud to the canonical coordinate system. */
218  void
219  computeAlignmentTransform ();
220 
221  /** \brief copy computed shape histograms to output descriptor point cloud
222  * \param[in] grid_size size of the regular grid used to compute the descriptor
223  * \param[in] hists_size size of the shape histograms
224  * \param[in] hists shape histograms
225  * \param[out] output output descriptor point cloud
226  * \param[in,out] pos current position of output descriptor point cloud
227  */
228  void
229  copyShapeHistogramsToOutput (const std::size_t grid_size,
230  const std::size_t hists_size,
231  const std::vector<Eigen::VectorXf> &hists,
232  PointCloudOut &output,
233  std::size_t &pos);
234  };
235 
236  /** \brief GASDColorEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given
237  * point cloud dataset given XYZ and RGB data.
238  *
239  * The suggested PointOutT is pcl::GASDSignature984.
240  *
241  * \note If you use this code in any academic work, please cite:
242  *
243  * - J. Lima, V. Teichrieb.
244  * An Efficient Global Point Cloud Descriptor for Object Recognition and Pose Estimation.
245  * In Proceedings of the 29th SIBGRAPI - Conference on Graphics, Patterns and Images,
246  * Sao Jose dos Campos, Brazil, October 4-7 2016.
247  *
248  * \author Joao Paulo Lima
249  *
250  * Voxar Labs, Centro de Informatica, Universidade Federal de Pernambuco, Brazil
251  *
252  * Departamento de Estatistica e Informatica, Universidade Federal Rural de Pernambuco, Brazil
253  *
254  * \ingroup features
255  */
256  template <typename PointInT, typename PointOutT = GASDSignature984>
257  class GASDColorEstimation : public GASDEstimation<PointInT, PointOutT>
258  {
259  public:
261  using Ptr = shared_ptr<GASDColorEstimation<PointInT, PointOutT> >;
262  using ConstPtr = shared_ptr<const GASDColorEstimation<PointInT, PointOutT> >;
263 
264  /** \brief Constructor.
265  * \param[in] view_direction view direction
266  * \param[in] shape_half_grid_size shape half grid size
267  * \param[in] shape_hists_size shape histograms size
268  * \param[in] color_half_grid_size color half grid size
269  * \param[in] color_hists_size color histograms size
270  * \param[in] shape_interp shape histograms interpolation method
271  * \param[in] color_interp color histograms interpolation method
272  */
273  GASDColorEstimation (const Eigen::Vector3f &view_direction = Eigen::Vector3f (0.0f, 0.0f, 1.0f),
274  const std::size_t shape_half_grid_size = 3,
275  const std::size_t shape_hists_size = 1,
276  const std::size_t color_half_grid_size = 2,
277  const std::size_t color_hists_size = 12,
278  const HistogramInterpolationMethod shape_interp = INTERP_NONE,
279  const HistogramInterpolationMethod color_interp = INTERP_NONE) :
280  GASDEstimation<PointInT, PointOutT> (view_direction, shape_half_grid_size, shape_hists_size, shape_interp),
281  color_half_grid_size_ (color_half_grid_size),
282  color_hists_size_ (color_hists_size),
283  color_interp_ (color_interp)
284  {
285  feature_name_ = "GASDColorEstimation";
286  }
287 
288  /** \brief Set the color half grid size.
289  * \param[in] chgs color half grid size
290  */
291  inline void
292  setColorHalfGridSize (const std::size_t chgs)
293  {
294  color_half_grid_size_ = chgs;
295  }
296 
297  /** \brief Set the color histograms size (number of bins in the hue histogram for each cell of the 3D regular grid).
298  * \param[in] chs color histograms size
299  */
300  inline void
301  setColorHistsSize (const std::size_t chs)
302  {
303  color_hists_size_ = chs;
304  }
305 
306  /** \brief Set the color histograms interpolation method.
307  * \param[in] interp color histograms interpolation method
308  */
309  inline void
311  {
312  color_interp_ = interp;
313  }
314 
315  protected:
326 
327  private:
328  /** \brief Half size of the regular grid used to compute the color descriptor. */
329  std::size_t color_half_grid_size_;
330 
331  /** \brief Size of the hue histograms. */
332  std::size_t color_hists_size_;
333 
334  /** \brief Interpolation method to be used while computing the color descriptor. */
335  HistogramInterpolationMethod color_interp_;
336 
337  /** \brief copy computed color histograms to output descriptor point cloud
338  * \param[in] grid_size size of the regular grid used to compute the descriptor
339  * \param[in] hists_size size of the color histograms
340  * \param[in,out] hists color histograms, which are finalized, since they are circular
341  * \param[out] output output descriptor point cloud
342  * \param[in,out] pos current position of output descriptor point cloud
343  */
344  void
345  copyColorHistogramsToOutput (const std::size_t grid_size,
346  const std::size_t hists_size,
347  std::vector<Eigen::VectorXf> &hists,
348  PointCloudOut &output,
349  std::size_t &pos);
350 
351  /** \brief Estimate GASD color descriptor
352  *
353  * \param[out] output the resultant point cloud model dataset containing the GASD color feature
354  */
355  void
356  computeFeature (PointCloudOut &output) override;
357  };
358 } // namespace pcl
359 
360 #ifdef PCL_NO_PRECOMPILE
361 #include <pcl/features/impl/gasd.hpp>
362 #endif
pcl
Definition: convolution.h:46
pcl::Feature< PointInT, GASDSignature984 >::Ptr
shared_ptr< Feature< PointInT, GASDSignature984 > > Ptr
Definition: feature.h:114
pcl::GASDEstimation::hist_incr_
float hist_incr_
Normalized sample contribution with respect to the total number of points in the cloud.
Definition: gasd.h:171
pcl::GASDEstimation::setShapeHalfGridSize
void setShapeHalfGridSize(const std::size_t shgs)
Set the shape half grid size.
Definition: gasd.h:116
pcl::GASDEstimation
GASDEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given poin...
Definition: gasd.h:75
pcl::GASDEstimation::pos_
std::size_t pos_
Current position of output descriptor point cloud.
Definition: gasd.h:174
pcl::GASDEstimation::compute
void compute(PointCloudOut &output)
Overloaded computed method from pcl::Feature.
Definition: gasd.hpp:50
pcl::INTERP_NONE
@ INTERP_NONE
no interpolation
Definition: gasd.h:49
pcl::GASDColorEstimation::setColorHistsInterpMethod
void setColorHistsInterpMethod(const HistogramInterpolationMethod interp)
Set the color histograms interpolation method.
Definition: gasd.h:310
pcl::GASDEstimation::setShapeHistsInterpMethod
void setShapeHistsInterpMethod(const HistogramInterpolationMethod interp)
Set the shape histograms interpolation method.
Definition: gasd.h:136
pcl::PointCloud< PointInT >
pcl::Feature< PointInT, GASDSignature984 >::ConstPtr
shared_ptr< const Feature< PointInT, GASDSignature984 > > ConstPtr
Definition: feature.h:115
pcl::GASDColorEstimation::GASDColorEstimation
GASDColorEstimation(const Eigen::Vector3f &view_direction=Eigen::Vector3f(0.0f, 0.0f, 1.0f), const std::size_t shape_half_grid_size=3, const std::size_t shape_hists_size=1, const std::size_t color_half_grid_size=2, const std::size_t color_hists_size=12, const HistogramInterpolationMethod shape_interp=INTERP_NONE, const HistogramInterpolationMethod color_interp=INTERP_NONE)
Constructor.
Definition: gasd.h:273
pcl::GASDEstimation::getTransform
const Eigen::Matrix4f & getTransform() const
Returns the transformation aligning the point cloud to the canonical coordinate system.
Definition: gasd.h:145
pcl::GASDColorEstimation::Ptr
shared_ptr< GASDColorEstimation< PointInT, PointOutT > > Ptr
Definition: gasd.h:261
pcl::GASDEstimation::setShapeHistsSize
void setShapeHistsSize(const std::size_t shs)
Set the shape histograms size.
Definition: gasd.h:127
pcl::Feature< PointInT, GASDSignature512 >::search_radius_
double search_radius_
The nearest neighbors search radius for each point.
Definition: feature.h:240
pcl::GASDEstimation::addSampleToHistograms
void addSampleToHistograms(const Eigen::Vector4f &p, const float max_coord, const std::size_t half_grid_size, const HistogramInterpolationMethod interp, const float hbin, const float hist_incr, std::vector< Eigen::VectorXf > &hists)
add a sample to its respective histogram, optionally performing interpolation.
Definition: gasd.hpp:117
pcl::GASDColorEstimation::ConstPtr
shared_ptr< const GASDColorEstimation< PointInT, PointOutT > > ConstPtr
Definition: gasd.h:262
pcl::INTERP_TRILINEAR
@ INTERP_TRILINEAR
trilinear interpolation
Definition: gasd.h:50
pcl::GASDEstimation::max_coord_
float max_coord_
Normalization factor with respect to axis-aligned bounding cube centered on the origin.
Definition: gasd.h:168
pcl::INTERP_QUADRILINEAR
@ INTERP_QUADRILINEAR
quadrilinear interpolation
Definition: gasd.h:51
pcl::GASDEstimation::computeFeature
void computeFeature(PointCloudOut &output) override
Estimate GASD descriptor.
Definition: gasd.hpp:252
pcl::GASDColorEstimation::setColorHistsSize
void setColorHistsSize(const std::size_t chs)
Set the color histograms size (number of bins in the hue histogram for each cell of the 3D regular gr...
Definition: gasd.h:301
pcl::Feature< PointInT, GASDSignature512 >::k_
int k_
The number of K nearest neighbors to use for each point.
Definition: feature.h:243
pcl::GASDColorEstimation
GASDColorEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given...
Definition: gasd.h:257
pcl::Feature< PointInT, GASDSignature512 >::PointCloudIn
pcl::PointCloud< PointInT > PointCloudIn
Definition: feature.h:120
pcl::Feature< PointInT, GASDSignature512 >::PointCloudOut
pcl::PointCloud< GASDSignature512 > PointCloudOut
Definition: feature.h:124
pcl::GASDEstimation::setViewDirection
void setViewDirection(const Eigen::Vector3f &dir)
Set the view direction.
Definition: gasd.h:107
pcl::HistogramInterpolationMethod
HistogramInterpolationMethod
Different histogram interpolation methods.
Definition: gasd.h:47
pcl::GASDEstimation::GASDEstimation
GASDEstimation(const Eigen::Vector3f &view_direction=Eigen::Vector3f(0.0f, 0.0f, 1.0f), const std::size_t shape_half_grid_size=4, const std::size_t shape_hists_size=1, const HistogramInterpolationMethod shape_interp=INTERP_TRILINEAR)
Constructor.
Definition: gasd.h:89
pcl::Feature< PointInT, GASDSignature512 >::feature_name_
std::string feature_name_
The feature name.
Definition: feature.h:223
pcl::GASDColorEstimation::setColorHalfGridSize
void setColorHalfGridSize(const std::size_t chgs)
Set the color half grid size.
Definition: gasd.h:292
pcl::GASDEstimation::shape_samples_
PointCloudIn shape_samples_
Point cloud aligned to the canonical coordinate system.
Definition: gasd.h:165
pcl::Feature
Feature represents the base feature class.
Definition: feature.h:106