3D Coordinate Transformations

0.4.2 · active · verified Mon Apr 13

transforms3d is a Python library providing a collection of functions and classes for creating and converting 3-dimensional transformations, including rotations, zooms, shears, and reflections. It is largely based on the `transformations.py` module by Christoph Gohlke, with significant restructuring and ongoing maintenance by Matthew Brett. The library is currently at version 0.4.2 and sees active maintenance for bugfixes and compatibility updates, particularly with NumPy.

Warnings

breaking In version 0.3, the calculation of quaternion to axis-angle changed. Quaternions are now normalized to unit quaternions on input, which may produce different results for code relying on previously unnormalized quaternions.
Fix: Ensure input quaternions are normalized before passing them to `transforms3d` functions, or be aware of the automatic normalization behavior.
gotcha When migrating from `tf.transformations` (used in ROS 1) to `transforms3d` (recommended for ROS 2), be aware that the quaternion order is different. `tf.transformations` uses `x, y, z, w`, whereas `transforms3d` uses `w, x, y, z`. This requires careful adjustment of quaternion components.
Fix: Manually reorder quaternion components or map them correctly when converting between `tf.transformations` and `transforms3d` APIs.
gotcha Some Euler angle functions may not work correctly or as expected with `float32` NumPy arrays, leading to potential precision or calculation errors.
Fix: Prefer using `float64` (default NumPy float type) for array inputs to Euler angle functions to ensure numerical stability and correctness.
gotcha The library is built upon specific conventions for 3D transformations, including rotation orders (e.g., 'sxyz', 'rzyx'), axis definitions, and gimbal lock considerations. Misunderstanding these conventions can lead to incorrect transformation results.
Fix: Thoroughly consult the `transforms3d` documentation, especially sections on 'Conventions for transforms' and 'Naming conventions', to ensure correct application of functions for specific transformation needs.
deprecated The original `transformations.py` module by Christoph Gohlke, from which `transforms3d` is derived, is no longer actively developed and has known issues and numerical instabilities. `transforms3d` is the recommended, actively maintained alternative.
Fix: Migrate existing code from `transformations.py` to `transforms3d` to benefit from ongoing development, bug fixes, and compatibility with newer Python and NumPy versions.

Install

pip install transforms3d Install with pip

Imports

euler2mat

from transforms3d.euler import euler2mat

mat2quat

from transforms3d.quaternions import mat2quat

axangle2mat

from transforms3d.axangles import axangle2mat

Quickstart

This quickstart demonstrates converting Euler angles to a rotation matrix, then converting that matrix to a quaternion, and finally reconstructing the matrix from the quaternion. This covers common transformations and module imports from `transforms3d` while leveraging `numpy` for array handling. The `axes` argument in `euler2mat` specifies the order and type of Euler angles (e.g., 'sxyz' for static XYZ).

import numpy as np
from transforms3d.euler import euler2mat, mat2euler
from transforms3d.quaternions import mat2quat, quat2mat

# Define Euler angles (roll, pitch, yaw) in radians
r, p, y = np.deg2rad(30), np.deg2rad(45), np.deg2rad(60)

# Convert Euler angles to a 3x3 rotation matrix
rotation_matrix = euler2mat(r, p, y, axes='sxyz')
print("Rotation Matrix:\n", rotation_matrix)

# Convert rotation matrix to a quaternion (w, x, y, z order)
quaternion = mat2quat(rotation_matrix)
print("Quaternion (w, x, y, z): ", quaternion)

# Convert quaternion back to rotation matrix
reconstructed_matrix = quat2mat(quaternion)
print("Reconstructed Matrix:\n", reconstructed_matrix)

# Verify accuracy
assert np.allclose(rotation_matrix, reconstructed_matrix)

view raw JSON →