pypose.randn_so3

class pypose.randn_so3(*lsize, sigma=1.0, **kwargs)

Returns so3_type LieTensor filled with random numbers.

\[\begin{aligned} \mathrm{data}[*, :] &= [\delta_x, \delta_y, \delta_z] \\ &= [\delta_x', \delta_y', \delta_z'] \cdot \theta, \end{aligned} \]

where \([\delta_x', \delta_y', \delta_z']\) is randomly generated from uniform distribution \(\mathcal{U}_{\mathrm{s}}\) on a standard sphere and \(\theta\) is generated from a normal distribution \(\mathcal{N}(0, \sigma)\), where sigma (\(\sigma\)) is the standard deviation.

The generated LieTensor satisfies that the corresponding rotation axis follows uniform distribution on the standard sphere and the rotation angle follows normal distribution.

Parameters:

• lsize (int...) – a sequence of integers defining the lshape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.

• sigma (float, optional) – standard deviation for the angle of the generated rotation. Default: 1.0.

• requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

• generator (torch.Generator, optional) – a pseudorandom number generator for sampling

• dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: None. If None, uses a global default (see torch.set_default_tensor_type()).

• layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.

• device (torch.device, optional) – the desired device of returned tensor. Default: None. If None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). Device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.

Returns:

a so3_type LieTensor

Return type:

LieTensor

Note

The uniform distributed points \([\delta_x', \delta_y', \delta_z']\) on a sphere are sampled using:

\[\delta_x' = \frac{x_0}{d}, \delta_y' = \frac{y_0}{d}, \delta_z' = \frac{z_0}{d}, \]

where

\[x_0, y_0, z_0 \sim \mathcal{N}(0, \sigma), \]

\[d = \sqrt{(x^2_0+y^2_0+z^2_0)}. \]

Note that the point \([x_0, y_0, z_0]\) follows 3-D Gaussian distribution, which is centrosymmetry with respect to \((0, 0, 0)\). Therefore, we have \(\delta_x'^2+\delta_y'^2+\delta_z'^2=1\) and the normalized points follow uniform distribution on a standard sphere, i.e., \([\delta_x', \delta_y', \delta_z'] \sim \mathcal{U}_{\mathrm{s}}\). The point \([\delta_x', \delta_y', \delta_z']\) can also represent an evenly sampled rotation axis.

Example

>>> pp.randn_so3()
so3Type LieTensor:
LieTensor([ 0.4811, -0.1487, -0.5949])  # Shape (3)
>>> pp.randn_so3(1)
so3Type LieTensor:
LieTensor([[0.0235, 0.0334, 1.2601]])   # Shape (1, 3)
>>> pp.randn_so3(2, sigma=0.1, requires_grad=True, dtype=torch.float64)
so3Type LieTensor:
tensor([[-0.0344,  0.0177,  0.0252],
        [-0.0040,  0.0032,  0.0149]], dtype=torch.float64, requires_grad=True)

Visualization of pypose.randn_so3(). A total of 5000 random rotations are sampled using pypose.randn_so3() and applied to the basepoint [0, 0, 1] (shown in blue).