omg-tools 0.1.1

Optimal Motion Generation tools: a user-friendly tool for modeling, simulating and embedding of (spline-based) motion planning problems

|Build Status| |Coverage Status| |Codacy Badge| |PyPI version|

Optimal Motion Generation-tools is a Python software toolbox
facilitating the modeling, simulation and embedding of motion planning
problems. Its main goal is to collect research topics concerning
(spline-based) motion planning into a user-friendly package in order to
enlarge its visibility towards the scientific and industrial world.

This toolbox focuses on receding horizon control for single-agent
systems as well as on distributed control for multi-agent systems. The
approaches implemented in OMG-tools are described in the following
publications: \* Mercy T., Van Loock W., Pipeleers G. (2016). Real-time
motion planning in the presence of moving obstacles. Proceedings of the
2016 European Control Conference. European Control Conference. Aalborg,
29 June - 1 July 2016 (pp. 1586-1591).
(`pdf <https://lirias.kuleuven.be/bitstream/123456789/538718/1/TimMercy_2016_ECC.pdf>`__)
\* Van Parys R., Pipeleers G. (2016). Online distributed motion planning
for multi-vehicle systems. Proceedings of the 2016 European Control
Conference. European Control Conference. Aalborg, 29 June - 1 July 2016
(pp. 1580-1585).
(`pdf <https://lirias.kuleuven.be/bitstream/123456789/526758/3/RubenVanParys_2016_ECC.pdf>`__)
\* Van Parys R., Pipeleers G. (2017). Spline-Based Motion Planning in an
Obstructed 3D environment. Proceedings of the 20th IFAC World Congress.
IFAC World Congress. Toulouse, France, 9-14 July 2017.
(`pdf <https://lirias.kuleuven.be/bitstream/123456789/575111/3/RubenVanParys_2017_IFAC_lirias.pdf>`__)

If these methods help you with your research, please cite us!

Examples
--------

Overview
~~~~~~~~

The animations below give an overview of typical problems that OMG-tools
can handle.

.. raw:: html

<table style="border: none; border-collapse: collapse;" border="0" cellspacing="0" cellpadding="0" width="100%" align="center">
<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
</tr>
<tr>
<td aliggn="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td aliggn="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>
<tr>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td aliggn="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>
<tr>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>
</table>

Experimental validation
~~~~~~~~~~~~~~~~~~~~~~~

OMG-tools implemented on real-life motion systems. Click on a picture to
watch the Youtube video.

.. raw:: html

<table style="border: none; border-collapse: collapse;" border="0" cellspacing="0" cellpadding="0" width="100%" align="center">
<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>

<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>

<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>

<tr>
<td align="center" valign="center" style="background-color:rgba(0, 0, 0, 0);">

.. raw:: html

</td>
<td align="center" valign="center" bgcolor="#FFFFFF">

.. raw:: html

</td>
</tr>

</table>

Code example
~~~~~~~~~~~~

This elementary code example illustrates the basic functionality of the
toolbox for steering a holonomic vehicle from an initial to terminal
pose in a dynamic environment.

.. code:: python

from omgtools import *

# make and set-up vehicle
vehicle = Holonomic()
vehicle.set_initial_conditions([-1.5, -1.5])
vehicle.set_terminal_conditions([2., 2.])
vehicle.set_options({'safety_distance': 0.1})

# make and set-up environment
environment = Environment(room={'shape': Square(5.)})

# add stationary obstacles to environment
rectangle = Rectangle(width=3., height=0.2)
environment.add_obstacle(Obstacle({'position': [-2.1, -0.5]}, shape=rectangle))
environment.add_obstacle(Obstacle({'position': [ 1.7, -0.5]}, shape=rectangle))

# generate trajectory for moving obstacle
traj = {'velocity': {'time': [3., 4.],
'values': [[-0.15, 0.0], [0., 0.15]]}}
# add moving obstacle to environment
environment.add_obstacle(Obstacle({'position': [1.5, 0.5]}, shape=Circle(0.4),
simulation={'trajectories': traj}))

# give problem settings and create problem
problem = Point2point(vehicle, environment)
problem.init()

# simulate, plot some signals and save a movie
simulator = Simulator(problem)
vehicle.plot('input', labels=['v_x (m/s)', 'v_y (m/s)'])
problem.plot('scene')
simulator.run()
problem.save_movie('scene')

.. raw:: html

<p align="center">

.. raw:: html

</p>

More examples
~~~~~~~~~~~~~

Check out the examples directory for more code examples. There you can
find a simple tutorial example which provides a documented overview of
the basic functionality of the toolbox.

Installation
------------

OMG-tools is written in Python 2.7 and depends on the packages numpy,
scipy and matplotlib:

``sudo apt-get install python-numpy python-scipy python-matplotlib``

It uses `CasADi <http://casadi.org>`__ as a framework for symbolic
computations and interface to IPOPT, a software package for large-scale
nonlinear optimization. The current implementation of this toolbox
relies on CasADi 3.1, which can be obtained from its `install
page <http://install31.casadi.org>`__. In the examples, we use the `HSL
linear solvers <https://github.com/casadi/casadi/wiki/Obtaining-HSL>`__,
as they result in a much faster execution.

If you want to save your simulation results in Tikz-format, you need
`matplotlib2tikz <https://github.com/nschloe/matplotlib2tikz>`__.

If you want to save your simulation results in gif-format, you need
`imagemagick <www.imagemagick.org>`__.

To install the toolbox itself, run the following command in the root
directory of this repository:

``sudo python setup.py install``

Authors
-------

OMG-tools is developed by Ruben Van Parys and Tim Mercy as part of their
research in spline-based motion planning, under supervision of Goele
Pipeleers within the `MECO research
team <https://www.mech.kuleuven.be/en/pma/research/meco>`__. Any
questions, comments or propositions of collaboration can be addressed to
ruben[dot]vanparys[at]kuleuven[dot]be and
tim[dot]mercy[at]kuleuven[dot]be.

.. |Build Status| image:: https://travis-ci.org/meco-group/omg-tools.svg?branch=master
:target: https://travis-ci.org/meco-group/omg-tools
.. |Coverage Status| image:: https://coveralls.io/repos/github/meco-group/omg-tools/badge.svg?branch=master
:target: https://coveralls.io/github/meco-group/omg-tools?branch=master
.. |Codacy Badge| image:: https://api.codacy.com/project/badge/grade/a44dd52c358e4cd09b12585915738627
:target: https://www.codacy.com/app/joris-gillis42/omg-tools
.. |PyPI version| image:: https://badge.fury.io/py/omg-tools.svg
:target: https://badge.fury.io/py/omg-tools