`scipy.spatial.transform._rotation:Rotation.random`

source: /scipy/spatial/transform/_rotation.py:2291

Signature

staticmethod

def random(num: int | None = None, rng: np.random.Generator | None = None, *, shape: tuple[int, ...] | None = None, random_state = None) → Rotation

Summary

Generate rotations that are uniformly distributed on a sphere.

Extended Summary

Formally, the rotations follow the Haar-uniform distribution over the SO(3) group.

Parameters

num : int or None, optional

Number of random rotations to generate. If None (default), then a single rotation is generated.

rng : {None, int, `numpy.random.Generator`}, optional

If rng is passed by keyword, types other than numpy.random.Generator are passed to numpy.random.default_rng to instantiate a Generator. If rng is already a Generator instance, then the provided instance is used. Specify rng for repeatable function behavior.

If this argument is passed by position or random_state is passed by keyword, legacy behavior for the argument random_state applies:

If random_state is None (or numpy.random), the numpy.random.RandomState singleton is used.
If random_state is an int, a new RandomState instance is used, seeded with random_state.
If random_state is already a Generator or RandomState instance then that instance is used.

shape : tuple of ints, optional

Shape of random rotations to generate. If specified, num must be None.

Returns

random_rotation : `Rotation` instance: Contains a single rotation if num is None. Otherwise contains a stack of num rotations.

Notes

This function is optimized for efficiently sampling random rotation matrices in three dimensions. For generating random rotation matrices in higher dimensions, see scipy.stats.special_ortho_group.

Examples

from scipy.spatial.transform import Rotation as R

✓

Sample a single rotation:

R.random().as_euler('zxy', degrees=True)

✗

array([51.86589, -7.59653, -8.07539])

Sample a stack of rotations:

R.random(5).as_euler('zxy', degrees=True)

✗

array([[ 172.19225,   31.80042, -147.99033],
       [ 144.45433,  -23.61466,  179.46657],
       [ -67.72847,  -16.92282,  -54.72594],
       [ -38.49567,  -43.46968,   45.01377],
       [ -79.23888,   50.44661, -127.61762]])

Aliases

scipy.spatial.transform.Rotation.random