Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/keypoints/include/pcl/keypoints/iss_3d.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Copyright (c) 2010, Willow Garage, Inc.
00005  *  All rights reserved.
00006  *
00007  *  Redistribution and use in source and binary forms, with or without
00008  *  modification, are permitted provided that the following conditions
00009  *  are met:
00010  *
00011  *   * Redistributions of source code must retain the above copyright
00012  *     notice, this list of conditions and the following disclaimer.
00013  *   * Redistributions in binary form must reproduce the above
00014  *     copyright notice, this list of conditions and the following
00015  *     disclaimer in the documentation and/or other materials provided
00016  *     with the distribution.
00017  *   * Neither the name of Willow Garage, Inc. nor the names of its
00018  *     contributors may be used to endorse or promote products derived
00019  *     from this software without specific prior written permission.
00020  *
00021  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00022  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00023  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00024  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00025  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00026  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00027  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00028  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00029  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00030  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00031  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00032  *  POSSIBILITY OF SUCH DAMAGE.
00033  *
00034  */
00035 
00036 #ifndef PCL_ISS_3D_H_
00037 #define PCL_ISS_3D_H_
00038 
00039 #include <pcl/keypoints/keypoint.h>
00040 
00041 namespace pcl
00042 {
00043   /** \brief ISSKeypoint3D detects the Intrinsic Shape Signatures keypoints for a given
00044     * point cloud. This class is based on a particular implementation made by Federico
00045     * Tombari and Samuele Salti and it has been explicitly adapted to PCL.
00046     *
00047     * For more information about the original ISS detector, see:
00048     *
00049     *\par
00050     * Yu Zhong, “Intrinsic shape signatures: A shape descriptor for 3D object recognition,”
00051     * Computer Vision Workshops (ICCV Workshops), 2009 IEEE 12th International Conference on ,
00052     * vol., no., pp.689-696, Sept. 27 2009-Oct. 4 2009
00053     *
00054     * Code example:
00055     *
00056     * \code
00057     * pcl::PointCloud<pcl::PointXYZRGBA>::Ptr model (new pcl::PointCloud<pcl::PointXYZRGBA> ());;
00058     * pcl::PointCloud<pcl::PointXYZRGBA>::Ptr model_keypoints (new pcl::PointCloud<pcl::PointXYZRGBA> ());
00059     * pcl::search::KdTree<pcl::PointXYZRGBA>::Ptr tree (new pcl::search::KdTree<pcl::PointXYZRGBA> ());
00060     *
00061     * // Fill in the model cloud
00062     *
00063     * double model_resolution;
00064     *
00065     * // Compute model_resolution
00066     *
00067     * pcl::ISSKeypoint3D<pcl::PointXYZRGBA, pcl::PointXYZRGBA> iss_detector;
00068     *
00069     * iss_detector.setSearchMethod (tree);
00070     * iss_detector.setSalientRadius (6 * model_resolution);
00071     * iss_detector.setNonMaxRadius (4 * model_resolution);
00072     * iss_detector.setThreshold21 (0.975);
00073     * iss_detector.setThreshold32 (0.975);
00074     * iss_detector.setMinNeighbors (5);
00075     * iss_detector.setNumberOfThreads (4);
00076     * iss_detector.setInputCloud (model);
00077     * iss_detector.compute (*model_keypoints);
00078     * \endcode
00079     *
00080     * \author Gioia Ballin
00081     * \ingroup keypoints
00082     */
00083 
00084   template <typename PointInT, typename PointOutT, typename NormalT = pcl::Normal>
00085   class ISSKeypoint3D : public Keypoint<PointInT, PointOutT>
00086   {
00087     public:
00088       typedef boost::shared_ptr<ISSKeypoint3D<PointInT, PointOutT, NormalT> > Ptr;
00089       typedef boost::shared_ptr<const ISSKeypoint3D<PointInT, PointOutT, NormalT> > ConstPtr;
00090 
00091       typedef typename Keypoint<PointInT, PointOutT>::PointCloudIn PointCloudIn;
00092       typedef typename Keypoint<PointInT, PointOutT>::PointCloudOut PointCloudOut;
00093 
00094       typedef typename pcl::PointCloud<NormalT> PointCloudN;
00095       typedef typename PointCloudN::Ptr PointCloudNPtr;
00096       typedef typename PointCloudN::ConstPtr PointCloudNConstPtr;
00097 
00098       typedef typename pcl::octree::OctreePointCloudSearch<PointInT> OctreeSearchIn;
00099       typedef typename OctreeSearchIn::Ptr OctreeSearchInPtr;
00100 
00101       using Keypoint<PointInT, PointOutT>::name_;
00102       using Keypoint<PointInT, PointOutT>::input_;
00103       using Keypoint<PointInT, PointOutT>::surface_;
00104       using Keypoint<PointInT, PointOutT>::tree_;
00105       using Keypoint<PointInT, PointOutT>::search_radius_;
00106       using Keypoint<PointInT, PointOutT>::search_parameter_;
00107 
00108       /** \brief Constructor.
00109         * \param[in] salient_radius the radius of the spherical neighborhood used to compute the scatter matrix.
00110         */
00111       ISSKeypoint3D (double salient_radius = 0.0001)
00112       : salient_radius_ (salient_radius)
00113       , non_max_radius_ (0.0)
00114       , normal_radius_ (0.0)
00115       , border_radius_ (0.0)
00116       , gamma_21_ (0.975)
00117       , gamma_32_ (0.975)
00118       , third_eigen_value_ (0)
00119       , edge_points_ (0)
00120       , min_neighbors_ (5)
00121       , normals_ (new pcl::PointCloud<NormalT>)
00122       , angle_threshold_ (static_cast<float> (M_PI) / 2.0f)
00123       , threads_ (0)
00124       {
00125         name_ = "ISSKeypoint3D";
00126         search_radius_ = salient_radius_;
00127       }
00128 
00129       /** \brief Set the radius of the spherical neighborhood used to compute the scatter matrix.
00130         * \param[in] salient_radius the radius of the spherical neighborhood
00131         */
00132       void
00133       setSalientRadius (double salient_radius);
00134 
00135       /** \brief Set the radius for the application of the non maxima supression algorithm.
00136         * \param[in] non_max_radius the non maxima suppression radius
00137         */
00138       void
00139       setNonMaxRadius (double non_max_radius);
00140 
00141       /** \brief Set the radius used for the estimation of the surface normals of the input cloud. If the radius is
00142   * too large, the temporal performances of the detector may degrade significantly.
00143         * \param[in] normals_radius the radius used to estimate surface normals
00144         */
00145       void
00146       setNormalRadius (double normal_radius);
00147 
00148       /** \brief Set the radius used for the estimation of the boundary points. If the radius is too large,
00149   * the temporal performances of the detector may degrade significantly.
00150         * \param[in] border_radius the radius used to compute the boundary points
00151         */
00152       void
00153       setBorderRadius (double border_radius);
00154 
00155       /** \brief Set the upper bound on the ratio between the second and the first eigenvalue.
00156         * \param[in] gamma_21 the upper bound on the ratio between the second and the first eigenvalue
00157         */
00158       void
00159       setThreshold21 (double gamma_21);
00160 
00161       /** \brief Set the upper bound on the ratio between the third and the second eigenvalue.
00162         * \param[in] gamma_32 the upper bound on the ratio between the third and the second eigenvalue
00163         */
00164       void
00165       setThreshold32 (double gamma_32);
00166 
00167       /** \brief Set the minimum number of neighbors that has to be found while applying the non maxima suppression algorithm.
00168         * \param[in] min_neighbors the minimum number of neighbors required
00169         */
00170       void
00171       setMinNeighbors (int min_neighbors);
00172 
00173       /** \brief Set the normals if pre-calculated normals are available.
00174         * \param[in] normals the given cloud of normals
00175         */
00176       void
00177       setNormals (const PointCloudNConstPtr &normals);
00178 
00179       /** \brief Set the decision boundary (angle threshold) that marks points as boundary or regular.
00180   * (default \f$\pi / 2.0\f$)
00181         * \param[in] angle the angle threshold
00182         */
00183       inline void
00184       setAngleThreshold (float angle)
00185       {
00186   angle_threshold_ = angle;
00187       }
00188 
00189       /** \brief Initialize the scheduler and set the number of threads to use.
00190         * \param[in] nr_threads the number of hardware threads to use (0 sets the value back to automatic)
00191         */
00192       inline void
00193       setNumberOfThreads (unsigned int nr_threads = 0) { threads_ = nr_threads; }
00194 
00195     protected:
00196 
00197       /** \brief Compute the boundary points for the given input cloud.
00198         * \param[in] input the input cloud
00199         * \param[in] border_radius the radius used to compute the boundary points
00200         * \param[in] the decision boundary that marks the points as boundary
00201         * \return the vector of boolean values in which the information about the boundary points is stored
00202         */
00203       bool*
00204       getBoundaryPoints (PointCloudIn &input, double border_radius, float angle_threshold);
00205 
00206       /** \brief Compute the scatter matrix for a point index.
00207         * \param[in] index the index of the point
00208         * \param[out] cov_m the point scatter matrix
00209         */
00210       void
00211       getScatterMatrix (const int &current_index, Eigen::Matrix3d &cov_m);
00212 
00213       /** \brief Perform the initial checks before computing the keypoints.
00214        *  \return true if all the checks are passed, false otherwise
00215         */
00216       bool
00217       initCompute ();
00218 
00219       /** \brief Detect the keypoints by performing the EVD of the scatter matrix.
00220         * \param[out] output the resultant cloud of keypoints
00221         */
00222       void
00223       detectKeypoints (PointCloudOut &output);
00224 
00225 
00226       /** \brief The radius of the spherical neighborhood used to compute the scatter matrix.*/
00227       double salient_radius_;
00228 
00229       /** \brief The non maxima suppression radius. */
00230       double non_max_radius_;
00231 
00232       /** \brief The radius used to compute the normals of the input cloud. */
00233       double normal_radius_;
00234 
00235       /** \brief The radius used to compute the boundary points of the input cloud. */
00236       double border_radius_;
00237 
00238       /** \brief The upper bound on the ratio between the second and the first eigenvalue returned by the EVD. */
00239       double gamma_21_;
00240 
00241       /** \brief The upper bound on the ratio between the third and the second eigenvalue returned by the EVD. */
00242       double gamma_32_;
00243 
00244       /** \brief Store the third eigen value associated to each point in the input cloud. */
00245       double *third_eigen_value_;
00246 
00247       /** \brief Store the information about the boundary points of the input cloud. */
00248       bool *edge_points_;
00249 
00250       /** \brief Minimum number of neighbors that has to be found while applying the non maxima suppression algorithm. */
00251       int min_neighbors_;
00252 
00253       /** \brief The cloud of normals related to the input surface. */
00254       PointCloudNConstPtr normals_;
00255 
00256       /** \brief The decision boundary (angle threshold) that marks points as boundary or regular. (default \f$\pi / 2.0\f$) */
00257       float angle_threshold_;
00258 
00259       /** \brief The number of threads that has to be used by the scheduler. */
00260       unsigned int threads_;
00261 
00262   };
00263 
00264 }
00265 
00266 #include <pcl/keypoints/impl/iss_3d.hpp>
00267 
00268 #endif /* PCL_ISS_3D_H_ */