DeformableGym

This repository contains a collection of gymnasium environments built with PyBullet and MuJoCo. In these environments, the agent needs to learn to grasp deformable 3D objects such as shoe insoles or pillows from sparse reward signals.

Installation

Install from PyPI

The easiest way to install deformable_gym is via PyPI:

pip install deformable_gym

Install from source

Alternatively, e.g. if you want to develop extensions, you can also clone the repository and then install it in editable mode:

git clone git@github.com:dfki-ric/deformable_gym.git
pip install -e .

Optional dependencies

To install the mujoco versions of the environments, use pip install 'deformable_gym[mujoco]'.

To install the development dependencies, use pip install 'deformable_gym[dev]'.

You can install all optional dependencies using pip install 'deformable_gym[all]'.

Available environments

Example

Here is an example of how to run a random agent in the FloatingMiaEnv. More can be found in the examples/ folder.

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):

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:

pip install numpydoc sphinx sphinx-gallery sphinx-bootstrap-theme

Contributing

If you wish to report bugs, please use the issue tracker. If you would like to contribute to DeformableGym, just open an issue or a pull request. 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.

@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 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 of the German Research Center for Artificial Intelligence (DFKI) in Bremen together with the Robotics Group of the University of Bremen. At this phase, the work was supported through a grant from the European Commission (870142).