3D Transformations for Python

Common errors

• AttributeError: module 'pytransform3d.transformations' has no attribute 'some_old_function'

  cause A function or attribute you are trying to access has been renamed, moved to a different module, or removed in a newer version, especially due to refactoring in 3.14.0.
  fix Check the official documentation or release notes for the current version to find the correct function name or its new location (e.g., it might have moved from `transformations` to `rotations` or vice-versa, or be in a new utility module).

• ValueError: Expected a 4x4 transformation matrix

  cause A function that expects a 4x4 homogeneous transformation matrix (e.g., `plot_transform`, `concatenate_transforms`) received an input array with an incorrect shape (e.g., 3x3, 3x4, or non-matrix input).
  fix Ensure that the input array is a `numpy.ndarray` of shape `(4, 4)`. You might need to convert a rotation matrix and translation vector using `pytransform3d.transformations.transform_from_Rt()` or a similar helper function.

• ImportError: cannot import name 'visualizer' from 'pytransform3d'

  cause The `visualizer` module and its functionalities depend on optional packages (like Open3D, Pyrender) that are not installed by default.
  fix Install `pytransform3d` with the necessary optional dependencies using `pip install pytransform3d[all]` or `pip install pytransform3d[open3d]` (replace `open3d` with the specific backend you need).

• numpy.linalg.LinAlgError: SVD did not converge

  cause This can occur during matrix decompositions (e.g., polar decomposition for orthonormalizing rotation matrices) when the input matrix is singular, poorly conditioned, or not close enough to a valid rotation matrix due to floating point errors or invalid data.
  fix If working with rotation matrices that might have accumulated floating point errors, consider using `pytransform3d.rotations.robust_polar_decomposition` (available since 3.12.0) which provides a more stable way to orthonormalize a matrix. Ensure your input data is valid and as numerically stable as possible.

Warnings

• breaking Support for Python 3.8 was dropped in version 3.14.1. Users on Python 3.8 will need to upgrade their Python version to 3.9 or higher to use recent `pytransform3d` releases.
  Fix: Upgrade Python to 3.9 or a newer supported version.
• gotcha Version 3.14.0 introduced a significant refactoring, splitting large files into smaller modules, particularly for conversions between rotations and transformations. While many common functions retained their path, some less common or deeply nested functions might have moved, potentially causing `AttributeError` or `ImportError` if custom or older scripts rely on specific, now-changed, internal module structures.
  Fix: Consult the official documentation for the updated import paths and function locations if you encounter `AttributeError` or `ImportError` after upgrading to 3.14.0 or later. For example, some functions previously available directly under `pytransform3d.rotations` might now be in `pytransform3d.transformations` or vice versa depending on their primary utility.
• gotcha Older versions (pre-3.14.3) had known bugs parsing URDF files, especially those with XML namespaces or comments, which could lead to errors or incorrect robot models. While fixed in recent versions, if you're working with URDFs, ensure you're on a recent version.
  Fix: Upgrade `pytransform3d` to version 3.14.4 or newer to ensure robust URDF parsing. If you must use an older version, manually clean or simplify URDF files known to cause issues.
• gotcha When using `pytransform3d.visualizer` or any of its submodules, you might encounter `ImportError` if optional dependencies like Open3D, Pyrender, or Trimesh are not installed. These are not installed by default with `pip install pytransform3d`.
  Fix: Install `pytransform3d` with the `[all]` extra (e.g., `pip install pytransform3d[all]`) or specifically for the visualization backend you intend to use (e.g., `pip install pytransform3d[open3d]`).

Install

• pip install pytransform3d Core library
• pip install pytransform3d[all] With all optional dependencies (e.g., Open3D, Pyrender, Numba)

Imports

• transformations

  import pytransform3d.transformations as ptf

• rotations

  import pytransform3d.rotations as pr

• plot_utils

  import pytransform3d.plot_utils as ppu

• visualizer

  import pytransform3d.visualizer as pv

Quickstart

This quickstart demonstrates how to define a 3D transformation (rotation + translation) using axis-angle representation and then visualize it using matplotlib utilities provided by pytransform3d. It shows a basic use of `transformations` and `plot_utils` modules.

import numpy as np
import pytransform3d.transformations as ptf
import pytransform3d.plot_utils as ppu
import matplotlib.pyplot as plt

# Define a transformation: rotate 90 degrees around Z-axis, then translate (1, 0, 0)
A2B = ptf.transform_from_axis_angle([0, 0, 1, np.deg2rad(90)], np.array([1, 0, 0]))

# Create a 3D axis for plotting
ax = ppu.make_3d_axis(ax_s=2, n_ticks=2)

# Plot the transformation
ppu.plot_transform(ax, A2B, s=0.5)

# Set title and display
ax.set_title("Basic Transformation Plot")
plt.show()