Install & Compatibility
Where this runs
tested against v0.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.296s · 91.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.284s · 87MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
euler2mat
✓ from transforms3d.euler import euler2mat
mat2quat
✓ from transforms3d.quaternions import mat2quat
axangle2mat
✓ from transforms3d.axangles import axangle2mat
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)
Debug
Known issues
breakingIn 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.fixEnsure input quaternions are normalized before passing them to `transforms3d` functions, or be aware of the automatic normalization behavior.
affects: 0.3 and later
gotchaWhen 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.fixManually reorder quaternion components or map them correctly when converting between `tf.transformations` and `transforms3d` APIs.
affects: All versions
gotchaSome Euler angle functions may not work correctly or as expected with `float32` NumPy arrays, leading to potential precision or calculation errors.fixPrefer using `float64` (default NumPy float type) for array inputs to Euler angle functions to ensure numerical stability and correctness.
affects: All versions
gotchaThe 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.fixThoroughly consult the `transforms3d` documentation, especially sections on 'Conventions for transforms' and 'Naming conventions', to ensure correct application of functions for specific transformation needs.
affects: All versions
deprecatedThe 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.fixMigrate existing code from `transformations.py` to `transforms3d` to benefit from ongoing development, bug fixes, and compatibility with newer Python and NumPy versions.
affects: Users of `transformations.py`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'transforms3d'
The 'transforms3d' library is not installed in the current Python environment.
fixpip install transforms3d
ImportError: cannot import name 'euler2mat' from 'transforms3d'
The function 'euler2mat' is defined within the 'transforms3d.euler' submodule, but the user is attempting to import it directly from the top-level 'transforms3d' package.
fixfrom transforms3d.euler import euler2mat
AttributeError: module 'transforms3d' has no attribute 'euler2mat'
The user is attempting to call 'transforms3d.euler2mat()' directly, but 'euler2mat' is a function within the 'transforms3d.euler' submodule, not the top-level 'transforms3d' module.
fiximport transforms3d.euler as t3d_euler; t3d_euler.euler2mat(...)
ValueError: not a proper rotation matrix
A function expecting a 3x3 rotation matrix (e.g., 'transforms3d.axangles.mat2axangle') received an input matrix that is not a valid rotation matrix (e.g., not orthogonal or determinant not 1).
fixEnsure the input matrix 'M' is a valid 3x3 rotation matrix where M @ M.T is approximately equal to the identity matrix and np.linalg.det(M) is approximately equal to 1.
Upgrade
Version history
0.4.2latest on PyPI · released Jun 20, 2024
Audit
Dependencies
numpyrequiredCore dependency for numerical array operations.