Point Cloud Library (PCL)  1.11.0
narf.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010, 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/memory.h>
42 #include <pcl/pcl_macros.h>
43 #include <pcl/features/eigen.h>
44 #include <pcl/common/common_headers.h>
45 #include <pcl/point_representation.h>
46 
47 namespace pcl
48 {
49  // Forward declarations
50  class RangeImage;
51  struct InterestPoint;
52 
53 #define NARF_DEFAULT_SURFACE_PATCH_PIXEL_SIZE 10
54 
55  /**
56  * \brief NARF (Normal Aligned Radial Features) is a point feature descriptor type for 3D data.
57  * Please refer to pcl/features/narf_descriptor.h if you want the class derived from pcl Feature.
58  * See B. Steder, R. B. Rusu, K. Konolige, and W. Burgard
59  * Point Feature Extraction on 3D Range Scans Taking into Account Object Boundaries
60  * In Proc. of the IEEE Int. Conf. on Robotics &Automation (ICRA). 2011.
61  * \author Bastian Steder
62  * \ingroup features
63  */
65  {
66  public:
67  // =====CONSTRUCTOR & DESTRUCTOR=====
68  //! Constructor
69  Narf();
70  //! Copy Constructor
71  Narf(const Narf& other);
72  //! Destructor
73  ~Narf();
74 
75  // =====Operators=====
76  //! Assignment operator
77  const Narf& operator=(const Narf& other);
78 
79  // =====STATIC=====
80  /** The maximum number of openmp threads that can be used in this class */
81  static int max_no_of_threads;
82 
83  /** Add features extracted at the given interest point and add them to the list */
84  static void
85  extractFromRangeImageAndAddToList (const RangeImage& range_image, const Eigen::Vector3f& interest_point, int descriptor_size,
86  float support_size, bool rotation_invariant, std::vector<Narf*>& feature_list);
87  /** Same as above */
88  static void
89  extractFromRangeImageAndAddToList (const RangeImage& range_image, float image_x, float image_y, int descriptor_size,
90  float support_size, bool rotation_invariant, std::vector<Narf*>& feature_list);
91  /** Get a list of features from the given interest points. */
92  static void
93  extractForInterestPoints (const RangeImage& range_image, const PointCloud<InterestPoint>& interest_points,
94  int descriptor_size, float support_size, bool rotation_invariant, std::vector<Narf*>& feature_list);
95  /** Extract an NARF for every point in the range image. */
96  static void
97  extractForEveryRangeImagePointAndAddToList (const RangeImage& range_image, int descriptor_size, float support_size,
98  bool rotation_invariant, std::vector<Narf*>& feature_list);
99 
100  // =====PUBLIC METHODS=====
101  /** Method to extract a NARF feature from a certain 3D point using a range image.
102  * pose determines the coordinate system of the feature, whereas it transforms a point from the world into the feature system.
103  * This means the interest point at which the feature is extracted will be the inverse application of pose onto (0,0,0).
104  * descriptor_size_ determines the size of the descriptor,
105  * support_size determines the support size of the feature, meaning the size in the world it covers */
106  bool
107  extractFromRangeImage (const RangeImage& range_image, const Eigen::Affine3f& pose, int descriptor_size, float support_size,
108  int surface_patch_world_size=NARF_DEFAULT_SURFACE_PATCH_PIXEL_SIZE);
109 
110  //! Same as above, but determines the transformation from the surface in the range image
111  bool
112  extractFromRangeImage (const RangeImage& range_image, float x, float y, int descriptor_size, float support_size);
113 
114  //! Same as above
115  bool
116  extractFromRangeImage (const RangeImage& range_image, const InterestPoint& interest_point, int descriptor_size, float support_size);
117 
118  //! Same as above
119  bool
120  extractFromRangeImage (const RangeImage& range_image, const Eigen::Vector3f& interest_point, int descriptor_size, float support_size);
121 
122  /** Same as above, but using the rotational invariant version by choosing the best extracted rotation around the normal.
123  * Use extractFromRangeImageAndAddToList if you want to enable the system to return multiple features with different rotations. */
124  bool
125  extractFromRangeImageWithBestRotation (const RangeImage& range_image, const Eigen::Vector3f& interest_point,
126  int descriptor_size, float support_size);
127 
128  /* Get the dominant rotations of the current descriptor
129  * \param rotations the returned rotations
130  * \param strength values describing how pronounced the corresponding rotations are
131  */
132  void
133  getRotations (std::vector<float>& rotations, std::vector<float>& strengths) const;
134 
135  /* Get the feature with a different rotation around the normal
136  * You are responsible for deleting the new features!
137  * \param range_image the source from which the feature is extracted
138  * \param rotations list of angles (in radians)
139  * \param rvps returned features
140  */
141  void
142  getRotatedVersions (const RangeImage& range_image, const std::vector<float>& rotations, std::vector<Narf*>& features) const;
143 
144  //! Calculate descriptor distance, value in [0,1] with 0 meaning identical and 1 every cell above maximum distance
145  inline float
146  getDescriptorDistance (const Narf& other) const;
147 
148  //! How many points on each beam of the gradient star are used to calculate the descriptor?
149  inline int
150  getNoOfBeamPoints () const { return (static_cast<int> (pcl_lrint (std::ceil (0.5f * float (surface_patch_pixel_size_))))); }
151 
152  //! Copy the descriptor and pose to the point struct Narf36
153  inline void
154  copyToNarf36 (Narf36& narf36) const;
155 
156  /** Write to file */
157  void
158  saveBinary (const std::string& filename) const;
159  /** Write to output stream */
160  void
161  saveBinary (std::ostream& file) const;
162 
163  /** Read from file */
164  void
165  loadBinary (const std::string& filename);
166  /** Read from input stream */
167  void
168  loadBinary (std::istream& file);
169 
170  //! Create the descriptor from the already set other members
171  bool
172  extractDescriptor (int descriptor_size);
173 
174  // =====GETTERS=====
175  //! Getter (const) for the descriptor
176  inline const float*
177  getDescriptor () const { return descriptor_;}
178  //! Getter for the descriptor
179  inline float*
180  getDescriptor () { return descriptor_;}
181  //! Getter (const) for the descriptor length
182  inline const int&
183  getDescriptorSize () const { return descriptor_size_;}
184  //! Getter for the descriptor length
185  inline int&
186  getDescriptorSize () { return descriptor_size_;}
187  //! Getter (const) for the position
188  inline const Eigen::Vector3f&
189  getPosition () const { return position_;}
190  //! Getter for the position
191  inline Eigen::Vector3f&
192  getPosition () { return position_;}
193  //! Getter (const) for the 6DoF pose
194  inline const Eigen::Affine3f&
195  getTransformation () const { return transformation_;}
196  //! Getter for the 6DoF pose
197  inline Eigen::Affine3f&
198  getTransformation () { return transformation_;}
199  //! Getter (const) for the pixel size of the surface patch (only one dimension)
200  inline const int&
201  getSurfacePatchPixelSize () const { return surface_patch_pixel_size_;}
202  //! Getter for the pixel size of the surface patch (only one dimension)
203  inline int&
204  getSurfacePatchPixelSize () { return surface_patch_pixel_size_;}
205  //! Getter (const) for the world size of the surface patch
206  inline const float&
207  getSurfacePatchWorldSize () const { return surface_patch_world_size_;}
208  //! Getter for the world size of the surface patch
209  inline float&
210  getSurfacePatchWorldSize () { return surface_patch_world_size_;}
211  //! Getter (const) for the rotation of the surface patch
212  inline const float&
213  getSurfacePatchRotation () const { return surface_patch_rotation_;}
214  //! Getter for the rotation of the surface patch
215  inline float&
216  getSurfacePatchRotation () { return surface_patch_rotation_;}
217  //! Getter (const) for the surface patch
218  inline const float*
219  getSurfacePatch () const { return surface_patch_;}
220  //! Getter for the surface patch
221  inline float*
222  getSurfacePatch () { return surface_patch_;}
223  //! Method to erase the surface patch and free the memory
224  inline void
225  freeSurfacePatch () { delete[] surface_patch_; surface_patch_=nullptr; surface_patch_pixel_size_=0; }
226 
227  // =====SETTERS=====
228  //! Setter for the descriptor
229  inline void
230  setDescriptor (float* descriptor) { descriptor_ = descriptor;}
231  //! Setter for the surface patch
232  inline void
233  setSurfacePatch (float* surface_patch) { surface_patch_ = surface_patch;}
234 
235  // =====PUBLIC MEMBER VARIABLES=====
236 
237  // =====PUBLIC STRUCTS=====
239  {
240  using PointT = Narf *;
241  FeaturePointRepresentation(int nr_dimensions) { this->nr_dimensions_ = nr_dimensions; }
242  /** \brief Empty destructor */
244  void copyToFloatArray (const PointT& p, float* out) const override { memcpy(out, p->getDescriptor(), sizeof(*p->getDescriptor())*this->nr_dimensions_); }
245  };
246 
247  protected:
248  // =====PROTECTED METHODS=====
249  //! Reset al members to default values and free allocated memory
250  void
251  reset ();
252  //! Create a deep copy of other
253  void
254  deepCopy (const Narf& other);
255  //! Get the surface patch with a blur on it
256  float*
257  getBlurredSurfacePatch (int new_pixel_size, int blur_radius) const;
258 
259  /** Write header to output stream */
260  void
261  saveHeader (std::ostream& file) const;
262  /** Read header from input stream */
263  int
264  loadHeader (std::istream& file) const;
265 
266  // =====PROTECTED STATIC METHODS=====
267  static const std::string
268  getHeaderKeyword () { return "NARF"; }
269 
270  // =====PROTECTED STATIC VARIABLES=====
271  const static int VERSION = 1;
272 
273  // =====PROTECTED MEMBER VARIABLES=====
274  Eigen::Vector3f position_;
275  Eigen::Affine3f transformation_;
280  float* descriptor_;
282 
283  // =====STATIC PROTECTED=====
284 
285  public:
287  };
288 #undef NARF_DEFAULT_SURFACE_PATCH_PIXEL_SIZE
289 
290 } // end namespace pcl
291 
292 #include <pcl/features/impl/narf.hpp>
pcl::Narf::reset
void reset()
Reset al members to default values and free allocated memory.
pcl_macros.h
Defines all the PCL and non-PCL macros used.
pcl
Definition: convolution.h:46
pcl::Narf::getSurfacePatchWorldSize
const float & getSurfacePatchWorldSize() const
Getter (const) for the world size of the surface patch.
Definition: narf.h:207
pcl::Narf::getPosition
Eigen::Vector3f & getPosition()
Getter for the position.
Definition: narf.h:192
pcl::Narf::getRotations
void getRotations(std::vector< float > &rotations, std::vector< float > &strengths) const
pcl::Narf::Narf
Narf(const Narf &other)
Copy Constructor.
pcl::Narf::extractFromRangeImage
bool extractFromRangeImage(const RangeImage &range_image, const Eigen::Vector3f &interest_point, int descriptor_size, float support_size)
Same as above.
pcl::Narf::getHeaderKeyword
static const std::string getHeaderKeyword()
Definition: narf.h:268
pcl::Narf
NARF (Normal Aligned Radial Features) is a point feature descriptor type for 3D data.
Definition: narf.h:65
pcl::Narf::extractForEveryRangeImagePointAndAddToList
static void extractForEveryRangeImagePointAndAddToList(const RangeImage &range_image, int descriptor_size, float support_size, bool rotation_invariant, std::vector< Narf * > &feature_list)
Extract an NARF for every point in the range image.
pcl::Narf::FeaturePointRepresentation::FeaturePointRepresentation
FeaturePointRepresentation(int nr_dimensions)
Definition: narf.h:241
pcl::Narf::loadBinary
void loadBinary(const std::string &filename)
Read from file.
pcl::Narf::loadHeader
int loadHeader(std::istream &file) const
Read header from input stream.
pcl::Narf::transformation_
Eigen::Affine3f transformation_
Definition: narf.h:275
pcl::PointCloud
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition: projection_matrix.h:52
pcl::Narf::getPosition
const Eigen::Vector3f & getPosition() const
Getter (const) for the position.
Definition: narf.h:189
pcl::Narf::descriptor_
float * descriptor_
Definition: narf.h:280
pcl::Narf::getDescriptor
float * getDescriptor()
Getter for the descriptor.
Definition: narf.h:180
pcl::Narf::setSurfacePatch
void setSurfacePatch(float *surface_patch)
Setter for the surface patch.
Definition: narf.h:233
pcl::RangeImage
RangeImage is derived from pcl/PointCloud and provides functionalities with focus on situations where...
Definition: range_image.h:56
pcl::Narf::getSurfacePatchPixelSize
const int & getSurfacePatchPixelSize() const
Getter (const) for the pixel size of the surface patch (only one dimension)
Definition: narf.h:201
pcl::Narf::getSurfacePatchWorldSize
float & getSurfacePatchWorldSize()
Getter for the world size of the surface patch.
Definition: narf.h:210
pcl::Narf::FeaturePointRepresentation
Definition: narf.h:239
pcl::Narf::setDescriptor
void setDescriptor(float *descriptor)
Setter for the descriptor.
Definition: narf.h:230
pcl::Narf::max_no_of_threads
static int max_no_of_threads
The maximum number of openmp threads that can be used in this class.
Definition: narf.h:81
pcl::Narf::extractFromRangeImageAndAddToList
static void extractFromRangeImageAndAddToList(const RangeImage &range_image, const Eigen::Vector3f &interest_point, int descriptor_size, float support_size, bool rotation_invariant, std::vector< Narf * > &feature_list)
Add features extracted at the given interest point and add them to the list.
pcl::PointRepresentation
PointRepresentation provides a set of methods for converting a point structs/object into an n-dimensi...
Definition: point_representation.h:60
pcl::Narf::extractFromRangeImage
bool extractFromRangeImage(const RangeImage &range_image, const Eigen::Affine3f &pose, int descriptor_size, float support_size, int surface_patch_world_size=NARF_DEFAULT_SURFACE_PATCH_PIXEL_SIZE)
Method to extract a NARF feature from a certain 3D point using a range image.
pcl::Narf::getDescriptor
const float * getDescriptor() const
Getter (const) for the descriptor.
Definition: narf.h:177
pcl::Narf::getSurfacePatchRotation
float & getSurfacePatchRotation()
Getter for the rotation of the surface patch.
Definition: narf.h:216
pcl::Narf::getSurfacePatch
const float * getSurfacePatch() const
Getter (const) for the surface patch.
Definition: narf.h:219
pcl::Narf::saveBinary
void saveBinary(const std::string &filename) const
Write to file.
pcl::Narf::getSurfacePatchRotation
const float & getSurfacePatchRotation() const
Getter (const) for the rotation of the surface patch.
Definition: narf.h:213
pcl::Narf::operator=
const Narf & operator=(const Narf &other)
Assignment operator.
PCL_MAKE_ALIGNED_OPERATOR_NEW
#define PCL_MAKE_ALIGNED_OPERATOR_NEW
Macro to signal a class requires a custom allocator.
Definition: memory.h:63
pcl::Narf::FeaturePointRepresentation::copyToFloatArray
void copyToFloatArray(const PointT &p, float *out) const override
Definition: narf.h:244
pcl::InterestPoint
A point structure representing an interest point with Euclidean xyz coordinates, and an interest valu...
Definition: point_types.hpp:779
pcl::Narf::deepCopy
void deepCopy(const Narf &other)
Create a deep copy of other.
pcl::Narf::extractForInterestPoints
static void extractForInterestPoints(const RangeImage &range_image, const PointCloud< InterestPoint > &interest_points, int descriptor_size, float support_size, bool rotation_invariant, std::vector< Narf * > &feature_list)
Get a list of features from the given interest points.
pcl::Narf::Narf
Narf()
Constructor.
pcl::Narf::saveBinary
void saveBinary(std::ostream &file) const
Write to output stream.
pcl::Narf::surface_patch_
float * surface_patch_
Definition: narf.h:276
pcl::Narf::surface_patch_pixel_size_
int surface_patch_pixel_size_
Definition: narf.h:277
pcl::Narf::saveHeader
void saveHeader(std::ostream &file) const
Write header to output stream.
pcl::Narf::surface_patch_world_size_
float surface_patch_world_size_
Definition: narf.h:278
pcl::Narf::extractFromRangeImageWithBestRotation
bool extractFromRangeImageWithBestRotation(const RangeImage &range_image, const Eigen::Vector3f &interest_point, int descriptor_size, float support_size)
Same as above, but using the rotational invariant version by choosing the best extracted rotation aro...
pcl::Narf::surface_patch_rotation_
float surface_patch_rotation_
Definition: narf.h:279
pcl::Narf36
A point structure representing the Narf descriptor.
Definition: point_types.hpp:1615
pcl::Narf::~Narf
~Narf()
Destructor.
pcl::Narf::FeaturePointRepresentation::~FeaturePointRepresentation
~FeaturePointRepresentation()
Empty destructor.
Definition: narf.h:243
pcl::Narf::getDescriptorSize
const int & getDescriptorSize() const
Getter (const) for the descriptor length.
Definition: narf.h:183
pcl::Narf::position_
Eigen::Vector3f position_
Definition: narf.h:274
pcl::Narf::getDescriptorSize
int & getDescriptorSize()
Getter for the descriptor length.
Definition: narf.h:186
pcl::Narf::getNoOfBeamPoints
int getNoOfBeamPoints() const
How many points on each beam of the gradient star are used to calculate the descriptor?
Definition: narf.h:150
pcl::Narf::freeSurfacePatch
void freeSurfacePatch()
Method to erase the surface patch and free the memory.
Definition: narf.h:225
pcl::Narf::extractFromRangeImageAndAddToList
static void extractFromRangeImageAndAddToList(const RangeImage &range_image, float image_x, float image_y, int descriptor_size, float support_size, bool rotation_invariant, std::vector< Narf * > &feature_list)
Same as above.
pcl::Narf::getBlurredSurfacePatch
float * getBlurredSurfacePatch(int new_pixel_size, int blur_radius) const
Get the surface patch with a blur on it.
pcl::Narf::extractFromRangeImage
bool extractFromRangeImage(const RangeImage &range_image, float x, float y, int descriptor_size, float support_size)
Same as above, but determines the transformation from the surface in the range image.
pcl::Narf::extractDescriptor
bool extractDescriptor(int descriptor_size)
Create the descriptor from the already set other members.
pcl::Narf::getTransformation
const Eigen::Affine3f & getTransformation() const
Getter (const) for the 6DoF pose.
Definition: narf.h:195
pcl::Narf::getTransformation
Eigen::Affine3f & getTransformation()
Getter for the 6DoF pose.
Definition: narf.h:198
pcl_lrint
#define pcl_lrint(x)
Definition: pcl_macros.h:261
pcl::Narf::getRotatedVersions
void getRotatedVersions(const RangeImage &range_image, const std::vector< float > &rotations, std::vector< Narf * > &features) const
pcl::Narf::loadBinary
void loadBinary(std::istream &file)
Read from input stream.
pcl::Narf::descriptor_size_
int descriptor_size_
Definition: narf.h:281
pcl::Narf::getSurfacePatch
float * getSurfacePatch()
Getter for the surface patch.
Definition: narf.h:222
memory.h
Defines functions, macros and traits for allocating and using memory.
PCL_EXPORTS
#define PCL_EXPORTS
Definition: pcl_macros.h:331
pcl::Narf::getSurfacePatchPixelSize
int & getSurfacePatchPixelSize()
Getter for the pixel size of the surface patch (only one dimension)
Definition: narf.h:204
pcl::Narf::extractFromRangeImage
bool extractFromRangeImage(const RangeImage &range_image, const InterestPoint &interest_point, int descriptor_size, float support_size)
Same as above.