[](https://github.com/dfki-ric/deformable_gym/actions/workflows/test.yaml)
[](https://github.com/psf/black)
[](https://github.com/pre-commit/pre-commit)
[](https://doi.org/10.5281/zenodo.15742434)
# DeformableGym
This repository contains a collection of [gymnasium](https://github.com/Farama-Foundation/Gymnasium) environments built with [PyBullet](https://pybullet.org/) and [MuJoCo](https://github.com/google-deepmind/mujoco).
In these environments, the agent needs to learn to grasp deformable 3D objects such as shoe insoles or pillows from sparse reward signals.
<p align="center">
<img src="doc/source/_static/defgym.svg"/>
</p>
## Installation
```bash
git clone git@github.com:dfki-ric/deformable_gym.git
```
After cloning the repository, it is recommended to install the library in editable mode.
```bash
pip install -e .
```
## Available environments
| Environment Name | PyBullet | MuJoCo |
| ------------------------- | :----------------: | :----------------: |
| FloatingMiaGraspInsole | :heavy_check_mark: | :heavy_check_mark: |
| FloatingShadowGraspInsole | :heavy_check_mark: | :heavy_check_mark: |
| FloatingMiaGraspPillow | :heavy_check_mark: | :heavy_check_mark: |
| FloatingShadowGraspPillow | :heavy_check_mark: | :heavy_check_mark: |
| URMiaGraspInsole | :heavy_check_mark: | :heavy_check_mark: |
| URShadowGraspInsole | :heavy_check_mark: | :heavy_check_mark: |
| URMiaGraspPillow | :heavy_check_mark: | :heavy_check_mark: |
| URShadowGraspPillow | :heavy_check_mark: | :heavy_check_mark: |
### Known Issues
If you use conda, you may experience the error below:
```
libGL error: MESA-LOADER: failed to open iris: /usr/lib/dri/iris_dri.so: cannot open shared object file: No such file or directory (search paths /usr/lib/x86_64-linux-gnu/dri:\$${ORIGIN}/dri:/usr/lib/dri, suffix _dri)
libGL error: failed to load driver: iris
libGL error: MESA-LOADER: failed to open swrast: /usr/lib/dri/swrast_dri.so: cannot open shared object file: No such file or directory (search paths /usr/lib/x86_64-linux-gnu/dri:\$${ORIGIN}/dri:/usr/lib/dri, suffix _dri)
libGL error: failed to load driver: swrast
```
In this case, install the following dependency via conda-forge:
```bash
conda install -c conda-forge libstdcxx-ng
```
## Example
<p align="center">
<img src="doc/source/_static/grasp_grid.gif" />
</p>
Here is an example of how to run a random agent in the FloatingMiaEnv. More can be found in the `examples/` folder.
```Python
import gymnasium
"""
=========
Floating Mia Example
=========
This is an example of how to use the FloatingMiaGraspEnv. A random policy is then
used to generate ten episodes.
"""
env = gymnasium.make("FloatingMiaGraspInsole-v0")
env.reset()
episode_return = 0
num_episodes = 0
while num_episodes <= 10:
action = env.action_space.sample()
state, reward, terminated, truncated, _ = env.step(action)
episode_return += reward
if terminated or truncated:
print(f"Episode finished with return {episode_return}!")
num_episodes += 1
env.reset()
```
## Documentation
The documentation can be found in the directory doc. To build the documentation, run e.g. (on linux):
```bash
cd doc
make html
```
The HTML documentation is now located at doc/build/html/index.html. You need the following packages to build the documentation:
```bash
pip install numpydoc sphinx sphinx-gallery sphinx-bootstrap-theme
```
## Contributing
If you wish to report bugs, please use the [issue tracker](https://github.com/dfki-ric/deformable_gym/issues). If you would like to contribute to DeformableGym, just open an issue or a
[pull request](https://github.com/dfki-ric/deformable_gym/pulls). The target branch for
merge requests is the development branch. The development branch will be merged to main for new releases. If you have
questions about the software, you should ask them in the discussion section.
The recommended workflow to add a new feature, add documentation, or fix a bug is the following:
- Push your changes to a branch (e.g. feature/x, doc/y, or fix/z) of your fork of the deformable_gym repository.
- Open a pull request to the latest development branch. There is usually an open merge request from the latest development branch to the main branch.
- When the latest development branch is merged to the main branch, a new release will be made.
Note that there is a checklist for new features.
It is forbidden to directly push to the main branch. Each new version has its own development branch from which a pull request will be opened to the main branch. Only the maintainers of the software are allowed to merge a development branch to the main branch.
## Referencing
If you use DeformableGym in your research, please consider citing it. You may find the paper [here](https://deformable-workshop.github.io/icra2023/spotlight/03-Laux-spotlight.pdf).
```
@inproceedings{Laux2023,
title = {Grasping 3D Deformable Objects via Reinforcement Learning: A Benchmark and Evaluation},
booktitle = {3rd Workshop on Representing and Manipulating Deformable Objects @ ICRA2023},
author = {Melvin Laux and Chandandeep Singh and Alexander Fabisch},
month = {May},
year = {2023},
url = {https://deformable-workshop.github.io/icra2023/},
}
```
## Releases
### Semantic Versioning
[Semantic versioning](https://semver.org/) must be used, that is, the major version number will be
incremented when the API changes in a backwards incompatible way, the minor
version will be incremented when new functionality is added in a backwards
compatible manner, and the patch version is incremented for bugfixes,
documentation, etc.
## Funding
This library has been developed initially at the
[Robotics Innovation Center](http://robotik.dfki-bremen.de/en/startpage.html) of the
[German Research Center for Artificial Intelligence (DFKI)](http://www.dfki.de) in Bremen together with the
[Robotics Group](https://robotik.dfki-bremen.de/en/about-us/university-of-bremen-robotics-group.html) of the
[University of Bremen](http://www.uni-bremen.de/en.html). At this phase, the work was supported through a grant from the European
Commission (870142).
<p float="left">
<img src="doc/source/_static/DFKI_Logo.png" height="100px" />
<img src="doc/source/_static/Uni_Logo.png" height="100px" />
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "deformable-gym",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Melvin Laux <melvin.laux@uni-bremen.de>",
"keywords": "Reinforcement Learning, Gymnasium, PyBullet, Mujoco",
"author": null,
"author_email": "Melvin Laux <melvin.laux@uni-bremen.de>, Alexander Fabisch <alexander.fabisch@dfki.de>",
"download_url": "https://files.pythonhosted.org/packages/da/03/e05286c20309922a9c1dfaf4093f87546621d297c27a2271c1e4eb957398/deformable_gym-0.5.0.tar.gz",
"platform": null,
"description": "[](https://github.com/dfki-ric/deformable_gym/actions/workflows/test.yaml)\n[](https://github.com/psf/black)\n[](https://github.com/pre-commit/pre-commit)\n[](https://doi.org/10.5281/zenodo.15742434)\n\n# DeformableGym\n\nThis repository contains a collection of [gymnasium](https://github.com/Farama-Foundation/Gymnasium) environments built with [PyBullet](https://pybullet.org/) and [MuJoCo](https://github.com/google-deepmind/mujoco).\nIn these environments, the agent needs to learn to grasp deformable 3D objects such as shoe insoles or pillows from sparse reward signals.\n\n<p align=\"center\">\n <img src=\"doc/source/_static/defgym.svg\"/>\n</p>\n\n## Installation\n\n```bash\ngit clone git@github.com:dfki-ric/deformable_gym.git\n```\n\nAfter cloning the repository, it is recommended to install the library in editable mode.\n\n```bash\npip install -e .\n```\n\n## Available environments\n\n| Environment Name | PyBullet | MuJoCo |\n| ------------------------- | :----------------: | :----------------: |\n| FloatingMiaGraspInsole | :heavy_check_mark: | :heavy_check_mark: |\n| FloatingShadowGraspInsole | :heavy_check_mark: | :heavy_check_mark: |\n| FloatingMiaGraspPillow | :heavy_check_mark: | :heavy_check_mark: |\n| FloatingShadowGraspPillow | :heavy_check_mark: | :heavy_check_mark: |\n| URMiaGraspInsole | :heavy_check_mark: | :heavy_check_mark: |\n| URShadowGraspInsole | :heavy_check_mark: | :heavy_check_mark: |\n| URMiaGraspPillow | :heavy_check_mark: | :heavy_check_mark: |\n| URShadowGraspPillow | :heavy_check_mark: | :heavy_check_mark: |\n\n### Known Issues\n\nIf you use conda, you may experience the error below:\n\n```\nlibGL error: MESA-LOADER: failed to open iris: /usr/lib/dri/iris_dri.so: cannot open shared object file: No such file or directory (search paths /usr/lib/x86_64-linux-gnu/dri:\\$${ORIGIN}/dri:/usr/lib/dri, suffix _dri)\nlibGL error: failed to load driver: iris\nlibGL error: MESA-LOADER: failed to open swrast: /usr/lib/dri/swrast_dri.so: cannot open shared object file: No such file or directory (search paths /usr/lib/x86_64-linux-gnu/dri:\\$${ORIGIN}/dri:/usr/lib/dri, suffix _dri)\nlibGL error: failed to load driver: swrast\n```\nIn this case, install the following dependency via conda-forge:\n\n```bash\nconda install -c conda-forge libstdcxx-ng\n```\n\n## Example\n\n<p align=\"center\">\n <img src=\"doc/source/_static/grasp_grid.gif\" />\n</p>\n\nHere is an example of how to run a random agent in the FloatingMiaEnv. More can be found in the `examples/` folder.\n\n```Python\nimport gymnasium\n\n\"\"\"\n=========\nFloating Mia Example\n=========\n\nThis is an example of how to use the FloatingMiaGraspEnv. A random policy is then\nused to generate ten episodes.\n\n\"\"\"\n\nenv = gymnasium.make(\"FloatingMiaGraspInsole-v0\")\n\nenv.reset()\nepisode_return = 0\nnum_episodes = 0\n\nwhile num_episodes <= 10:\n\n action = env.action_space.sample()\n\n state, reward, terminated, truncated, _ = env.step(action)\n episode_return += reward\n\n if terminated or truncated:\n print(f\"Episode finished with return {episode_return}!\")\n num_episodes += 1\n\n env.reset()\n\n```\n\n## Documentation\n\nThe documentation can be found in the directory doc. To build the documentation, run e.g. (on linux):\n\n```bash\ncd doc\nmake html\n```\n\nThe HTML documentation is now located at doc/build/html/index.html. You need the following packages to build the documentation:\n\n```bash\npip install numpydoc sphinx sphinx-gallery sphinx-bootstrap-theme\n```\n\n## Contributing\n\nIf you wish to report bugs, please use the [issue tracker](https://github.com/dfki-ric/deformable_gym/issues). If you would like to contribute to DeformableGym, just open an issue or a\n[pull request](https://github.com/dfki-ric/deformable_gym/pulls). The target branch for\nmerge requests is the development branch. The development branch will be merged to main for new releases. If you have\nquestions about the software, you should ask them in the discussion section.\n\nThe recommended workflow to add a new feature, add documentation, or fix a bug is the following:\n\n- Push your changes to a branch (e.g. feature/x, doc/y, or fix/z) of your fork of the deformable_gym repository.\n- Open a pull request to the latest development branch. There is usually an open merge request from the latest development branch to the main branch.\n- When the latest development branch is merged to the main branch, a new release will be made.\n\nNote that there is a checklist for new features.\n\nIt is forbidden to directly push to the main branch. Each new version has its own development branch from which a pull request will be opened to the main branch. Only the maintainers of the software are allowed to merge a development branch to the main branch.\n\n## Referencing\n\nIf you use DeformableGym in your research, please consider citing it. You may find the paper [here](https://deformable-workshop.github.io/icra2023/spotlight/03-Laux-spotlight.pdf).\n\n```\n@inproceedings{Laux2023,\ntitle = {Grasping 3D Deformable Objects via Reinforcement Learning: A Benchmark and Evaluation},\nbooktitle = {3rd Workshop on Representing and Manipulating Deformable Objects @ ICRA2023},\nauthor = {Melvin Laux and Chandandeep Singh and Alexander Fabisch},\nmonth = {May},\nyear = {2023},\nurl = {https://deformable-workshop.github.io/icra2023/},\n}\n```\n\n## Releases\n\n### Semantic Versioning\n\n[Semantic versioning](https://semver.org/) must be used, that is, the major version number will be\nincremented when the API changes in a backwards incompatible way, the minor\nversion will be incremented when new functionality is added in a backwards\ncompatible manner, and the patch version is incremented for bugfixes,\ndocumentation, etc.\n\n## Funding\n\nThis library has been developed initially at the\n[Robotics Innovation Center](http://robotik.dfki-bremen.de/en/startpage.html) of the\n[German Research Center for Artificial Intelligence (DFKI)](http://www.dfki.de) in Bremen together with the\n[Robotics Group](https://robotik.dfki-bremen.de/en/about-us/university-of-bremen-robotics-group.html) of the\n[University of Bremen](http://www.uni-bremen.de/en.html). At this phase, the work was supported through a grant from the European\nCommission (870142).\n\n<p float=\"left\">\n <img src=\"doc/source/_static/DFKI_Logo.png\" height=\"100px\" />\n <img src=\"doc/source/_static/Uni_Logo.png\" height=\"100px\" />\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "Gymnasium environments for grasping 3D deformable objects",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/dfki-ric/deformable_gym",
"Issues": "https://github.com/dfki-ric/deformable_gym/issues"
},
"split_keywords": [
"reinforcement learning",
" gymnasium",
" pybullet",
" mujoco"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b34379bccc47825a5f33b1313c947429c6bc8245df8e91ed20f9e312598c9fdd",
"md5": "654a84f2160ce20ee09585c89059e26f",
"sha256": "5940628e9db7efbec625b0306ac2ad5afb4bc644242fdf640376a8978ed99882"
},
"downloads": -1,
"filename": "deformable_gym-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "654a84f2160ce20ee09585c89059e26f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28451166,
"upload_time": "2025-08-01T23:19:54",
"upload_time_iso_8601": "2025-08-01T23:19:54.235535Z",
"url": "https://files.pythonhosted.org/packages/b3/43/79bccc47825a5f33b1313c947429c6bc8245df8e91ed20f9e312598c9fdd/deformable_gym-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "da03e05286c20309922a9c1dfaf4093f87546621d297c27a2271c1e4eb957398",
"md5": "786014c8e21a2c0d65ea5ff22d024c40",
"sha256": "3846662bef53fe99b99a9ff644c215ad7eab3eafaabcceeceaad19aa92c5673e"
},
"downloads": -1,
"filename": "deformable_gym-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "786014c8e21a2c0d65ea5ff22d024c40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 28230109,
"upload_time": "2025-08-01T23:20:03",
"upload_time_iso_8601": "2025-08-01T23:20:03.775134Z",
"url": "https://files.pythonhosted.org/packages/da/03/e05286c20309922a9c1dfaf4093f87546621d297c27a2271c1e4eb957398/deformable_gym-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 23:20:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dfki-ric",
"github_project": "deformable_gym",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "gymnasium",
"specs": [
[
">=",
"1.0.0a2"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.23.5"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "pybullet",
"specs": [
[
">=",
"3.2.5"
]
]
},
{
"name": "pytransform3d",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.10.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"65.5.1"
]
]
},
{
"name": "mujoco",
"specs": [
[
"==",
"3.2.3"
]
]
},
{
"name": "imageio",
"specs": [
[
">=",
"2.34.1"
]
]
}
],
"lcname": "deformable-gym"
}
JSON
