Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/common/include/pcl/common/random.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 the copyright holder(s) 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_COMMON_RANDOM_H_
00041 #define PCL_COMMON_RANDOM_H_
00042 
00043 #ifdef __GNUC__
00044 #pragma GCC system_header 
00045 #endif
00046 
00047 #include <boost/random/uniform_real.hpp>
00048 #include <boost/random/uniform_int.hpp>
00049 #include <boost/random/variate_generator.hpp>
00050 #include <boost/random/normal_distribution.hpp>
00051 #include <boost/random/mersenne_twister.hpp>
00052 #include <pcl/pcl_macros.h>
00053 
00054 namespace pcl 
00055 {
00056   namespace common 
00057   {
00058     /// uniform distribution dummy struct
00059     template <typename T> struct uniform_distribution;
00060     /// uniform distribution int specialized
00061     template<> 
00062     struct uniform_distribution<int> 
00063     {
00064       typedef boost::uniform_int<int> type;
00065     };
00066     /// uniform distribution float specialized
00067     template<> 
00068     struct uniform_distribution<float> 
00069     {
00070       typedef boost::uniform_real<float> type;
00071     };
00072     ///  normal distribution
00073     template<typename T> 
00074     struct normal_distribution
00075     {
00076       typedef boost::normal_distribution<T> type;
00077     };
00078 
00079     /** \brief UniformGenerator class generates a random number from range [min, max] at each run picked
00080       * according to a uniform distribution i.e eaach number within [min, max] has almost the same 
00081       * probability of being drawn.
00082       *
00083       * \author Nizar Sallem
00084       */
00085     template<typename T>
00086     class UniformGenerator 
00087     {
00088       public:
00089         struct Parameters
00090         {
00091             Parameters (T _min = 0, T _max = 1, pcl::uint32_t _seed = 1)
00092             : min (_min)
00093             , max (_max)
00094             , seed (_seed)
00095           {}
00096 
00097           T min;
00098           T max;
00099           pcl::uint32_t seed;
00100         };
00101 
00102         /** Constructor
00103           * \param min: included lower bound
00104           * \param max: included higher bound
00105           * \param seed: seeding value
00106           */
00107         UniformGenerator(T min = 0, T max = 1, pcl::uint32_t seed = -1);
00108 
00109         /** Constructor
00110           * \param parameters uniform distribution parameters and generator seed
00111           */
00112         UniformGenerator(const Parameters& paramters);
00113 
00114         /** Change seed value
00115           * \param[in] seed new generator seed value
00116           */
00117         void 
00118         setSeed (pcl::uint32_t seed);
00119 
00120         /** Set the uniform number generator parameters
00121           * \param[in] min minimum allowed value
00122           * \param[in] max maximum allowed value
00123           * \param[in] seed random number generator seed (applied if != -1)
00124           */
00125         void 
00126         setParameters (T min, T max, pcl::uint32_t seed = -1);
00127 
00128         /** Set generator parameters
00129           * \param parameters uniform distribution parameters and generator seed
00130           */
00131         void
00132         setParameters (const Parameters& parameters);
00133 
00134         /// \return uniform distribution parameters and generator seed
00135         const Parameters&
00136         getParameters () { return (parameters_); }
00137 
00138         /// \return a randomly generated number in the interval [min, max]
00139         inline T 
00140         run () { return (generator_ ()); }
00141 
00142       private:
00143         typedef boost::mt19937 EngineType;
00144         typedef typename uniform_distribution<T>::type DistributionType;
00145         /// parameters
00146         Parameters parameters_;
00147         /// uniform distribution
00148         DistributionType distribution_;
00149         /// random number generator
00150         EngineType rng_;
00151         /// generator of random number from a uniform distribution
00152         boost::variate_generator<EngineType&, DistributionType> generator_;
00153     };
00154 
00155     /** \brief NormalGenerator class generates a random number from a normal distribution specified
00156       * by (mean, sigma).
00157       *
00158       * \author Nizar Sallem
00159       */
00160     template<typename T>
00161     class NormalGenerator 
00162     {
00163       public:
00164         struct Parameters
00165         {
00166             Parameters (T _mean = 0, T _sigma = 1, pcl::uint32_t _seed = 1)
00167             : mean (_mean)
00168             , sigma (_sigma)
00169             , seed (_seed)
00170           {}
00171 
00172           T mean;
00173           T sigma;
00174           pcl::uint32_t seed;
00175         };
00176 
00177         /** Constructor
00178           * \param[in] mean normal mean
00179           * \param[in] sigma normal variation
00180           * \param[in] seed seeding value
00181           */
00182         NormalGenerator(T mean = 0, T sigma = 1, pcl::uint32_t seed = -1);
00183 
00184         /** Constructor
00185           * \param parameters normal distribution parameters and seed
00186           */
00187         NormalGenerator(const Parameters& parameters);
00188 
00189         /** Change seed value
00190           * \param[in] seed new seed value
00191           */
00192         void 
00193         setSeed (pcl::uint32_t seed);
00194 
00195         /** Set the normal number generator parameters
00196           * \param[in] mean mean of the normal distribution
00197           * \param[in] sigma standard variation of the normal distribution
00198           * \param[in] seed random number generator seed (applied if != -1)
00199           */
00200         void 
00201         setParameters (T mean, T sigma, pcl::uint32_t seed = -1);
00202 
00203         /** Set generator parameters
00204           * \param parameters normal distribution parameters and seed
00205           */
00206         void
00207         setParameters (const Parameters& parameters);
00208 
00209         /// \return normal distribution parameters and generator seed
00210         const Parameters&
00211         getParameters () { return (parameters_); }
00212 
00213         /// \return a randomly generated number in the normal distribution (mean, sigma)
00214         inline T 
00215         run () { return (generator_ ()); }
00216 
00217         typedef boost::mt19937 EngineType;
00218         typedef typename normal_distribution<T>::type DistributionType;
00219         /// parameters
00220         Parameters parameters_;
00221         /// normal distribution
00222         DistributionType distribution_;
00223         /// random number generator
00224         EngineType rng_;
00225         /// generator of random number from a normal distribution
00226         boost::variate_generator<EngineType&, DistributionType > generator_;
00227     };
00228   }
00229 }
00230 
00231 #include <pcl/common/impl/random.hpp>
00232 
00233 #endif