Point Cloud Library (PCL)  1.9.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/pcl_macros.h>
41 #include <pcl/point_cloud.h>
42 #include <pcl/point_types.h>
43 #include <pcl/keypoints/keypoint.h>
44 
45 namespace pcl {
46 
47 // Forward declarations
48 class RangeImage;
49 class RangeImageBorderExtractor;
50 
51 /** \brief @b NARF (Normal Aligned Radial Feature) keypoints. Input is a range image,
52  * output the indices of the keypoints
53  * See B. Steder, R. B. Rusu, K. Konolige, and W. Burgard
54  * Point Feature Extraction on 3D Range Scans Taking into Account Object Boundaries
55  * In Proc. of the IEEE Int. Conf. on Robotics &Automation (ICRA). 2011.
56  * \author Bastian Steder
57  * \ingroup keypoints
58  */
59 class PCL_EXPORTS NarfKeypoint : public Keypoint<PointWithRange, int>
60 {
61  public:
62  typedef boost::shared_ptr<NarfKeypoint> Ptr;
63  typedef boost::shared_ptr<const NarfKeypoint> ConstPtr;
64 
65  // =====TYPEDEFS=====
67 
69 
70  // =====PUBLIC STRUCTS=====
71  //! Parameters used in this class
72  struct Parameters
73  {
74  Parameters() : support_size(-1.0f), max_no_of_interest_points(-1), min_distance_between_interest_points(0.25f),
75  optimal_distance_to_high_surface_change(0.25), min_interest_value(0.45f),
76  min_surface_change_score(0.2f), optimal_range_image_patch_size(10),
77  distance_for_additional_points(0.0f), add_points_on_straight_edges(false),
78  do_non_maximum_suppression(true), no_of_polynomial_approximations_per_point(0),
79  max_no_of_threads(1), use_recursive_scale_reduction(false),
80  calculate_sparse_interest_image(true) {}
81 
82  float support_size; //!< This defines the area 'covered' by an interest point (in meters)
83  int max_no_of_interest_points; //!< The maximum number of interest points that will be returned
84  float min_distance_between_interest_points; /**< Minimum distance between maximas
85  * (this is a factor for support_size, i.e. the distance is
86  * min_distance_between_interest_points*support_size) */
87  float optimal_distance_to_high_surface_change; /**< The distance we want keep between keypoints and areas
88  * of high surface change
89  * (this is a factor for support_size, i.e., the distance is
90  * optimal_distance_to_high_surface_change*support_size) */
91  float min_interest_value; //!< The minimum value to consider a point as an interest point
92  float min_surface_change_score; //!< The minimum value of the surface change score to consider a point
93  int optimal_range_image_patch_size; /**< The size (in pixels) of the image patches from which the interest value
94  * should be computed. This influences, which range image is selected from
95  * the scale space to compute the interest value of a pixel at a certain
96  * distance. */
97  // TODO:
98  float distance_for_additional_points; /**< All points in this distance to a found maximum, that
99  * are above min_interest_value are also added as interest points
100  * (this is a factor for support_size, i.e. the distance is
101  * distance_for_additional_points*support_size) */
102  bool add_points_on_straight_edges; /**< If this is set to true, there will also be interest points on
103  * straight edges, e.g., just indicating an area of high surface change */
104  bool do_non_maximum_suppression; /**< If this is set to false there will be much more points
105  * (can be used to spread points over the whole scene
106  * (combined with a low min_interest_value)) */
107  bool no_of_polynomial_approximations_per_point; /**< If this is >0, the exact position of the interest point is
108  determined using bivariate polynomial approximations of the
109  interest values of the area. */
110  int max_no_of_threads; //!< The maximum number of threads this code is allowed to use with OPNEMP
111  bool use_recursive_scale_reduction; /**< Try to decrease runtime by extracting interest points at lower reolution
112  * in areas that contain enough points, i.e., have lower range. */
113  bool calculate_sparse_interest_image; /**< Use some heuristics to decide which areas of the interest image
114  can be left out to improve the runtime. */
115  };
116 
117  // =====CONSTRUCTOR & DESTRUCTOR=====
118  NarfKeypoint (RangeImageBorderExtractor* range_image_border_extractor=NULL, float support_size=-1.0f);
119  virtual ~NarfKeypoint ();
120 
121  // =====PUBLIC METHODS=====
122  //! Erase all data calculated for the current range image
123  void
124  clearData ();
125 
126  //! Set the RangeImageBorderExtractor member (required)
127  void
128  setRangeImageBorderExtractor (RangeImageBorderExtractor* range_image_border_extractor);
129 
130  //! Get the RangeImageBorderExtractor member
132  getRangeImageBorderExtractor () { return range_image_border_extractor_; }
133 
134  //! Set the RangeImage member of the RangeImageBorderExtractor
135  void
136  setRangeImage (const RangeImage* range_image);
137 
138  /** Extract interest value per image point */
139  float*
140  getInterestImage () { calculateInterestImage(); return interest_image_;}
141 
142  //! Extract maxima from an interest image
143  const ::pcl::PointCloud<InterestPoint>&
144  getInterestPoints () { calculateInterestPoints(); return *interest_points_;}
145 
146  //! Set all points in the image that are interest points to true, the rest to false
147  const std::vector<bool>&
148  getIsInterestPointImage () { calculateInterestPoints(); return is_interest_point_image_;}
149 
150  //! Getter for the parameter struct
151  Parameters&
152  getParameters () { return parameters_;}
153 
154  //! Getter for the range image of range_image_border_extractor_
155  const RangeImage&
156  getRangeImage ();
157 
158  //! Overwrite the compute function of the base class
159  void
160  compute (PointCloudOut& output);
161 
162  protected:
163  // =====PROTECTED METHODS=====
164  void
165  calculateScaleSpace ();
166  void
167  calculateInterestImage ();
168  void
169  calculateCompleteInterestImage ();
170  void
171  calculateSparseInterestImage ();
172  void
173  calculateInterestPoints ();
174  //void
175  //blurInterestImage ();
176  //! Detect key points
177  virtual void
178  detectKeypoints (PointCloudOut& output);
179 
180  // =====PROTECTED MEMBER VARIABLES=====
181  using BaseClass::name_;
186  std::vector<bool> is_interest_point_image_;
187  std::vector<RangeImage*> range_image_scale_space_;
188  std::vector<RangeImageBorderExtractor*> border_extractor_scale_space_;
189  std::vector<float*> interest_image_scale_space_;
190 };
191 
192 /**
193  * \ingroup keypoints
194  */
195 inline std::ostream&
196  operator << (std::ostream& os, const NarfKeypoint::Parameters& p)
197 {
198  os << PVARC(p.support_size) << PVARC(p.min_distance_between_interest_points)
199  << PVARC(p.min_interest_value) << PVARN(p.distance_for_additional_points);
200  return (os);
201 }
202 
203 } // end namespace pcl
Keypoint< PointWithRange, int >::PointCloudOut PointCloudOut
Definition: narf_keypoint.h:68
Parameters used in this class.
Definition: narf_keypoint.h:72
RangeImage is derived from pcl/PointCloud and provides functionalities with focus on situations where...
Definition: range_image.h:54
Extract obstacle borders from range images, meaning positions where there is a transition from foregr...
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:44
bool use_recursive_scale_reduction
Try to decrease runtime by extracting interest points at lower reolution in areas that contain enough...
const ::pcl::PointCloud< InterestPoint > & getInterestPoints()
Extract maxima from an interest image.
const std::vector< bool > & getIsInterestPointImage()
Set all points in the image that are interest points to true, the rest to false.
bool no_of_polynomial_approximations_per_point
If this is >0, the exact position of the interest point is determined using bivariate polynomial appr...
boost::shared_ptr< const NarfKeypoint > ConstPtr
Definition: narf_keypoint.h:63
RangeImageBorderExtractor * range_image_border_extractor_
float min_surface_change_score
The minimum value of the surface change score to consider a point.
Definition: narf_keypoint.h:92
Keypoint< PointWithRange, int > BaseClass
Definition: narf_keypoint.h:66
std::ostream & operator<<(std::ostream &os, const BivariatePolynomialT< real > &p)
Keypoint represents the base class for key points.
Definition: keypoint.h:48
int max_no_of_interest_points
The maximum number of interest points that will be returned.
Definition: narf_keypoint.h:83
float min_distance_between_interest_points
Minimum distance between maximas (this is a factor for support_size, i.e.
Definition: narf_keypoint.h:84
std::vector< RangeImage * > range_image_scale_space_
int optimal_range_image_patch_size
The size (in pixels) of the image patches from which the interest value should be computed...
Definition: narf_keypoint.h:93
float support_size
This defines the area &#39;covered&#39; by an interest point (in meters)
Definition: narf_keypoint.h:82
int max_no_of_threads
The maximum number of threads this code is allowed to use with OPNEMP.
boost::shared_ptr< NarfKeypoint > Ptr
Definition: narf_keypoint.h:62
PointCloud represents the base class in PCL for storing collections of 3D points. ...
std::vector< float * > interest_image_scale_space_
Parameters parameters_
::pcl::PointCloud< InterestPoint > * interest_points_
std::vector< RangeImageBorderExtractor * > border_extractor_scale_space_
bool add_points_on_straight_edges
If this is set to true, there will also be interest points on straight edges, e.g., just indicating an area of high surface change.
float optimal_distance_to_high_surface_change
The distance we want keep between keypoints and areas of high surface change (this is a factor for su...
Definition: narf_keypoint.h:87
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:98
bool do_non_maximum_suppression
If this is set to false there will be much more points (can be used to spread points over the whole s...
NARF (Normal Aligned Radial Feature) keypoints.
Definition: narf_keypoint.h:59
float min_interest_value
The minimum value to consider a point as an interest point.
Definition: narf_keypoint.h:91
Parameters & getParameters()
Getter for the parameter struct.
RangeImageBorderExtractor * getRangeImageBorderExtractor()
Get the RangeImageBorderExtractor member.
float * getInterestImage()
Extract interest value per image point.
std::vector< bool > is_interest_point_image_
bool calculate_sparse_interest_image
Use some heuristics to decide which areas of the interest image can be left out to improve the runtim...