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