.. image:: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/timor_banner.png
:alt: Timor Banner
:align: center
:target: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/timor_banner.png
Timor Python
============
The Toolbox for Industrial Modular Robotics (Timor) is a python library for model generation and simulation of modular robots (`arXiV <https://arxiv.org/abs/2209.06758>`_).
.. image:: https://gitlab.lrz.de/tum-cps/timor-python/badges/main/pipeline.svg
:target: https://gitlab.lrz.de/tum-cps/timor-python/-/commits/%main
:alt: Pipeline Status
.. image:: https://readthedocs.org/projects/timor-python/badge/?version=latest
:target: https://timor-python.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://gitlab.lrz.de/tum-cps/timor-python/badges/main/coverage.svg
:target: https://gitlab.lrz.de/tum-cps/timor-python/-/jobs/artifacts/main/file/ci/coverage/html//index.html?job=coverage&min_acceptable=80&min_good=90
:alt: Coverage Report
Timor is available on `GitLab <https://gitlab.lrz.de/tum-cps/timor-python>`_ and on `GitHub <https://github.com/JonathanKuelz/timor-python>`_.
With Timor you can:
- Create, export and load sets of robot modules
- Assemble modules and generate kinematic, dynamic and collision models for you assembly
- Transfer your assembly to a `pinocchio <https://github.com/stack-of-tasks/pinocchio>`_-based robot model and perform forwards- and inverse kinematics and dynamics calculations
- Visualize modules and assemblies and animate trajectories
- Define robot tasks and evaluate solutions based on various cost functions
- Get started working with modular robots!
.. image:: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/animations/demo_animation.gif
:alt: Animation of a robot assembly moving between two goals
:align: center
:target: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/animations/demo_animation.gif
Installation
------------
Timor-python is available on PyPI. It requires **at least Python 3.8** and a linux distribution (for windows and macOS, see below). For installation, use::
pip install timor-python
Some requirements are not included by default - in order to install them, use::
pip install timor-python[option]
where option can be one or multiple (comma-separated) of the following:
- ``dev``: Installs development requirements for local unittesting
- ``optimization``: Installs useful requirements for optimizing module composition.
- ``viz``: This installs a custom meshcat version and enables you to place billboards in the meshcat visualizer. It is **not** available on PyPI.
- ``full``: All of the above - except for the custom meshcat visualizer.
If you want to work with the bleeding-edge version, you can download the source code from the project repository and install it locally.
Nagivate to the timor-python repository you cloned and enter::
pip install -e .
to install it in editeable mode. This requires :code:`setuptools>=61` and :code:`pip>=21.3` (previous versions of setuptools require a :code:`setup.py`-file). To install optional dependencies, proceed in the same manner as for PyPI installs.
To run unittest locally, you need to `setup git lfs <https://git-lfs.com/>`_ in order to download assets.
If you want to use pre-commit hooks provided with Timor, for installation please use::
pip install pre-commit
then::
pre-commit install
After that, each time you commit files, it will automatically perform linting and style checks.
other OS: Currently, Windows and MacOS are not officially supported. Crucially, pinocchio is not available on PyPI for these operating systems.
However, if you want to use Timor, you can try::
pip install --no-deps timor-python
conda install pinocchio -c conda-forge
and then :code:`pip install` all other requirements from the [dependencies] section in the `pyproject.toml file. <https://gitlab.lrz.de/tum-cps/timor-python/-/blob/main/pyproject.toml>`_
Usage
-----
The `tutorials folder <tutorials/>`_ contains jupyter notebooks that cover the most common use cases for Timor.
To open and run the notebooks, you will need jupyter, which can be installed from PyPI::
pip install jupyterlab
To inspect, run, or edit the tutorials, navigate to the tutorials folder and start the notebook::
jupyter lab
You can set custom configurations such as file paths of robot libraries or logging behavior by editing the config file. You can import the file location of the config file as :code:`from timor.utilities.configurations import CONFIG_FILE`.
For further information, please visit the `documentation <https://timor-python.readthedocs.io>`_.
Updating
--------
Some timor updates might require to re-acquire the task, schema, or robot module data-bases. Try to reset the caches by running ``timor.utilities.file_locations.clean_caches()`` and re-import the timor module.
Typical errors indicating this action:
* ValueError: modules.json invalid.
Support
-------
Do you have a question or an issue using Timor? You can either `submit an issue <https://gitlab.lrz.de/tum-cps/timor-python/-/issues>`_ or write an email to the `repository maintainer <mailto:jonathan.kuelz@tum.de>`_.
Contributing
------------
We welcome every contribution to Timor. For more details, please refer to our `contribution guidelines <https://gitlab.lrz.de/tum-cps/timor-python/-/blob/main/CONTRIBUTING.md>`_.
Citing Timor
------------
If you want to cite Timor for your academic research, please use the following bibtex entry::
@InProceedings{Kuelz2023,
author = {Külz, Jonathan and Mayer, Matthias and Althoff, Matthias},
booktitle = {International Conference on Intelligent Robots and Systems},
title = {{Timor Python}: A Toolbox for Industrial Modular Robotics},
pages = {424--431},
year = {2023},
publisher = {IEEE},
doi = {10.1109/IROS55552.2023.10341935},
}
Authors and acknowledgment
--------------------------
Timor was developed at the chair of robotics, artificial intelligence and embedded systems at TU Munich.
It is designed, developed and maintained by Jonathan Külz, Matthias Mayer, and Matthias Althoff.
The Timor Python logo was AI-generated using the OpenAI's Dall-E 2 API.
The developers gratefully acknowledge financial support by the Horizon 2020 EU Framework Project `CONCERT <https://concertproject.eu/>`_.
Raw data
{
"_id": null,
"home_page": "",
"name": "timor-python",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Modular Reconfigurable Robots,Robot Design,Model Generation,Simulation",
"author": "",
"author_email": "Jonathan Kuelz <jonathan.kuelz@tum.de>",
"download_url": "https://files.pythonhosted.org/packages/a1/2e/f1f162c20bdfec04ddd26b1dcfa80c589e927df85557a1ce8839db61e8ad/timor-python-1.0.tar.gz",
"platform": null,
"description": ".. image:: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/timor_banner.png\n :alt: Timor Banner\n :align: center\n :target: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/timor_banner.png\n\n\nTimor Python\n============\nThe Toolbox for Industrial Modular Robotics (Timor) is a python library for model generation and simulation of modular robots (`arXiV <https://arxiv.org/abs/2209.06758>`_).\n\n.. image:: https://gitlab.lrz.de/tum-cps/timor-python/badges/main/pipeline.svg\n :target: https://gitlab.lrz.de/tum-cps/timor-python/-/commits/%main\n :alt: Pipeline Status\n\n.. image:: https://readthedocs.org/projects/timor-python/badge/?version=latest\n :target: https://timor-python.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://gitlab.lrz.de/tum-cps/timor-python/badges/main/coverage.svg\n :target: https://gitlab.lrz.de/tum-cps/timor-python/-/jobs/artifacts/main/file/ci/coverage/html//index.html?job=coverage&min_acceptable=80&min_good=90\n :alt: Coverage Report\n\nTimor is available on `GitLab <https://gitlab.lrz.de/tum-cps/timor-python>`_ and on `GitHub <https://github.com/JonathanKuelz/timor-python>`_.\n\nWith Timor you can:\n\n- Create, export and load sets of robot modules\n- Assemble modules and generate kinematic, dynamic and collision models for you assembly\n- Transfer your assembly to a `pinocchio <https://github.com/stack-of-tasks/pinocchio>`_-based robot model and perform forwards- and inverse kinematics and dynamics calculations\n- Visualize modules and assemblies and animate trajectories\n- Define robot tasks and evaluate solutions based on various cost functions\n- Get started working with modular robots!\n\n.. image:: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/animations/demo_animation.gif\n :alt: Animation of a robot assembly moving between two goals\n :align: center\n :target: https://gitlab.lrz.de/tum-cps/timor-python/-/raw/main/img/animations/demo_animation.gif\n\n\nInstallation\n------------\nTimor-python is available on PyPI. It requires **at least Python 3.8** and a linux distribution (for windows and macOS, see below). For installation, use::\n\n pip install timor-python\n\nSome requirements are not included by default - in order to install them, use::\n\n pip install timor-python[option]\n\nwhere option can be one or multiple (comma-separated) of the following:\n\n- ``dev``: Installs development requirements for local unittesting\n- ``optimization``: Installs useful requirements for optimizing module composition.\n- ``viz``: This installs a custom meshcat version and enables you to place billboards in the meshcat visualizer. It is **not** available on PyPI.\n- ``full``: All of the above - except for the custom meshcat visualizer.\n\nIf you want to work with the bleeding-edge version, you can download the source code from the project repository and install it locally.\nNagivate to the timor-python repository you cloned and enter::\n\n pip install -e .\n\nto install it in editeable mode. This requires :code:`setuptools>=61` and :code:`pip>=21.3` (previous versions of setuptools require a :code:`setup.py`-file). To install optional dependencies, proceed in the same manner as for PyPI installs.\n\nTo run unittest locally, you need to `setup git lfs <https://git-lfs.com/>`_ in order to download assets.\n\nIf you want to use pre-commit hooks provided with Timor, for installation please use::\n\n pip install pre-commit\n\nthen::\n\n pre-commit install\n\n\nAfter that, each time you commit files, it will automatically perform linting and style checks.\n\nother OS: Currently, Windows and MacOS are not officially supported. Crucially, pinocchio is not available on PyPI for these operating systems.\nHowever, if you want to use Timor, you can try::\n\n pip install --no-deps timor-python\n conda install pinocchio -c conda-forge\n\nand then :code:`pip install` all other requirements from the [dependencies] section in the `pyproject.toml file. <https://gitlab.lrz.de/tum-cps/timor-python/-/blob/main/pyproject.toml>`_\n\nUsage\n-----\nThe `tutorials folder <tutorials/>`_ contains jupyter notebooks that cover the most common use cases for Timor.\nTo open and run the notebooks, you will need jupyter, which can be installed from PyPI::\n\n pip install jupyterlab\n\nTo inspect, run, or edit the tutorials, navigate to the tutorials folder and start the notebook::\n\n jupyter lab\n\nYou can set custom configurations such as file paths of robot libraries or logging behavior by editing the config file. You can import the file location of the config file as :code:`from timor.utilities.configurations import CONFIG_FILE`.\n\nFor further information, please visit the `documentation <https://timor-python.readthedocs.io>`_.\n\nUpdating\n--------\n\nSome timor updates might require to re-acquire the task, schema, or robot module data-bases. Try to reset the caches by running ``timor.utilities.file_locations.clean_caches()`` and re-import the timor module.\n\nTypical errors indicating this action:\n * ValueError: modules.json invalid.\n\nSupport\n-------\nDo you have a question or an issue using Timor? You can either `submit an issue <https://gitlab.lrz.de/tum-cps/timor-python/-/issues>`_ or write an email to the `repository maintainer <mailto:jonathan.kuelz@tum.de>`_.\n\nContributing\n------------\nWe welcome every contribution to Timor. For more details, please refer to our `contribution guidelines <https://gitlab.lrz.de/tum-cps/timor-python/-/blob/main/CONTRIBUTING.md>`_.\n\nCiting Timor\n------------\nIf you want to cite Timor for your academic research, please use the following bibtex entry::\n\n\t@InProceedings{Kuelz2023,\n\t author = {K\u00fclz, Jonathan and Mayer, Matthias and Althoff, Matthias},\n\t booktitle = {International Conference on Intelligent Robots and Systems},\n\t title = {{Timor Python}: A Toolbox for Industrial Modular Robotics},\n\t pages\t = {424--431},\n\t year = {2023},\n\t publisher = {IEEE},\n\t doi = {10.1109/IROS55552.2023.10341935},\n\t}\n\n\n\nAuthors and acknowledgment\n--------------------------\nTimor was developed at the chair of robotics, artificial intelligence and embedded systems at TU Munich.\nIt is designed, developed and maintained by Jonathan K\u00fclz, Matthias Mayer, and Matthias Althoff.\n\nThe Timor Python logo was AI-generated using the OpenAI's Dall-E 2 API.\n\nThe developers gratefully acknowledge financial support by the Horizon 2020 EU Framework Project `CONCERT <https://concertproject.eu/>`_.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Toolbox for Industrial Modular Robots",
"version": "1.0",
"project_urls": {
"Bug Tracker": "https://gitlab.lrz.de/tum-cps/timor-python/-/issues",
"Documentation": "https://timor-python.readthedocs.io/en/latest/",
"Source Code": "https://gitlab.lrz.de/tum-cps/timor-python"
},
"split_keywords": [
"modular reconfigurable robots",
"robot design",
"model generation",
"simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a04b896b4a811f48576956d719133fc5178b49c3bacbbe19f5a5262efd30f24",
"md5": "0b861c8f26ab3f216fa4521d7f9e0db6",
"sha256": "a29082ba4a5d7c0c020e8fd745899c00269611a1eb161e70000f9b35e6b18a55"
},
"downloads": -1,
"filename": "timor_python-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b861c8f26ab3f216fa4521d7f9e0db6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5748408,
"upload_time": "2024-03-06T16:38:01",
"upload_time_iso_8601": "2024-03-06T16:38:01.084070Z",
"url": "https://files.pythonhosted.org/packages/7a/04/b896b4a811f48576956d719133fc5178b49c3bacbbe19f5a5262efd30f24/timor_python-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a12ef1f162c20bdfec04ddd26b1dcfa80c589e927df85557a1ce8839db61e8ad",
"md5": "dad6cc99c5bfb1f3d33e416e661b5e4b",
"sha256": "d9a718e08a138bfb722e3d29691d04015779f910bedff03178acb5cc3a43ba89"
},
"downloads": -1,
"filename": "timor-python-1.0.tar.gz",
"has_sig": false,
"md5_digest": "dad6cc99c5bfb1f3d33e416e661b5e4b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5764444,
"upload_time": "2024-03-06T16:38:04",
"upload_time_iso_8601": "2024-03-06T16:38:04.716514Z",
"url": "https://files.pythonhosted.org/packages/a1/2e/f1f162c20bdfec04ddd26b1dcfa80c589e927df85557a1ce8839db61e8ad/timor-python-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 16:38:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "timor-python"
}
JSON