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