Skip to main content

3D transformations for Python

Project description

codecov Paper DOI Release DOI

pytransform3d

A Python library for transformations in three dimensions.

pytransform3d offers...

  • operations like concatenation and inversion for most common representations of rotation (orientation) and translation (position)
  • conversions between those representations
  • clear documentation of transformation conventions
  • tight coupling with matplotlib to quickly visualize (or animate) transformations
  • the TransformManager which manages complex chains of transformations (with export to graph visualization as PNG, additionally requires pydot)
  • the TransformEditor which allows to modify transformations graphically (additionally requires PyQt4/5)
  • the UrdfTransformManager which is able to load transformations from URDF files (additionally requires lxml)
  • a matplotlib-like interface to Open3D's visualizer to display and animate geometries and transformations (additionally requires Open3D)

pytransform3d is used in various domains, for example:

  • specifying motions of a robot
  • learning robot movements from human demonstration
  • sensor fusion for human pose estimation
  • collision detection for robots

The API documentation can be found here.

I gave a talk at EuroSciPy 2023 about pytransform3d. Slides are available here.

If you need similar features in JAX (on GPU, vectorized, differentiable), have a look at the experimental library jaxtransform3d.

Installation

Use pip to install the package from PyPI:

pip install 'pytransform3d[all]'

or conda:

conda install -c conda-forge pytransform3d

Take a look at the installation instructions in the documentation for more details.

Gallery

The following plots and visualizations have been generated with pytransform3d. The code for most examples can be found in the documentation.

Left: Nao robot with URDF from Bullet3. Right: Kuka iiwa. The animation is based on pytransform3d's visualization interface to Open3D.

Visualizations based on Open3D.

Various plots based on Matplotlib.

Transformation editor based on Qt.

Example

This is just one simple example. You can find more examples in the subfolder examples/.

import numpy as np
import matplotlib.pyplot as plt
from pytransform3d import rotations as pr
from pytransform3d import transformations as pt
from pytransform3d.transform_manager import TransformManager


rng = np.random.default_rng(0)

ee2robot = pt.transform_from_pq(
    np.hstack((np.array([0.4, -0.3, 0.5]),
               pr.random_quaternion(rng))))
cam2robot = pt.transform_from_pq(
    np.hstack((np.array([0.0, 0.0, 0.8]), pr.q_id)))
object2cam = pt.transform_from(
    pr.active_matrix_from_intrinsic_euler_xyz(np.array([0.0, 0.0, -0.5])),
    np.array([0.5, 0.1, 0.1]))

tm = TransformManager()
tm.add_transform("end-effector", "robot", ee2robot)
tm.add_transform("camera", "robot", cam2robot)
tm.add_transform("object", "camera", object2cam)

ee2object = tm.get_transform("end-effector", "object")

ax = tm.plot_frames_in("robot", s=0.1)
ax.set_xlim((-0.25, 0.75))
ax.set_ylim((-0.5, 0.5))
ax.set_zlim((0.0, 1.0))
plt.show()

output

Documentation

The API documentation can be found here.

The documentation can be found in the directory doc. To build the documentation, run e.g. (on linux):

cd doc
make html

The HTML documentation is now located at doc/build/html/index.html. Execute the following command in the main folder of the repository to install the dependencies:

pip install -e '.[doc]'

Tests

You can use pytest to run the tests of this project in the root directory:

pytest

A coverage report will be located at htmlcov/index.html. Note that you have to install pytest to run the tests and pytest-cov to obtain the code coverage report.

Contributing

If you wish to report bugs, please use the issue tracker at Github. If you would like to contribute to pytransform3d, just open an issue or a pull request. The target branch for pull requests is the develop branch. The development branch will be merged to main for new releases. If you have questions about the software, you should ask them in the discussion section.

The recommended workflow to add a new feature, add documentation, or fix a bug is the following:

  • Push your changes to a branch (e.g. feature/x, doc/y, or fix/z) of your fork of the pytransform3d repository.
  • Open a pull request to the latest development branch. There is usually an open merge request from the latest development branch to the main branch.
  • When the latest development branch is merged to the main branch, a new release will be made.

Note that there is a checklist for new features.

It is forbidden to directly push to the main branch. Each new version has its own development branch from which a pull request will be opened to the main branch. Only the maintainer of the software is allowed to merge a development branch to the main branch.

License

The library is distributed under the 3-Clause BSD license.

Citation

If you use pytransform3d for a scientific publication, I would appreciate citation of the following paper:

Fabisch, A. (2019). pytransform3d: 3D Transformations for Python. Journal of Open Source Software, 4(33), 1159, Paper DOI

Bibtex entry:

@article{Fabisch2019,
  doi = {10.21105/joss.01159},
  url = {https://doi.org/10.21105/joss.01159},
  year = {2019},
  publisher = {The Open Journal},
  volume = {4},
  number = {33},
  pages = {1159},
  author = {Alexander Fabisch},
  title = {pytransform3d: 3D Transformations for Python},
  journal = {Journal of Open Source Software}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytransform3d-3.14.2.tar.gz (8.3 MB view details)

Uploaded Source

Built Distribution

pytransform3d-3.14.2-py3-none-any.whl (164.7 kB view details)

Uploaded Python 3

File details

Details for the file pytransform3d-3.14.2.tar.gz.

File metadata

  • Download URL: pytransform3d-3.14.2.tar.gz
  • Upload date:
  • Size: 8.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.9

File hashes

Hashes for pytransform3d-3.14.2.tar.gz
Algorithm Hash digest
SHA256 d6d0e13fb8790aaac271356caf79e6404983fa6125916cabb722c3d5714ff9e0
MD5 2500cf2ba52ea7c1d39d575ae6e9b807
BLAKE2b-256 afbe6220070bffc81710ea8896e888cb44e4c4ee37634cda480356de858d01b6

See more details on using hashes here.

File details

Details for the file pytransform3d-3.14.2-py3-none-any.whl.

File metadata

  • Download URL: pytransform3d-3.14.2-py3-none-any.whl
  • Upload date:
  • Size: 164.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.9

File hashes

Hashes for pytransform3d-3.14.2-py3-none-any.whl
Algorithm Hash digest
SHA256 2543ab760bb22d9385d6dca6f79a98583a12f4b12009367bc3e1e90abf5cf8bd
MD5 521f67a3f4edd567f8ce6fd099691b5b
BLAKE2b-256 d199c106f03c988e9aa5ce58906513fcc4447ee5874c88f1408df5dbce143e50

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page