Point Cloud Library (PCL)  1.11.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 #pragma once
41 
42 #include <pcl/memory.h>
43 #include <pcl/pcl_macros.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 
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 number 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 the 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  void
124  computeFeature (PointCloudOut& output) override;
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 performance 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 stores 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 stores 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 representing the mesh. */
219  std::vector <pcl::Vertices> triangles_;
220 
221  /** \brief Stores the set of triangles for each point. Its purpose is to improve performance. */
222  std::vector <std::vector <unsigned int> > triangles_of_the_point_;
223 
224  public:
226  };
227 }
228 
229 #define PCL_INSTANTIATE_ROPSEstimation(InT, OutT) template class pcl::ROPSEstimation<InT, OutT>;
230 
231 #ifdef PCL_NO_PRECOMPILE
232 #include <pcl/features/impl/rops_estimation.hpp>
233 #endif
Feature represents the base feature class.
Definition: feature.h:107
This class implements the method for extracting RoPS features presented in the article "Rotational Pr...
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: memory.h:63
Defines functions, macros and traits for allocating and using memory.
Defines all the PCL and non-PCL macros used.
#define PCL_EXPORTS
Definition: pcl_macros.h:328