Point Cloud Library (PCL)  1.14.1-dev
narf_keypoint.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Copyright (c) 2010, Willow Garage, Inc.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * * Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * * Redistributions in binary form must reproduce the above
14  * copyright notice, this list of conditions and the following
15  * disclaimer in the documentation and/or other materials provided
16  * with the distribution.
17  * * Neither the name of Willow Garage, Inc. nor the names of its
18  * contributors may be used to endorse or promote products derived
19  * from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  */
35 
36 /* \author Bastian Steder */
37 
38 #pragma once
39 
40 #include <pcl/memory.h>
41 #include <pcl/pcl_macros.h>
42 #include <pcl/point_cloud.h>
43 #include <pcl/point_types.h>
44 #include <pcl/keypoints/keypoint.h>
45 
46 namespace pcl {
47 
48 // Forward declarations
49 class RangeImage;
50 class RangeImageBorderExtractor;
51 
52 /** \brief @b NARF (Normal Aligned Radial Feature) keypoints. Input is a range image,
53  * output the indices of the keypoints
54  * See B. Steder, R. B. Rusu, K. Konolige, and W. Burgard
55  * Point Feature Extraction on 3D Range Scans Taking into Account Object Boundaries
56  * In Proc. of the IEEE Int. Conf. on Robotics &Automation (ICRA). 2011.
57  * \author Bastian Steder
58  * \ingroup keypoints
59  */
60 class PCL_EXPORTS NarfKeypoint : public Keypoint<PointWithRange, int>
61 {
62  public:
63  using Ptr = shared_ptr<NarfKeypoint>;
64  using ConstPtr = shared_ptr<const NarfKeypoint>;
65 
66  // =====TYPEDEFS=====
68 
70 
71  // =====PUBLIC STRUCTS=====
72  //! Parameters used in this class
73  struct Parameters
74  {
75  Parameters() = default;
76 
77  float support_size{-1.0f}; //!< This defines the area 'covered' by an interest point (in meters)
78  int max_no_of_interest_points{-1}; //!< The maximum number of interest points that will be returned
79  float min_distance_between_interest_points{0.25f}; /**< Minimum distance between maximas
80  * (this is a factor for support_size, i.e. the distance is
81  * min_distance_between_interest_points*support_size) */
82  float optimal_distance_to_high_surface_change{0.25}; /**< The distance we want keep between keypoints and areas
83  * of high surface change
84  * (this is a factor for support_size, i.e., the distance is
85  * optimal_distance_to_high_surface_change*support_size) */
86  float min_interest_value{0.45f}; //!< The minimum value to consider a point as an interest point
87  float min_surface_change_score{0.2f}; //!< The minimum value of the surface change score to consider a point
88  int optimal_range_image_patch_size{10}; /**< The size (in pixels) of the image patches from which the interest value
89  * should be computed. This influences, which range image is selected from
90  * the scale space to compute the interest value of a pixel at a certain
91  * distance. */
92  // TODO:
93  float distance_for_additional_points{0.0f}; /**< All points in this distance to a found maximum, that
94  * are above min_interest_value are also added as interest points
95  * (this is a factor for support_size, i.e. the distance is
96  * distance_for_additional_points*support_size) */
97  bool add_points_on_straight_edges{false}; /**< If this is set to true, there will also be interest points on
98  * straight edges, e.g., just indicating an area of high surface change */
99  bool do_non_maximum_suppression{true}; /**< If this is set to false there will be much more points
100  * (can be used to spread points over the whole scene
101  * (combined with a low min_interest_value)) */
102  bool no_of_polynomial_approximations_per_point{false}; /**< If this is >0, the exact position of the interest point is
103  determined using bivariate polynomial approximations of the
104  interest values of the area. */
105  int max_no_of_threads{1}; //!< The maximum number of threads this code is allowed to use with OPNEMP
106  bool use_recursive_scale_reduction{false}; /**< Try to decrease runtime by extracting interest points at lower reolution
107  * in areas that contain enough points, i.e., have lower range. */
108  bool calculate_sparse_interest_image{true}; /**< Use some heuristics to decide which areas of the interest image
109  can be left out to improve the runtime. */
110  };
111 
112  // =====CONSTRUCTOR & DESTRUCTOR=====
113  NarfKeypoint (RangeImageBorderExtractor* range_image_border_extractor=nullptr, float support_size=-1.0f);
114  ~NarfKeypoint () override;
115 
116  // =====PUBLIC METHODS=====
117  //! Erase all data calculated for the current range image
118  void
120 
121  //! Set the RangeImageBorderExtractor member (required)
122  void
124 
125  //! Get the RangeImageBorderExtractor member
127  getRangeImageBorderExtractor () { return range_image_border_extractor_; }
128 
129  //! Set the RangeImage member of the RangeImageBorderExtractor
130  void
131  setRangeImage (const RangeImage* range_image);
132 
133  /** Extract interest value per image point */
134  float*
135  getInterestImage () { calculateInterestImage(); return interest_image_;}
136 
137  //! Extract maxima from an interest image
138  const ::pcl::PointCloud<InterestPoint>&
139  getInterestPoints () { calculateInterestPoints(); return *interest_points_;}
140 
141  //! Set all points in the image that are interest points to true, the rest to false
142  const std::vector<bool>&
143  getIsInterestPointImage () { calculateInterestPoints(); return is_interest_point_image_;}
144 
145  //! Getter for the parameter struct
146  Parameters&
147  getParameters () { return parameters_;}
148 
149  //! Getter for the range image of range_image_border_extractor_
150  const RangeImage&
152 
153  //! Overwrite the compute function of the base class
154  void
156 
157  protected:
158  // =====PROTECTED METHODS=====
159  void
161  void
163  void
165  void
167  void
169  //void
170  //blurInterestImage ();
171  //! Detect key points
172  void
173  detectKeypoints (PointCloudOut& output) override;
174 
175  // =====PROTECTED MEMBER VARIABLES=====
176  using BaseClass::name_;
179  float* interest_image_{nullptr};
180  ::pcl::PointCloud<InterestPoint>* interest_points_{nullptr};
181  std::vector<bool> is_interest_point_image_;
182  std::vector<RangeImage*> range_image_scale_space_;
183  std::vector<RangeImageBorderExtractor*> border_extractor_scale_space_;
184  std::vector<float*> interest_image_scale_space_;
185 };
186 
187 /**
188  * \ingroup keypoints
189  */
190 inline std::ostream&
191  operator << (std::ostream& os, const NarfKeypoint::Parameters& p)
192 {
195  return (os);
196 }
197 
198 } // end namespace pcl
Keypoint represents the base class for key points.
Definition: keypoint.h:49
NARF (Normal Aligned Radial Feature) keypoints.
Definition: narf_keypoint.h:61
const RangeImage & getRangeImage()
Getter for the range image of range_image_border_extractor_.
Keypoint< PointWithRange, int >::PointCloudOut PointCloudOut
Definition: narf_keypoint.h:69
Parameters & getParameters()
Getter for the parameter struct.
shared_ptr< NarfKeypoint > Ptr
Definition: narf_keypoint.h:63
void calculateInterestPoints()
const ::pcl::PointCloud< InterestPoint > & getInterestPoints()
Extract maxima from an interest image.
void detectKeypoints(PointCloudOut &output) override
Detect key points.
void compute(PointCloudOut &output)
Overwrite the compute function of the base class.
Parameters parameters_
std::vector< float * > interest_image_scale_space_
void calculateInterestImage()
NarfKeypoint(RangeImageBorderExtractor *range_image_border_extractor=nullptr, float support_size=-1.0f)
void calculateCompleteInterestImage()
void setRangeImage(const RangeImage *range_image)
Set the RangeImage member of the RangeImageBorderExtractor.
void setRangeImageBorderExtractor(RangeImageBorderExtractor *range_image_border_extractor)
Set the RangeImageBorderExtractor member (required)
void clearData()
Erase all data calculated for the current range image.
float * getInterestImage()
Extract interest value per image point.
~NarfKeypoint() override
std::vector< RangeImageBorderExtractor * > border_extractor_scale_space_
shared_ptr< const NarfKeypoint > ConstPtr
Definition: narf_keypoint.h:64
RangeImageBorderExtractor * getRangeImageBorderExtractor()
Get the RangeImageBorderExtractor member.
void calculateSparseInterestImage()
const std::vector< bool > & getIsInterestPointImage()
Set all points in the image that are interest points to true, the rest to false.
std::vector< bool > is_interest_point_image_
void calculateScaleSpace()
RangeImageBorderExtractor * range_image_border_extractor_
std::vector< RangeImage * > range_image_scale_space_
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: point_cloud.h:173
Extract obstacle borders from range images, meaning positions where there is a transition from foregr...
RangeImage is derived from pcl/PointCloud and provides functionalities with focus on situations where...
Definition: range_image.h:55
Defines all the PCL implemented PointT point type structures.
Defines functions, macros and traits for allocating and using memory.
std::ostream & operator<<(std::ostream &os, const BivariatePolynomialT< real > &p)
Defines all the PCL and non-PCL macros used.
#define PVARN(s)
Definition: pcl_macros.h:268
#define PCL_EXPORTS
Definition: pcl_macros.h:323
#define PVARC(s)
Definition: pcl_macros.h:272
Parameters used in this class.
Definition: narf_keypoint.h:74
float min_distance_between_interest_points
Minimum distance between maximas (this is a factor for support_size, i.e.
Definition: narf_keypoint.h:79
float distance_for_additional_points
All points in this distance to a found maximum, that are above min_interest_value are also added as i...
Definition: narf_keypoint.h:93
float min_interest_value
The minimum value to consider a point as an interest point.
Definition: narf_keypoint.h:86
float support_size
This defines the area 'covered' by an interest point (in meters)
Definition: narf_keypoint.h:77