taochenshh/dexenv

---
license: mit
---

# Visual Dexterity

---

This is the codebase for [Visual Dexterity: In-Hand Reorientation of Novel and Complex Object Shapes](https://arxiv.org/abs/2211.11744), accepted by Science Robotics. While we provide the code that uses the D'Claw robot hand, it can be easily adapted to other robot hands.

### [[Project Page]](https://taochenshh.github.io/projects/visual-dexterity), [[Science Robotics]](https://www.science.org/doi/10.1126/scirobotics.adc9244), [[arXiv]](https://arxiv.org/abs/2211.11744), [[Github]](https://github.com/Improbable-AI/dexenv)

[](https://doi.org/10.5281/zenodo.10039109)

## :books: Citation

```
@article{chen2023visual,
author = {Tao Chen and Megha Tippur and Siyang Wu and Vikash Kumar and Edward Adelson and Pulkit Agrawal },
title = {Visual dexterity: In-hand reorientation of novel and complex object shapes},
journal = {Science Robotics},
volume = {8},
number = {84},
pages = {eadc9244},
year = {2023},
doi = {10.1126/scirobotics.adc9244},
URL = {https://www.science.org/doi/abs/10.1126/scirobotics.adc9244},
eprint = {https://www.science.org/doi/pdf/10.1126/scirobotics.adc9244},
}
```

```
@article{chen2021system,
title={A System for General In-Hand Object Re-Orientation},
author={Chen, Tao and Xu, Jie and Agrawal, Pulkit},
journal={Conference on Robot Learning},
year={2021}
}
```

## :gear: Installation

#### Dependencies
* [PyTorch](https://pytorch.org/)
* [PyTorch3D](https://pytorch3d.org/)
* [Isaac Gym](https://developer.nvidia.com/isaac-gym) (results in the paper are trained with Preview 3.)
* [IsaacGymEnvs](https://github.com/NVIDIA-Omniverse/IsaacGymEnvs)
* [Minkowski Engine](https://github.com/NVIDIA/MinkowskiEngine)
* [Wandb](https://wandb.ai/site)

#### Download packages
You can either use a virtual python environment or a docker for training. Below we show the process to set up the docker image. If you prefer using a virtual python environment, you can just install the dependencies in the virtual environment.

Here is how the directory looks like:
```
-- Root
---- dexenv
---- IsaacGymEnvs
---- isaacgym
```

```
# download packages
git clone [e-mail]:Improbable-AI/dexenv.git
git clone https://github.com/NVIDIA-Omniverse/IsaacGymEnvs.git

# download IsaacGym from:
# (https://developer.nvidia.com/isaac-gym)
# unzip it in the current directory

# remove the package dependencies in the setup.py in isaacgym/python and IsaacGymEnvs/
```

#### Download the assets

Download the robot and object assets from [here](https://huggingface.co/datasets/taochenshh/dexenv/blob/main/assets.zip), and unzip it to `dexenv/dexenv/`.

#### Download the pretrained models

Download the pretrained checkpoints from [here](https://huggingface.co/datasets/taochenshh/dexenv/blob/main/pretrained.zip), and unzip it to `dexenv/dexenv/`.

#### Prepare the docker image
1. You can download a pre-built docker image:
```
docker pull improbableailab/dexenv:latest
```
2. Or you can build the docker image locally:
```
cd dexenv/docker
python docker_build.py -f Dockerfile
```

#### Launch the docker image

To run the docker image, you would need to have the nvidia-docker installed. Follow the instructions [here](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
```bash
# launch docker
./run_image.sh # you would need to have wandb installed in the python environment
```

In another terminal
```bash
./visualize_access.sh
# after this, you can close it, just need to run this once after every machine reboot
```

## :scroll: Usage

#### :bulb: Training Teacher

```bash
# if you are running in the docker, you might need to run the following line
git config --global --add safe.directory /workspace/dexenv

# debug teacher (run debug first to make sure everything runs)
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py -cn=debug_dclaw # show the GUI
python mlp.py task.headless=True -cn=debug_dclaw # in headless mode

# if you wanna just train the hand to reorient a cube, add `task.env.name=DClawBase`
python mlp.py task.env.name=DClawBase -cn=debug_dclaw

# training teacher
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py -cn=dclaw
python mlp.py task.task.randomize=False -cn=dclaw # turn off domain randomization
python mlp.py task.env.name=DClawBase task.task.randomize=False -cn=dclaw # reorient a cube without domain randomization

# if you wanna change the number of objects or the number of environments
python mlp.py alg.num_envs=4000 task.obj.num_objs=10 -cn=dclaw

# testing teacher
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py alg.num_envs=20 resume_id=<wandb exp ID> -cn=test_dclaw
# e.g. python mlp.py alg.num_envs=20 resume_id=dexenv/1d1tvd0b -cn=test_dclaw

```

#### :high_brightness: Training Student with Synthetic Point Cloud (student stage 1)

```
# debug student
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=debug_dclaw_fptd
# by default, the command above used the pretrained teacher model you downloaded above,
#if you wanna use another teacher model, add `alg.expert_path=<path>`
python rnn.py alg.expert_path=<path to teacher model> -cn=debug_dclaw_fptd

# training student
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=dclaw_fptd

# testing student
cd /workspace/dexenv/dexenv/train/student
python rnn.py resume_id=<wandb exp ID> -cn=test_dclaw_fptd
```

#### :tada: Training Student with rendered Point Cloud (student stage 2)

```
# debug student
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=debug_dclaw_rptd

# training student
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=dclaw_rptd

# testing student
cd /workspace/dexenv/dexenv/train/student
python rnn.py resume_id=<wandb exp ID> -cn=test_dclaw_rptd
```

## :rocket: Pre-trained models

We provide the pre-trained models for both the teacher and the student (stage 2) in `dexenv/expert/artifacts`. The models were trained using Isaac Gym preview 3.

```
# to see the teacher pretrained model
cd /workspace/dexenv/dexenv/train/teacher
python demo.py

# to see the student pretrained model
cd /workspace/dexenv/dexenv/train/student
python rnn.py alg.num_envs=20 task.obj.num_objs=10 alg.pretrain_model=/workspace/dexenv/dexenv/pretrained/artifacts/student/train-model.pt test_pretrain=True test_num=3 -cn=debug_dclaw_rptd
```

---
license: mit
---

# 视觉灵巧性

---

这是论文《Visual Dexterity: In-Hand Reorientation of Novel and Complex Object Shapes》（发表于《Science Robotics》）的代码库，该论文已被《Science Robotics》收录。我们提供了适用于D'Claw机械抓手（D'Claw robot hand）的代码，但它也可轻松适配其他机械抓手。

### [[项目页面]](https://taochenshh.github.io/projects/visual-dexterity)、[[Science Robotics论文链接]](https://www.science.org/doi/10.1126/scirobotics.adc9244)、[[arXiv链接]](https://arxiv.org/abs/2211.11744)、[[Github仓库]](https://github.com/Improbable-AI/dexenv)

[](https://doi.org/10.5281/zenodo.10039109)

## :books: 引用格式

@article{chen2023visual,
author = {Tao Chen and Megha Tippur and Siyang Wu and Vikash Kumar and Edward Adelson and Pulkit Agrawal },
title = {Visual dexterity: In-hand reorientation of novel and complex object shapes},
journal = {Science Robotics},
volume = {8},
number = {84},
pages = {eadc9244},
year = {2023},
doi = {10.1126/scirobotics.adc9244},
URL = {https://www.science.org/doi/abs/10.1126/scirobotics.adc9244},
eprint = {https://www.science.org/doi/pdf/10.1126/scirobotics.adc9244},
}

@article{chen2021system,
title={A System for General In-Hand Object Re-Orientation},
author={Chen, Tao and Xu, Jie and Agrawal, Pulkit},
journal={Conference on Robot Learning},
year={2021}
}

## :gear: 安装指南

#### 依赖项
* PyTorch（PyTorch）：[官网链接](https://pytorch.org/)
* PyTorch3D（PyTorch3D）：[官网链接](https://pytorch3d.org/)
* Isaac Gym（Isaac Gym）：[官网链接](https://developer.nvidia.com/isaac-gym)（论文中的结果使用Preview 3版本训练）
* IsaacGymEnvs（IsaacGymEnvs）：[仓库链接](https://github.com/NVIDIA-Omniverse/IsaacGymEnvs)
* Minkowski Engine（Minkowski Engine）：[仓库链接](https://github.com/NVIDIA/MinkowskiEngine)
* Wandb（Wandb）：[官网链接](https://wandb.ai/site)

#### 下载包
您可以使用Python虚拟环境或Docker镜像进行训练。以下是Docker镜像的设置流程；若您偏好虚拟环境，直接在虚拟环境中安装依赖项即可。

目录结构如下：

-- Root
---- dexenv
---- IsaacGymEnvs
---- isaacgym

# 下载包
git clone [e-mail]:Improbable-AI/dexenv.git
git clone https://github.com/NVIDIA-Omniverse/IsaacGymEnvs.git

# 从以下链接下载IsaacGym：
# (https://developer.nvidia.com/isaac-gym)
# 在当前目录解压

# 移除isaacgym/python和IsaacGymEnvs/目录下setup.py中的包依赖项

#### 下载资产
从[此处](https://huggingface.co/datasets/taochenshh/dexenv/blob/main/assets.zip)下载机器人和物体资产包，并解压到`dexenv/dexenv/`目录下。

#### 下载预训练模型
从[此处](https://huggingface.co/datasets/taochenshh/dexenv/blob/main/pretrained.zip)下载预训练检查点（pretrained checkpoints），并解压到`dexenv/dexenv/`目录下。

#### 准备Docker镜像
1. 您可以下载预构建的Docker镜像（Docker image）：

docker pull improbableailab/dexenv:latest

2. 或本地构建Docker镜像：

cd dexenv/docker
python docker_build.py -f Dockerfile

#### 启动Docker镜像
运行Docker镜像需要安装NVIDIA Docker（nvidia-docker），请参考[安装指南](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。
bash
# 启动Docker
./run_image.sh # 需在Python环境中安装Wandb

在另一个终端中：
bash
./visualize_access.sh
# 执行后可关闭此终端，每次机器重启后只需运行一次

## :scroll: 使用指南

#### :bulb: 训练教师模型
bash
# 若在Docker中运行，可能需要执行以下命令
git config --global --add safe.directory /workspace/dexenv

# 调试教师模型（先运行调试确保所有程序正常）
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py -cn=debug_dclaw # 显示图形用户界面（GUI）
python mlp.py task.headless=True -cn=debug_dclaw # 无头模式（headless mode）

# 若仅需训练抓手重定向立方体，添加`task.env.name=DClawBase`参数
python mlp.py task.env.name=DClawBase -cn=debug_dclaw

# 训练教师模型
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py -cn=dclaw
python mlp.py task.task.randomize=False -cn=dclaw # 关闭域随机化（domain randomization）
python mlp.py task.env.name=DClawBase task.task.randomize=False -cn=dclaw # 无域随机化的立方体重定向训练

# 若需修改物体数量或环境数量
python mlp.py alg.num_envs=4000 task.obj.num_objs=10 -cn=dclaw

# 测试教师模型
cd /workspace/dexenv/dexenv/train/teacher
python mlp.py alg.num_envs=20 resume_id=<wandb实验ID> -cn=test_dclaw
# 示例：python mlp.py alg.num_envs=20 resume_id=dexenv/1d1tvd0b -cn=test_dclaw

#### :high_brightness: 使用合成点云训练学生模型（第一阶段）

# 调试学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=debug_dclaw_fptd
# 默认使用上述下载的预训练教师模型，若需使用其他模型，添加`alg.expert_path=<路径>`参数
python rnn.py alg.expert_path=<教师模型路径> -cn=debug_dclaw_fptd

# 训练学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=dclaw_fptd

# 测试学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py resume_id=<wandb实验ID> -cn=test_dclaw_fptd

#### :tada: 使用渲染点云训练学生模型（第二阶段）

# 调试学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=debug_dclaw_rptd

# 训练学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py -cn=dclaw_rptd

# 测试学生模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py resume_id=<wandb实验ID> -cn=test_dclaw_rptd

## :rocket: 预训练模型
我们在`dexenv/expert/artifacts`目录下提供了教师模型和第二阶段学生模型的预训练版本，这些模型使用Isaac Gym Preview 3训练。

# 查看教师预训练模型
cd /workspace/dexenv/dexenv/train/teacher
python demo.py

# 查看学生预训练模型
cd /workspace/dexenv/dexenv/train/student
python rnn.py alg.num_envs=20 task.obj.num_objs=10 alg.pretrain_model=/workspace/dexenv/dexenv/pretrained/artifacts/student/train-model.pt test_pretrain=True test_num=3 -cn=debug_dclaw_rptd

原始信息汇总

数据集概述

数据集名称

• Visual Dexterity

数据集描述

• 该数据集为Visual Dexterity: In-Hand Reorientation of Novel and Complex Object Shapes的研究代码库，已被Science Robotics接受。主要用于支持DClaw机器人手的操作，但可适应于其他机器人手。

许可证

• MIT

引用信息

@article{chen2023visual, author = {Tao Chen and Megha Tippur and Siyang Wu and Vikash Kumar and Edward Adelson and Pulkit Agrawal }, title = {Visual dexterity: In-hand reorientation of novel and complex object shapes}, journal = {Science Robotics}, volume = {8}, number = {84}, pages = {eadc9244}, year = {2023}, doi = {10.1126/scirobotics.adc9244}, URL = {https://www.science.org/doi/abs/10.1126/scirobotics.adc9244}, eprint = {https://www.science.org/doi/pdf/10.1126/scirobotics.adc9244}, }

安装依赖

• PyTorch
• PyTorch3D
• Isaac Gym
• IsaacGymEnvs
• Minkowski Engine
• Wandb

下载资源

• 机器人和对象资产：从此处下载并解压至dexenv/dexenv/。
• 预训练模型：从此处下载并解压至dexenv/dexenv/。

预训练模型位置

• 教师模型：dexenv/expert/artifacts
• 学生模型（阶段2）：dexenv/expert/artifacts

使用说明

• 训练教师：在/workspace/dexenv/dexenv/train/teacher目录下使用python mlp.py命令进行训练和测试。
• 训练学生：分两个阶段，在/workspace/dexenv/dexenv/train/student目录下使用python rnn.py命令进行训练和测试。

预训练模型演示

• 教师模型演示：在/workspace/dexenv/dexenv/train/teacher目录下运行python demo.py。
• 学生模型演示：在/workspace/dexenv/dexenv/train/student目录下配置参数后运行python rnn.py。

搜集汇总

数据集介绍

构建方式

在机器人灵巧操作领域，视觉引导下的物体重定向任务对数据集的构建提出了高要求。该数据集依托D'Claw机器人手平台，通过Isaac Gym仿真环境生成。构建过程采用两阶段训练范式：首先在仿真环境中训练教师策略，利用强化学习算法生成专家演示数据；随后基于合成点云与渲染点云，分阶段训练学生策略以学习视觉表征。数据集包含多样化的物体形状与姿态，并通过域随机化技术增强泛化能力，为视觉灵巧操作研究提供了高质量的仿真训练资源。

特点

该数据集的核心特点在于其专注于复杂形状物体的在手机器人重定向任务。数据集涵盖了新颖且形态各异的物体，通过高保真仿真环境模拟真实物理交互。其采用渐进式训练架构，将教师策略的强化学习与学生策略的视觉模仿学习相结合，有效解决了从状态信息到视觉观察的迁移难题。数据集提供了完整的训练代码、预训练模型及资产文件，支持在Docker环境中快速复现，确保了实验的可重复性与易用性。

使用方法

使用该数据集需遵循其提供的结构化流程。首先配置依赖环境，包括PyTorch、Isaac Gym等核心库，并下载机器人及物体资产。通过提供的Docker镜像可快速搭建实验环境。训练过程分为教师策略训练、基于合成点云的学生训练以及基于渲染点云的学生训练三个阶段，每个阶段均有对应的调试、训练与测试脚本。用户可通过修改配置文件参数调整环境数量、物体数目等，并利用预训练模型进行快速验证与部署。

背景与挑战

背景概述

视觉灵巧性数据集（taochenshh/dexenv）由麻省理工学院Improbable AI实验室的研究团队于2023年创建，并发表于《科学机器人》期刊。该数据集旨在解决机器人灵巧操作中的核心问题——在复杂动态环境中对新颖及不规则形状物体进行精确的手内重定向。研究团队通过结合深度强化学习与视觉感知技术，构建了一个包含多样化物体模型与仿真环境的综合性资源，推动了机器人从结构化任务向通用化灵巧操作的范式转变，为后续研究提供了关键的基准平台。

当前挑战

该数据集致力于应对机器人手内重定向任务的多重挑战：在领域层面，需克服高维状态空间下的动作规划复杂性、物体形状与物理特性的高度不确定性，以及视觉感知与运动控制的实时协同难题。在构建过程中，研究团队面临仿真环境与真实世界间的动力学差异、大规模多样化物体模型的生成与标注，以及从仿真到实际机器人的跨域迁移等工程挑战，这些因素共同构成了数据集开发的核心难点。

常用场景

经典使用场景

在机器人灵巧操作领域，Visual Dexterity数据集为研究复杂物体在手中的重定向任务提供了关键支持。该数据集通过模拟环境生成多样化物体的点云数据，结合强化学习框架，使机器人能够学习如何仅凭视觉输入对未知形状的物体进行精确的抓取和旋转操作。这一场景不仅验证了视觉感知与运动控制的有效结合，还为后续研究提供了标准化的训练与评估基准。

实际应用

在实际工业与服务业中，Visual Dexterity数据集所支撑的技术能够应用于自动化装配、物流分拣及家庭服务机器人等场景。例如，在仓储环境中，机器人可借助该技术灵活抓取形状各异的包裹并进行定向摆放；在医疗辅助领域，机械手能够安全地操作不规则器械。这些应用不仅提高了作业效率，还降低了对人工预编程的依赖，展现了智能化操作的广阔前景。

衍生相关工作

基于Visual Dexterity数据集，多项经典研究工作得以衍生，进一步拓展了视觉灵巧操作的边界。例如，后续研究通过引入更高效的点云处理网络，提升了模型对遮挡与噪声的鲁棒性；亦有工作将多模态感知与触觉反馈相结合，增强了复杂动态环境下的操作稳定性。这些进展共同构成了机器人灵巧操作领域的重要技术脉络，持续推动着该方向向更高层次的自主性与通用性发展。