Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/keypoints/include/pcl/keypoints/sift_keypoint.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_SIFT_KEYPOINT_H_
00037 #define PCL_SIFT_KEYPOINT_H_
00038 
00039 #include <pcl/keypoints/keypoint.h>
00040 
00041 namespace pcl
00042 {
00043   template<typename PointT>
00044   struct SIFTKeypointFieldSelector
00045   {
00046     inline float
00047     operator () (const PointT & p) const
00048     {
00049       return p.intensity;
00050     }
00051   };
00052   template<>
00053   struct SIFTKeypointFieldSelector<PointNormal>
00054   {
00055     inline float
00056     operator () (const PointNormal & p) const
00057     {
00058       return p.curvature;
00059     }
00060   };
00061   template<>
00062   struct SIFTKeypointFieldSelector<PointXYZRGB>
00063   {
00064     inline float
00065     operator () (const PointXYZRGB & p) const
00066     {
00067       return (static_cast<float> (299*p.r + 587*p.g + 114*p.b) / 1000.0f);
00068     }
00069   };
00070   template<>
00071   struct SIFTKeypointFieldSelector<PointXYZRGBA>
00072   {
00073     inline float
00074     operator () (const PointXYZRGBA & p) const
00075     {
00076       return (static_cast<float> (299*p.r + 587*p.g + 114*p.b) / 1000.0f);
00077     }
00078   };
00079 
00080   /** \brief @b SIFTKeypoint detects the Scale Invariant Feature Transform
00081     * keypoints for a given point cloud dataset containing points and intensity.
00082     * This implementation adapts the original algorithm from images to point
00083     * clouds. 
00084     *
00085     * For more information about the image-based SIFT interest operator, see:
00086     *
00087     *    David G. Lowe, "Distinctive image features from scale-invariant keypoints," 
00088     *    International Journal of Computer Vision, 60, 2 (2004), pp. 91-110.
00089     *
00090     * \author Michael Dixon
00091     * \ingroup keypoints
00092     */
00093   template <typename PointInT, typename PointOutT>
00094   class SIFTKeypoint : public Keypoint<PointInT, PointOutT>
00095   {
00096     public:
00097       typedef boost::shared_ptr<SIFTKeypoint<PointInT, PointOutT> > Ptr;
00098       typedef boost::shared_ptr<const SIFTKeypoint<PointInT, PointOutT> > ConstPtr;
00099 
00100       typedef typename Keypoint<PointInT, PointOutT>::PointCloudIn PointCloudIn;
00101       typedef typename Keypoint<PointInT, PointOutT>::PointCloudOut PointCloudOut;
00102       typedef typename Keypoint<PointInT, PointOutT>::KdTree KdTree;
00103 
00104       using Keypoint<PointInT, PointOutT>::name_;
00105       using Keypoint<PointInT, PointOutT>::input_;
00106       using Keypoint<PointInT, PointOutT>::indices_;
00107       using Keypoint<PointInT, PointOutT>::surface_;
00108       using Keypoint<PointInT, PointOutT>::tree_;
00109       using Keypoint<PointInT, PointOutT>::initCompute;    
00110 
00111       /** \brief Empty constructor. */
00112       SIFTKeypoint () : min_scale_ (0.0), nr_octaves_ (0), nr_scales_per_octave_ (0), 
00113         min_contrast_ (-std::numeric_limits<float>::max ()), scale_idx_ (-1), 
00114         out_fields_ (), getFieldValue_ ()
00115       {
00116         name_ = "SIFTKeypoint";
00117       }
00118 
00119       /** \brief Specify the range of scales over which to search for keypoints
00120         * \param min_scale the standard deviation of the smallest scale in the scale space
00121         * \param nr_octaves the number of octaves (i.e. doublings of scale) to compute 
00122         * \param nr_scales_per_octave the number of scales to compute within each octave
00123         */
00124       void 
00125       setScales (float min_scale, int nr_octaves, int nr_scales_per_octave);
00126 
00127       /** \brief Provide a threshold to limit detection of keypoints without sufficient contrast
00128         * \param min_contrast the minimum contrast required for detection
00129         */
00130       void 
00131       setMinimumContrast (float min_contrast);
00132 
00133     protected:
00134       bool
00135       initCompute ();
00136 
00137       /** \brief Detect the SIFT keypoints for a set of points given in setInputCloud () using the spatial locator in 
00138         * setSearchMethod ().
00139         * \param output the resultant cloud of keypoints
00140         */
00141       void 
00142       detectKeypoints (PointCloudOut &output);
00143 
00144     private:
00145       /** \brief Detect the SIFT keypoints for a given point cloud for a single octave.
00146         * \param input the point cloud to detect keypoints in
00147         * \param tree a k-D tree of the points in \a input
00148         * \param base_scale the first (smallest) scale in the octave
00149         * \param nr_scales_per_octave the number of scales to to compute
00150         * \param output the resultant point cloud containing the SIFT keypoints
00151         */
00152       void 
00153       detectKeypointsForOctave (const PointCloudIn &input, KdTree &tree, 
00154                                 float base_scale, int nr_scales_per_octave, 
00155                                 PointCloudOut &output);
00156 
00157       /** \brief Compute the difference-of-Gaussian (DoG) scale space for the given input and scales
00158         * \param input the point cloud for which the DoG scale space will be computed
00159         * \param tree a k-D tree of the points in \a input
00160         * \param scales a vector containing the scales over which to compute the DoG scale space
00161         * \param diff_of_gauss the resultant DoG scale space (in a number-of-points by number-of-scales matrix)
00162         */
00163       void 
00164       computeScaleSpace (const PointCloudIn &input, KdTree &tree, 
00165                          const std::vector<float> &scales, 
00166                          Eigen::MatrixXf &diff_of_gauss);
00167 
00168       /** \brief Find the local minima and maxima in the provided difference-of-Gaussian (DoG) scale space
00169         * \param input the input point cloud 
00170         * \param tree a k-D tree of the points in \a input
00171         * \param diff_of_gauss the DoG scale space (in a number-of-points by number-of-scales matrix)
00172         * \param extrema_indices the resultant vector containing the point indices of each keypoint
00173         * \param extrema_scales the resultant vector containing the scale indices of each keypoint
00174         */
00175       void 
00176       findScaleSpaceExtrema (const PointCloudIn &input, KdTree &tree, 
00177                              const Eigen::MatrixXf &diff_of_gauss,
00178                              std::vector<int> &extrema_indices, std::vector<int> &extrema_scales);
00179 
00180 
00181       /** \brief The standard deviation of the smallest scale in the scale space.*/
00182       float min_scale_;
00183 
00184       /** \brief The number of octaves (i.e. doublings of scale) over which to search for keypoints.*/
00185       int nr_octaves_;
00186 
00187       /** \brief The number of scales to be computed for each octave.*/
00188       int nr_scales_per_octave_;
00189 
00190       /** \brief The minimum contrast required for detection.*/
00191       float min_contrast_;
00192 
00193       /** \brief Set to a value different than -1 if the output cloud has a "scale" field and we have to save 
00194         * the keypoints scales. */
00195       int scale_idx_;
00196 
00197       /** \brief The list of fields present in the output point cloud data. */
00198       std::vector<pcl::PCLPointField> out_fields_;
00199 
00200       SIFTKeypointFieldSelector<PointInT> getFieldValue_;
00201   };
00202 }
00203 
00204 #include <pcl/keypoints/impl/sift_keypoint.hpp>
00205 
00206 #endif // #ifndef PCL_SIFT_KEYPOINT_H_