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

source: build-install/usr/lib/python3.14/site-packages/scipy/spatial/transform/_rotation.py:2296

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([ 108.30981,   47.63721, -125.98432])

Sample a stack of rotations:

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

✗

array([[   3.02241,    3.11116, -111.87423],
       [ -23.6988 ,   70.6207 ,  126.14996],
       [ 150.28098,   40.06959,  -48.65577],
       [-104.06281,    1.53809,   -5.1012 ],
       [  41.27019,   24.18738,   33.25914]])

Aliases

scipy.spatial.transform.Rotation.random