Skip to content

Commit 3c55db4

Browse files
nosewormiakinola23kellyguo11
authored
Adds Factory contact-rich manipulation tasks to IsaacLab (#1520)
# Description This MR adds new tasks for contact-rich manipulation based on the Factory line of work. Tasks include peg insertion, gear meshing, and nut threading. ## Type of change - New feature (non-breaking change which adds functionality) - This change requires a documentation update ## Screenshots <img src="https://github.com/user-attachments/assets/c8c32592-8972-4b1e-be7c-51b0313393bf" alt="peg_insertion" height="200"/> <img src="https://github.com/user-attachments/assets/437baf31-f9cb-4a27-94ac-5f21e2309089" alt="gear_meshing" height="200"/> <img src="https://github.com/user-attachments/assets/bccdf71b-cd5f-45f7-b4ca-71616885ef48" alt="nut_threading" height="200"/> ## Checklist - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [x] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file - [x] I have added my name to the `CONTRIBUTORS.md` or my name already exists there --------- Signed-off-by: Kelly Guo <[email protected]> Signed-off-by: Kelly Guo <[email protected]> Co-authored-by: Iretiayo Akinola <[email protected]> Co-authored-by: Kelly Guo <[email protected]> Co-authored-by: Kelly Guo <[email protected]>
1 parent fc6042f commit 3c55db4

File tree

16 files changed

+1963
-3
lines changed

16 files changed

+1963
-3
lines changed

‎CONTRIBUTORS.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ Guidelines for modifications:
5050
* Haoran Zhou
5151
* HoJin Jeon
5252
* Hongwei Xiong
53+
* Iretiayo Akinola
5354
* Jan Kerner
5455
* Jean Tampon
5556
* Jia Lin Yuan
@@ -63,6 +64,7 @@ Guidelines for modifications:
6364
* Lorenz Wellhausen
6465
* Masoud Moghani
6566
* Michael Gussert
67+
* Michael Noseworthy
6668
* Muhong Guo
6769
* Nuralem Abizov
6870
* Oyindamola Omotuyi
@@ -91,3 +93,4 @@ Guidelines for modifications:
9193
* Gavriel State
9294
* Hammad Mazhar
9395
* Marco Hutter
96+
* Yashraj Narang

‎docs/source/_static/tasks/factory/gear_mesh.jpg

46.2 KB
Loading

‎docs/source/_static/tasks/factory/nut_thread.jpg

43.5 KB
Loading

‎docs/source/_static/tasks/factory/peg_insert.jpg

42.9 KB
Loading

‎docs/source/overview/environments.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,39 @@ for the lift-cube environment:
152152
.. |cube-shadow-lstm-link| replace:: `Isaac-Repose-Cube-Shadow-OpenAI-LSTM-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/shadow_hand/shadow_hand_env_cfg.py>`__
153153
.. |cube-shadow-vis-link| replace:: `Isaac-Repose-Cube-Shadow-Vision-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/shadow_hand/shadow_hand_vision_env.py>`__
154154

155+
Contact-rich Manipulation
156+
~~~~~~~~~~~~
157+
158+
Environments based on contact-rich manipulation tasks such as peg insertion, gear meshing and nut-bolt fastening.
159+
160+
These tasks share the same task configurations and control options. You can switch between them by specifying the task name.
161+
For example:
162+
163+
* |factory-peg-link|: Peg insertion with the Franka arm
164+
* |factory-gear-link|: Gear meshing with the Franka arm
165+
* |factory-nut-link|: Nut-Bolt fastening with the Franka arm
166+
167+
.. table::
168+
:widths: 33 37 30
169+
170+
+--------------------+-------------------------+-----------------------------------------------------------------------------+
171+
| World | Environment ID | Description |
172+
+====================+=========================+=============================================================================+
173+
| |factory-peg| | |factory-peg-link| | Insert peg into the socket with the Franka robot |
174+
+--------------------+-------------------------+-----------------------------------------------------------------------------+
175+
| |factory-gear| | |factory-gear-link| | Insert and mesh gear into the base with other gears, using the Franka robot |
176+
+--------------------+-------------------------+-----------------------------------------------------------------------------+
177+
| |factory-nut| | |factory-nut-link| | Thread the nut onto the first 2 threads of the bolt, using the Franka robot |
178+
+--------------------+-------------------------+-----------------------------------------------------------------------------+
179+
180+
.. |factory-peg| image:: ../_static/tasks/factory/peg_insert.jpg
181+
.. |factory-gear| image:: ../_static/tasks/factory/gear_mesh.jpg
182+
.. |factory-nut| image:: ../_static/tasks/factory/nut_thread.jpg
183+
184+
.. |factory-peg-link| replace:: `Isaac-Factory-PegInsert-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/factory_env_cfg.py>`__
185+
.. |factory-gear-link| replace:: `Isaac-Factory-GearMesh-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/factory_env_cfg.py>`__
186+
.. |factory-nut-link| replace:: `Isaac-Factory-NutThread-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/factory_env_cfg.py>`__
187+
155188
Locomotion
156189
~~~~~~~~~~
157190

@@ -369,6 +402,18 @@ Comprehensive List of Environments
369402
-
370403
- Manager Based
371404
- **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO), **sb3** (PPO)
405+
* - Isaac-Factory-GearMesh-Direct-v0
406+
-
407+
- Direct
408+
- **rl_games** (PPO)
409+
* - Isaac-Factory-NutThread-Direct-v0
410+
-
411+
- Direct
412+
- **rl_games** (PPO)
413+
* - Isaac-Factory-PegInsert-Direct-v0
414+
-
415+
- Direct
416+
- **rl_games** (PPO)
372417
* - Isaac-Franka-Cabinet-Direct-v0
373418
-
374419
- Direct

‎source/extensions/omni.isaac.lab_tasks/config/extension.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[package]
22

33
# Note: Semantic Versioning is used: https://semver.org/
4-
version = "0.10.15"
4+
version = "0.10.16"
55

66
# Description
77
title = "Isaac Lab Environments"

‎source/extensions/omni.isaac.lab_tasks/docs/CHANGELOG.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,23 @@
11
Changelog
22
---------
33

4+
0.10.16 (2024-12-16)
5+
~~~~~~~~~~~~~~~~~~~~
6+
7+
Added
8+
^^^^^
9+
10+
* Added ``Factory-Direct-v0`` environment as a direct RL env that
11+
implements contact-rich manipulation tasks including peg insertion,
12+
gear meshing, and nut threading.
13+
14+
415
0.10.15 (2024-12-16)
516
~~~~~~~~~~~~~~~~~~~~
617

718
Added
819
^^^^^
20+
921
* Added ``Isaac-Reach-Franka-OSC-v0`` and ``Isaac-Reach-Franka-OSC-Play-v0``
1022
variations of the manager based reach environment that uses
1123
:class:`omni.isaac.lab.envs.mdp.actions.OperationalSpaceControllerAction`.
@@ -20,6 +32,7 @@ Added
2032
* Added ``Isaac-Stack-Cube-Franka-IK-Rel-v0`` and ``Isaac-Stack-Cube-Instance-Randomize-Franka-IK-Rel-v0`` environments
2133
as manager-based RL envs that implement a three cube stacking task.
2234

35+
2336
0.10.13 (2024-10-30)
2437
~~~~~~~~~~~~~~~~~~~~
2538

@@ -49,6 +62,7 @@ Added
4962

5063
* Added feature extracted observation cartpole examples.
5164

65+
5266
0.10.10 (2024-10-25)
5367
~~~~~~~~~~~~~~~~~~~~
5468

‎source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/__init__.py

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Copyright (c) 2022-2024, The Isaac Lab Project Developers.
2+
# All rights reserved.
3+
#
4+
# SPDX-License-Identifier: BSD-3-Clause
5+
6+
import gymnasium as gym
7+
8+
from . import agents
9+
from .factory_env import FactoryEnv
10+
from .factory_env_cfg import FactoryTaskGearMeshCfg, FactoryTaskNutThreadCfg, FactoryTaskPegInsertCfg
11+
12+
##
13+
# Register Gym environments.
14+
##
15+
16+
gym.register(
17+
id="Isaac-Factory-PegInsert-Direct-v0",
18+
entry_point="omni.isaac.lab_tasks.direct.factory:FactoryEnv",
19+
disable_env_checker=True,
20+
kwargs={
21+
"env_cfg_entry_point": FactoryTaskPegInsertCfg,
22+
"rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_ppo_cfg.yaml",
23+
},
24+
)
25+
26+
gym.register(
27+
id="Isaac-Factory-GearMesh-Direct-v0",
28+
entry_point="omni.isaac.lab_tasks.direct.factory:FactoryEnv",
29+
disable_env_checker=True,
30+
kwargs={
31+
"env_cfg_entry_point": FactoryTaskGearMeshCfg,
32+
"rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_ppo_cfg.yaml",
33+
},
34+
)
35+
36+
gym.register(
37+
id="Isaac-Factory-NutThread-Direct-v0",
38+
entry_point="omni.isaac.lab_tasks.direct.factory:FactoryEnv",
39+
disable_env_checker=True,
40+
kwargs={
41+
"env_cfg_entry_point": FactoryTaskNutThreadCfg,
42+
"rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_ppo_cfg.yaml",
43+
},
44+
)

‎source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/agents/__init__.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Copyright (c) 2022-2024, The Isaac Lab Project Developers.
2+
# All rights reserved.
3+
#
4+
# SPDX-License-Identifier: BSD-3-Clause

‎source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks/direct/factory/agents/rl_games_ppo_cfg.yaml

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
params:
2+
seed: 0
3+
algo:
4+
name: a2c_continuous
5+
6+
env:
7+
clip_actions: 1.0
8+
9+
model:
10+
name: continuous_a2c_logstd
11+
12+
network:
13+
name: actor_critic
14+
separate: False
15+
16+
space:
17+
continuous:
18+
mu_activation: None
19+
sigma_activation: None
20+
mu_init:
21+
name: default
22+
sigma_init:
23+
name: const_initializer
24+
val: 0
25+
fixed_sigma: False
26+
mlp:
27+
units: [512, 128, 64]
28+
activation: elu
29+
d2rl: False
30+
31+
initializer:
32+
name: default
33+
regularizer:
34+
name: None
35+
36+
rnn:
37+
name: lstm
38+
units: 1024
39+
layers: 2
40+
before_mlp: True
41+
concat_input: True
42+
layer_norm: True
43+
44+
load_checkpoint: False
45+
load_path: ""
46+
47+
config:
48+
name: Factory
49+
device: cuda:0
50+
full_experiment_name: test
51+
env_name: rlgpu
52+
multi_gpu: False
53+
ppo: True
54+
mixed_precision: True
55+
normalize_input: True
56+
normalize_value: True
57+
value_bootstrap: True
58+
num_actors: 128
59+
reward_shaper:
60+
scale_value: 1.0
61+
normalize_advantage: True
62+
gamma: 0.995
63+
tau: 0.95
64+
learning_rate: 1.0e-4
65+
lr_schedule: adaptive
66+
schedule_type: standard
67+
kl_threshold: 0.008
68+
score_to_win: 20000
69+
max_epochs: 200
70+
save_best_after: 10
71+
save_frequency: 100
72+
print_stats: True
73+
grad_norm: 1.0
74+
entropy_coef: 0.0 # 0.0001 # 0.0
75+
truncate_grads: True
76+
e_clip: 0.2
77+
horizon_length: 128
78+
minibatch_size: 512 # batch size = num_envs * horizon_length; minibatch_size = batch_size / num_minibatches
79+
mini_epochs: 4
80+
critic_coef: 2
81+
clip_value: True
82+
seq_length: 128
83+
bounds_loss_coef: 0.0001
84+
85+
central_value_config:
86+
minibatch_size: 512
87+
mini_epochs: 4
88+
learning_rate: 1e-4
89+
lr_schedule: adaptive
90+
kl_threshold: 0.008
91+
clip_value: True
92+
normalize_input: True
93+
truncate_grads: True
94+
95+
network:
96+
name: actor_critic
97+
central_value: True
98+
99+
mlp:
100+
units: [512, 128, 64]
101+
activation: elu
102+
d2rl: False
103+
104+
initializer:
105+
name: default
106+
regularizer:
107+
name: None
108+
109+
rnn:
110+
name: lstm
111+
units: 1024
112+
layers: 2
113+
before_mlp: True
114+
concat_input: True
115+
layer_norm: True
116+
117+
player:
118+
deterministic: False

0 commit comments

Comments
 (0)