Point Cloud Library (PCL)  1.7.1
boundary.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2011, 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  * $Id$
38  *
39  */
40 
41 #ifndef PCL_BOUNDARY_H_
42 #define PCL_BOUNDARY_H_
43 
44 #include <pcl/features/eigen.h>
45 #include <pcl/features/feature.h>
46 
47 namespace pcl
48 {
49  /** \brief BoundaryEstimation estimates whether a set of points is lying on surface boundaries using an angle
50  * criterion. The code makes use of the estimated surface normals at each point in the input dataset.
51  *
52  * Here's an example for estimating boundary points for a PointXYZ point cloud:
53  * \code
54  * pcl::PointCloud<pcl::PointXYZ>::Ptr cloud (new pcl::PointCloud<pcl::PointXYZ>);
55  * // fill in the cloud data here
56  *
57  * pcl::PointCloud<pcl::Normal>::Ptr normals (new pcl::PointCloud<pcl::Normal>);
58  * // estimate normals and fill in \a normals
59  *
60  * pcl::PointCloud<pcl::Boundary> boundaries;
61  * pcl::BoundaryEstimation<pcl::PointXYZ, pcl::Normal, pcl::Boundary> est;
62  * est.setInputCloud (cloud);
63  * est.setInputNormals (normals);
64  * est.setRadiusSearch (0.02); // 2cm radius
65  * est.setSearchMethod (typename pcl::search::KdTree<PointXYZ>::Ptr (new pcl::search::KdTree<PointXYZ>)
66  * est.compute (boundaries);
67  * \endcode
68  *
69  * \attention
70  * The convention for Boundary features is:
71  * - if a query point's nearest neighbors cannot be estimated, the boundary feature will be set to NaN
72  * (not a number)
73  * - it is impossible to estimate a boundary property for a point that
74  * doesn't have finite 3D coordinates. Therefore, any point that contains
75  * NaN data on x, y, or z, will have its boundary feature property set to NaN.
76  *
77  * \author Radu B. Rusu
78  * \ingroup features
79  */
80  template <typename PointInT, typename PointNT, typename PointOutT>
81  class BoundaryEstimation: public FeatureFromNormals<PointInT, PointNT, PointOutT>
82  {
83  public:
84  typedef boost::shared_ptr<BoundaryEstimation<PointInT, PointNT, PointOutT> > Ptr;
85  typedef boost::shared_ptr<const BoundaryEstimation<PointInT, PointNT, PointOutT> > ConstPtr;
86 
97 
99 
100  public:
101  /** \brief Empty constructor.
102  * The angular threshold \a angle_threshold_ is set to M_PI / 2.0
103  */
104  BoundaryEstimation () : angle_threshold_ (static_cast<float> (M_PI) / 2.0f)
105  {
106  feature_name_ = "BoundaryEstimation";
107  };
108 
109  /** \brief Check whether a point is a boundary point in a planar patch of projected points given by indices.
110  * \note A coordinate system u-v-n must be computed a-priori using \a getCoordinateSystemOnPlane
111  * \param[in] cloud a pointer to the input point cloud
112  * \param[in] q_idx the index of the query point in \a cloud
113  * \param[in] indices the estimated point neighbors of the query point
114  * \param[in] u the u direction
115  * \param[in] v the v direction
116  * \param[in] angle_threshold the threshold angle (default \f$\pi / 2.0\f$)
117  */
118  bool
120  int q_idx, const std::vector<int> &indices,
121  const Eigen::Vector4f &u, const Eigen::Vector4f &v, const float angle_threshold);
122 
123  /** \brief Check whether a point is a boundary point in a planar patch of projected points given by indices.
124  * \note A coordinate system u-v-n must be computed a-priori using \a getCoordinateSystemOnPlane
125  * \param[in] cloud a pointer to the input point cloud
126  * \param[in] q_point a pointer to the querry point
127  * \param[in] indices the estimated point neighbors of the query point
128  * \param[in] u the u direction
129  * \param[in] v the v direction
130  * \param[in] angle_threshold the threshold angle (default \f$\pi / 2.0\f$)
131  */
132  bool
134  const PointInT &q_point,
135  const std::vector<int> &indices,
136  const Eigen::Vector4f &u, const Eigen::Vector4f &v, const float angle_threshold);
137 
138  /** \brief Set the decision boundary (angle threshold) that marks points as boundary or regular.
139  * (default \f$\pi / 2.0\f$)
140  * \param[in] angle the angle threshold
141  */
142  inline void
143  setAngleThreshold (float angle)
144  {
145  angle_threshold_ = angle;
146  }
147 
148  /** \brief Get the decision boundary (angle threshold) as set by the user. */
149  inline float
151  {
152  return (angle_threshold_);
153  }
154 
155  /** \brief Get a u-v-n coordinate system that lies on a plane defined by its normal
156  * \param[in] p_coeff the plane coefficients (containing the plane normal)
157  * \param[out] u the resultant u direction
158  * \param[out] v the resultant v direction
159  */
160  inline void
161  getCoordinateSystemOnPlane (const PointNT &p_coeff,
162  Eigen::Vector4f &u, Eigen::Vector4f &v)
163  {
164  pcl::Vector4fMapConst p_coeff_v = p_coeff.getNormalVector4fMap ();
165  v = p_coeff_v.unitOrthogonal ();
166  u = p_coeff_v.cross3 (v);
167  }
168 
169  protected:
170  /** \brief Estimate whether a set of points is lying on surface boundaries using an angle criterion for all points
171  * given in <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
172  * setSearchMethod ()
173  * \param[out] output the resultant point cloud model dataset that contains boundary point estimates
174  */
175  void
176  computeFeature (PointCloudOut &output);
177 
178  /** \brief The decision boundary (angle threshold) that marks points as boundary or regular. (default \f$\pi / 2.0\f$) */
180  };
181 }
182 
183 #ifdef PCL_NO_PRECOMPILE
184 #include <pcl/features/impl/boundary.hpp>
185 #endif
186 
187 #endif //#ifndef PCL_BOUNDARY_H_
Feature< PointInT, PointOutT >::PointCloudOut PointCloudOut
Definition: boundary.h:98
std::string feature_name_
The feature name.
Definition: feature.h:222
boost::shared_ptr< BoundaryEstimation< PointInT, PointNT, PointOutT > > Ptr
Definition: boundary.h:84
BoundaryEstimation estimates whether a set of points is lying on surface boundaries using an angle cr...
Definition: boundary.h:81
void computeFeature(PointCloudOut &output)
Estimate whether a set of points is lying on surface boundaries using an angle criterion for all poin...
Definition: boundary.hpp:117
BoundaryEstimation()
Empty constructor.
Definition: boundary.h:104
boost::shared_ptr< const BoundaryEstimation< PointInT, PointNT, PointOutT > > ConstPtr
Definition: boundary.h:85
bool isBoundaryPoint(const pcl::PointCloud< PointInT > &cloud, int q_idx, const std::vector< int > &indices, const Eigen::Vector4f &u, const Eigen::Vector4f &v, const float angle_threshold)
Check whether a point is a boundary point in a planar patch of projected points given by indices...
Definition: boundary.hpp:49
float getAngleThreshold()
Get the decision boundary (angle threshold) as set by the user.
Definition: boundary.h:150
Feature represents the base feature class.
Definition: feature.h:105
float angle_threshold_
The decision boundary (angle threshold) that marks points as boundary or regular. ...
Definition: boundary.h:179
void getCoordinateSystemOnPlane(const PointNT &p_coeff, Eigen::Vector4f &u, Eigen::Vector4f &v)
Get a u-v-n coordinate system that lies on a plane defined by its normal.
Definition: boundary.h:161
const Eigen::Map< const Eigen::Vector4f, Eigen::Aligned > Vector4fMapConst
PointCloud represents the base class in PCL for storing collections of 3D points. ...
void setAngleThreshold(float angle)
Set the decision boundary (angle threshold) that marks points as boundary or regular.
Definition: boundary.h:143