cv::RNG Class Reference

Random Number Generator. More...

#include <opencv2/core.hpp>

Collaboration diagram for cv::RNG:

Public Types
enum	{   UNIFORM = 0 ,   NORMAL = 1 }

Public Member Functions
	RNG ()
	constructor
	RNG (uint64 state)
void	fill (InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange=false)
	Fills arrays with random numbers.
double	gaussian (double sigma)
	Returns the next random number sampled from the Gaussian distribution.
unsigned	next ()
	operator double ()
	operator float ()
	operator schar ()
	operator short ()
	operator uchar ()
	operator unsigned ()
	operator ushort ()
unsigned	operator() ()
	returns a random integer sampled uniformly from [0, N).
unsigned	operator() (unsigned N)
bool	operator== (const RNG &other) const
double	uniform (double a, double b)
float	uniform (float a, float b)
int	uniform (int a, int b)
	returns uniformly distributed integer random number from [a,b) range

Public Attributes
uint64	state

Detailed Description

Random Number Generator.

Random number generator. It encapsulates the state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia ( http://en.wikipedia.org/wiki/Multiply-with-carry ). Gaussian-distribution random numbers are generated using the Ziggurat algorithm ( http://en.wikipedia.org/wiki/Ziggurat_algorithm ), introduced by G. Marsaglia and W. W. Tsang.

Examples

samples/cpp/image_alignment.cpp, samples/cpp/snippets/epipolar_lines.cpp, samples/cpp/snippets/falsecolor.cpp, samples/cpp/snippets/kmeans.cpp, samples/cpp/tutorial_code/ImgProc/basic_drawing/Drawing_2.cpp, and samples/cpp/tutorial_code/ImgTrans/copyMakeBorder_demo.cpp.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
UNIFORM
NORMAL

Constructor & Destructor Documentation

RNG() [1/2]

cv::RNG::RNG

(

)

constructor

These are the RNG constructors. The first form sets the state to some pre-defined value, equal to 2**32-1 in the current implementation. The second form sets the state to the specified value. If you passed state=0 , the constructor uses the above default value instead to avoid the singular random number sequence, consisting of all zeros.

RNG() [2/2]

cv::RNG::RNG

(

uint64

state

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

state

64-bit value used to initialize the RNG.

Member Function Documentation

fill()

void cv::RNG::fill	(	InputOutputArray	mat,
		int	distType,
		InputArray	a,
		InputArray	b,
		bool	saturateRange = false
	)

Fills arrays with random numbers.

Parameters

mat	2D or N-dimensional matrix; currently matrices with more than 4 channels are not supported by the methods, use Mat::reshape as a possible workaround.
distType	distribution type, RNG::UNIFORM or RNG::NORMAL.
a	first distribution parameter; in case of the uniform distribution, this is an inclusive lower boundary, in case of the normal distribution, this is a mean value.
b	second distribution parameter; in case of the uniform distribution, this is a non-inclusive upper boundary, in case of the normal distribution, this is a standard deviation (diagonal of the standard deviation matrix or the full standard deviation matrix).
saturateRange	pre-saturation flag; for uniform distribution only; if true, the method will first convert a and b to the acceptable value range (according to the mat datatype) and then will generate uniformly distributed random numbers within the range [saturate(a), saturate(b)), if saturateRange=false, the method will generate uniformly distributed random numbers in the original range [a, b) and then will saturate them, it means, for example, that theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX) will likely produce array mostly filled with 0's and 255's, since the range (0, 255) is significantly smaller than [-DBL_MAX, DBL_MAX).

Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariance matrix directly. To do that, the method generates samples from multi-dimensional standard Gaussian distribution with zero mean and identity covariation matrix, and then transforms them using transform to get samples from the specified Gaussian distribution.

Examples

samples/cpp/snippets/kmeans.cpp.

gaussian()

double cv::RNG::gaussian

(

double

sigma

)

Returns the next random number sampled from the Gaussian distribution.

Parameters

sigma

standard deviation of the distribution.

The method transforms the state using the MWC algorithm and returns the next random number from the Gaussian distribution N(0,sigma) . That is, the mean value of the returned random numbers is zero and the standard deviation is the specified sigma .

next()

unsigned cv::RNG::next

(

)

The method updates the state using the MWC algorithm and returns the next 32-bit random number.

operator double()

cv::RNG::operator double

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator float()

cv::RNG::operator float

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator schar()

cv::RNG::operator schar

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator short()

cv::RNG::operator short

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator uchar()

cv::RNG::operator uchar

(

)

Each of the methods updates the state using the MWC algorithm and returns the next random number of the specified type. In case of integer types, the returned number is from the available value range for the specified type. In case of floating-point types, the returned value is from [0,1) range.

operator unsigned()

cv::RNG::operator unsigned

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator ushort()

cv::RNG::operator ushort

(

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator()() [1/2]

unsigned cv::RNG::operator()

(

)

returns a random integer sampled uniformly from [0, N).

The methods transform the state using the MWC algorithm and return the next random number. The first form is equivalent to RNG::next . The second form returns the random number modulo N, which means that the result is in the range [0, N) .

operator()() [2/2]

unsigned cv::RNG::operator()

(

unsigned

N

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

N	upper non-inclusive boundary of the returned random number.

operator==()

bool cv::RNG::operator==

(

const RNG &

other

)

const

uniform() [1/3]

double cv::RNG::uniform	(	double	a,
		double	b
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uniform() [2/3]

float cv::RNG::uniform	(	float	a,
		float	b
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uniform() [3/3]

int cv::RNG::uniform	(	int	a,
		int	b
	)

returns uniformly distributed integer random number from [a,b) range

The methods transform the state using the MWC algorithm and return the next uniformly-distributed random number of the specified type, deduced from the input parameter type, from the range [a, b) . There is a nuance illustrated by the following sample:

RNG rng;
 
// always produces 0
double a = rng.uniform(0, 1);
 
// produces double from [0, 1)
double a1 = rng.uniform((double)0, (double)1);
 
// produces float from [0, 1)
float b = rng.uniform(0.f, 1.f);
 
// produces double from [0, 1)
double c = rng.uniform(0., 1.);
 
// may cause compiler error because of ambiguity:
//  RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
double d = rng.uniform(0, 0.999999);

The compiler does not take into account the type of the variable to which you assign the result of RNG::uniform . The only thing that matters to the compiler is the type of a and b parameters. So, if you want a floating-point random number, but the range boundaries are integer numbers, either put dots in the end, if they are constants, or use explicit type cast operators, as in the a1 initialization above.

Parameters

a	lower inclusive boundary of the returned random number.
b	upper non-inclusive boundary of the returned random number.

Examples

samples/cpp/snippets/epipolar_lines.cpp, samples/cpp/snippets/falsecolor.cpp, samples/cpp/snippets/kmeans.cpp, samples/cpp/snippets/watershed.cpp, and samples/cpp/tutorial_code/ImgProc/basic_drawing/Drawing_2.cpp.

Member Data Documentation

state

uint64 cv::RNG::state

---

The documentation for this class was generated from the following file:

• opencv2/core.hpp