Point Cloud Library (PCL)  1.11.1-dev
3dsc.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  * $Id$
38  *
39  */
40 
41 #pragma once
42 
43 #include <random>
44 
45 #include <pcl/point_types.h>
46 #include <pcl/features/feature.h>
47 
48 namespace pcl
49 {
50  /** \brief ShapeContext3DEstimation implements the 3D shape context descriptor as
51  * described in:
52  * - Andrea Frome, Daniel Huber, Ravi Kolluri and Thomas B├╝low, Jitendra Malik
53  * Recognizing Objects in Range Data Using Regional Point Descriptors,
54  * In proceedings of the 8th European Conference on Computer Vision (ECCV),
55  * Prague, May 11-14, 2004
56  *
57  * The suggested PointOutT is pcl::ShapeContext1980
58  *
59  * \attention
60  * The convention for a 3D shape context descriptor is:
61  * - if a query point's nearest neighbors cannot be estimated, the feature descriptor will be set to NaN (not a number), and the RF to 0
62  * - it is impossible to estimate a 3D shape context descriptor for a
63  * point that doesn't have finite 3D coordinates. Therefore, any point
64  * that contains NaN data on x, y, or z, will have its boundary feature
65  * property set to NaN.
66  *
67  * \author Alessandro Franchi, Samuele Salti, Federico Tombari (original code)
68  * \author Nizar Sallem (port to PCL)
69  * \ingroup features
70  */
71  template <typename PointInT, typename PointNT, typename PointOutT = pcl::ShapeContext1980>
72  class ShapeContext3DEstimation : public FeatureFromNormals<PointInT, PointNT, PointOutT>
73  {
74  public:
75  using Ptr = shared_ptr<ShapeContext3DEstimation<PointInT, PointNT, PointOutT> >;
76  using ConstPtr = shared_ptr<const ShapeContext3DEstimation<PointInT, PointNT, PointOutT> >;
77 
87 
90 
91  /** \brief Constructor.
92  * \param[in] random If true the random seed is set to current time, else it is
93  * set to 12345 prior to computing the descriptor (used to select X axis)
94  */
95  ShapeContext3DEstimation (bool random = false) :
96  radii_interval_(0),
98  phi_divisions_(0),
99  volume_lut_(0),
100  azimuth_bins_(12),
101  elevation_bins_(11),
102  radius_bins_(15),
103  min_radius_(0.1),
106  rng_dist_ (0.0f, 1.0f)
107  {
108  feature_name_ = "ShapeContext3DEstimation";
109  search_radius_ = 2.5;
110 
111  // Create a random number generator object
112  if (random)
113  {
114  std::random_device rd;
115  rng_.seed (rd());
116  }
117  else
118  rng_.seed (12345u);
119  }
120 
122 
123  //inline void
124  //setAzimuthBins (std::size_t bins) { azimuth_bins_ = bins; }
125 
126  /** \return the number of bins along the azimuth */
127  inline std::size_t
128  getAzimuthBins () { return (azimuth_bins_); }
129 
130  //inline void
131  //setElevationBins (std::size_t bins) { elevation_bins_ = bins; }
132 
133  /** \return The number of bins along the elevation */
134  inline std::size_t
136 
137  //inline void
138  //setRadiusBins (std::size_t bins) { radius_bins_ = bins; }
139 
140  /** \return The number of bins along the radii direction */
141  inline std::size_t
142  getRadiusBins () { return (radius_bins_); }
143 
144  /** \brief The minimal radius value for the search sphere (rmin) in the original paper
145  * \param[in] radius the desired minimal radius
146  */
147  inline void
148  setMinimalRadius (double radius) { min_radius_ = radius; }
149 
150  /** \return The minimal sphere radius */
151  inline double
152  getMinimalRadius () { return (min_radius_); }
153 
154  /** \brief This radius is used to compute local point density
155  * density = number of points within this radius
156  * \param[in] radius value of the point density search radius
157  */
158  inline void
159  setPointDensityRadius (double radius) { point_density_radius_ = radius; }
160 
161  /** \return The point density search radius */
162  inline double
164 
165  protected:
166  /** \brief Initialize computation by allocating all the intervals and the volume lookup table. */
167  bool
168  initCompute () override;
169 
170  /** \brief Estimate a descriptor for a given point.
171  * \param[in] index the index of the point to estimate a descriptor for
172  * \param[in] normals a pointer to the set of normals
173  * \param[in] rf the reference frame
174  * \param[out] desc the resultant estimated descriptor
175  * \return true if the descriptor was computed successfully, false if there was an error
176  * (e.g. the nearest neighbor didn't return any neighbors)
177  */
178  bool
179  computePoint (std::size_t index, const pcl::PointCloud<PointNT> &normals, float rf[9], std::vector<float> &desc);
180 
181  /** \brief Estimate the actual feature.
182  * \param[out] output the resultant feature
183  */
184  void
185  computeFeature (PointCloudOut &output) override;
186 
187  /** \brief Values of the radii interval */
188  std::vector<float> radii_interval_;
189 
190  /** \brief Theta divisions interval */
191  std::vector<float> theta_divisions_;
192 
193  /** \brief Phi divisions interval */
194  std::vector<float> phi_divisions_;
195 
196  /** \brief Volumes look up table */
197  std::vector<float> volume_lut_;
198 
199  /** \brief Bins along the azimuth dimension */
200  std::size_t azimuth_bins_;
201 
202  /** \brief Bins along the elevation dimension */
203  std::size_t elevation_bins_;
204 
205  /** \brief Bins along the radius dimension */
206  std::size_t radius_bins_;
207 
208  /** \brief Minimal radius value */
209  double min_radius_;
210 
211  /** \brief Point density radius */
213 
214  /** \brief Descriptor length */
215  std::size_t descriptor_length_;
216 
217  /** \brief Random number generator algorithm. */
218  std::mt19937 rng_;
219 
220  /** \brief Random number generator distribution. */
221  std::uniform_real_distribution<float> rng_dist_;
222 
223  /* \brief Shift computed descriptor "L" times along the azimuthal direction
224  * \param[in] block_size the size of each azimuthal block
225  * \param[in] desc at input desc == original descriptor and on output it contains
226  * shifted descriptor resized descriptor_length_ * azimuth_bins_
227  */
228  //void
229  //shiftAlongAzimuth (std::size_t block_size, std::vector<float>& desc);
230 
231  /** \brief Boost-based random number generator. */
232  inline float
233  rnd ()
234  {
235  return (rng_dist_ (rng_));
236  }
237  };
238 }
239 
240 #ifdef PCL_NO_PRECOMPILE
241 #include <pcl/features/impl/3dsc.hpp>
242 #endif
pcl::ShapeContext3DEstimation::computePoint
bool computePoint(std::size_t index, const pcl::PointCloud< PointNT > &normals, float rf[9], std::vector< float > &desc)
Estimate a descriptor for a given point.
Definition: 3dsc.hpp:133
pcl::ShapeContext3DEstimation::getMinimalRadius
double getMinimalRadius()
Definition: 3dsc.h:152
pcl::ShapeContext3DEstimation::initCompute
bool initCompute() override
Initialize computation by allocating all the intervals and the volume lookup table.
Definition: 3dsc.hpp:53
pcl
Definition: convolution.h:46
pcl::ShapeContext3DEstimation::radii_interval_
std::vector< float > radii_interval_
Values of the radii interval.
Definition: 3dsc.h:188
point_types.h
pcl::ShapeContext3DEstimation::ConstPtr
shared_ptr< const ShapeContext3DEstimation< PointInT, PointNT, PointOutT > > ConstPtr
Definition: 3dsc.h:76
pcl::ShapeContext3DEstimation::rng_dist_
std::uniform_real_distribution< float > rng_dist_
Random number generator distribution.
Definition: 3dsc.h:221
pcl::ShapeContext3DEstimation::phi_divisions_
std::vector< float > phi_divisions_
Phi divisions interval.
Definition: 3dsc.h:194
pcl::ShapeContext3DEstimation::getAzimuthBins
std::size_t getAzimuthBins()
Definition: 3dsc.h:128
pcl::ShapeContext3DEstimation::theta_divisions_
std::vector< float > theta_divisions_
Theta divisions interval.
Definition: 3dsc.h:191
pcl::ShapeContext3DEstimation::PointCloudOut
typename Feature< PointInT, PointOutT >::PointCloudOut PointCloudOut
Definition: 3dsc.h:88
pcl::ShapeContext3DEstimation::azimuth_bins_
std::size_t azimuth_bins_
Bins along the azimuth dimension.
Definition: 3dsc.h:200
pcl::ShapeContext3DEstimation::Ptr
shared_ptr< ShapeContext3DEstimation< PointInT, PointNT, PointOutT > > Ptr
Definition: 3dsc.h:75
pcl::ShapeContext3DEstimation::elevation_bins_
std::size_t elevation_bins_
Bins along the elevation dimension.
Definition: 3dsc.h:203
pcl::ShapeContext3DEstimation::setPointDensityRadius
void setPointDensityRadius(double radius)
This radius is used to compute local point density density = number of points within this radius.
Definition: 3dsc.h:159
pcl::PointCloud< PointOutT >
pcl::ShapeContext3DEstimation::min_radius_
double min_radius_
Minimal radius value.
Definition: 3dsc.h:209
pcl::ShapeContext3DEstimation::setMinimalRadius
void setMinimalRadius(double radius)
The minimal radius value for the search sphere (rmin) in the original paper.
Definition: 3dsc.h:148
pcl::ShapeContext3DEstimation::~ShapeContext3DEstimation
~ShapeContext3DEstimation()
Definition: 3dsc.h:121
pcl::ShapeContext3DEstimation::getElevationBins
std::size_t getElevationBins()
Definition: 3dsc.h:135
pcl::ShapeContext3DEstimation::radius_bins_
std::size_t radius_bins_
Bins along the radius dimension.
Definition: 3dsc.h:206
pcl::ShapeContext3DEstimation::point_density_radius_
double point_density_radius_
Point density radius.
Definition: 3dsc.h:212
pcl::Feature< PointInT, pcl::ShapeContext1980 >::search_radius_
double search_radius_
The nearest neighbors search radius for each point.
Definition: feature.h:240
pcl::ShapeContext3DEstimation::rnd
float rnd()
Boost-based random number generator.
Definition: 3dsc.h:233
pcl::ShapeContext3DEstimation::PointCloudIn
typename Feature< PointInT, PointOutT >::PointCloudIn PointCloudIn
Definition: 3dsc.h:89
pcl::ShapeContext3DEstimation::ShapeContext3DEstimation
ShapeContext3DEstimation(bool random=false)
Constructor.
Definition: 3dsc.h:95
pcl::ShapeContext3DEstimation::rng_
std::mt19937 rng_
Random number generator algorithm.
Definition: 3dsc.h:218
pcl::ShapeContext3DEstimation::getRadiusBins
std::size_t getRadiusBins()
Definition: 3dsc.h:142
pcl::ShapeContext3DEstimation::computeFeature
void computeFeature(PointCloudOut &output) override
Estimate the actual feature.
Definition: 3dsc.hpp:249
pcl::FeatureFromNormals
Definition: feature.h:311
pcl::ShapeContext3DEstimation::volume_lut_
std::vector< float > volume_lut_
Volumes look up table.
Definition: 3dsc.h:197
pcl::ShapeContext3DEstimation
ShapeContext3DEstimation implements the 3D shape context descriptor as described in:
Definition: 3dsc.h:72
pcl::ShapeContext3DEstimation::descriptor_length_
std::size_t descriptor_length_
Descriptor length.
Definition: 3dsc.h:215
pcl::Feature< PointInT, pcl::ShapeContext1980 >::feature_name_
std::string feature_name_
The feature name.
Definition: feature.h:223
pcl::ShapeContext3DEstimation::getPointDensityRadius
double getPointDensityRadius()
Definition: 3dsc.h:163
pcl::Feature
Feature represents the base feature class.
Definition: feature.h:106