Bi-DexHands: Bimanual Dexterous Manipulation via Reinforcement Learning

Update

[2023/02/09] We re-package the Bi-DexHands. Now you can call the Bi-DexHands' environments not only on the command line, but also in your Python script. check our README Use Bi-DexHands in Python scripts below.

[2022/11/24] Now we support visual observation for all the tasks, check this document for visual input.

[2022/10/02] Now we support for the default IsaacGymEnvs RL library rl-games, check our README below.

Bi-DexHands (click bi-dexhands.ai) provides a collection of bimanual dexterous manipulations tasks and reinforcement learning algorithms. Reaching human-level sophistication of hand dexterity and bimanual coordination remains an open challenge for modern robotics researchers. To better help the community study this problem, Bi-DexHands are developed with the following key features:

Isaac Efficiency: Bi-DexHands is built within Isaac Gym; it supports running thousands of environments simultaneously. For example, on one NVIDIA RTX 3090 GPU, Bi-DexHands can reach 40,000+ mean FPS by running 2,048 environments in parallel.
Comprehensive RL Benchmark: we provide the first bimanual manipulation task environment for RL, MARL, Multi-task RL, Meta RL, and Offline RL practitioners, along with a comprehensive benchmark for SOTA continuous control model-free RL/MARL methods. See example
Heterogeneous-agents Cooperation: Agents in Bi-DexHands (i.e., joints, fingers, hands,...) are genuinely heterogeneous; this is very different from common multi-agent environments such as SMAC where agents can simply share parameters to solve the task.
Task Generalization: we introduce a variety of dexterous manipulation tasks (e.g., handover, lift up, throw, place, put...) as well as enormous target objects from the YCB and SAPIEN dataset (>2,000 objects); this allows meta-RL and multi-task RL algorithms to be tested on the task generalization front.
Point Cloud: We provide the ability to use point clouds as observations. We used the depth camera in Isaacc Gym to get the depth image and then convert it to partial point cloud. We can customize the pose and numbers of depth cameras to get point cloud from difference angles. The density of generated point cloud depends on the number of the camera pixels. See the visual input docs.
Quick Demos

Contents of this repo are as follows:

Installation
- Pre-requisites

- Install from source code
Introduction to Bi-DexHands
Overview of Environments
Overview of Algorithms
Getting Started
Enviroments Performance
- Figures
Offline RL Datasets
Use rl_games to train our tasks
Future Plan
Customizing your Environments
How to change the type of dexterous hand
How to add a robotic arm drive to the dexterous hand
The Team
License <br></br>

For more information about this work, please check our paper.

Installation

Details regarding installation of IsaacGym can be found here. We currently support the Preview Release 3/4 version of IsaacGym.

Pre-requisites

The code has been tested on Ubuntu 18.04/20.04 with Python 3.7/3.8. The minimum recommended NVIDIA driver version for Linux is 470.74 (dictated by support of IsaacGym).

It uses Anaconda to create virtual environments. To install Anaconda, follow instructions here.

Ensure that Isaac Gym works on your system by running one of the examples from the python/examples directory, like joint_monkey.py. Please follow troubleshooting steps described in the Isaac Gym Preview Release 3/4 install instructions if you have any trouble running the samples.

Once Isaac Gym is installed and samples work within your current python environment, install this repo:

Install from source code

You can also install this repo from the source code:

pip install -e .

Introduction

This repository contains complex dexterous hands control tasks. Bi-DexHands is built in the NVIDIA Isaac Gym with high performance guarantee for training RL algorithms. Our environments focus on applying model-free RL/MARL algorithms for bimanual dexterous manipulation, which are considered as a challenging task for traditional control methods.

Getting Started

<span id="task">Tasks</span>

Source code for tasks can be found in envs/tasks. The detailed settings of state/action/reward are in here.

So far, we release the following tasks (with many more to come):

Environments	Description	Demo
ShadowHand Over	These environments involve two fixed-position hands. The hand which starts with the object must find a way to hand it over to the second hand.	<img src="assets/image_folder/0v2.gif" width="250"/>
ShadowHandCatch Underarm	These environments again have two hands, however now they have some additional degrees of freedom that allows them to translate/rotate their centre of masses within some constrained region.	<img src="assets/image_folder/hand_catch_underarmv2.gif" align="middle" width="250"/>
ShadowHandCatch Over2Underarm	This environment is made up of half ShadowHandCatchUnderarm and half ShadowHandCatchOverarm, the object needs to be thrown from the vertical hand to the palm-up hand	<img src="assets/image_folder/2v2.gif" align="middle" width="250"/>
ShadowHandCatch Abreast	This environment is similar to ShadowHandCatchUnderarm, the difference is that the two hands are changed from relative to side-by-side posture.	<img src="assets/image_folder/1v2.gif" align="middle" width="250"/>
ShadowHandCatch TwoCatchUnderarm	These environments involve coordination between the two hands so as to throw the two objects between hands (i.e. swapping them).	<img src="assets/image_folder/two_catchv2.gif" align="middle" width="250"/>
ShadowHandLift Underarm	This environment requires grasping the pot handle with two hands and lifting the pot to the designated position	<img src="assets/image_folder/3v2.gif" align="middle" width="250"/>
ShadowHandDoor OpenInward	This environment requires the closed door to be opened, and the door can only be pulled inwards	<img src="assets/image_folder/door_open_inwardv2.gif" align="middle" width="250"/>
ShadowHandDoor OpenOutward	This environment requires a closed door to be opened and the door can only be pushed outwards	<img src="assets/image_folder/open_outwardv2.gif" align="middle" width="250"/>
ShadowHandDoor CloseInward	This environment requires the open door to be closed, and the door is initially open inwards	<img src="assets/image_folder/close_inwardv2.gif" align="middle" width="250"/>
ShadowHand BottleCap	This environment involves two hands and a bottle, we need to hold the bottle with one hand and open the bottle cap with the other hand	<img src="assets/image_folder/bottle_capv2.gif" align="middle" width="250"/>
ShadowHandPush Block	This environment requires both hands to touch the block and push it forward	<img src="assets/image_folder/push_block.gif" align="middle" width="250"/>
ShadowHandOpen Scissors	This environment requires both hands to cooperate to open the scissors	<img src="assets/image_folder/scissors.gif" align="middle" width="250"/>
ShadowHandOpen PenCap	This environment requires both hands to cooperate to open the pen cap	<img src="assets/image_folder/pen.gif" align="middle" width="250"/>
ShadowHandSwing Cup	This environment requires two hands to hold the cup handle and rotate it 90 degrees	<img src="assets/image_folder/swing_cup.gif" align="middle" width="250"/>
ShadowHandTurn Botton	This environment requires both hands to press the button	<img src="assets/image_folder/switch.gif" align="middle" width="250"/>
ShadowHandGrasp AndPlace	This environment has a bucket and an object, we need to put the object into the bucket	<img src="assets/image_folder/g&p.gif" align="middle" width="250"/>

Training

Training Examples

RL/MARL Examples

For example, if you want to train a policy for the ShadowHandOver task by the PPO algorithm, run this line in bidexhands folder:

python train.py --task=ShadowHandOver --algo=ppo

To select an algorithm, pass --algo=ppo/mappo/happo/hatrpo/... as an argument. For example, if you want to use happo algorithm, run this line in bidexhands folder:

python train.py --task=ShadowHandOver --algo=happo

Supported Single-Agent RL algorithms are listed below:

Supported Multi-Agent RL algorithms are listed below:

Multi-task/Meta RL Examples

The training method of multi-task/meta RL is similar to the RL/MARL, it is only need to select the multi-task/meta categories and the corresponding algorithm. For example, if you want to train a policy for the ShadowHandMT4 categories by the MTPPO algorithm, run this line in bidexhands folder:

python train.py --task=ShadowHandMetaMT4 --algo=mtppo

Supported Multi-task RL algorithms are listed below:

Supported Meta RL algorithms are listed below:

ProMP: Proximal Meta-Policy Search (ProMP)

Gym-Like API

We provide a Gym-Like API that allows us to get information from the Isaac Gym environment. Our single-agent Gym-Like wrapper is the code of the Isaac Gym team used, and we have developed a multi-agent Gym-Like wrapper based on it:

class MultiVecTaskPython(MultiVecTask):
    # Get environment state information
    def get_state(self):
        return torch.clamp(self.task.states_buf, -self.clip_obs, self.clip_obs).to(self.rl_device)

    def step(self, actions):
        # Stack all agent actions in order and enter them into the environment
        a_hand_actions = actions[0]
        for i in range(1, len(actions)):
            a_hand_actions = torch.hstack((a_hand_actions, actions[i]))
        actions = a_hand_actions
        # Clip the actions
        actions_tensor = torch.clamp(actions, -self.clip_actions, self.clip_actions)
        self.task.step(actions_tensor)
        # Obtain information in the environment and distinguish the observation of different agents by hand
        obs_buf = torch.clamp(self.task.obs_buf, -self.clip_obs, self.clip_obs).to(self.rl_device)
        hand_obs = []
        hand_obs.append(torch.cat([obs_buf[:, :self.num_hand_obs], obs_buf[:, 2*self.num_hand_obs:]], dim=1))
        hand_obs.append(torch.cat([obs_buf[:, self.num_hand_obs:2*self.num_hand_obs], obs_buf[:, 2*self.num_hand_obs:]], dim=1))
        rewards = self.task.rew_buf.unsqueeze(-1).to(self.rl_device)
        dones = self.task.reset_buf.to(self.rl_device)
        # Organize information into Multi-Agent RL format
        # Refer to https://github.com/tinyzqh/light_mappo/blob/HEAD/envs/env.py
        sub_agent_obs = []
        ...
        sub_agent_done = []
        for i in range(len(self.agent_index[0] + self.agent_index[1])):
            ...
            sub_agent_done.append(dones)
        # Transpose dim-0 and dim-1 values
        obs_all = torch.transpose(torch.stack(sub_agent_obs), 1, 0)
        ...
        done_all = torch.transpose(torch.stack(sub_agent_done), 1, 0)
        return obs_all, state_all, reward_all, done_all, info_all, None

    def reset(self):
        # Use a random action as the first action after the environment reset
        actions = 0.01 * (1 - 2 * torch.rand([self.task.num_envs, self.task.num_actions * 2], dtype=torch.float32, device=self.rl_device))
        # step the simulator
        self.task.step(actions)
        # Get the observation and state buffer in the environment, the detailed are the same as step(self, actions)
        obs_buf = torch.clamp(self.task.obs_buf, -self.clip_obs, self.clip_obs)
        ...
        obs = torch.transpose(torch.stack(sub_agent_obs), 1, 0)
        state_all = torch.transpose(torch.stack(agent_state), 1, 0)
        return obs, state_all, None

RL/Multi-Agent RL API

We also provide single-agent and multi-agent RL interfaces. In order to adapt to Isaac Gym and speed up the running efficiency, all operations are implemented on GPUs using tensor. Therefore, there is no need to transfer data between the CPU and GPU.

We give an example using HATRPO (the SOTA MARL algorithm for cooperative tasks) to illustrate multi-agent RL APIs, please refer to