"""
Random Numbers Utilities
========================
Random number generator objects:
- :func:`colour.algebra.random_triplet_generator`
References
----------
- :cite:`Laurent2012a` : Laurent. (2012). Reproducibility of python
pseudo-random numbers across systems and versions? Retrieved January 20,
2015, from
http://stackoverflow.com/questions/8786084/\
reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions
"""
from __future__ import annotations
import typing
import numpy as np
if typing.TYPE_CHECKING:
from colour.hints import ArrayLike, NDArrayFloat
from colour.utilities import as_float_array, tstack
__author__ = "Colour Developers"
__copyright__ = "Copyright 2013 Colour Developers"
__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
__maintainer__ = "Colour Developers"
__email__ = "colour-developers@colour-science.org"
__status__ = "Production"
__all__ = [
"RANDOM_STATE",
"random_triplet_generator",
]
RANDOM_STATE = np.random.RandomState()
[docs]
def random_triplet_generator(
size: int,
limits: ArrayLike = ([0, 1], [0, 1], [0, 1]),
random_state: np.random.RandomState = RANDOM_STATE,
) -> NDArrayFloat:
"""
Generate random triplets using a pseudo-random number generator.
Generate an array of random triplets with values constrained within
specified limits for each dimension. The triplets are generated using
a Mersenne Twister pseudo-random number generator.
Parameters
----------
size
Number of random triplets to generate.
limits
Random value limits for each axis of the triplets, specified as a
sequence of [min, max] pairs. Default limits are [0, 1] for each
axis.
random_state
Mersenne Twister pseudo-random number generator instance used for
generating random values.
Returns
-------
:class:`numpy.ndarray`
Array of shape (size, 3) containing the generated random triplets.
Notes
-----
- The test is assuming that :func:`np.random.RandomState` definition
will return the same sequence no matter which *OS* or *Python*
version is used. There is however no formal promise about the
*prng* sequence reproducibility of either *Python* or *Numpy*
implementations, see :cite:`Laurent2012a`.
Examples
--------
>>> from pprint import pprint
>>> prng = np.random.RandomState(4)
>>> random_triplet_generator(10, random_state=prng)
... # doctest: +ELLIPSIS
array([[ 0.9670298..., 0.7793829..., 0.4361466...],
[ 0.5472322..., 0.1976850..., 0.9489773...],
[ 0.9726843..., 0.8629932..., 0.7863059...],
[ 0.7148159..., 0.9834006..., 0.8662893...],
[ 0.6977288..., 0.1638422..., 0.1731654...],
[ 0.2160895..., 0.5973339..., 0.0749485...],
[ 0.9762744..., 0.0089861..., 0.6007427...],
[ 0.0062302..., 0.3865712..., 0.1679721...],
[ 0.2529823..., 0.0441600..., 0.7333801...],
[ 0.4347915..., 0.9566529..., 0.4084438...]])
"""
limit_x, limit_y, limit_z = as_float_array(limits)
return tstack(
[
random_state.uniform(limit_x[0], limit_x[1], size=size),
random_state.uniform(limit_y[0], limit_y[1], size=size),
random_state.uniform(limit_z[0], limit_z[1], size=size),
]
)
