movement-primitives 0.6.0

Movement primitives

Movement Primitives

Movement primitives are a common group of policy representations in robotics. There are many types and variations. This repository focuses mainly on imitation learning, generalization, and adaptation of movement primitives. It provides implementations in Python and Cython.

Features

• Dynamical Movement Primitives (DMPs) for
  • positions (with fast Runge-Kutta integration)
  • Cartesian position and orientation (with fast Cython implementation)
  • Dual Cartesian position and orientation (with fast Cython implementation)
• Coupling terms for synchronization of position and/or orientation of dual Cartesian DMPs
• Propagation of DMP weight distribution to state space distribution
• Probabilistic Movement Primitives (ProMPs)

Example of dual Cartesian DMP with RH5 Manus:

Example of joint space DMP with UR5:

API Documentation

The API documentation is available here.

Install Library

This library requires Python 3.6 or later and pip is recommended for the installation. In the following instructions, we assume that the command python refers to Python 3. If you use the system's Python version, you might have to add the flag --user to any installation command.

I recommend to install the library via pip:

python -m pip install movement_primitives[all]

or clone the git repository and install it in editable mode:

python -m pip install -e .[all]

If you don't want to have all dependencies installed, just omit [all]. Alternatively, you can install dependencies with

python -m pip install -r requirements.txt

You could also just build the Cython extension with

python setup.py build_ext --inplace

or install the library with

python setup.py install

Non-public Extensions

Note that scripts from the subfolder examples/external_dependencies/ require access to git repositories (URDF files or optional dependencies) that are not publicly available.

MoCap Library

# untested: pip install git+https://git.hb.dfki.de/dfki-interaction/mocap.git
git clone [e-mail]:dfki-interaction/mocap.git
cd mocap
python -m pip install -e .
cd ..

Get URDFs

# RH5
git clone [e-mail]:models-robots/rh5_models/pybullet-only-arms-urdf.git --recursive
# RH5v2
git clone [e-mail]:models-robots/rh5v2_models/pybullet-urdf.git --recursive
# Kuka
git clone [e-mail]:models-robots/kuka_lbr.git
# Solar panel
git clone [e-mail]:models-objects/solar_panels.git
# RH5 Gripper
git clone [e-mail]:motto/abstract-urdf-gripper.git --recursive

Data

I assume that your data is located in the folder data/ in most scripts. You should put a symlink there to point to your actual data folder.

Build API Documentation

You can build an API documentation with pdoc3. You can install pdoc3 with

pip install pdoc3

... and build the documentation from the main folder with

pdoc movement_primitives --html

It will be located at html/movement_primitives/index.html.

Test

To run the tests some python libraries are required:

python -m pip install -e .[test]

The tests are located in the folder test/ and can be executed with: python -m nose test

This command searches for all files with test and executes the functions with test_*.

Contributing

To add new features, documentation, or fix bugs you can open a pull request. Directly pushing to the main branch is not allowed.

Examples

Conditional ProMPs

Probabilistic Movement Primitives (ProMPs) define distributions over trajectories that can be conditioned on viapoints. In this example, we plot the resulting posterior distribution after conditioning on varying start positions.

Script

Potential Field of 2D DMP

A Dynamical Movement Primitive defines a potential field that superimposes several components: transformation system (goal-directed movement), forcing term (learned shape), and coupling terms (e.g., obstacle avoidance).

Script

DMP with Final Velocity

Not all DMPs allow a final velocity > 0. In this case we analyze the effect of changing final velocities in an appropriate variation of the DMP formulation that allows to set the final velocity.

Script

ProMPs

The LASA Handwriting dataset learned with ProMPs. The dataset consists of 2D handwriting motions. The first and third column of the plot represent demonstrations and the second and fourth column show the imitated ProMPs with 1-sigma interval.

Script

Cartesian DMPs

A trajectory is created manually, imitated with a Cartesian DMP, converted to a joint trajectory by inverse kinematics, and executed with a UR5.

Script

Contextual ProMPs

We use a dataset of Mronga and Kirchner (2021) with 10 demonstrations per 3 different panel widths that were obtained through kinesthetic teaching. The panel width is considered to be the context over which we generalize with contextual ProMPs. Each color in the above visualizations corresponds to a ProMP for a different context.

Script

Dependencies that are not publicly available:

• Dataset: panel rotation dataset of Mronga and Kirchner (2021)
• MoCap library
• URDF of dual arm Kuka system from DFKI RIC's MRK lab:

  git clone [e-mail]:models-robots/kuka_lbr.git
  

Dual Cartesian DMP

We offer specific dual Cartesian DMPs to control dual-arm robotic systems like humanoid robots.

Scripts: Open3D, PyBullet

Dependencies that are not publicly available:

• MoCap library
• URDF of DFKI RIC's RH5 robot:

  git clone [e-mail]:models-robots/rh5_models/pybullet-only-arms-urdf.git --recursive
  

• URDF of solar panel:

  git clone [e-mail]:models-objects/solar_panels.git
  

Coupled Dual Cartesian DMP

We can introduce a coupling term in a dual Cartesian DMP to constrain the relative position, orientation, or pose of two end-effectors of a dual-arm robot.

Scripts: Open3D, PyBullet

Dependencies that are not publicly available:

• URDF of DFKI RIC's gripper:

  git clone [e-mail]:motto/abstract-urdf-gripper.git --recursive
  

• URDF of DFKI RIC's RH5 robot:

  git clone [e-mail]:models-robots/rh5_models/pybullet-only-arms-urdf.git --recursive
  

Propagation of DMP Distribution to State Space

If we have a distribution over DMP parameters, we can propagate them to state space through an unscented transform.

Script

Dependencies that are not publicly available:

• Dataset: panel rotation dataset of Mronga and Kirchner (2021)
• MoCap library
• URDF of dual arm Kuka system from DFKI RIC's MRK lab:

  git clone [e-mail]:models-robots/kuka_lbr.git
  

Funding

This library has been developed initially at the Robotics Innovation Center of the German Research Center for Artificial Intelligence (DFKI GmbH) in Bremen. At this phase the work was supported through a grant of the German Federal Ministry of Economic Affairs and Energy (BMWi, FKZ 50 RA 1701).