Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/recognition/include/pcl/recognition/cg/correspondence_grouping.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2012, Willow Garage, Inc.
00006  *  
00007  *  All rights reserved.
00008  *
00009  *  Redistribution and use in source and binary forms, with or without
00010  *  modification, are permitted provided that the following conditions
00011  *  are met:
00012  *
00013  *   * Redistributions of source code must retain the above copyright
00014  *     notice, this list of conditions and the following disclaimer.
00015  *   * Redistributions in binary form must reproduce the above
00016  *     copyright notice, this list of conditions and the following
00017  *     disclaimer in the documentation and/or other materials provided
00018  *     with the distribution.
00019  *   * Neither the name of Willow Garage, Inc. nor the names of its
00020  *     contributors may be used to endorse or promote products derived
00021  *     from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00027  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034  *  POSSIBILITY OF SUCH DAMAGE.
00035  *
00036  * $Id$
00037  *
00038  */
00039 
00040 #ifndef PCL_RECOGNITION_CORRESPONDENCE_GROUPING_H_
00041 #define PCL_RECOGNITION_CORRESPONDENCE_GROUPING_H_
00042 
00043 #include <pcl/pcl_base.h>
00044 #include <pcl/correspondence.h>
00045 #include <pcl/console/print.h>
00046 
00047 namespace pcl
00048 {
00049   /** \brief Abstract base class for Correspondence Grouping algorithms.
00050     *
00051     * \author Tommaso Cavallari, Federico Tombari, Aitor Aldoma
00052     * \ingroup recognition
00053     */
00054   template <typename PointModelT, typename PointSceneT>
00055   class CorrespondenceGrouping : public PCLBase<PointModelT>
00056   {
00057     public:
00058       typedef pcl::PointCloud<PointSceneT> SceneCloud;
00059       typedef typename SceneCloud::Ptr SceneCloudPtr;
00060       typedef typename SceneCloud::ConstPtr SceneCloudConstPtr;
00061 
00062       /** \brief Empty constructor. */
00063       CorrespondenceGrouping () : scene_ (), model_scene_corrs_ () {}
00064 
00065       /** \brief destructor. */
00066       virtual ~CorrespondenceGrouping() 
00067       {
00068         scene_.reset ();
00069         model_scene_corrs_.reset ();
00070       }
00071 
00072       /** \brief Provide a pointer to the scene dataset.
00073         * 
00074         * \param[in] scene the const boost shared pointer to a PointCloud message.
00075         */
00076       virtual inline void
00077       setSceneCloud (const SceneCloudConstPtr &scene)
00078       {
00079         scene_ = scene;
00080       }
00081 
00082       /** \brief Getter for the scene dataset.
00083         * 
00084         * \return the const boost shared pointer to a PointCloud message.
00085         */
00086       inline SceneCloudConstPtr
00087       getSceneCloud () const
00088       {
00089         return (scene_);
00090       }
00091 
00092       /** \brief Provide a pointer to the precomputed correspondences between points in the input dataset and 
00093         * points in the scene dataset. The correspondences are going to be clustered into different model hypotheses
00094         * by the algorithm.
00095         * 
00096         * \param[in] corrs the correspondences between the model and the scene.
00097         */
00098       virtual inline void
00099       setModelSceneCorrespondences (const CorrespondencesConstPtr &corrs)
00100       {
00101         model_scene_corrs_ = corrs;
00102       }
00103 
00104       /** \brief Getter for the precomputed correspondences between points in the input dataset and 
00105         * points in the scene dataset. 
00106         * 
00107         * \return the correspondences between the model and the scene.
00108         */
00109       inline CorrespondencesConstPtr
00110       getModelSceneCorrespondences () const
00111       {
00112         return (model_scene_corrs_);
00113       }
00114 
00115      /** \brief Getter for the vector of characteristic scales associated to each cluster
00116         * 
00117         * \return the vector of characteristic scales (assuming scale = model / scene)
00118         */
00119       inline std::vector<double>
00120       getCharacteristicScales () const
00121       {
00122         return (corr_group_scale_);
00123       }
00124 
00125       /** \brief Clusters the input correspondences belonging to different model instances.
00126         *
00127         * \param[out] clustered_corrs a vector containing the correspondences for each instance of the model found within the input data.
00128         */
00129       void
00130       cluster (std::vector<Correspondences> &clustered_corrs);
00131 
00132     protected:
00133       /** \brief The scene cloud. */
00134       SceneCloudConstPtr scene_;
00135 
00136       using PCLBase<PointModelT>::input_;
00137 
00138       /** \brief The correspondences between points in the input and the scene datasets. */
00139       CorrespondencesConstPtr model_scene_corrs_;
00140 
00141     /** \brief characteristic scale associated to each correspondence subset; 
00142     * if the cg algorithm can not handle scale invariance, the size of the vector will be 0. */
00143     std::vector <double> corr_group_scale_;
00144 
00145       /** \brief The actual clustering method, should be implemented by each subclass.
00146         *
00147         * \param[out] clustered_corrs a vector containing the correspondences for each instance of the model found within the input data.
00148         */
00149       virtual void
00150       clusterCorrespondences (std::vector<Correspondences> &clustered_corrs) = 0;
00151 
00152       /** \brief This method should get called before starting the actual computation. 
00153         *
00154         * Internally, initCompute() does the following:
00155         *   - checks if an input dataset is given, and returns false otherwise
00156         *   - checks if a scene dataset is given, and returns false otherwise
00157         *   - checks if the model-scene correspondences have been given, and returns false otherwise
00158         */
00159       inline bool
00160       initCompute ()
00161       {
00162         if (!PCLBase<PointModelT>::initCompute ())
00163         {
00164           return (false);
00165         }
00166 
00167         if (!scene_)
00168         {
00169           PCL_ERROR ("[initCompute] Scene not set.\n");
00170           return (false);
00171         }
00172 
00173         if (!input_)
00174         {
00175           PCL_ERROR ("[initCompute] Input not set.\n");
00176           return (false);
00177         }
00178 
00179         if (!model_scene_corrs_)
00180         {
00181           PCL_ERROR ("[initCompute] Model-Scene Correspondences not set.\n");
00182           return (false);
00183         }
00184 
00185         return (true);
00186       }
00187 
00188       /** \brief This method should get called after finishing the actual computation. 
00189         *
00190         */
00191       inline bool
00192       deinitCompute ()
00193       {
00194         return (true);
00195       }
00196 
00197   };
00198 }
00199 
00200 #include <pcl/recognition/impl/cg/correspondence_grouping.hpp>
00201 
00202 #endif // PCL_RECOGNITION_CORRESPONDENCE_GROUPING_H_