Implementation:Haosulab ManiSkill RotationConversions

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, 3D Geometry
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool for converting between rotation representations (quaternions, rotation matrices, axis-angle, Euler angles) using PyTorch tensors.

Description

The rotation_conversions.py module provides a comprehensive set of differentiable rotation conversion functions pulled from PyTorch3D (Meta Platforms, BSD-licensed) to avoid requiring the full PyTorch3D package as a dependency. All functions operate on PyTorch tensors and support batched inputs.

The module implements conversions between the following rotation representations:

Quaternions (real-first format, shape (..., 4))
Rotation matrices (shape (..., 3, 3))
Axis-angle (shape (..., 3))
Euler angles (any convention string like "XYZ", "ZYX", etc.)
6D rotation representation (shape (..., 6)) -- the continuous rotation representation from Zhou et al.

Key functions include:

quaternion_to_matrix() / matrix_to_quaternion()
quaternion_to_axis_angle() / axis_angle_to_quaternion()
matrix_to_axis_angle() / axis_angle_to_matrix()
euler_angles_to_matrix() / matrix_to_euler_angles()
rotation_6d_to_matrix() / matrix_to_rotation_6d()
quaternion_multiply() / quaternion_apply()

The transformation matrices assume column-vector convention (post-multiplication). Quaternions use the [w, x, y, z] (real-first) convention.

Usage

Import specific conversion functions when implementing rotation-related logic in environment tasks, reward computation, or observation processing. These are heavily used by the Pose struct and throughout the codebase.

Code Reference

Source Location

Repository: Haosulab_ManiSkill
File: mani_skill/utils/geometry/rotation_conversions.py

Signature

def quaternion_to_matrix(quaternions: torch.Tensor) -> torch.Tensor: ...
def matrix_to_quaternion(matrix: torch.Tensor) -> torch.Tensor: ...
def quaternion_to_axis_angle(quaternions: torch.Tensor) -> torch.Tensor: ...
def axis_angle_to_quaternion(axis_angle: torch.Tensor) -> torch.Tensor: ...
def euler_angles_to_matrix(euler_angles: torch.Tensor, convention: str) -> torch.Tensor: ...
def matrix_to_euler_angles(matrix: torch.Tensor, convention: str) -> torch.Tensor: ...
def rotation_6d_to_matrix(d6: torch.Tensor) -> torch.Tensor: ...
def matrix_to_rotation_6d(matrix: torch.Tensor) -> torch.Tensor: ...
def quaternion_multiply(a: torch.Tensor, b: torch.Tensor) -> torch.Tensor: ...
def quaternion_apply(quaternion: torch.Tensor, point: torch.Tensor) -> torch.Tensor: ...

Import

from mani_skill.utils.geometry.rotation_conversions import (
    quaternion_to_matrix,
    matrix_to_quaternion,
    quaternion_multiply,
    quaternion_apply,
)

I/O Contract

Inputs

Name	Type	Required	Description
quaternions	torch.Tensor (..., 4)	Yes	Quaternions in [w, x, y, z] format
matrix	torch.Tensor (..., 3, 3)	Yes	Rotation matrices
axis_angle	torch.Tensor (..., 3)	Yes	Axis-angle vectors (direction is axis, magnitude is angle)
convention	str	Yes	Euler angle convention string, e.g. "XYZ"

Outputs

Name	Type	Description
return	torch.Tensor	Converted rotation in the target representation

Usage Examples

Basic Usage

import torch
from mani_skill.utils.geometry.rotation_conversions import (
    quaternion_to_matrix,
    euler_angles_to_matrix,
    quaternion_multiply,
)

# Convert quaternion to rotation matrix
quat = torch.tensor([[1.0, 0.0, 0.0, 0.0]])  # identity
mat = quaternion_to_matrix(quat)  # shape (1, 3, 3)

# Euler angles to matrix
angles = torch.tensor([[0.0, 0.0, 1.57]])  # 90 degrees around Z
mat = euler_angles_to_matrix(angles, "XYZ")

# Compose two rotations via quaternion multiplication
q1 = torch.tensor([[1.0, 0.0, 0.0, 0.0]])
q2 = torch.tensor([[0.707, 0.707, 0.0, 0.0]])
q_composed = quaternion_multiply(q1, q2)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment