Point Cloud Library (PCL)  1.11.0-dev
rsd.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2009, 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 <pcl/memory.h>
44 #include <pcl/pcl_macros.h>
45 #include <pcl/features/feature.h>
46 
47 namespace pcl
48 {
49  /** \brief Transform a list of 2D matrices into a point cloud containing the values in a vector (Histogram<N>).
50  * Can be used to transform the 2D histograms obtained in \ref RSDEstimation into a point cloud.
51  * @note The template parameter N should be (greater or) equal to the product of the number of rows and columns.
52  * \param[in] histograms2D the list of neighborhood 2D histograms
53  * \param[out] histogramsPC the dataset containing the linearized matrices
54  * \ingroup features
55  */
56  template <int N> void
57  getFeaturePointCloud (const std::vector<Eigen::MatrixXf, Eigen::aligned_allocator<Eigen::MatrixXf> > &histograms2D, PointCloud<Histogram<N> > &histogramsPC)
58  {
59  histogramsPC.points.resize (histograms2D.size ());
60  histogramsPC.width = histograms2D.size ();
61  histogramsPC.height = 1;
62  histogramsPC.is_dense = true;
63 
64  const int rows = histograms2D.at(0).rows();
65  const int cols = histograms2D.at(0).cols();
66 
67  typename PointCloud<Histogram<N> >::VectorType::iterator it = histogramsPC.points.begin ();
68  for (const Eigen::MatrixXf& h : histograms2D)
69  {
70  Eigen::Map<Eigen::MatrixXf> histogram (&(it->histogram[0]), rows, cols);
71  histogram = h;
72  ++it;
73  }
74  }
75 
76  /** \brief Estimate the Radius-based Surface Descriptor (RSD) for a given point based on its spatial neighborhood of 3D points with normals
77  * \param[in] surface the dataset containing the XYZ points
78  * \param[in] normals the dataset containing the surface normals at each point in the dataset
79  * \param[in] indices the neighborhood point indices in the dataset (first point is used as the reference)
80  * \param[in] max_dist the upper bound for the considered distance interval
81  * \param[in] nr_subdiv the number of subdivisions for the considered distance interval
82  * \param[in] plane_radius maximum radius, above which everything can be considered planar
83  * \param[in] radii the output point of a type that should have r_min and r_max fields
84  * \param[in] compute_histogram if not false, the full neighborhood histogram is provided, usable as a point signature
85  * \ingroup features
86  */
87  template <typename PointInT, typename PointNT, typename PointOutT> Eigen::MatrixXf
88  computeRSD (const pcl::PointCloud<PointInT> &surface, const pcl::PointCloud<PointNT> &normals,
89  const std::vector<int> &indices, double max_dist,
90  int nr_subdiv, double plane_radius, PointOutT &radii, bool compute_histogram = false);
91 
92  template <typename PointInT, typename PointNT, typename PointOutT>
93  PCL_DEPRECATED(1, 12, "use computeRSD() overload that takes input point clouds by const reference")
94  Eigen::MatrixXf
95  computeRSD (typename pcl::PointCloud<PointInT>::ConstPtr &surface, typename pcl::PointCloud<PointNT>::ConstPtr &normals,
96  const std::vector<int> &indices, double max_dist,
97  int nr_subdiv, double plane_radius, PointOutT &radii, bool compute_histogram = false)
98  {
99  return computeRSD (*surface, *normals, indices, max_dist, nr_subdiv, plane_radius, radii, compute_histogram);
100  }
101 
102  /** \brief Estimate the Radius-based Surface Descriptor (RSD) for a given point based on its spatial neighborhood of 3D points with normals
103  * \param[in] normals the dataset containing the surface normals at each point in the dataset
104  * \param[in] indices the neighborhood point indices in the dataset (first point is used as the reference)
105  * \param[in] sqr_dists the squared distances from the first to all points in the neighborhood
106  * \param[in] max_dist the upper bound for the considered distance interval
107  * \param[in] nr_subdiv the number of subdivisions for the considered distance interval
108  * \param[in] plane_radius maximum radius, above which everything can be considered planar
109  * \param[in] radii the output point of a type that should have r_min and r_max fields
110  * \param[in] compute_histogram if not false, the full neighborhood histogram is provided, usable as a point signature
111  * \ingroup features
112  */
113  template <typename PointNT, typename PointOutT> Eigen::MatrixXf
114  computeRSD (const pcl::PointCloud<PointNT> &normals,
115  const std::vector<int> &indices, const std::vector<float> &sqr_dists, double max_dist,
116  int nr_subdiv, double plane_radius, PointOutT &radii, bool compute_histogram = false);
117 
118  template <typename PointNT, typename PointOutT>
119  PCL_DEPRECATED(1, 12, "use computeRSD() overload that takes input point cloud by const reference")
120  Eigen::MatrixXf
121  computeRSD (typename pcl::PointCloud<PointNT>::ConstPtr &normals,
122  const std::vector<int> &indices, const std::vector<float> &sqr_dists, double max_dist,
123  int nr_subdiv, double plane_radius, PointOutT &radii, bool compute_histogram = false)
124  {
125  return computeRSD (*normals, indices, sqr_dists, max_dist, nr_subdiv, plane_radius, radii, compute_histogram);
126  }
127 
128  /** \brief @b RSDEstimation estimates the Radius-based Surface Descriptor (minimal and maximal radius of the local surface's curves)
129  * for a given point cloud dataset containing points and normals.
130  *
131  * @note If you use this code in any academic work, please cite:
132  *
133  * <ul>
134  * <li> Z.C. Marton , D. Pangercic , N. Blodow , J. Kleinehellefort, M. Beetz
135  * General 3D Modelling of Novel Objects from a Single View
136  * In Proceedings of the 2010 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)
137  * Taipei, Taiwan, October 18-22, 2010
138  * </li>
139  * <li> Z.C. Marton, D. Pangercic, N. Blodow, Michael Beetz.
140  * Combined 2D-3D Categorization and Classification for Multimodal Perception Systems.
141  * In The International Journal of Robotics Research, Sage Publications
142  * pages 1378--1402, Volume 30, Number 11, September 2011.
143  * </li>
144  * </ul>
145  *
146  * @note The code is stateful as we do not expect this class to be multicore parallelized.
147  * \author Zoltan-Csaba Marton
148  * \ingroup features
149  */
150  template <typename PointInT, typename PointNT, typename PointOutT>
151  class RSDEstimation : public FeatureFromNormals<PointInT, PointNT, PointOutT>
152  {
153  public:
161 
164 
165  using Ptr = shared_ptr<RSDEstimation<PointInT, PointNT, PointOutT> >;
166  using ConstPtr = shared_ptr<const RSDEstimation<PointInT, PointNT, PointOutT> >;
167 
168 
169  /** \brief Empty constructor. */
170  RSDEstimation () : nr_subdiv_ (5), plane_radius_ (0.2), save_histograms_ (false)
171  {
172  feature_name_ = "RadiusSurfaceDescriptor";
173  };
174 
175  /** \brief Set the number of subdivisions for the considered distance interval.
176  * \param[in] nr_subdiv the number of subdivisions
177  */
178  inline void
179  setNrSubdivisions (int nr_subdiv) { nr_subdiv_ = nr_subdiv; }
180 
181  /** \brief Get the number of subdivisions for the considered distance interval.
182  * \return the number of subdivisions
183  */
184  inline int
185  getNrSubdivisions () const { return (nr_subdiv_); }
186 
187  /** \brief Set the maximum radius, above which everything can be considered planar.
188  * \note the order of magnitude should be around 10-20 times the search radius (0.2 works well for typical datasets).
189  * \note on accurate 3D data (e.g. openni sernsors) a search radius as low as 0.01 still gives good results.
190  * \param[in] plane_radius the new plane radius
191  */
192  inline void
193  setPlaneRadius (double plane_radius) { plane_radius_ = plane_radius; }
194 
195  /** \brief Get the maximum radius, above which everything can be considered planar.
196  * \return the plane_radius used
197  */
198  inline double
199  getPlaneRadius () const { return (plane_radius_); }
200 
201  /** \brief Disables the setting of the number of k nearest neighbors to use for the feature estimation. */
202  inline void
203  setKSearch (int)
204  {
205  PCL_ERROR ("[pcl::%s::setKSearch] RSD does not work with k nearest neighbor search. Use setRadiusSearch() instead!\n", getClassName ().c_str ());
206  }
207 
208  /** \brief Set whether the full distance-angle histograms should be saved.
209  * @note Obtain the list of histograms by getHistograms ()
210  * \param[in] save set to true if histograms should be saved
211  */
212  inline void
213  setSaveHistograms (bool save) { save_histograms_ = save; }
214 
215  /** \brief Returns whether the full distance-angle histograms are being saved.
216  * \return true if the histograms are being be saved
217  */
218  inline bool
219  getSaveHistograms () const { return (save_histograms_); }
220 
221  /** \brief Returns a pointer to the list of full distance-angle histograms for all points.
222  * \return the histogram being saved when computing RSD
223  */
224  inline shared_ptr<std::vector<Eigen::MatrixXf, Eigen::aligned_allocator<Eigen::MatrixXf> > >
225  getHistograms () const { return (histograms_); }
226 
227  protected:
228 
229  /** \brief Estimate the estimates the Radius-based Surface Descriptor (RSD) at a set of points given by
230  * <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
231  * setSearchMethod ()
232  * \param output the resultant point cloud model dataset that contains the RSD feature estimates (r_min and r_max values)
233  */
234  void
235  computeFeature (PointCloudOut &output) override;
236 
237  /** \brief The list of full distance-angle histograms for all points. */
238  shared_ptr<std::vector<Eigen::MatrixXf, Eigen::aligned_allocator<Eigen::MatrixXf> > > histograms_;
239 
240  private:
241  /** \brief The number of subdivisions for the considered distance interval. */
242  int nr_subdiv_;
243 
244  /** \brief The maximum radius, above which everything can be considered planar. */
245  double plane_radius_;
246 
247  /** \brief Signals whether the full distance-angle histograms are being saved. */
248  bool save_histograms_;
249 
250  public:
252  };
253 }
254 
255 #ifdef PCL_NO_PRECOMPILE
256 #include <pcl/features/impl/rsd.hpp>
257 #endif
pcl_macros.h
Defines all the PCL and non-PCL macros used.
pcl
Definition: convolution.h:46
pcl::Feature::Ptr
shared_ptr< Feature< PointInT, PointOutT > > Ptr
Definition: feature.h:114
Eigen
Definition: bfgs.h:9
pcl::PointCloud::points
std::vector< PointT, Eigen::aligned_allocator< PointT > > points
The point data.
Definition: point_cloud.h:411
pcl::RSDEstimation::getNrSubdivisions
int getNrSubdivisions() const
Get the number of subdivisions for the considered distance interval.
Definition: rsd.h:185
pcl::getFeaturePointCloud
void getFeaturePointCloud(const std::vector< Eigen::MatrixXf, Eigen::aligned_allocator< Eigen::MatrixXf > > &histograms2D, PointCloud< Histogram< N > > &histogramsPC)
Transform a list of 2D matrices into a point cloud containing the values in a vector (Histogram<N>).
Definition: rsd.h:57
pcl::RSDEstimation::computeFeature
void computeFeature(PointCloudOut &output) override
Estimate the estimates the Radius-based Surface Descriptor (RSD) at a set of points given by <setInpu...
Definition: rsd.hpp:248
pcl::RSDEstimation::getSaveHistograms
bool getSaveHistograms() const
Returns whether the full distance-angle histograms are being saved.
Definition: rsd.h:219
pcl::PointCloud
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: projection_matrix.h:53
pcl::RSDEstimation::getHistograms
shared_ptr< std::vector< Eigen::MatrixXf, Eigen::aligned_allocator< Eigen::MatrixXf > > > getHistograms() const
Returns a pointer to the list of full distance-angle histograms for all points.
Definition: rsd.h:225
pcl::Feature::ConstPtr
shared_ptr< const Feature< PointInT, PointOutT > > ConstPtr
Definition: feature.h:115
PCL_DEPRECATED
#define PCL_DEPRECATED(Major, Minor, Message)
macro for compatibility across compilers and help remove old deprecated items for the Major....
Definition: pcl_macros.h:150
pcl::RSDEstimation
RSDEstimation estimates the Radius-based Surface Descriptor (minimal and maximal radius of the local ...
Definition: rsd.h:151
pcl::RSDEstimation::PointCloudOut
typename Feature< PointInT, PointOutT >::PointCloudOut PointCloudOut
Definition: rsd.h:162
PCL_MAKE_ALIGNED_OPERATOR_NEW
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: memory.h:63
pcl::RSDEstimation::setPlaneRadius
void setPlaneRadius(double plane_radius)
Set the maximum radius, above which everything can be considered planar.
Definition: rsd.h:193
pcl::FeatureFromNormals
Definition: feature.h:311
pcl::RSDEstimation::getPlaneRadius
double getPlaneRadius() const
Get the maximum radius, above which everything can be considered planar.
Definition: rsd.h:199
pcl::computeRSD
Eigen::MatrixXf computeRSD(const pcl::PointCloud< PointInT > &surface, const pcl::PointCloud< PointNT > &normals, const std::vector< int > &indices, double max_dist, int nr_subdiv, double plane_radius, PointOutT &radii, bool compute_histogram=false)
Estimate the Radius-based Surface Descriptor (RSD) for a given point based on its spatial neighborhoo...
Definition: rsd.hpp:49
pcl::RSDEstimation::RSDEstimation
RSDEstimation()
Empty constructor.
Definition: rsd.h:170
pcl::Histogram
A point structure representing an N-D histogram.
Definition: point_types.hpp:1677
pcl::io::save
PCL_EXPORTS int save(const std::string &file_name, const pcl::PCLPointCloud2 &blob, unsigned precision=5)
Save point cloud data to a binary file when available else to ASCII.
pcl::RSDEstimation::setSaveHistograms
void setSaveHistograms(bool save)
Set whether the full distance-angle histograms should be saved.
Definition: rsd.h:213
pcl::Feature::getClassName
const std::string & getClassName() const
Get a string representation of the name of this class.
Definition: feature.h:247
pcl::Feature::feature_name_
std::string feature_name_
The feature name.
Definition: feature.h:223
memory.h
Defines functions, macros and traits for allocating and using memory.
pcl::RSDEstimation::histograms_
shared_ptr< std::vector< Eigen::MatrixXf, Eigen::aligned_allocator< Eigen::MatrixXf > > > histograms_
The list of full distance-angle histograms for all points.
Definition: rsd.h:238
pcl::RSDEstimation::setNrSubdivisions
void setNrSubdivisions(int nr_subdiv)
Set the number of subdivisions for the considered distance interval.
Definition: rsd.h:179
pcl::RSDEstimation::setKSearch
void setKSearch(int)
Disables the setting of the number of k nearest neighbors to use for the feature estimation.
Definition: rsd.h:203
pcl::Feature
Feature represents the base feature class.
Definition: feature.h:106