Skip to main content

3D transformations for Python

Project description

Travis Status CircleCI Status

pytransform3d

A Python library for transformations in three dimensions.

The library focuses on readability and debugging, not on computational efficiency. If you want to have an efficient implementation of some function from the library you can easily extract the relevant code and implement it more efficiently in a language of your choice.

The library integrates well with the scientific Python ecosystem with its core libraries Numpy, Scipy and Matplotlib. We rely on Numpy for linear algebra and on Matplotlib to offer plotting functionalities. Scipy is used if you want to automatically compute new transformations from a graph of existing transformations.

Heterogenous software systems that consist of proprietary and open source software are often combined when we work with transformations. For example, suppose you want to transfer a trajectory demonstrated by a human to a robot. The human trajectory could be measured from an RGB-D camera, fused with IMU sensors that are attached to the human, and then translated to joint angles by inverse kinematics. That involves at least three different software systems that might all use different conventions for transformations. Sometimes even one software uses more than one convention. The following aspects are of crucial importance to glue and debug transformations in systems with heterogenous and often incompatible software:

  • Compatibility: Compatibility between heterogenous softwares is a difficult topic. It might involve, for example, communicating between proprietary and open source software or different languages.
  • Conventions: Lots of different conventions are used for transformations in three dimensions. These have to be determined or specified.
  • Conversions: We need conversions between these conventions to communicate transformations between different systems.
  • Visualization: Finally, transformations should be visually verified and that should be as easy as possible.

pytransform3d assists in solving these issues. Its documentation clearly states all of the used conventions, it makes conversions between rotation and transformation conventions as easy as possible, it is tightly coupled with Matplotlib to quickly visualize (or animate) transformations and it is written in Python with few dependencies. Python is a widely adopted language. It is used in many domains and supports a wide spectrum of communication to other software.

In addition, pytransform3d offers...

  • the TransformManager which manages complex chains of transformations
  • the TransformEditor which allows to modify transformations graphically (additionally requires PyQt4)
  • the UrdfTransformManager which is able to load transformations from URDF files (additionally requires beautifulsoup4)

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

Installation

Clone the repository and go to the main folder.

Install dependencies with:

pip install -r requirements.txt

Install the package with:

python setup.py install

Documentation

The API documentation can be found here.

The docmentation of this project can be found in the directory doc. Note that currently sphinx 1.6.7 is required to build the documentation. To build the documentation, run e.g. (on unix):

cd doc
make html

The HTML documentation is now located at doc/build/html/index.html. Note that sphinx is required to build the documentation.

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
import pytransform3d.rotations as pr
import pytransform3d.transformations as pt
from pytransform3d.transform_manager import TransformManager


random_state = np.random.RandomState(0)

ee2robot = pt.transform_from_pq(
    np.hstack((np.array([0.4, -0.3, 0.5]), pr.random_quaternion(random_state))))
cam2robot = pt.transform_from_pq(
    np.hstack((np.array([0.0, 0.0, 0.8]), pr.q_id)))
object2cam = pt.transform_from(
    pr.matrix_from_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

Tests

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

nosetests

A coverage report will be located at cover/index.html. Note that you have to install nose to run the tests and coverage to obtain the code coverage report. The branch coverage is currently 100% for code that is not related to the GUI.

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 merge request.

Project details


Download files

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

Files for pytransform3d, version 1.0
Filename, size File type Python version Upload date Hashes
Filename, size pytransform3d-1.0.tar.gz (26.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page