Point Cloud Library (PCL)  1.7.1
random.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2012, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of the copyright holder(s) nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  * $Id$
37  *
38  */
39 
40 #ifndef PCL_COMMON_RANDOM_H_
41 #define PCL_COMMON_RANDOM_H_
42 
43 #ifdef __GNUC__
44 #pragma GCC system_header
45 #endif
46 
47 #include <boost/random/uniform_real.hpp>
48 #include <boost/random/uniform_int.hpp>
49 #include <boost/random/variate_generator.hpp>
50 #include <boost/random/normal_distribution.hpp>
51 #include <boost/random/mersenne_twister.hpp>
52 #include <pcl/pcl_macros.h>
53 
54 namespace pcl
55 {
56  namespace common
57  {
58  /// uniform distribution dummy struct
59  template <typename T> struct uniform_distribution;
60  /// uniform distribution int specialized
61  template<>
62  struct uniform_distribution<int>
63  {
64  typedef boost::uniform_int<int> type;
65  };
66  /// uniform distribution float specialized
67  template<>
68  struct uniform_distribution<float>
69  {
70  typedef boost::uniform_real<float> type;
71  };
72  /// normal distribution
73  template<typename T>
75  {
76  typedef boost::normal_distribution<T> type;
77  };
78 
79  /** \brief UniformGenerator class generates a random number from range [min, max] at each run picked
80  * according to a uniform distribution i.e eaach number within [min, max] has almost the same
81  * probability of being drawn.
82  *
83  * \author Nizar Sallem
84  */
85  template<typename T>
87  {
88  public:
89  struct Parameters
90  {
91  Parameters (T _min = 0, T _max = 1, pcl::uint32_t _seed = 1)
92  : min (_min)
93  , max (_max)
94  , seed (_seed)
95  {}
96 
97  T min;
98  T max;
99  pcl::uint32_t seed;
100  };
101 
102  /** Constructor
103  * \param min: included lower bound
104  * \param max: included higher bound
105  * \param seed: seeding value
106  */
107  UniformGenerator(T min = 0, T max = 1, pcl::uint32_t seed = -1);
108 
109  /** Constructor
110  * \param parameters uniform distribution parameters and generator seed
111  */
112  UniformGenerator(const Parameters& paramters);
113 
114  /** Change seed value
115  * \param[in] seed new generator seed value
116  */
117  void
118  setSeed (pcl::uint32_t seed);
119 
120  /** Set the uniform number generator parameters
121  * \param[in] min minimum allowed value
122  * \param[in] max maximum allowed value
123  * \param[in] seed random number generator seed (applied if != -1)
124  */
125  void
126  setParameters (T min, T max, pcl::uint32_t seed = -1);
127 
128  /** Set generator parameters
129  * \param parameters uniform distribution parameters and generator seed
130  */
131  void
132  setParameters (const Parameters& parameters);
133 
134  /// \return uniform distribution parameters and generator seed
135  const Parameters&
136  getParameters () { return (parameters_); }
137 
138  /// \return a randomly generated number in the interval [min, max]
139  inline T
140  run () { return (generator_ ()); }
141 
142  private:
143  typedef boost::mt19937 EngineType;
144  typedef typename uniform_distribution<T>::type DistributionType;
145  /// parameters
146  Parameters parameters_;
147  /// uniform distribution
148  DistributionType distribution_;
149  /// random number generator
150  EngineType rng_;
151  /// generator of random number from a uniform distribution
152  boost::variate_generator<EngineType&, DistributionType> generator_;
153  };
154 
155  /** \brief NormalGenerator class generates a random number from a normal distribution specified
156  * by (mean, sigma).
157  *
158  * \author Nizar Sallem
159  */
160  template<typename T>
162  {
163  public:
164  struct Parameters
165  {
166  Parameters (T _mean = 0, T _sigma = 1, pcl::uint32_t _seed = 1)
167  : mean (_mean)
168  , sigma (_sigma)
169  , seed (_seed)
170  {}
171 
172  T mean;
173  T sigma;
174  pcl::uint32_t seed;
175  };
176 
177  /** Constructor
178  * \param[in] mean normal mean
179  * \param[in] sigma normal variation
180  * \param[in] seed seeding value
181  */
182  NormalGenerator(T mean = 0, T sigma = 1, pcl::uint32_t seed = -1);
183 
184  /** Constructor
185  * \param parameters normal distribution parameters and seed
186  */
187  NormalGenerator(const Parameters& parameters);
188 
189  /** Change seed value
190  * \param[in] seed new seed value
191  */
192  void
193  setSeed (pcl::uint32_t seed);
194 
195  /** Set the normal number generator parameters
196  * \param[in] mean mean of the normal distribution
197  * \param[in] sigma standard variation of the normal distribution
198  * \param[in] seed random number generator seed (applied if != -1)
199  */
200  void
201  setParameters (T mean, T sigma, pcl::uint32_t seed = -1);
202 
203  /** Set generator parameters
204  * \param parameters normal distribution parameters and seed
205  */
206  void
207  setParameters (const Parameters& parameters);
208 
209  /// \return normal distribution parameters and generator seed
210  const Parameters&
211  getParameters () { return (parameters_); }
212 
213  /// \return a randomly generated number in the normal distribution (mean, sigma)
214  inline T
215  run () { return (generator_ ()); }
216 
217  typedef boost::mt19937 EngineType;
219  /// parameters
221  /// normal distribution
223  /// random number generator
225  /// generator of random number from a normal distribution
226  boost::variate_generator<EngineType&, DistributionType > generator_;
227  };
228  }
229 }
230 
231 #include <pcl/common/impl/random.hpp>
232 
233 #endif