Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/features/include/pcl/features/shot.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2011, Willow Garage, Inc.
00006  *  Copyright (c) 2012-, Open Perception, Inc.
00007  *
00008  *  All rights reserved.
00009  *
00010  *  Redistribution and use in source and binary forms, with or without
00011  *  modification, are permitted provided that the following conditions
00012  *  are met:
00013  *
00014  *   * Redistributions of source code must retain the above copyright
00015  *     notice, this list of conditions and the following disclaimer.
00016  *   * Redistributions in binary form must reproduce the above
00017  *     copyright notice, this list of conditions and the following
00018  *     disclaimer in the documentation and/or other materials provided
00019  *     with the distribution.
00020  *   * Neither the name of the copyright holder(s) nor the names of its
00021  *     contributors may be used to endorse or promote products derived
00022  *     from this software without specific prior written permission.
00023  *
00024  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00025  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00026  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00027  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00028  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00029  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00030  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00031  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00032  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00033  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00034  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035  *  POSSIBILITY OF SUCH DAMAGE.
00036  *
00037  *
00038  */
00039 
00040 #ifndef PCL_SHOT_H_
00041 #define PCL_SHOT_H_
00042 
00043 #include <pcl/point_types.h>
00044 #include <pcl/features/feature.h>
00045 
00046 namespace pcl
00047 {
00048   /** \brief SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for
00049     * a given point cloud dataset containing points and normals.
00050     *
00051     * The suggested PointOutT is pcl::SHOT352.
00052     *
00053     * \note If you use this code in any academic work, please cite:
00054     *
00055     *   - F. Tombari, S. Salti, L. Di Stefano
00056     *     Unique Signatures of Histograms for Local Surface Description.
00057     *     In Proceedings of the 11th European Conference on Computer Vision (ECCV),
00058     *     Heraklion, Greece, September 5-11 2010.
00059     *   - F. Tombari, S. Salti, L. Di Stefano
00060     *     A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
00061     *     In Proceedings of the 18th International Conference on Image Processing (ICIP),
00062     *     Brussels, Belgium, September 11-14 2011.
00063     *
00064     * \author Samuele Salti, Federico Tombari
00065     * \ingroup features
00066     */
00067   template <typename PointInT, typename PointNT, typename PointOutT, typename PointRFT = pcl::ReferenceFrame>
00068   class SHOTEstimationBase : public FeatureFromNormals<PointInT, PointNT, PointOutT>,
00069                              public FeatureWithLocalReferenceFrames<PointInT, PointRFT>
00070   {
00071     public:
00072       typedef boost::shared_ptr<SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
00073       typedef boost::shared_ptr<const SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
00074       using Feature<PointInT, PointOutT>::feature_name_;
00075       using Feature<PointInT, PointOutT>::getClassName;
00076       using Feature<PointInT, PointOutT>::input_;
00077       using Feature<PointInT, PointOutT>::indices_;
00078       using Feature<PointInT, PointOutT>::k_;
00079       using Feature<PointInT, PointOutT>::search_parameter_;
00080       using Feature<PointInT, PointOutT>::search_radius_;
00081       using Feature<PointInT, PointOutT>::surface_;
00082       using Feature<PointInT, PointOutT>::fake_surface_;
00083       using FeatureFromNormals<PointInT, PointNT, PointOutT>::normals_;
00084       using FeatureWithLocalReferenceFrames<PointInT, PointRFT>::frames_;
00085 
00086       typedef typename Feature<PointInT, PointOutT>::PointCloudIn PointCloudIn;
00087 
00088     protected:
00089       /** \brief Empty constructor.
00090         * \param[in] nr_shape_bins the number of bins in the shape histogram
00091         */
00092       SHOTEstimationBase (int nr_shape_bins = 10) :
00093         nr_shape_bins_ (nr_shape_bins),
00094         shot_ (), lrf_radius_ (0),
00095         sqradius_ (0), radius3_4_ (0), radius1_4_ (0), radius1_2_ (0),
00096         nr_grid_sector_ (32),
00097         maxAngularSectors_ (28),
00098         descLength_ (0)
00099       {
00100         feature_name_ = "SHOTEstimation";
00101       };
00102       
00103 
00104     public:
00105 
00106       /** \brief Empty destructor */
00107       virtual ~SHOTEstimationBase () {}
00108 
00109        /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
00110          * \param[in] index the index of the point in indices_
00111          * \param[in] indices the k-neighborhood point indices in surface_
00112          * \param[in] sqr_dists the k-neighborhood point distances in surface_
00113          * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
00114          */
00115       virtual void
00116       computePointSHOT (const int index,
00117                         const std::vector<int> &indices,
00118                         const std::vector<float> &sqr_dists,
00119                         Eigen::VectorXf &shot) = 0;
00120 
00121         /** \brief Set the radius used for local reference frame estimation if the frames are not set by the user */
00122       virtual void
00123       setLRFRadius (float radius) { lrf_radius_ = radius; }
00124 
00125         /** \brief Get the radius used for local reference frame estimation */
00126       virtual float
00127       getLRFRadius () const { return lrf_radius_; }
00128 
00129     protected:
00130 
00131       /** \brief This method should get called before starting the actual computation. */
00132       virtual bool
00133       initCompute ();
00134 
00135       /** \brief Quadrilinear interpolation used when color and shape descriptions are NOT activated simultaneously
00136         *
00137         * \param[in] indices the neighborhood point indices
00138         * \param[in] sqr_dists the neighborhood point distances
00139         * \param[in] index the index of the point in indices_
00140         * \param[out] binDistance the resultant distance shape histogram
00141         * \param[in] nr_bins the number of bins in the shape histogram
00142         * \param[out] shot the resultant SHOT histogram
00143         */
00144       void
00145       interpolateSingleChannel (const std::vector<int> &indices,
00146                                 const std::vector<float> &sqr_dists,
00147                                 const int index,
00148                                 std::vector<double> &binDistance,
00149                                 const int nr_bins,
00150                                 Eigen::VectorXf &shot);
00151 
00152       /** \brief Normalize the SHOT histogram.
00153         * \param[in,out] shot the SHOT histogram
00154         * \param[in] desc_length the length of the histogram
00155         */
00156       void
00157       normalizeHistogram (Eigen::VectorXf &shot, int desc_length);
00158 
00159 
00160       /** \brief Create a binned distance shape histogram
00161         * \param[in] index the index of the point in indices_
00162         * \param[in] indices the k-neighborhood point indices in surface_
00163         * \param[in] sqr_dists the k-neighborhood point distances in surface_
00164         * \param[out] bin_distance_shape the resultant histogram
00165         */
00166       void
00167       createBinDistanceShape (int index, const std::vector<int> &indices,
00168                               std::vector<double> &bin_distance_shape);
00169 
00170       /** \brief The number of bins in each shape histogram. */
00171       int nr_shape_bins_;
00172 
00173       /** \brief Placeholder for a point's SHOT. */
00174       Eigen::VectorXf shot_;
00175 
00176       /** \brief The radius used for the LRF computation */
00177       float lrf_radius_;
00178 
00179       /** \brief The squared search radius. */
00180       double sqradius_;
00181 
00182       /** \brief 3/4 of the search radius. */
00183       double radius3_4_;
00184 
00185       /** \brief 1/4 of the search radius. */
00186       double radius1_4_;
00187 
00188       /** \brief 1/2 of the search radius. */
00189       double radius1_2_;
00190 
00191       /** \brief Number of azimuthal sectors. */
00192       const int nr_grid_sector_;
00193 
00194       /** \brief ... */
00195       const int maxAngularSectors_;
00196 
00197       /** \brief One SHOT length. */
00198       int descLength_;
00199   };
00200 
00201   /** \brief SHOTEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for
00202     * a given point cloud dataset containing points and normals.
00203     *
00204     * The suggested PointOutT is pcl::SHOT352
00205     *
00206     * \note If you use this code in any academic work, please cite:
00207     *
00208     *   - F. Tombari, S. Salti, L. Di Stefano
00209     *     Unique Signatures of Histograms for Local Surface Description.
00210     *     In Proceedings of the 11th European Conference on Computer Vision (ECCV),
00211     *     Heraklion, Greece, September 5-11 2010.
00212     *   - F. Tombari, S. Salti, L. Di Stefano
00213     *     A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
00214     *     In Proceedings of the 18th International Conference on Image Processing (ICIP),
00215     *     Brussels, Belgium, September 11-14 2011.
00216     *
00217     * \author Samuele Salti, Federico Tombari
00218     * \ingroup features
00219     */
00220   template <typename PointInT, typename PointNT, typename PointOutT = pcl::SHOT352, typename PointRFT = pcl::ReferenceFrame>
00221   class SHOTEstimation : public SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>
00222   {
00223     public:
00224       typedef boost::shared_ptr<SHOTEstimation<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
00225       typedef boost::shared_ptr<const SHOTEstimation<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
00226       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::feature_name_;
00227       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::getClassName;
00228       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::indices_;
00229       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::k_;
00230       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::search_parameter_;
00231       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::search_radius_;
00232       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::surface_;
00233       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::input_;
00234       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::normals_;
00235       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::descLength_;
00236       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::nr_grid_sector_;
00237       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::nr_shape_bins_;
00238       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::sqradius_;
00239       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius3_4_;
00240       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius1_4_;
00241       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius1_2_;
00242       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::maxAngularSectors_;
00243       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::interpolateSingleChannel;
00244       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::shot_;
00245       using FeatureWithLocalReferenceFrames<PointInT, PointRFT>::frames_;
00246 
00247       typedef typename Feature<PointInT, PointOutT>::PointCloudIn PointCloudIn;
00248 
00249       /** \brief Empty constructor. */
00250       SHOTEstimation () : SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> (10)
00251       {
00252         feature_name_ = "SHOTEstimation";
00253       };
00254       
00255       /** \brief Empty destructor */
00256       virtual ~SHOTEstimation () {}
00257 
00258       /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
00259         * \param[in] index the index of the point in indices_
00260         * \param[in] indices the k-neighborhood point indices in surface_
00261         * \param[in] sqr_dists the k-neighborhood point distances in surface_
00262         * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
00263         */
00264       virtual void
00265       computePointSHOT (const int index,
00266                         const std::vector<int> &indices,
00267                         const std::vector<float> &sqr_dists,
00268                         Eigen::VectorXf &shot);
00269     protected:
00270       /** \brief Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by
00271         * <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
00272         * setSearchMethod ()
00273         * \param output the resultant point cloud model dataset that contains the SHOT feature estimates
00274         */
00275       void
00276       computeFeature (pcl::PointCloud<PointOutT> &output);
00277   };
00278 
00279   /** \brief SHOTColorEstimation estimates the Signature of Histograms of OrienTations (SHOT) descriptor for a given point cloud dataset
00280     * containing points, normals and colors.
00281     *
00282     * The suggested PointOutT is pcl::SHOT1344
00283     *
00284     * \note If you use this code in any academic work, please cite:
00285     *
00286     *   - F. Tombari, S. Salti, L. Di Stefano
00287     *     Unique Signatures of Histograms for Local Surface Description.
00288     *     In Proceedings of the 11th European Conference on Computer Vision (ECCV),
00289     *     Heraklion, Greece, September 5-11 2010.
00290     *   - F. Tombari, S. Salti, L. Di Stefano
00291     *     A Combined Texture-Shape Descriptor For Enhanced 3D Feature Matching.
00292     *     In Proceedings of the 18th International Conference on Image Processing (ICIP),
00293     *     Brussels, Belgium, September 11-14 2011.
00294     *
00295     * \author Samuele Salti, Federico Tombari
00296     * \ingroup features
00297     */
00298   template <typename PointInT, typename PointNT, typename PointOutT = pcl::SHOT1344, typename PointRFT = pcl::ReferenceFrame>
00299   class SHOTColorEstimation : public SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>
00300   {
00301     public:
00302       typedef boost::shared_ptr<SHOTColorEstimation<PointInT, PointNT, PointOutT, PointRFT> > Ptr;
00303       typedef boost::shared_ptr<const SHOTColorEstimation<PointInT, PointNT, PointOutT, PointRFT> > ConstPtr;
00304       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::feature_name_;
00305       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::getClassName;
00306       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::indices_;
00307       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::k_;
00308       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::search_parameter_;
00309       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::search_radius_;
00310       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::surface_;
00311       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::input_;
00312       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::normals_;
00313       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::descLength_;
00314       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::nr_grid_sector_;
00315       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::nr_shape_bins_;
00316       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::sqradius_;
00317       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius3_4_;
00318       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius1_4_;
00319       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::radius1_2_;
00320       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::maxAngularSectors_;
00321       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::interpolateSingleChannel;
00322       using SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT>::shot_;
00323       using FeatureWithLocalReferenceFrames<PointInT, PointRFT>::frames_;
00324 
00325       typedef typename Feature<PointInT, PointOutT>::PointCloudIn PointCloudIn;
00326 
00327       /** \brief Empty constructor.
00328         * \param[in] describe_shape
00329         * \param[in] describe_color
00330         */
00331       SHOTColorEstimation (bool describe_shape = true,
00332                            bool describe_color = true)
00333         : SHOTEstimationBase<PointInT, PointNT, PointOutT, PointRFT> (10),
00334           b_describe_shape_ (describe_shape),
00335           b_describe_color_ (describe_color),
00336           nr_color_bins_ (30)
00337       {
00338         feature_name_ = "SHOTColorEstimation";
00339       };
00340       
00341       /** \brief Empty destructor */
00342       virtual ~SHOTColorEstimation () {}
00343 
00344       /** \brief Estimate the SHOT descriptor for a given point based on its spatial neighborhood of 3D points with normals
00345         * \param[in] index the index of the point in indices_
00346         * \param[in] indices the k-neighborhood point indices in surface_
00347         * \param[in] sqr_dists the k-neighborhood point distances in surface_
00348         * \param[out] shot the resultant SHOT descriptor representing the feature at the query point
00349         */
00350       virtual void
00351       computePointSHOT (const int index,
00352                         const std::vector<int> &indices,
00353                         const std::vector<float> &sqr_dists,
00354                         Eigen::VectorXf &shot);
00355     protected:
00356       /** \brief Estimate the Signatures of Histograms of OrienTations (SHOT) descriptors at a set of points given by
00357         * <setInputCloud (), setIndices ()> using the surface in setSearchSurface () and the spatial locator in
00358         * setSearchMethod ()
00359         * \param output the resultant point cloud model dataset that contains the SHOT feature estimates
00360         */
00361       void
00362       computeFeature (pcl::PointCloud<PointOutT> &output);
00363 
00364       /** \brief Quadrilinear interpolation; used when color and shape descriptions are both activated
00365         * \param[in] indices the neighborhood point indices
00366         * \param[in] sqr_dists the neighborhood point distances
00367         * \param[in] index the index of the point in indices_
00368         * \param[out] binDistanceShape the resultant distance shape histogram
00369         * \param[out] binDistanceColor the resultant color shape histogram
00370         * \param[in] nr_bins_shape the number of bins in the shape histogram
00371         * \param[in] nr_bins_color the number of bins in the color histogram
00372         * \param[out] shot the resultant SHOT histogram
00373         */
00374       void
00375       interpolateDoubleChannel (const std::vector<int> &indices,
00376                                 const std::vector<float> &sqr_dists,
00377                                 const int index,
00378                                 std::vector<double> &binDistanceShape,
00379                                 std::vector<double> &binDistanceColor,
00380                                 const int nr_bins_shape,
00381                                 const int nr_bins_color,
00382                                 Eigen::VectorXf &shot);
00383 
00384       /** \brief Compute shape descriptor. */
00385       bool b_describe_shape_;
00386 
00387       /** \brief Compute color descriptor. */
00388       bool b_describe_color_;
00389 
00390       /** \brief The number of bins in each color histogram. */
00391       int nr_color_bins_;
00392 
00393     public:
00394       /** \brief Converts RGB triplets to CIELab space.
00395         * \param[in] R the red channel
00396         * \param[in] G the green channel
00397         * \param[in] B the blue channel
00398         * \param[out] L the lightness
00399         * \param[out] A the first color-opponent dimension
00400         * \param[out] B2 the second color-opponent dimension
00401         */
00402       static void
00403       RGB2CIELAB (unsigned char R, unsigned char G, unsigned char B, float &L, float &A, float &B2);
00404 
00405       static float sRGB_LUT[256];
00406       static float sXYZ_LUT[4000];
00407   };
00408 }
00409 
00410 #ifdef PCL_NO_PRECOMPILE
00411 #include <pcl/features/impl/shot.hpp>
00412 #endif
00413 
00414 #endif  //#ifndef PCL_SHOT_H_