ISyHand Simulation Experiments

This project contains the code for the simulation experiments in the following publication:

Benjamin A. Richardson, Felix Grüninger, Lukas Mack, Joerg Stueckler and Katherine J. Kuchenbecker, "ISyHand: A Dexterous Multi-finger Robot Hand with an Articulated Palm". In IEEE-RAS International Conference on Humanoid Robots (Humanoids) 2025, Seoul, Korea.
Paper: https://ieeexplore.ieee.org/document/11203015
Preprint: https://arxiv.org/abs/2509.26236

ISyHand project page: https://isyhand.is.mpg.de/

Setup

This project is based on the IsaacGymEnvs repository at commit aeed298. Please follow their installation instructions to install Isaac Gym and setup IsaacGymEnvs.

The URDF and mesh files of all four robot hands are not included in this repository and need to be downloaded from their respective sources. Please note the respective licenses of these files when downloading and copying them over.

The ISyHand and ISyHand (flat) URDF and mesh files need to be downloaded from the official ISyHand website:

• Visit https://isyhand.is.mpg.de/ and navigate to the download section.
• Download the isyhand_v6_isaacgym.zip and extract the content to assets/urdf/isyhand_description.

The Allegro hand and objects URDF and mesh files need to be downloaded from the original IsaacGymEnvs repository:

• Clone the IsaacGymEnvs repository at commit aeed298.
• Navigate to the assets/urdf/kuka_allegro_description directory and copy over its content to the assets/urdf/kuka_allegro_description directory of this repository.
• Navigate to the assets/urdf/objects directory and copy over its content to the assets/urdf/objects directory of this repository.

The LEAP hand URDF and mesh files need to be downloaded from the LEAP_Hand_Sim repository:

• Clone the LEAP_Hand_Sim repository at commit c61aa5b.
• Navigate to the assets/leap_hand directory and copy over its content to the assets/urdf/leaphand_description directory of this repository.
• Rename the robot.urdf to leap_hand.urdf.

Policy Training

Training a single RL policy to reorient the cube in-hand follows the same scheme as in IsaacGymEnvs.

First, select a task and training configuration. The following combinations are supported:

• For the ISyHand: export TASK=Isyhandv6 && export TRAIN=Isyhandv6PPO
• For the ISyHand (flat): export TASK=Isyhandv6Flat && export TRAIN=Isyhandv6PPO
• For the Allegro hand: export TASK=AllegroHand && export TRAIN=AllegroHandPPO
• For the LEAP hand: export TASK=LeapHand && export TRAIN=LeapHandPPO

Next, set the following parameters:

• experiment: Select a unique experiment name.
• seed: Set the seed for the training run.
• max_iterations: Maximum number of training iterations.
• task.env.obj_init_pos_delta: This array defines the positional offset of the cube init and target position from a neutral point on the inner hand surface. (See paper for more details.)
• task.env.obj_goal_pos_delta_from_init: This array defines the positional offset of the cube target from the cube init position. When set to [0.,0.,0.] the cube target position is identical to the cube init position. (Default setting in this project.)

For example, to train a single RL policy for the ISyHand to reorient the cube in-hand, run

export TASK=Isyhandv6 && export TRAIN=Isyhandv6PPO && export OBJ_INIT_POS_DELTA=[0.06,0.04,0.0613]

python train.py \
task=${TASK} \
train=${TRAIN} \
experiment="${TASK}_test" \
torch_deterministic=True \
headless=True \
seed=42 \
max_iterations=5000 \
train.params.config.save_frequency=5000 \
task.env.obj_init_pos_delta=${OBJ_INIT_POS_DELTA} \
task.env.obj_goal_pos_delta_from_init=[0.0,0.0,0.0] \
array_task_id=0

Policy Evaluation

After training a policy, the following evaluation spawns a single environment and counts the successfull in-hand cube reorientations.

First, select the task and training configuration as explained in the policy training section above. Additionally, set the environment variable CKPT to the path of the policy checkpoint to evaluate.

Next, set the following parameters:

• num_envs=1: Must be set to 1! Currently the evaluation does not support parallel environments.
• task.env.doRecordFrames: If set to True, saves image frames from the viewer with an added simulation time stamp.
• train.params.config.player.save_eval_df: If set to True, saves the evaluation dataframe containing the number of successfull in-hand cube reorientation per evaluation episode.
• train.params.config.player.games_num: Number of evaluation episodes.
• task.env.obj_init_pos_delta: Must match the values from the training run! Otherwise the policy is evaluated with a different cube init and target position that it was trained on.
• task.env.obj_goal_pos_delta_from_init: Must match the values from the training run! Otherwise the policy is evaluated with a different cube init and target position that it was trained on.

For example, to evaluate the last checkpoint at 5000 training iterations of the ISyHand RL policy mentioned above, run

export TASK=Isyhandv6 && export TRAIN=Isyhandv6PPO
# NOTE: Adapt the CKPT path and the OBJ_INIT_POS_DELTA accordingly!
export CKPT="runs/path/to/ckpt.pth" && export OBJ_INIT_POS_DELTA=[0.06,0.04,0.0613]

python train.py \
task=${TASK} \
train=${TRAIN} \
test=True \
torch_deterministic=True \
checkpoint=${CKPT} \
headless=False \
task.env.doRecordFrames=False \
seed=42 \
num_envs=1 \
train.params.config.player.save_eval_df=False \
train.params.config.player.games_num=100 \
task.env.obj_init_pos_delta=${OBJ_INIT_POS_DELTA} \
task.env.obj_goal_pos_delta_from_init=[0.0,0.0,0.0]

This repository includes a pretrained policy checkpoint for each hand to test the setup of the code. The corresponding configurations are:

export TASK=Isyhandv6 && export TRAIN=Isyhandv6PPO
export CKPT="runs/pretrained/Isyhandv6/last_Isyhandv6_Best_Cell_LongSeed42_array1_ep_300000_rew_16965.436.pth" && export OBJ_INIT_POS_DELTA=[0.06,0.04,0.0613]

export TASK=Isyhandv6Flat && export TRAIN=Isyhandv6PPO
export CKPT="runs/pretrained/Isyhandv6Flat/last_Isyhandv6Flat_Best_Cell_LongSeed42_array2_ep_300000_rew_13468.672.pth" && export OBJ_INIT_POS_DELTA=[0.12,-0.04,0.0613]

export TASK=AllegroHand && export TRAIN=AllegroHandPPO
export CKPT="runs/pretrained/Allegro/last_AllegroHand_Best_Cell_LongSeed42_array1_ep_300000_rew_15614.625.pth" && export OBJ_INIT_POS_DELTA=[0.04,0.0,0.0613]

export TASK=LeapHand && export TRAIN=LeapHandPPO
export CKPT="runs/pretrained/Leap/last_LeapHand_Best_Cell_LongSeed42_array2_ep_300000_rew_16328.162.pth" && export OBJ_INIT_POS_DELTA=[0.02,-0.04,0.0613]

When evaluating the policy checkpoint (and save_eval_df=True is set) a eval_*.pkl file is created that contains the evaluation results.
The pkl file can be loaded to inspect the evaluation performance and access metrics such as the cube reorientation successes.

For example, to access the evaluation results of the last policy checkpoint at 5000 training iterations, call

python demo_load_eval.py --exp-dir="runs/<name>" --filter-substring="5000"

Citing

If you use ISyHand or this codebase in your research, please cite:

@inproceedings{Richardson25-HR-ISyHand,
    author      = {Richardson, Benjamin A. and Gr{\"u}ninger, Felix and Mack, Lukas and Stueckler, Joerg and Kuchenbecker, Katherine J.},
    title       = {ISyHand: A Dexterous Multi-finger Robot Hand with an Articulated Palm},
    booktitle   = {Proceedings of the IEEE-RAS International Conference on Humanoid Robots (Humanoids)},
    address     = {Seoul, Korea},
    month       = sep,
    year        = {2025},
    note        = {Benjamin A. Richardson, Felix Grüninger and Lukas Mack contributed equally to this publication},
    slug        = {richardson25-hr-isyhand},
    month_numeric = {9}
}

License

See the notice file NOTICE.md.