"""
Random Numbers Utilities
========================
Define the 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 numpy as np
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 = np.array([[0, 1], [0, 1], [0, 1]]),
random_state: np.random.RandomState = RANDOM_STATE,
) -> NDArrayFloat:
"""
Return a generator yielding random triplets.
Parameters
----------
size
Generator size.
limits
Random values limits on each triplet axis.
random_state
Mersenne Twister pseudo-random number generator.
Returns
-------
:class:`numpy.ndarray`
Random triplet generator.
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),
]
)
