Implementation:Google deepmind Dm control Transformations

Knowledge Sources	Google_deepmind_Dm_control
Domains	Mathematics, Robotics, 3D Geometry
Last Updated	2026-02-15 04:00 GMT

Overview

This module provides a comprehensive library of rigid-body transformation functions for converting between quaternions, rotation matrices, Euler angles, and axis-angle representations.

Description

The transformations module implements conversions across all major 3D rotation representations used in robotics and physics simulation. It supports Euler angle conversions with seven orderings (XYZ, XYX, ZYX, XZY, YZX, ZXY, YXZ) through a dispatch map, rotation matrix construction for each principal axis (X, Y, Z) with batch support via np.einsum, and full quaternion algebra including the Hamilton product, conjugate, inverse, difference, logarithm, distance, and vector rotation.

Key conversion functions include euler_to_rmat and euler_to_quat for Euler-to-matrix/quaternion conversion, quat_to_mat and mat_to_quat for quaternion-matrix interconversion, quat_to_axisangle and axisangle_to_quat for quaternion-axis-angle interconversion, and rmat_to_euler for matrix-to-Euler conversion. The quat_mul function uses a precomputed index-and-sign matrix approach for efficient Hamilton product computation that supports arbitrary leading batch dimensions.

The module handles gimbal lock (pole) edge cases with tolerance-based detection and logging warnings. Numerical precision is maintained through clipping functions with configurable tolerance. A 2D rotation matrix function is also provided.

Usage

Use this module whenever you need to convert between rotation representations, compute rotational distances or differences, rotate vectors by quaternions, or construct rotation matrices from Euler angles. It is the foundational mathematical utility for the entire dm_control ecosystem, essential for specifying body orientations, computing rotational errors for IK and rewards, and interfacing with MuJoCo's quaternion-based representation.

Code Reference

Source Location

• Repository: Google_deepmind_Dm_control
• File: dm_control/utils/transformations.py
• Lines: 1-659

Signature

def euler_to_quat(euler_vec, ordering='XYZ'):
    """Returns the quaternion corresponding to the provided euler angles."""

def euler_to_rmat(euler_vec, ordering='ZXZ', full=False):
    """Returns rotation matrix (or transform) for the given Euler rotations."""

def quat_conj(quat):
    """Return conjugate of quaternion."""

def quat_inv(quat):
    """Return inverse of quaternion."""

def quat_mul(quat1, quat2):
    """Computes the Hamilton product of two quaternions."""

def quat_diff(source, target):
    """Computes quaternion difference between source and target quaternions."""

def quat_log(quat, tol=_TOL):
    """Log of a quaternion."""

def quat_dist(source, target):
    """Computes distance between source and target quaternions."""

def quat_rotate(quat, vec):
    """Rotate a vector by a quaternion."""

def quat_to_axisangle(quat):
    """Returns the axis-angle corresponding to the provided quaternion."""

def quat_to_euler(quat, ordering='XYZ'):
    """Returns the euler angles corresponding to the provided quaternion."""

def quat_to_mat(quat):
    """Return homogeneous rotation matrix from quaternion."""

def mat_to_quat(mat):
    """Return quaternion from homogeneous or rotation matrix."""

def axisangle_to_quat(axisangle, tol=0.0):
    """Returns the quaternion corresponding to the provided axis-angle."""

def rmat_to_euler(rmat, ordering='ZXZ'):
    """Returns the euler angles corresponding to the provided rotation matrix."""

def rotation_x_axis(theta, full=False):
    """Returns a rotation matrix of a rotation about the X-axis."""

def rotation_y_axis(theta, full=False):
    """Returns a rotation matrix of a rotation about the Y-axis."""

def rotation_z_axis(theta, full=False):
    """Returns a rotation matrix of a rotation about the z-axis."""

def rotation_matrix_2d(theta):
    """Returns a 2D rotation matrix."""

Import

from dm_control.utils import transformations

I/O Contract

Inputs

Name	Type	Required	Description
quat	np.ndarray	Yes (quat functions)	Quaternion in [w, i, j, k] format
euler_vec	np.ndarray	Yes (euler functions)	Euler angle vector (3 components)
ordering	str	No	Euler angle ordering string, e.g. 'XYZ', 'ZYX' (default varies by function)
rmat	np.ndarray	Yes (rmat functions)	3x3 rotation matrix
mat	np.ndarray	Yes (mat_to_quat)	3x3 rotation matrix or 4x4 homogeneous transform
axisangle	np.ndarray	Yes (axisangle functions)	3-component axis-angle vector (axis direction, angle as magnitude)
theta	float or np.ndarray	Yes (rotation_*_axis)	Rotation angle(s) in radians, supports batched input
full	bool	No	If True, return 4x4 homogeneous transform instead of 3x3 rotation matrix
vec	np.ndarray	Yes (quat_rotate)	3-component position vector to rotate

Outputs

Name	Type	Description
quat	np.ndarray	Quaternion [w, i, j, k] (from conversion or algebra functions)
rmat	np.ndarray	3x3 rotation matrix or 4x4 homogeneous transform (batch dimensions supported)
euler_vec	np.ndarray	3-component Euler angle vector
axisangle	np.ndarray	3-component axis-angle vector
distance	float	Scalar rotational distance (from quat_dist)

Usage Examples

Basic Usage

from dm_control.utils import transformations
import numpy as np

# Convert Euler angles to quaternion
euler = np.array([0.1, 0.2, 0.3])
quat = transformations.euler_to_quat(euler, ordering='XYZ')

# Convert quaternion to rotation matrix
mat = transformations.quat_to_mat(quat)

# Compute quaternion product
quat1 = np.array([1.0, 0.0, 0.0, 0.0])
quat2 = transformations.euler_to_quat(np.array([0.0, 0.0, np.pi/4]))
result = transformations.quat_mul(quat1, quat2)

Rotational Distance

from dm_control.utils import transformations
import numpy as np

# Compute rotational distance between two orientations
source = np.array([1.0, 0.0, 0.0, 0.0])  # identity quaternion
target = transformations.euler_to_quat(np.array([0.1, 0.0, 0.0]))
dist = transformations.quat_dist(source, target)

# Rotate a vector by a quaternion
vec = np.array([1.0, 0.0, 0.0])
rotated = transformations.quat_rotate(target, vec)