Point Cloud Library (PCL)  1.14.1-dev
flare.h
1 /*
2 * Software License Agreement (BSD License)
3 *
4 * Point Cloud Library (PCL) - www.pointclouds.org
5 * Copyright (c) 2016-, Open Perception, Inc.
6 *
7 * All rights reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * * Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * * Redistributions in binary form must reproduce the above
16 * copyright notice, this list of conditions and the following
17 * disclaimer in the documentation and/or other materials provided
18 * with the distribution.
19 * * Neither the name of the copyright holder(s) nor the names of its
20 * contributors may be used to endorse or promote products derived
21 * from this software without specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 * POSSIBILITY OF SUCH DAMAGE.
35 *
36 *
37 */
38 
39 #pragma once
40 
41 #include <pcl/point_types.h>
42 #include <pcl/features/feature.h>
43 #include <pcl/features/normal_3d.h>
44 
45 
46 namespace pcl
47 {
48 
49  /** \brief FLARELocalReferenceFrameEstimation implements the Fast LocAl Reference framE algorithm
50  * for local reference frame estimation as described here:
51  *
52  * - A. Petrelli, L. Di Stefano,
53  * "A repeatable and efficient canonical reference for surface matching",
54  * 3DimPVT, 2012
55  *
56  * FLARE algorithm is deployed in ReLOC algorithm proposed in:
57  *
58  * Petrelli A., Di Stefano L., "Pairwise registration by local orientation cues", Computer Graphics Forum, 2015.
59  *
60  * \author Alioscia Petrelli
61  * \ingroup features
62  */
63  template<typename PointInT, typename PointNT, typename PointOutT = ReferenceFrame, typename SignedDistanceT = float>
64  class FLARELocalReferenceFrameEstimation : public FeatureFromNormals<PointInT, PointNT, PointOutT>
65  {
66  protected:
76 
79 
81 
83 
86 
87  using Ptr = shared_ptr<FLARELocalReferenceFrameEstimation<PointInT, PointNT, PointOutT> >;
88  using ConstPtr = shared_ptr<const FLARELocalReferenceFrameEstimation<PointInT, PointNT, PointOutT> >;
89 
90  public:
91  /** \brief Constructor. */
93 
94  sampled_surface_ (),
95  sampled_tree_ ()
96  {
97  feature_name_ = "FLARELocalReferenceFrameEstimation";
98  }
99 
100  //Getters/Setters
101 
102  /** \brief Set the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a given point.
103  *
104  * \param[in] radius The search radius for x axis.
105  */
106  inline void
107  setTangentRadius (float radius)
108  {
109  tangent_radius_ = radius;
110  }
111 
112  /** \brief Get the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a given point.
113  *
114  * \return The search radius for x axis.
115  */
116  inline float
118  {
119  return (tangent_radius_);
120  }
121 
122  /** \brief Set the percentage of the search tangent radius after which a point is considered part of the support.
123  *
124  * \param[in] margin_thresh the percentage of the search tangent radius after which a point is considered part of the support.
125  */
126  inline void
127  setMarginThresh (float margin_thresh)
128  {
129  margin_thresh_ = margin_thresh;
130  }
131 
132  /** \brief Get the percentage of the search tangent radius after which a point is considered part of the support.
133  *
134  * \return The percentage of the search tangent radius after which a point is considered part of the support.
135  */
136  inline float
138  {
139  return (margin_thresh_);
140  }
141 
142 
143  /** \brief Set min number of neighbours required for the computation of Z axis.
144  *
145  * \param[in] min_neighbors_for_normal_axis min number of neighbours required for the computation of Z axis.
146  */
147  inline void
148  setMinNeighboursForNormalAxis (int min_neighbors_for_normal_axis)
149  {
150  min_neighbors_for_normal_axis_ = min_neighbors_for_normal_axis;
151  }
152 
153  /** \brief Get min number of neighbours required for the computation of Z axis.
154  *
155  * \return min number of neighbours required for the computation of Z axis.
156  */
157  inline int
159  {
160  return (min_neighbors_for_normal_axis_);
161  }
162 
163 
164  /** \brief Set min number of neighbours required for the computation of X axis.
165  *
166  * \param[in] min_neighbors_for_tangent_axis min number of neighbours required for the computation of X axis.
167  */
168  inline void
169  setMinNeighboursForTangentAxis (int min_neighbors_for_tangent_axis)
170  {
171  min_neighbors_for_tangent_axis_ = min_neighbors_for_tangent_axis;
172  }
173 
174  /** \brief Get min number of neighbours required for the computation of X axis.
175  *
176  * \return min number of neighbours required for the computation of X axis.
177  */
178  inline int
180  {
181  return (min_neighbors_for_tangent_axis_);
182  }
183 
184 
185  /** \brief Provide a pointer to the dataset used for the estimation of X axis.
186  * As the estimation of x axis is negligibly affected by surface downsampling,
187  * this method lets to consider a downsampled version of surface_ in the estimation of x axis.
188  * This is optional, if this is not set, it will only use the data in the
189  * surface_ cloud to estimate the x axis.
190  * \param[in] cloud a pointer to a PointCloud
191  */
192  inline void
194  {
195  sampled_surface_ = cloud;
196  fake_sampled_surface_ = false;
197  }
198 
199  /** \brief Get a pointer to the sampled_surface_ cloud dataset. */
200  inline const PointCloudInConstPtr&
202  {
203  return (sampled_surface_);
204  }
205 
206  /** \brief Provide a pointer to the search object linked to sampled_surface.
207  * \param[in] tree a pointer to the spatial search object linked to sampled_surface.
208  */
209  inline void
210  setSearchMethodForSampledSurface (const KdTreePtr &tree) { sampled_tree_ = tree; }
211 
212  /** \brief Get a pointer to the search method used for the estimation of x axis. */
213  inline const KdTreePtr&
215  {
216  return (sampled_tree_);
217  }
218 
219  /** \brief Get the signed distances of the highest points from the fitted planes. */
220  inline const std::vector<SignedDistanceT> &
222  {
223  return (signed_distances_from_highest_points_);
224  }
225 
226  protected:
227  /** \brief This method should get called before starting the actual computation. */
228  bool
229  initCompute () override;
230 
231  /** \brief This method should get called after the actual computation is ended. */
232  bool
233  deinitCompute () override;
234 
235  /** \brief Estimate the LRF descriptor for a given point based on its spatial neighborhood of 3D points with normals
236  * \param[in] index the index of the point in input_
237  * \param[out] lrf the resultant local reference frame
238  * \return signed distance of the highest point from the fitted plane. Max if the lrf is not computable.
239  */
240  SignedDistanceT
241  computePointLRF (const int index, Eigen::Matrix3f &lrf);
242 
243  /** \brief Abstract feature estimation method.
244  * \param[out] output the resultant features
245  */
246  void
247  computeFeature (PointCloudOut &output) override;
248 
249 
250  private:
251  /** \brief Radius used to find tangent axis. */
252  float tangent_radius_{0.0f};
253 
254  /** \brief Threshold that define if a support point is near the margins. */
255  float margin_thresh_{0.85f};
256 
257  /** \brief Min number of neighbours required for the computation of Z axis. Otherwise, feature point normal is used. */
258  int min_neighbors_for_normal_axis_{6};
259 
260  /** \brief Min number of neighbours required for the computation of X axis. Otherwise, a random X axis is set */
261  int min_neighbors_for_tangent_axis_{6};
262 
263  /** \brief An input point cloud describing the surface that is to be used
264  * for nearest neighbor searches for the estimation of X axis.
265  */
266  PointCloudInConstPtr sampled_surface_;
267 
268  /** \brief A pointer to the spatial search object used for the estimation of X axis. */
269  KdTreePtr sampled_tree_;
270 
271  /** \brief Class for normal estimation. */
272  NormalEstimation<PointInT, PointNT> normal_estimation_;
273 
274  /** \brief Signed distances of the highest points from the fitted planes.*/
275  std::vector<SignedDistanceT> signed_distances_from_highest_points_;
276 
277  /** \brief If no sampled_surface_ is given, we use surface_ as the sampled surface. */
278  bool fake_sampled_surface_{false};
279 
280  };
281 
282 }
283 
284 #ifdef PCL_NO_PRECOMPILE
285 #include <pcl/features/impl/flare.hpp>
286 #endif
FLARELocalReferenceFrameEstimation implements the Fast LocAl Reference framE algorithm for local refe...
Definition: flare.h:65
FLARELocalReferenceFrameEstimation()
Constructor.
Definition: flare.h:92
int getMinNeighboursForNormalAxis() const
Get min number of neighbours required for the computation of Z axis.
Definition: flare.h:158
void setMarginThresh(float margin_thresh)
Set the percentage of the search tangent radius after which a point is considered part of the support...
Definition: flare.h:127
const std::vector< SignedDistanceT > & getSignedDistancesFromHighestPoints() const
Get the signed distances of the highest points from the fitted planes.
Definition: flare.h:221
const PointCloudInConstPtr & getSearchSampledSurface() const
Get a pointer to the sampled_surface_ cloud dataset.
Definition: flare.h:201
bool deinitCompute() override
This method should get called after the actual computation is ended.
Definition: flare.hpp:91
void setSearchMethodForSampledSurface(const KdTreePtr &tree)
Provide a pointer to the search object linked to sampled_surface.
Definition: flare.h:210
shared_ptr< const FLARELocalReferenceFrameEstimation< PointInT, PointNT, PointOutT > > ConstPtr
Definition: flare.h:88
void computeFeature(PointCloudOut &output) override
Abstract feature estimation method.
Definition: flare.hpp:233
float getMarginThresh() const
Get the percentage of the search tangent radius after which a point is considered part of the support...
Definition: flare.h:137
void setTangentRadius(float radius)
Set the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a...
Definition: flare.h:107
float getTangentRadius() const
Get the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a...
Definition: flare.h:117
int getMinNeighboursForTangentAxis() const
Get min number of neighbours required for the computation of X axis.
Definition: flare.h:179
bool initCompute() override
This method should get called before starting the actual computation.
Definition: flare.hpp:47
SignedDistanceT computePointLRF(const int index, Eigen::Matrix3f &lrf)
Estimate the LRF descriptor for a given point based on its spatial neighborhood of 3D points with nor...
Definition: flare.hpp:110
void setMinNeighboursForNormalAxis(int min_neighbors_for_normal_axis)
Set min number of neighbours required for the computation of Z axis.
Definition: flare.h:148
void setMinNeighboursForTangentAxis(int min_neighbors_for_tangent_axis)
Set min number of neighbours required for the computation of X axis.
Definition: flare.h:169
const KdTreePtr & getSearchMethodForSampledSurface() const
Get a pointer to the search method used for the estimation of x axis.
Definition: flare.h:214
void setSearchSampledSurface(const PointCloudInConstPtr &cloud)
Provide a pointer to the dataset used for the estimation of X axis.
Definition: flare.h:193
typename PointCloudSignedDistance::Ptr PointCloudSignedDistancePtr
Definition: flare.h:85
shared_ptr< FLARELocalReferenceFrameEstimation< PointInT, PointNT, PointOutT > > Ptr
Definition: flare.h:87
Feature represents the base feature class.
Definition: feature.h:107
std::string feature_name_
The feature name.
Definition: feature.h:220
typename KdTree::Ptr KdTreePtr
Definition: feature.h:118
typename PointCloudIn::ConstPtr PointCloudInConstPtr
Definition: feature.h:122
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:413
Defines all the PCL implemented PointT point type structures.