Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/sample_consensus/include/pcl/sample_consensus/mlesac.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2009, 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 
00041 #ifndef PCL_SAMPLE_CONSENSUS_MLESAC_H_
00042 #define PCL_SAMPLE_CONSENSUS_MLESAC_H_
00043 
00044 #include <pcl/sample_consensus/sac.h>
00045 #include <pcl/sample_consensus/sac_model.h>
00046 
00047 namespace pcl
00048 {
00049   /** \brief @b MaximumLikelihoodSampleConsensus represents an implementation of the MLESAC (Maximum Likelihood 
00050     * Estimator SAmple Consensus) algorithm, as described in: "MLESAC: A new robust estimator with application to 
00051     * estimating image geometry", P.H.S. Torr and A. Zisserman, Computer Vision and Image Understanding, vol 78, 2000.
00052     * \note MLESAC is useful in situations where most of the data samples belong to the model, and a fast outlier rejection algorithm is needed.
00053     * \author Radu B. Rusu
00054     * \ingroup sample_consensus
00055     */
00056   template <typename PointT>
00057   class MaximumLikelihoodSampleConsensus : public SampleConsensus<PointT>
00058   {
00059     typedef typename SampleConsensusModel<PointT>::Ptr SampleConsensusModelPtr;
00060     typedef typename SampleConsensusModel<PointT>::PointCloudConstPtr PointCloudConstPtr; 
00061 
00062     public:
00063       typedef boost::shared_ptr<MaximumLikelihoodSampleConsensus> Ptr;
00064       typedef boost::shared_ptr<const MaximumLikelihoodSampleConsensus> ConstPtr;
00065 
00066       using SampleConsensus<PointT>::max_iterations_;
00067       using SampleConsensus<PointT>::threshold_;
00068       using SampleConsensus<PointT>::iterations_;
00069       using SampleConsensus<PointT>::sac_model_;
00070       using SampleConsensus<PointT>::model_;
00071       using SampleConsensus<PointT>::model_coefficients_;
00072       using SampleConsensus<PointT>::inliers_;
00073       using SampleConsensus<PointT>::probability_;
00074 
00075       /** \brief MLESAC (Maximum Likelihood Estimator SAmple Consensus) main constructor
00076         * \param[in] model a Sample Consensus model
00077         */
00078       MaximumLikelihoodSampleConsensus (const SampleConsensusModelPtr &model) : 
00079         SampleConsensus<PointT> (model),
00080         iterations_EM_ (3),      // Max number of EM (Expectation Maximization) iterations
00081         sigma_ (0)
00082       {
00083         max_iterations_ = 10000; // Maximum number of trials before we give up.
00084       }
00085 
00086       /** \brief MLESAC (Maximum Likelihood Estimator SAmple Consensus) main constructor
00087         * \param[in] model a Sample Consensus model
00088         * \param[in] threshold distance to model threshold
00089         */
00090       MaximumLikelihoodSampleConsensus (const SampleConsensusModelPtr &model, double threshold) : 
00091         SampleConsensus<PointT> (model, threshold),
00092         iterations_EM_ (3),      // Max number of EM (Expectation Maximization) iterations
00093         sigma_ (0)
00094       {
00095         max_iterations_ = 10000; // Maximum number of trials before we give up.
00096       }
00097 
00098       /** \brief Compute the actual model and find the inliers
00099         * \param[in] debug_verbosity_level enable/disable on-screen debug information and set the verbosity level
00100         */
00101       bool 
00102       computeModel (int debug_verbosity_level = 0);
00103 
00104       /** \brief Set the number of EM iterations.
00105         * \param[in] iterations the number of EM iterations
00106         */
00107       inline void 
00108       setEMIterations (int iterations) { iterations_EM_ = iterations; }
00109 
00110       /** \brief Get the number of EM iterations. */
00111       inline int 
00112       getEMIterations () const { return (iterations_EM_); }
00113 
00114 
00115     protected:
00116       /** \brief Compute the median absolute deviation:
00117         * \f[
00118         * MAD = \sigma * median_i (| Xi - median_j(Xj) |)
00119         * \f]
00120         * \note Sigma needs to be chosen carefully (a good starting sigma value is 1.4826)
00121         * \param[in] cloud the point cloud data message
00122         * \param[in] indices the set of point indices to use
00123         * \param[in] sigma the sigma value
00124         */
00125       double 
00126       computeMedianAbsoluteDeviation (const PointCloudConstPtr &cloud, 
00127                                       const boost::shared_ptr <std::vector<int> > &indices, 
00128                                       double sigma);
00129 
00130       /** \brief Determine the minimum and maximum 3D bounding box coordinates for a given set of points
00131         * \param[in] cloud the point cloud message
00132         * \param[in] indices the set of point indices to use
00133         * \param[out] min_p the resultant minimum bounding box coordinates
00134         * \param[out] max_p the resultant maximum bounding box coordinates
00135         */
00136       void 
00137       getMinMax (const PointCloudConstPtr &cloud, 
00138                  const boost::shared_ptr <std::vector<int> > &indices, 
00139                  Eigen::Vector4f &min_p, 
00140                  Eigen::Vector4f &max_p);
00141 
00142       /** \brief Compute the median value of a 3D point cloud using a given set point indices and return it as a Point32.
00143         * \param[in] cloud the point cloud data message
00144         * \param[in] indices the point indices
00145         * \param[out] median the resultant median value
00146         */
00147       void 
00148       computeMedian (const PointCloudConstPtr &cloud, 
00149                      const boost::shared_ptr <std::vector<int> > &indices, 
00150                      Eigen::Vector4f &median);
00151 
00152     private:
00153       /** \brief Maximum number of EM (Expectation Maximization) iterations. */
00154       int iterations_EM_;
00155       /** \brief The MLESAC sigma parameter. */
00156       double sigma_;
00157   };
00158 }
00159 
00160 #ifdef PCL_NO_PRECOMPILE
00161 #include <pcl/sample_consensus/impl/mlesac.hpp>
00162 #endif
00163 
00164 #endif  //#ifndef PCL_SAMPLE_CONSENSUS_MLESAC_H_