Point Cloud Library (PCL)  1.8.1
rops_estimation.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  *
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * * Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  * * Redistributions in binary form must reproduce the above
15  * copyright notice, this list of conditions and the following
16  * disclaimer in the documentation and/or other materials provided
17  * with the distribution.
18  * * Neither the name of Willow Garage, Inc. nor the names of its
19  * contributors may be used to endorse or promote products derived
20  * from this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
25  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
26  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
27  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
30  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  *
35  * Author : Sergey Ushakov
36  * Email : sergey.s.ushakov@mail.ru
37  *
38  */
39 
40 #ifndef PCL_ROPS_ESIMATION_H_
41 #define PCL_ROPS_ESIMATION_H_
42 
43 #include <pcl/PolygonMesh.h>
44 #include <pcl/features/feature.h>
45 #include <set>
46 
47 namespace pcl
48 {
49  /** \brief
50  * This class implements the method for extracting RoPS features presented in the article
51  * "Rotational Projection Statistics for 3D Local Surface Description and Object Recognition" by
52  * Yulan Guo, Ferdous Sohel, Mohammed Bennamoun, Min Lu and Jianwei Wan.
53  */
54  template <typename PointInT, typename PointOutT>
55  class PCL_EXPORTS ROPSEstimation : public pcl::Feature <PointInT, PointOutT>
56  {
57  public:
58 
63 
66 
67  public:
68 
69  /** \brief Simple constructor. */
70  ROPSEstimation ();
71 
72  /** \brief Virtual destructor. */
73  virtual
74  ~ROPSEstimation ();
75 
76  /** \brief Allows to set the number of partition bins that is used for distribution matrix calculation.
77  * \param[in] number_of_bins number of partition bins
78  */
79  void
80  setNumberOfPartitionBins (unsigned int number_of_bins);
81 
82  /** \brief Returns the nmber of partition bins. */
83  unsigned int
84  getNumberOfPartitionBins () const;
85 
86  /** \brief This method sets the number of rotations.
87  * \param[in] number_of_rotations number of rotations
88  */
89  void
90  setNumberOfRotations (unsigned int number_of_rotations);
91 
92  /** \brief returns the number of rotations. */
93  unsigned int
94  getNumberOfRotations () const;
95 
96  /** \brief Allows to set the support radius that is used to crop the local surface of the point.
97  * \param[in] support_radius support radius
98  */
99  void
100  setSupportRadius (float support_radius);
101 
102  /** \brief Returns the support radius. */
103  float
104  getSupportRadius () const;
105 
106  /** \brief This method sets the triangles of the mesh.
107  * \param[in] triangles list of triangles of the mesh
108  */
109  void
110  setTriangles (const std::vector <pcl::Vertices>& triangles);
111 
112  /** \brief Returns the triangles of the mesh.
113  * \param[out] triangles triangles of tthe mesh
114  */
115  void
116  getTriangles (std::vector <pcl::Vertices>& triangles) const;
117 
118  private:
119 
120  /** \brief Abstract feature estimation method.
121  * \param[out] output the resultant features
122  */
123  virtual void
124  computeFeature (PointCloudOut& output);
125 
126  /** \brief This method simply builds the list of triangles for every point.
127  * The list of triangles for each point consists of indices of triangles it belongs to.
128  * The only purpose of this method is to improve perfomance of the algorithm.
129  */
130  void
131  buildListOfPointsTriangles ();
132 
133  /** \brief This method crops all the triangles within the given radius of the given point.
134  * \param[in] point point for which the local surface is computed
135  * \param[out] local_triangles strores the indices of the triangles that belong to the local surface
136  * \param[out] local_points stores the indices of the points that belong to the local surface
137  */
138  void
139  getLocalSurface (const PointInT& point, std::set <unsigned int>& local_triangles, std::vector <int>& local_points) const;
140 
141  /** \brief This method computes LRF (Local Reference Frame) matrix for the given point.
142  * \param[in] point point for which the LRF is computed
143  * \param[in] local_triangles list of triangles that represents the local surface of the point
144  * \paran[out] lrf_matrix strores computed LRF matrix for the given point
145  */
146  void
147  computeLRF (const PointInT& point, const std::set <unsigned int>& local_triangles, Eigen::Matrix3f& lrf_matrix) const;
148 
149  /** \brief This method calculates the eigen values and eigen vectors
150  * for the given covariance matrix. Note that it returns normalized eigen
151  * vectors that always form the right-handed coordinate system.
152  * \param[in] matrix covariance matrix of the cloud
153  * \param[out] major_axis eigen vector which corresponds to a major eigen value
154  * \param[out] middle_axis eigen vector which corresponds to a middle eigen value
155  * \param[out] minor_axis eigen vector which corresponds to a minor eigen value
156  */
157  void
158  computeEigenVectors (const Eigen::Matrix3f& matrix, Eigen::Vector3f& major_axis, Eigen::Vector3f& middle_axis,
159  Eigen::Vector3f& minor_axis) const;
160 
161  /** \brief This method translates the cloud so that the given point becomes the origin.
162  * After that the cloud is rotated with the help of the given matrix.
163  * \param[in] point point which stores the translation information
164  * \param[in] matrix rotation matrix
165  * \param[in] local_points point to transform
166  * \param[out] transformed_cloud stores the transformed cloud
167  */
168  void
169  transformCloud (const PointInT& point, const Eigen::Matrix3f& matrix, const std::vector <int>& local_points, PointCloudIn& transformed_cloud) const;
170 
171  /** \brief This method rotates the cloud around the given axis and computes AABB of the rotated cloud.
172  * \param[in] axis axis around which cloud must be rotated
173  * \param[in] angle angle in degrees
174  * \param[in] cloud cloud to rotate
175  * \param[out] rotated_cloud stores the rotated cloud
176  * \param[out] min stores the min point of the AABB
177  * \param[out] max stores the max point of the AABB
178  */
179  void
180  rotateCloud (const PointInT& axis, const float angle, const PointCloudIn& cloud, PointCloudIn& rotated_cloud,
181  Eigen::Vector3f& min, Eigen::Vector3f& max) const;
182 
183  /** \brief This method projects the local surface onto the XY, XZ or YZ plane
184  * and computes the distribution matrix.
185  * \param[in] projection represents the case of projection. 1 - XY, 2 - XZ, 3 - YZ
186  * \param[in] min min point of the AABB
187  * \param[in] max max point of the AABB
188  * \param[in] cloud cloud containing the points of the local surface
189  * \param[out] matrix stores computed distribution matrix
190  */
191  void
192  getDistributionMatrix (const unsigned int projection, const Eigen::Vector3f& min, const Eigen::Vector3f& max, const PointCloudIn& cloud, Eigen::MatrixXf& matrix) const;
193 
194  /** \brief This method computes the set ofcentral moments for the given matrix.
195  * \param[in] matrix input matrix
196  * \param[out] moments set of computed moments
197  */
198  void
199  computeCentralMoments (const Eigen::MatrixXf& matrix, std::vector <float>& moments) const;
200 
201  private:
202 
203  /** \brief Stores the number of partition bins that is used for distribution matrix calculation. */
204  unsigned int number_of_bins_;
205 
206  /** \brief Stores number of rotations. Central moments are calculated for every rotation. */
207  unsigned int number_of_rotations_;
208 
209  /** \brief Support radius that is used to crop the local surface of the point. */
210  float support_radius_;
211 
212  /** \brief Stores the squared support radius. Used to improve performance. */
213  float sqr_support_radius_;
214 
215  /** \brief Stores the angle step. Step is calculated with respect to number of rotations. */
216  float step_;
217 
218  /** \brief Stores the set of triangles reprsenting the mesh. */
219  std::vector <pcl::Vertices> triangles_;
220 
221  /** \brief Stores the set of triangles for each point. Its purpose is to improve perfomance. */
222  std::vector <std::vector <unsigned int> > triangles_of_the_point_;
223 
224  public:
225 
226  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
227  };
228 }
229 
230 #define PCL_INSTANTIATE_ROPSEstimation(InT, OutT) template class pcl::ROPSEstimation<InT, OutT>;
231 
232 #ifdef PCL_NO_PRECOMPILE
233 #include <pcl/features/impl/rops_estimation.hpp>
234 #endif
235 
236 #endif
pcl::Feature< PointInT, PointOutT >::PointCloudOut PointCloudOut
This class implements the method for extracting RoPS features presented in the article "Rotational Pr...
PointCloud represents the base class in PCL for storing collections of 3D points. ...
pcl::Feature< PointInT, PointOutT >::PointCloudIn PointCloudIn
Feature represents the base feature class.
Definition: feature.h:105