Implementation:Google deepmind Dm control Variation Rotations
| Knowledge Sources | |
|---|---|
| Domains | Reinforcement_Learning, Domain_Randomization, Robotics |
| Last Updated | 2026-02-15 04:00 GMT |
Overview
Variation classes for randomizing 3D rotations expressed as quaternions, supporting uniform sampling, axis-angle construction, quaternion composition, and vector rotation within the Variation framework.
Description
The rotations module provides four Variation subclasses that handle 3D rotation randomization using quaternion mathematics. All classes produce quaternion arrays (4-element vectors in [w, x, y, z] format) or rotated 3D vectors.
UniformQuaternion samples uniformly distributed unit quaternions using the Shoemake method: three uniform random values are mapped to quaternion components via trigonometric functions, ensuring uniform coverage of the rotation group SO(3). QuaternionFromAxisAngle constructs a quaternion from an axis and angle, both of which may be variation objects, using transformations.axisangle_to_quat for the conversion.
QuaternionPreMultiply composes a variation-generated quaternion with an existing quaternion value via transformations.quat_mul. In non-cumulative mode, the new quaternion is pre-multiplied with the initial value; in cumulative mode, it is pre-multiplied with the current value, enabling incremental rotation drift. QuaternionRotate applies a variation-generated quaternion rotation to a 3D vector via transformations.quat_rotate, where the vector can come from another variation or from the initial/current value.
The module also defines the constant IDENTITY_QUATERNION = [1, 0, 0, 0] for convenience.
Usage
Use these classes when building Composer tasks that require randomization of 3D orientations. UniformQuaternion is the standard choice for fully random orientations. Use QuaternionFromAxisAngle for constrained rotations around specific axes. Use QuaternionPreMultiply to apply random perturbations to existing orientations, and QuaternionRotate to rotate position vectors.
Code Reference
Source Location
- Repository: Google_deepmind_Dm_control
- File: dm_control/composer/variation/rotations.py
- Lines: 1-147
Signature
IDENTITY_QUATERNION = np.array([1., 0., 0., 0.])
class UniformQuaternion(base.Variation):
def __call__(self, initial_value=None, current_value=None, random_state=None):
...
class QuaternionFromAxisAngle(base.Variation):
def __init__(self, axis, angle):
...
class QuaternionPreMultiply(base.Variation):
def __init__(self, quat, cumulative=False):
...
class QuaternionRotate(base.Variation):
def __init__(self, quat, vec=None, cumulative=False):
...
Import
from dm_control.composer.variation import rotations
from dm_control.composer.variation.rotations import UniformQuaternion, QuaternionFromAxisAngle
I/O Contract
Inputs (UniformQuaternion)
| Name | Type | Required | Description |
|---|---|---|---|
| (no constructor args) | -- | -- | Samples a uniformly random unit quaternion |
Inputs (QuaternionFromAxisAngle)
| Name | Type | Required | Description |
|---|---|---|---|
| axis | Variation or array-like | Yes | The rotation axis (3D vector), may be a variation |
| angle | Variation or float | Yes | The rotation angle in radians, may be a variation |
Inputs (QuaternionPreMultiply)
| Name | Type | Required | Description |
|---|---|---|---|
| quat | Variation | Yes | Variation generating the quaternion to pre-multiply |
| cumulative | bool | No | If True, pre-multiply with current_value; if False (default), with initial_value
|
Inputs (QuaternionRotate)
| Name | Type | Required | Description |
|---|---|---|---|
| quat | Variation | Yes | Variation generating the rotation quaternion |
| vec | Variation or None | No | Variation generating the vector to rotate; if None, uses initial/current value
|
| cumulative | bool | No | If True and vec=None, rotate current_value; if False (default), rotate initial_value
|
Outputs
| Name | Type | Description |
|---|---|---|
| UniformQuaternion return | numpy.ndarray (4,) |
A uniformly sampled unit quaternion [w, x, y, z] |
| QuaternionFromAxisAngle return | numpy.ndarray (4,) |
Quaternion corresponding to the given axis-angle rotation |
| QuaternionPreMultiply return | numpy.ndarray (4,) |
Result of quaternion multiplication |
| QuaternionRotate return | numpy.ndarray (3,) |
The rotated 3D vector |
Usage Examples
from dm_control.composer.variation import rotations, distributions
import numpy as np
rng = np.random.RandomState(42)
# Sample a fully random orientation
random_quat = rotations.UniformQuaternion()
quat = random_quat(random_state=rng) # e.g. [0.35, 0.12, -0.89, 0.27]
# Create a rotation around the z-axis with a random angle
z_rotation = rotations.QuaternionFromAxisAngle(
axis=[0, 0, 1],
angle=distributions.Uniform(0, 2 * np.pi)
)
quat_z = z_rotation(random_state=rng)
# Apply a random perturbation to an existing orientation
perturb = rotations.QuaternionPreMultiply(
quat=rotations.QuaternionFromAxisAngle(
axis=distributions.UniformPointOnSphere(),
angle=distributions.Normal(0, 0.1)
)
)
initial_quat = rotations.IDENTITY_QUATERNION
perturbed = perturb(initial_value=initial_quat, random_state=rng)
# Rotate a position vector by a random quaternion
rotated_pos = rotations.QuaternionRotate(
quat=rotations.UniformQuaternion()
)
initial_pos = np.array([1.0, 0.0, 0.0])
new_pos = rotated_pos(initial_value=initial_pos, random_state=rng)