{"id":8566,"library":"pytransform3d","title":"3D Transformations for Python","description":"pytransform3d is a Python library for 3D transformations, offering tools to manipulate and visualize 3D poses, rotations (matrices, quaternions, axis-angle), translations, trajectories, and meshes. It emphasizes conventions that are common in robotics and computer vision. The current version is 3.15.0, and the project maintains an active release cadence with frequent updates and bug fixes.","status":"active","version":"3.15.0","language":"en","source_language":"en","source_url":"https://github.com/dfki-ric/pytransform3d","tags":["3d","transformations","rotations","quaternions","robotics","computer-vision","visualization","numpy"],"install":[{"cmd":"pip install pytransform3d","lang":"bash","label":"Core library"},{"cmd":"pip install pytransform3d[all]","lang":"bash","label":"With all optional dependencies (e.g., Open3D, Pyrender, Numba)"}],"dependencies":[{"reason":"Core dependency for numerical operations.","package":"numpy"},{"reason":"Core dependency for scientific computing functions.","package":"scipy"},{"reason":"Optional, for 2D/3D plotting functionalities.","package":"matplotlib","optional":true},{"reason":"Optional, for performance improvements via JIT compilation.","package":"numba","optional":true},{"reason":"Optional, for advanced 3D visualization and mesh processing.","package":"open3d","optional":true},{"reason":"Optional, for mesh loading and manipulation.","package":"trimesh","optional":true},{"reason":"Optional, for rendering 3D scenes.","package":"pyrender","optional":true}],"imports":[{"symbol":"transformations","correct":"import pytransform3d.transformations as ptf"},{"symbol":"rotations","correct":"import pytransform3d.rotations as pr"},{"symbol":"plot_utils","correct":"import pytransform3d.plot_utils as ppu"},{"symbol":"visualizer","correct":"import pytransform3d.visualizer as pv"}],"quickstart":{"code":"import numpy as np\nimport pytransform3d.transformations as ptf\nimport pytransform3d.plot_utils as ppu\nimport matplotlib.pyplot as plt\n\n# Define a transformation: rotate 90 degrees around Z-axis, then translate (1, 0, 0)\nA2B = ptf.transform_from_axis_angle([0, 0, 1, np.deg2rad(90)], np.array([1, 0, 0]))\n\n# Create a 3D axis for plotting\nax = ppu.make_3d_axis(ax_s=2, n_ticks=2)\n\n# Plot the transformation\nppu.plot_transform(ax, A2B, s=0.5)\n\n# Set title and display\nax.set_title(\"Basic Transformation Plot\")\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.9 or a newer supported version.","message":"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.","severity":"breaking","affected_versions":">=3.14.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.14.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.14.3"},{"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]`).","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"AttributeError: module 'pytransform3d.transformations' has no attribute 'some_old_function'"},{"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.","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).","error":"ValueError: Expected a 4x4 transformation matrix"},{"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).","cause":"The `visualizer` module and its functionalities depend on optional packages (like Open3D, Pyrender) that are not installed by default.","error":"ImportError: cannot import name 'visualizer' from 'pytransform3d'"},{"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.","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.","error":"numpy.linalg.LinAlgError: SVD did not converge"}]}