Point Cloud Library (PCL)  1.14.0-dev
correspondence_rejection_poly.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  */
38 
39 #pragma once
40 
41 #include <pcl/registration/correspondence_rejection.h>
42 #include <pcl/point_cloud.h>
43 
44 namespace pcl {
45 namespace registration {
46 /** \brief CorrespondenceRejectorPoly implements a correspondence rejection method that
47  * exploits low-level and pose-invariant geometric constraints between two point sets by
48  * forming virtual polygons of a user-specifiable cardinality on each model using the
49  * input correspondences. These polygons are then checked in a pose-invariant manner
50  * (i.e. the side lengths must be approximately equal), and rejection is performed by
51  * thresholding these edge lengths.
52  *
53  * If you use this in academic work, please cite:
54  *
55  * A. G. Buch, D. Kraft, J.-K. Kämäräinen, H. G. Petersen and N. Krüger.
56  * Pose Estimation using Local Structure-Specific Shape and Appearance Context.
57  * International Conference on Robotics and Automation (ICRA), 2013.
58  *
59  * \author Anders Glent Buch
60  * \ingroup registration
61  */
62 template <typename SourceT, typename TargetT>
67 
68 public:
69  using Ptr = shared_ptr<CorrespondenceRejectorPoly<SourceT, TargetT>>;
70  using ConstPtr = shared_ptr<const CorrespondenceRejectorPoly<SourceT, TargetT>>;
71 
75 
79 
80  /** \brief Empty constructor */
81  CorrespondenceRejectorPoly() { rejection_name_ = "CorrespondenceRejectorPoly"; }
82 
83  /** \brief Get a list of valid correspondences after rejection from the original set
84  * of correspondences.
85  * \param[in] original_correspondences the set of initial correspondences given
86  * \param[out] remaining_correspondences the resultant filtered set of remaining
87  * correspondences
88  */
89  void
90  getRemainingCorrespondences(const pcl::Correspondences& original_correspondences,
91  pcl::Correspondences& remaining_correspondences) override;
92 
93  /** \brief Provide a source point cloud dataset (must contain XYZ data!), used to
94  * compute the correspondence distance.
95  * \param[in] cloud a cloud containing XYZ data
96  */
97  inline void
99  {
100  input_ = cloud;
101  }
102 
103  /** \brief Provide a target point cloud dataset (must contain XYZ data!), used to
104  * compute the correspondence distance.
105  * \param[in] target a cloud containing XYZ data
106  */
107  inline void
109  {
110  target_ = target;
111  }
112 
113  /** \brief See if this rejector requires source points */
114  bool
115  requiresSourcePoints() const override
116  {
117  return (true);
118  }
119 
120  /** \brief Blob method for setting the source cloud */
121  void
123  {
125  fromPCLPointCloud2(*cloud2, *cloud);
126  setInputSource(cloud);
127  }
128 
129  /** \brief See if this rejector requires a target cloud */
130  bool
131  requiresTargetPoints() const override
132  {
133  return (true);
134  }
135 
136  /** \brief Method for setting the target cloud */
137  void
139  {
141  fromPCLPointCloud2(*cloud2, *cloud);
142  setInputTarget(cloud);
143  }
144 
145  /** \brief Set the polygon cardinality
146  * \param cardinality polygon cardinality
147  */
148  inline void
149  setCardinality(int cardinality)
150  {
151  cardinality_ = cardinality;
152  }
153 
154  /** \brief Get the polygon cardinality
155  * \return polygon cardinality
156  */
157  inline int
159  {
160  return (cardinality_);
161  }
162 
163  /** \brief Set the similarity threshold in [0,1[ between edge lengths,
164  * where 1 is a perfect match
165  * \param similarity_threshold similarity threshold
166  */
167  inline void
168  setSimilarityThreshold(float similarity_threshold)
169  {
170  similarity_threshold_ = similarity_threshold;
171  similarity_threshold_squared_ = similarity_threshold * similarity_threshold;
172  }
173 
174  /** \brief Get the similarity threshold between edge lengths
175  * \return similarity threshold
176  */
177  inline float
179  {
180  return (similarity_threshold_);
181  }
182 
183  /** \brief Set the number of iterations
184  * \param iterations number of iterations
185  */
186  inline void
187  setIterations(int iterations)
188  {
189  iterations_ = iterations;
190  }
191 
192  /** \brief Get the number of iterations
193  * \return number of iterations
194  */
195  inline int
197  {
198  return (iterations_);
199  }
200 
201  /** \brief Polygonal rejection of a single polygon, indexed by a subset of
202  * correspondences \param corr all correspondences into \ref input_ and \ref target_
203  * \param idx sampled indices into \b correspondences, must have a size equal to \ref
204  * cardinality_ \return true if all edge length ratios are larger than or equal to
205  * \ref similarity_threshold_
206  */
207  inline bool
208  thresholdPolygon(const pcl::Correspondences& corr, const std::vector<int>& idx)
209  {
210  if (cardinality_ ==
211  2) // Special case: when two points are considered, we only have one edge
212  {
213  return (thresholdEdgeLength(corr[idx[0]].index_query,
214  corr[idx[1]].index_query,
215  corr[idx[0]].index_match,
216  corr[idx[1]].index_match,
217  similarity_threshold_squared_));
218  }
219  // Otherwise check all edges
220  for (int i = 0; i < cardinality_; ++i) {
221  if (!thresholdEdgeLength(corr[idx[i]].index_query,
222  corr[idx[(i + 1) % cardinality_]].index_query,
223  corr[idx[i]].index_match,
224  corr[idx[(i + 1) % cardinality_]].index_match,
225  similarity_threshold_squared_)) {
226  return (false);
227  }
228  }
229  return (true);
230  }
231 
232  /** \brief Polygonal rejection of a single polygon, indexed by two point index vectors
233  * \param source_indices indices of polygon points in \ref input_, must have a size
234  * equal to \ref cardinality_
235  * \param target_indices corresponding indices of polygon points in \ref target_, must
236  * have a size equal to \ref cardinality_
237  * \return true if all edge length ratios are larger than or equal to
238  * \ref similarity_threshold_
239  */
240  inline bool
241  thresholdPolygon(const pcl::Indices& source_indices,
242  const pcl::Indices& target_indices)
243  {
244  // Convert indices to correspondences and an index vector pointing to each element
245  pcl::Correspondences corr(cardinality_);
246  std::vector<int> idx(cardinality_);
247  for (int i = 0; i < cardinality_; ++i) {
248  corr[i].index_query = source_indices[i];
249  corr[i].index_match = target_indices[i];
250  idx[i] = i;
251  }
252 
253  return (thresholdPolygon(corr, idx));
254  }
255 
256 protected:
257  /** \brief Apply the rejection algorithm.
258  * \param[out] correspondences the set of resultant correspondences.
259  */
260  inline void
261  applyRejection(pcl::Correspondences& correspondences) override
262  {
263  getRemainingCorrespondences(*input_correspondences_, correspondences);
264  }
265 
266  /** \brief Get k unique random indices in range {0,...,n-1} (sampling without
267  * replacement) \note No check is made to ensure that k <= n.
268  * \param n upper index range, exclusive
269  * \param k number of unique indices to sample
270  * \return k unique random indices in range {0,...,n-1}
271  */
272  inline std::vector<int>
274  {
275  // Marked sampled indices and sample counter
276  std::vector<bool> sampled(n, false);
277  int samples = 0;
278  // Resulting unique indices
279  std::vector<int> result;
280  result.reserve(k);
281  do {
282  // Pick a random index in the range
283  const int idx = (std::rand() % n);
284  // If unique
285  if (!sampled[idx]) {
286  // Mark as sampled and increment result counter
287  sampled[idx] = true;
288  ++samples;
289  // Store
290  result.push_back(idx);
291  }
292  } while (samples < k);
293 
294  return (result);
295  }
296 
297  /** \brief Squared Euclidean distance between two points using the members x, y and z
298  * \param p1 first point
299  * \param p2 second point
300  * \return squared Euclidean distance
301  */
302  inline float
303  computeSquaredDistance(const SourceT& p1, const TargetT& p2)
304  {
305  const float dx = p2.x - p1.x;
306  const float dy = p2.y - p1.y;
307  const float dz = p2.z - p1.z;
308 
309  return (dx * dx + dy * dy + dz * dz);
310  }
311 
312  /** \brief Edge length similarity thresholding
313  * \param index_query_1 index of first source vertex
314  * \param index_query_2 index of second source vertex
315  * \param index_match_1 index of first target vertex
316  * \param index_match_2 index of second target vertex
317  * \param simsq squared similarity threshold in [0,1]
318  * \return true if edge length ratio is larger than or equal to threshold
319  */
320  inline bool
321  thresholdEdgeLength(int index_query_1,
322  int index_query_2,
323  int index_match_1,
324  int index_match_2,
325  float simsq)
326  {
327  // Distance between source points
328  const float dist_src =
329  computeSquaredDistance((*input_)[index_query_1], (*input_)[index_query_2]);
330  // Distance between target points
331  const float dist_tgt =
332  computeSquaredDistance((*target_)[index_match_1], (*target_)[index_match_2]);
333  // Edge length similarity [0,1] where 1 is a perfect match
334  const float edge_sim =
335  (dist_src < dist_tgt ? dist_src / dist_tgt : dist_tgt / dist_src);
336 
337  return (edge_sim >= simsq);
338  }
339 
340  /** \brief Compute a linear histogram. This function is equivalent to the MATLAB
341  * function \b histc, with the edges set as follows: <b>
342  * lower:(upper-lower)/bins:upper </b>
343  * \param data input samples
344  * \param lower lower bound of input samples
345  * \param upper upper bound of input samples
346  * \param bins number of bins in output
347  * \return linear histogram
348  */
349  std::vector<int>
350  computeHistogram(const std::vector<float>& data, float lower, float upper, int bins);
351 
352  /** \brief Find the optimal value for binary histogram thresholding using Otsu's
353  * method
354  * \param histogram input histogram \return threshold value according to Otsu's
355  * criterion
356  */
357  int
358  findThresholdOtsu(const std::vector<int>& histogram);
359 
360  /** \brief The input point cloud dataset */
362 
363  /** \brief The input point cloud dataset target */
365 
366  /** \brief Number of iterations to run */
367  int iterations_{10000};
368 
369  /** \brief The polygon cardinality used during rejection */
370  int cardinality_{3};
371 
372  /** \brief Lower edge length threshold in [0,1] used for verifying polygon
373  * similarities, where 1 is a perfect match */
374  float similarity_threshold_{0.75f};
375 
376  /** \brief Squared value if \ref similarity_threshold_, only for internal use */
377  float similarity_threshold_squared_{0.75f * 0.75f};
378 };
379 } // namespace registration
380 } // namespace pcl
381 
382 #include <pcl/registration/impl/correspondence_rejection_poly.hpp>
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:414
CorrespondenceRejector represents the base class for correspondence rejection methods
shared_ptr< const CorrespondenceRejector > ConstPtr
CorrespondencesConstPtr input_correspondences_
The input correspondences.
const std::string & getClassName() const
Get a string representation of the name of this class.
shared_ptr< CorrespondenceRejector > Ptr
std::string rejection_name_
The name of the rejection method.
CorrespondenceRejectorPoly implements a correspondence rejection method that exploits low-level and p...
bool thresholdPolygon(const pcl::Correspondences &corr, const std::vector< int > &idx)
Polygonal rejection of a single polygon, indexed by a subset of correspondences.
float computeSquaredDistance(const SourceT &p1, const TargetT &p2)
Squared Euclidean distance between two points using the members x, y and z.
typename PointCloudTarget::ConstPtr PointCloudTargetConstPtr
PointCloudSourceConstPtr input_
The input point cloud dataset.
float getSimilarityThreshold()
Get the similarity threshold between edge lengths.
void setTargetPoints(pcl::PCLPointCloud2::ConstPtr cloud2) override
Method for setting the target cloud.
bool thresholdPolygon(const pcl::Indices &source_indices, const pcl::Indices &target_indices)
Polygonal rejection of a single polygon, indexed by two point index vectors.
void applyRejection(pcl::Correspondences &correspondences) override
Apply the rejection algorithm.
void setCardinality(int cardinality)
Set the polygon cardinality.
void setSimilarityThreshold(float similarity_threshold)
Set the similarity threshold in [0,1[ between edge lengths, where 1 is a perfect match.
void setIterations(int iterations)
Set the number of iterations.
bool thresholdEdgeLength(int index_query_1, int index_query_2, int index_match_1, int index_match_2, float simsq)
Edge length similarity thresholding.
PointCloudTargetConstPtr target_
The input point cloud dataset target.
void setInputTarget(const PointCloudTargetConstPtr &target)
Provide a target point cloud dataset (must contain XYZ data!), used to compute the correspondence dis...
void setSourcePoints(pcl::PCLPointCloud2::ConstPtr cloud2) override
Blob method for setting the source cloud.
void setInputSource(const PointCloudSourceConstPtr &cloud)
Provide a source point cloud dataset (must contain XYZ data!), used to compute the correspondence dis...
bool requiresTargetPoints() const override
See if this rejector requires a target cloud.
std::vector< int > getUniqueRandomIndices(int n, int k)
Get k unique random indices in range {0,...,n-1} (sampling without replacement)
bool requiresSourcePoints() const override
See if this rejector requires source points.
typename PointCloudSource::ConstPtr PointCloudSourceConstPtr
void fromPCLPointCloud2(const pcl::PCLPointCloud2 &msg, pcl::PointCloud< PointT > &cloud, const MsgFieldMap &field_map, const std::uint8_t *msg_data)
Convert a PCLPointCloud2 binary data blob into a pcl::PointCloud<T> object using a field_map.
Definition: conversions.h:164
std::vector< pcl::Correspondence, Eigen::aligned_allocator< pcl::Correspondence > > Correspondences
IndicesAllocator<> Indices
Type used for indices in PCL.
Definition: types.h:133
#define PCL_EXPORTS
Definition: pcl_macros.h:323
shared_ptr< const ::pcl::PCLPointCloud2 > ConstPtr