Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/registration/include/pcl/registration/correspondence_rejection_sample_consensus.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  * $Id$
00038  *
00039  */
00040 #ifndef PCL_REGISTRATION_CORRESPONDENCE_REJECTION_SAMPLE_CONSENSUS_H_
00041 #define PCL_REGISTRATION_CORRESPONDENCE_REJECTION_SAMPLE_CONSENSUS_H_
00042 
00043 #include <pcl/registration/correspondence_rejection.h>
00044 
00045 #include <pcl/sample_consensus/ransac.h>
00046 #include <pcl/sample_consensus/sac_model_registration.h>
00047 #include <pcl/common/transforms.h>
00048 
00049 namespace pcl
00050 {
00051   namespace registration
00052   {
00053     /** \brief CorrespondenceRejectorSampleConsensus implements a correspondence rejection
00054       * using Random Sample Consensus to identify inliers (and reject outliers)
00055       * \author Dirk Holz
00056       * \ingroup registration
00057       */
00058     template <typename PointT>
00059     class CorrespondenceRejectorSampleConsensus: public CorrespondenceRejector
00060     {
00061       typedef pcl::PointCloud<PointT> PointCloud;
00062       typedef typename PointCloud::Ptr PointCloudPtr;
00063       typedef typename PointCloud::ConstPtr PointCloudConstPtr;
00064 
00065       public:
00066         using CorrespondenceRejector::input_correspondences_;
00067         using CorrespondenceRejector::rejection_name_;
00068         using CorrespondenceRejector::getClassName;
00069 
00070         typedef boost::shared_ptr<CorrespondenceRejectorSampleConsensus> Ptr;
00071         typedef boost::shared_ptr<const CorrespondenceRejectorSampleConsensus> ConstPtr;
00072 
00073         /** \brief Empty constructor. Sets the inlier threshold to 5cm (0.05m), 
00074           * and the maximum number of iterations to 1000. 
00075           */
00076         CorrespondenceRejectorSampleConsensus () 
00077           : inlier_threshold_ (0.05)
00078           , max_iterations_ (1000) // std::numeric_limits<int>::max ()
00079           , input_ ()
00080           , input_transformed_ ()
00081           , target_ ()
00082           , best_transformation_ ()
00083           , refine_ (false)
00084         {
00085           rejection_name_ = "CorrespondenceRejectorSampleConsensus";
00086         }
00087 
00088         /** \brief Empty destructor. */
00089         virtual ~CorrespondenceRejectorSampleConsensus () {}
00090 
00091         /** \brief Get a list of valid correspondences after rejection from the original set of correspondences.
00092           * \param[in] original_correspondences the set of initial correspondences given
00093           * \param[out] remaining_correspondences the resultant filtered set of remaining correspondences
00094           */
00095         inline void 
00096         getRemainingCorrespondences (const pcl::Correspondences& original_correspondences, 
00097                                      pcl::Correspondences& remaining_correspondences);
00098 
00099         /** \brief Provide a source point cloud dataset (must contain XYZ data!)
00100           * \param[in] cloud a cloud containing XYZ data
00101           */
00102         PCL_DEPRECATED (virtual void setInputCloud (const PointCloudConstPtr &cloud), 
00103             "[pcl::registration::CorrespondenceRejectorSampleConsensus::setInputCloud] setInputCloud is deprecated. Please use setInputSource instead.");
00104 
00105         /** \brief Get a pointer to the input point cloud dataset target. */
00106         PCL_DEPRECATED (PointCloudConstPtr const getInputCloud (), "[pcl::registration::CorrespondenceRejectorSampleConsensus::getInputCloud] getInputCloud is deprecated. Please use getInputSource instead.");
00107 
00108         /** \brief Provide a source point cloud dataset (must contain XYZ data!)
00109           * \param[in] cloud a cloud containing XYZ data
00110           */
00111         virtual inline void 
00112         setInputSource (const PointCloudConstPtr &cloud) 
00113         { 
00114           input_ = cloud; 
00115         }
00116 
00117         /** \brief Get a pointer to the input point cloud dataset target. */
00118         inline PointCloudConstPtr const 
00119         getInputSource () { return (input_); }
00120 
00121         /** \brief Provide a target point cloud dataset (must contain XYZ data!)
00122           * \param[in] cloud a cloud containing XYZ data
00123           */
00124         PCL_DEPRECATED (virtual void setTargetCloud (const PointCloudConstPtr &cloud), "[pcl::registration::CorrespondenceRejectorSampleConsensus::setTargetCloud] setTargetCloud is deprecated. Please use setInputTarget instead.");
00125 
00126         /** \brief Provide a target point cloud dataset (must contain XYZ data!)
00127           * \param[in] cloud a cloud containing XYZ data
00128           */
00129         virtual inline void 
00130         setInputTarget (const PointCloudConstPtr &cloud) { target_ = cloud; }
00131 
00132         /** \brief Get a pointer to the input point cloud dataset target. */
00133         inline PointCloudConstPtr const 
00134         getInputTarget () { return (target_ ); }
00135 
00136         /** \brief Set the maximum distance between corresponding points.
00137           * Correspondences with distances below the threshold are considered as inliers.
00138           * \param[in] threshold Distance threshold in the same dimension as source and target data sets.
00139           */
00140         inline void 
00141         setInlierThreshold (double threshold) { inlier_threshold_ = threshold; };
00142 
00143         /** \brief Get the maximum distance between corresponding points.
00144           * \return Distance threshold in the same dimension as source and target data sets.
00145           */
00146         inline double 
00147         getInlierThreshold() { return inlier_threshold_; };
00148 
00149         /** \brief Set the maximum number of iterations.
00150           * \param[in] max_iterations Maximum number if iterations to run
00151           */
00152         PCL_DEPRECATED (void setMaxIterations (int max_iterations), "[pcl::registration::CorrespondenceRejectorSampleConsensus::setMaxIterations] setMaxIterations is deprecated. Please use setMaximumIterations instead.");
00153 
00154         /** \brief Set the maximum number of iterations.
00155           * \param[in] max_iterations Maximum number if iterations to run
00156           */
00157         inline void 
00158         setMaximumIterations (int max_iterations) { max_iterations_ = std::max (max_iterations, 0); }
00159 
00160         /** \brief Get the maximum number of iterations.
00161           * \return max_iterations Maximum number if iterations to run
00162           */
00163         PCL_DEPRECATED (int getMaxIterations (), "[pcl::registration::CorrespondenceRejectorSampleConsensus::getMaxIterations] getMaxIterations is deprecated. Please use getMaximumIterations instead.");
00164 
00165         /** \brief Get the maximum number of iterations.
00166           * \return max_iterations Maximum number if iterations to run
00167           */
00168         inline int 
00169         getMaximumIterations () { return (max_iterations_); }
00170 
00171         /** \brief Get the best transformation after RANSAC rejection.
00172           * \return The homogeneous 4x4 transformation yielding the largest number of inliers.
00173           */
00174         inline Eigen::Matrix4f 
00175         getBestTransformation () { return best_transformation_; };
00176 
00177         /** \brief Specify whether the model should be refined internally using the variance of the inliers
00178           * \param[in] refine true if the model should be refined, false otherwise
00179           */
00180         inline void
00181         setRefineModel (const bool refine)
00182         {
00183           refine_ = refine;
00184         }
00185 
00186         /** \brief Get the internal refine parameter value as set by the user using setRefineModel */
00187         inline bool
00188         getRefineModel () const
00189         {
00190           return (refine_);
00191         }
00192       protected:
00193 
00194         /** \brief Apply the rejection algorithm.
00195           * \param[out] correspondences the set of resultant correspondences.
00196           */
00197         inline void 
00198         applyRejection (pcl::Correspondences &correspondences)
00199         {
00200           getRemainingCorrespondences (*input_correspondences_, correspondences);
00201         }
00202 
00203         double inlier_threshold_;
00204 
00205         int max_iterations_;
00206 
00207         PointCloudConstPtr input_;
00208         PointCloudPtr input_transformed_;
00209         PointCloudConstPtr target_;
00210 
00211         Eigen::Matrix4f best_transformation_;
00212 
00213         bool refine_;
00214       public:
00215         EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00216     };
00217   }
00218 }
00219 
00220 #include <pcl/registration/impl/correspondence_rejection_sample_consensus.hpp>
00221 
00222 #endif    // PCL_REGISTRATION_CORRESPONDENCE_REJECTION_SAMPLE_CONSENSUS_H_