invariants-py is a Python library to robustly calculate coordinate-invariant trajectory representations using geometric optimal control. It also supports trajectory generation under user-specified trajectory constraints starting from invariant representations.

More information can be found on the documentation website: https://trajectory-invariants.github.io

Features

The main features are:

• Calculation of invariant descriptors for trajectories.
• Fast trajectory adaptation starting from the invariant descriptors.

Invariant trajectory representations find their application in trajectory analysis, trajectory segmentation, recognition and generalization.

Installation

The package can be installed from PyPI or from source.

Prerequisites

The package requires Python 3.8 or higher.

1. Installation from PyPI

This installation option is recommended if you only want to use the package and do not plan to modify the source code.

Upgrade your version of pip:

pip install --upgrade pip    

Install the package:

pip install invariants-py

2. Installation from source

This installation option is recommended if you plan to modify or experiment with the source code.

Clone (or download) the invariants-py repository:

git clone https://github.com/trajectory-invariants/invariants_py.git

Navigate to the cloned repository:

cd invariants_py

Upgrade your version of pip:

pip install --upgrade pip    

Install the package:

pip install -e .

Getting started

Basic examples are provided to get you started in the examples folder.

More detailed examples and tutorials can be found on the documentation website.

Speed up using Fatrop

To speed up the solution of the optimal control problems, you can optionally install the fatrop solver. The instructions are available on this page of the documentation website.

Roadmap

The following features are planned for future releases:

• Support for more types of invariant representations (e.g. screw invariants, global invariants, ...).
• Support for more types of constraints in the trajectory generation.
• Benchmarking between different invariant representations in terms of robustness, computational efficiency, and generalizability.

Contributing

We welcome contributions to this repository, for example in the form of pull requests.

Contributors

We wish to thank the following people for their contributions to an early version of the software: Victor van Wymeersch, Zeno Gillis, Toon Daemen, Glenn Maes, Ali Mousavi, Lander Vanroye

Support

For questions, bugs, feature requests, etc., please open an issue on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citing

If you use this package in your research, please cite the following paper:

@article{vochten2023invariant,
  title={Invariant Descriptors of Motion and Force Trajectories for Interpreting Object Manipulation Tasks in Contact},
  author={Vochten, Maxim and Mohammadi, Ali Mousavi and Verduyn, Arno and De Laet, Tinne and Aertbeli{\"e}n, Erwin and De Schutter, Joris},
  journal={IEEE Transactions on Robotics},
  year={2023},
  volume={39},
  number={6},
  pages={4892-4912},
  doi={10.1109/TRO.2023.3309230}}