Point Cloud Library (PCL)  1.9.1
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 #ifndef PCL_FLARE_H_
40 #define PCL_FLARE_H_
41 
42 #include <pcl/point_types.h>
43 #include <pcl/features/feature.h>
44 #include <pcl/features/normal_3d.h>
45 
46 
47 namespace pcl
48 {
49 
50  /** \brief FLARELocalReferenceFrameEstimation implements the Fast LocAl Reference framE algorithm
51  * for local reference frame estimation as described here:
52  *
53  * - A. Petrelli, L. Di Stefano,
54  * "A repeatable and efficient canonical reference for surface matching",
55  * 3DimPVT, 2012
56  *
57  * FLARE algorithm is deployed in ReLOC algorithm proposed in:
58  *
59  * Petrelli A., Di Stefano L., "Pairwise registration by local orientation cues", Computer Graphics Forum, 2015.
60  *
61  * \author Alioscia Petrelli
62  * \ingroup features
63  */
64  template<typename PointInT, typename PointNT, typename PointOutT = ReferenceFrame, typename SignedDistanceT = float>
65  class FLARELocalReferenceFrameEstimation : public FeatureFromNormals<PointInT, PointNT, PointOutT>
66  {
67  protected:
77 
80 
82 
84 
87 
88  typedef boost::shared_ptr<FLARELocalReferenceFrameEstimation<PointInT, PointNT, PointOutT> > Ptr;
89  typedef boost::shared_ptr<const FLARELocalReferenceFrameEstimation<PointInT, PointNT, PointOutT> > ConstPtr;
90 
91  public:
92  /** \brief Constructor. */
94  tangent_radius_ (0.0f),
95  margin_thresh_ (0.85f),
96  min_neighbors_for_normal_axis_ (6),
97  min_neighbors_for_tangent_axis_ (6),
98  sampled_surface_ (),
99  sampled_tree_ (),
100  fake_sampled_surface_ (false)
101  {
102  feature_name_ = "FLARELocalReferenceFrameEstimation";
103  }
104 
105  //Getters/Setters
106 
107  /** \brief Set the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a given point.
108  *
109  * \param[in] radius The search radius for x axis.
110  */
111  inline void
112  setTangentRadius (float radius)
113  {
114  tangent_radius_ = radius;
115  }
116 
117  /** \brief Get the maximum distance of the points used to estimate the x_axis of the FLARE Reference Frame for a given point.
118  *
119  * \return The search radius for x axis.
120  */
121  inline float
123  {
124  return (tangent_radius_);
125  }
126 
127  /** \brief Set the percentage of the search tangent radius after which a point is considered part of the support.
128  *
129  * \param[in] margin_thresh the percentage of the search tangent radius after which a point is considered part of the support.
130  */
131  inline void
132  setMarginThresh (float margin_thresh)
133  {
134  margin_thresh_ = margin_thresh;
135  }
136 
137  /** \brief Get the percentage of the search tangent radius after which a point is considered part of the support.
138  *
139  * \return The percentage of the search tangent radius after which a point is considered part of the support.
140  */
141  inline float
143  {
144  return (margin_thresh_);
145  }
146 
147 
148  /** \brief Set min number of neighbours required for the computation of Z axis.
149  *
150  * \param[in] min_neighbors_for_normal_axis min number of neighbours required for the computation of Z axis.
151  */
152  inline void
153  setMinNeighboursForNormalAxis (int min_neighbors_for_normal_axis)
154  {
155  min_neighbors_for_normal_axis_ = min_neighbors_for_normal_axis;
156  }
157 
158  /** \brief Get min number of neighbours required for the computation of Z axis.
159  *
160  * \return min number of neighbours required for the computation of Z axis.
161  */
162  inline int
164  {
165  return (min_neighbors_for_normal_axis_);
166  }
167 
168 
169  /** \brief Set min number of neighbours required for the computation of X axis.
170  *
171  * \param[in] min_neighbors_for_tangent_axis min number of neighbours required for the computation of X axis.
172  */
173  inline void
174  setMinNeighboursForTangentAxis (int min_neighbors_for_tangent_axis)
175  {
176  min_neighbors_for_tangent_axis_ = min_neighbors_for_tangent_axis;
177  }
178 
179  /** \brief Get min number of neighbours required for the computation of X axis.
180  *
181  * \return min number of neighbours required for the computation of X axis.
182  */
183  inline int
185  {
186  return (min_neighbors_for_tangent_axis_);
187  }
188 
189 
190  /** \brief Provide a pointer to the dataset used for the estimation of X axis.
191  * As the estimation of x axis is negligibly affected by surface downsampling,
192  * this method lets to consider a downsampled version of surface_ in the estimation of x axis.
193  * This is optional, if this is not set, it will only use the data in the
194  * surface_ cloud to estimate the x axis.
195  * \param[in] cloud a pointer to a PointCloud
196  */
197  inline void
198  setSearchSampledSurface(const PointCloudInConstPtr &cloud)
199  {
200  sampled_surface_ = cloud;
201  fake_sampled_surface_ = false;
202  }
203 
204  /** \brief Get a pointer to the sampled_surface_ cloud dataset. */
205  inline const PointCloudInConstPtr&
207  {
208  return (sampled_surface_);
209  }
210 
211  /** \brief Provide a pointer to the search object linked to sampled_surface.
212  * \param[in] tree a pointer to the spatial search object linked to sampled_surface.
213  */
214  inline void
215  setSearchMethodForSampledSurface (const KdTreePtr &tree) { sampled_tree_ = tree; }
216 
217  /** \brief Get a pointer to the search method used for the extimation of x axis. */
218  inline const KdTreePtr&
220  {
221  return (sampled_tree_);
222  }
223 
224  /** \brief Get the signed distances of the highest points from the fitted planes. */
225  inline const std::vector<SignedDistanceT> &
227  {
228  return (signed_distances_from_highest_points_);
229  }
230 
231  protected:
232  /** \brief This method should get called before starting the actual computation. */
233  virtual bool
234  initCompute ();
235 
236  /** \brief This method should get called after the actual computation is ended. */
237  virtual bool
238  deinitCompute ();
239 
240  /** \brief Estimate the LRF descriptor for a given point based on its spatial neighborhood of 3D points with normals
241  * \param[in] index the index of the point in input_
242  * \param[out] lrf the resultant local reference frame
243  * \return signed distance of the highest point from the fitted plane. Max if the lrf is not computable.
244  */
245  SignedDistanceT
246  computePointLRF (const int index, Eigen::Matrix3f &lrf);
247 
248  /** \brief Abstract feature estimation method.
249  * \param[out] output the resultant features
250  */
251  virtual void
252  computeFeature (PointCloudOut &output);
253 
254 
255  private:
256  /** \brief Radius used to find tangent axis. */
257  float tangent_radius_;
258 
259  /** \brief Threshold that define if a support point is near the margins. */
260  float margin_thresh_;
261 
262  /** \brief Min number of neighbours required for the computation of Z axis. Otherwise, feature point normal is used. */
263  int min_neighbors_for_normal_axis_;
264 
265  /** \brief Min number of neighbours required for the computation of X axis. Otherwise, a random X axis is set */
266  int min_neighbors_for_tangent_axis_;
267 
268  /** \brief An input point cloud describing the surface that is to be used
269  * for nearest neighbor searches for the estimation of X axis.
270  */
271  PointCloudInConstPtr sampled_surface_;
272 
273  /** \brief A pointer to the spatial search object used for the estimation of X axis. */
274  KdTreePtr sampled_tree_;
275 
276  /** \brief Class for normal estimation. */
277  NormalEstimation<PointInT, PointNT> normal_estimation_;
278 
279  /** \brief Signed distances of the highest points from the fitted planes.*/
280  std::vector<SignedDistanceT> signed_distances_from_highest_points_;
281 
282  /** \brief If no sampled_surface_ is given, we use surface_ as the sampled surface. */
283  bool fake_sampled_surface_;
284 
285  };
286 
287 }
288 
289 #ifdef PCL_NO_PRECOMPILE
290 #include <pcl/features/impl/flare.hpp>
291 #endif
292 
293 #endif //#ifndef PCL_FLARE_H_
pcl
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
point_types.h
pcl::PointCloud::Ptr
boost::shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:428
pcl::NormalEstimation< PointInT, PointNT >
pcl::FLARELocalReferenceFrameEstimation::setMarginThresh
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:132
pcl::FLARELocalReferenceFrameEstimation::initCompute
virtual bool initCompute()
This method should get called before starting the actual computation.
Definition: flare.hpp:47
pcl::FLARELocalReferenceFrameEstimation::Ptr
boost::shared_ptr< FLARELocalReferenceFrameEstimation< PointInT, PointNT, PointOutT > > Ptr
Definition: flare.h:88
pcl::FLARELocalReferenceFrameEstimation::setMinNeighboursForTangentAxis
void setMinNeighboursForTangentAxis(int min_neighbors_for_tangent_axis)
Set min number of neighbours required for the computation of X axis.
Definition: flare.h:174
pcl::FLARELocalReferenceFrameEstimation::ConstPtr
boost::shared_ptr< const FLARELocalReferenceFrameEstimation< PointInT, PointNT, PointOutT > > ConstPtr
Definition: flare.h:89
pcl::FLARELocalReferenceFrameEstimation::getMarginThresh
float getMarginThresh() const
Get the percentage of the search tangent radius after which a point is considered part of the support...
Definition: flare.h:142
pcl::PointCloud< PointInT >
pcl::FLARELocalReferenceFrameEstimation::PointCloudSignedDistancePtr
PointCloudSignedDistance::Ptr PointCloudSignedDistancePtr
Definition: flare.h:86
pcl::FLARELocalReferenceFrameEstimation::setSearchSampledSurface
void setSearchSampledSurface(const PointCloudInConstPtr &cloud)
Provide a pointer to the dataset used for the estimation of X axis.
Definition: flare.h:198
pcl::FLARELocalReferenceFrameEstimation::computeFeature
virtual void computeFeature(PointCloudOut &output)
Abstract feature estimation method.
Definition: flare.hpp:231
pcl::FLARELocalReferenceFrameEstimation::computePointLRF
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
pcl::FLARELocalReferenceFrameEstimation::getMinNeighboursForTangentAxis
int getMinNeighboursForTangentAxis() const
Get min number of neighbours required for the computation of X axis.
Definition: flare.h:184
pcl::FLARELocalReferenceFrameEstimation::setSearchMethodForSampledSurface
void setSearchMethodForSampledSurface(const KdTreePtr &tree)
Provide a pointer to the search object linked to sampled_surface.
Definition: flare.h:215
pcl::Feature::KdTreePtr
pcl::search::Search< PointInT >::Ptr KdTreePtr
Definition: feature.h:117
pcl::FLARELocalReferenceFrameEstimation
FLARELocalReferenceFrameEstimation implements the Fast LocAl Reference framE algorithm for local refe...
Definition: flare.h:65
pcl::FLARELocalReferenceFrameEstimation::setMinNeighboursForNormalAxis
void setMinNeighboursForNormalAxis(int min_neighbors_for_normal_axis)
Set min number of neighbours required for the computation of Z axis.
Definition: flare.h:153
pcl::FeatureFromNormals
Definition: feature.h:310
pcl::FLARELocalReferenceFrameEstimation::getMinNeighboursForNormalAxis
int getMinNeighboursForNormalAxis() const
Get min number of neighbours required for the computation of Z axis.
Definition: flare.h:163
pcl::FLARELocalReferenceFrameEstimation::getSearchMethodForSampledSurface
const KdTreePtr & getSearchMethodForSampledSurface() const
Get a pointer to the search method used for the extimation of x axis.
Definition: flare.h:219
pcl::FLARELocalReferenceFrameEstimation::deinitCompute
virtual bool deinitCompute()
This method should get called after the actual computation is ended.
Definition: flare.hpp:91
pcl::FLARELocalReferenceFrameEstimation::setTangentRadius
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:112
pcl::FLARELocalReferenceFrameEstimation::getTangentRadius
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:122
pcl::Feature< PointInT, ReferenceFrame >::feature_name_
std::string feature_name_
The feature name.
Definition: feature.h:222
pcl::FLARELocalReferenceFrameEstimation::PointCloudSignedDistance
pcl::PointCloud< SignedDistanceT > PointCloudSignedDistance
Definition: flare.h:85
pcl::Feature::PointCloudInConstPtr
PointCloudIn::ConstPtr PointCloudInConstPtr
Definition: feature.h:121
pcl::FLARELocalReferenceFrameEstimation::FLARELocalReferenceFrameEstimation
FLARELocalReferenceFrameEstimation()
Constructor.
Definition: flare.h:93
pcl::FLARELocalReferenceFrameEstimation::getSignedDistancesFromHighestPoints
const std::vector< SignedDistanceT > & getSignedDistancesFromHighestPoints() const
Get the signed distances of the highest points from the fitted planes.
Definition: flare.h:226
pcl::FLARELocalReferenceFrameEstimation::getSearchSampledSurface
const PointCloudInConstPtr & getSearchSampledSurface() const
Get a pointer to the sampled_surface_ cloud dataset.
Definition: flare.h:206
pcl::Feature
Feature represents the base feature class.
Definition: feature.h:105