Transformations

Warnings

• deprecated The 'transformations' library is no longer actively developed and is largely superseded by other, more actively maintained modules like Pytransform3d, Scipy.spatial.transform, Transforms3d, or Numpy-quaternion. Consider using these alternatives for new projects.
  Fix: Migrate to a more actively maintained library such as `scipy.spatial.transform` or `transforms3d` for new development. For existing code, be aware that support may be limited.
• breaking The API is explicitly stated as 'not stable yet and is expected to change between revisions.' This means minor version updates might introduce breaking changes.
  Fix: Pin the library version in your `requirements.txt` (e.g., `transformations==2026.1.18`) and thoroughly test after any upgrade. Review the `CHANGES` file on GitHub before updating.
• gotcha Quaternions in this library are represented as `[w, x, y, z]`. This differs from some other common libraries (e.g., older ROS `tf.transformations` used `[x, y, z, w]`), which can lead to incorrect calculations if not handled carefully.
  Fix: Always verify the quaternion convention when integrating with other libraries or systems. Convert components if necessary to match the expected order.
• gotcha The Python implementation of transformations is not optimized for speed. For performance-critical applications, consider using the `transformations.c` module (if available in your distribution) or alternative libraries that offer optimized (e.g., C/Cython backed) implementations.
  Fix: For speed-critical paths, profile your code and consider rewriting parts using a faster library or the `transformations.c` module. The core `numpy` operations are generally fast, but some high-level functions might have overhead.
• gotcha Transformation matrices generated by this library might require transposing when interfacing with some other graphics systems, such as OpenGL's `glMultMatrixd()`, due to differing column-major/row-major conventions.
  Fix: When passing matrices to external graphics APIs, test and, if necessary, transpose the matrix (e.g., `M.T`) to ensure correct orientation and position.

Install

• pip install -U transformations Install latest version

Imports

• transformations

  import transformations as tf

  Common practice to alias for brevity and to distinguish from other transformation libraries.

Quickstart

This quickstart demonstrates how to create rotation and translation matrices and apply them to a 3D point using homogeneous coordinates. It also shows how to concatenate transformations.

import numpy as np
import transformations as tf

# Create a rotation matrix around the Z-axis by 90 degrees (pi/2 radians)
angle = np.pi / 2
rotation_matrix = tf.rotation_matrix(angle, [0, 0, 1])

# Define a point in homogeneous coordinates (x, y, z, w=1)
point = np.array([1.0, 0.0, 0.0, 1.0])

# Apply the transformation
transformed_point = np.dot(rotation_matrix, point)

print(f"Original point: {point[:3]}")
print(f"Rotation matrix:\n{rotation_matrix}")
print(f"Transformed point: {transformed_point[:3]}")

# Create a translation matrix
translation_matrix = tf.translation_matrix([5.0, 2.0, 0.0])

# Concatenate transformations (apply rotation then translation)
combined_matrix = np.dot(translation_matrix, rotation_matrix)
combined_transformed_point = np.dot(combined_matrix, point)

print(f"\nCombined transformation matrix:\n{combined_matrix}")
print(f"Combined transformed point: {combined_transformed_point[:3]}")