✋🤟 PCHands 🖖✌️

PCHands:
PCA-based Hand Pose Retargeting
on Manipulators with N-DoF

2025 IEEE-RAS 24th International Conference on Humanoid Robots

Paper | Video | Page | Dataset

teaser.mp4

📜 Table of Contents

• Updates
• Installation
• Manipulator
• Usage
• Hotfix
• Acknowledgement
• License
• Citation

🆕 Updates

• [2025-Oct-21]: Official 🎆code🎆 released on GitHub.
• [2025-Oct-16]: 🎉Model Checkpoint🎉 and 🎉task demonstrations🎉 are released on Hugging Face and on IIT Dataverse.

⚙️ Installation

1. PCHands

   git clone https://github.com/hsp-iit/PCHands.git --recursive
   

2. Download MANO-v1_2 and place MANO_LEFT.pkl, MANO_RIGHT.pkl in assets/mano_hand/models

3. Download ARC-checkpoint and place wild.pkl in arhand/checkpoints

4. Conda Env:

   conda create -n pch python=3.11
   conda activate pch
   

5. Pytorch3D

   pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu118
   conda install -c conda-forge cudatoolkit-dev
   FORCE_CUDA=1 pip install https://github.com/facebookresearch/pytorch3d/archive/refs/tags/V0.7.8.tar.gz
   

6. Others:

   pip install -r requirements.txt
   

🛠️ Manipulator

1. robotiq_2f85
2. franka_gripper
3. widowx_gripper
4. xarm_gripper
5. wsg50_gripper
6. rethink_egripper
7. fetch_gripper
8. google_gripper
9. kinova_2f
10. kinova_3f_right
11. ergocub_hand_right
12. schunk_hand_right
13. allegro_hand_right
14. shadow_hand_left
15. armar_hand_right
16. Leap_hand_right
17. mano_hand_right

Examine manipulator:

import numpy as np
from adf.manipulator import Manipulator

# list all available manipulator names
print(Manipulator.names)
# create manipulator instance
manip = Manipulator(Manipulator.names[i], verbose=True)
# random values in joint-space
q = np.random.rand(manip.dof)
# map into manipulator's joint limit
q = manip.denormalize_joint(q)
# forward kinematic with joint values
manip.forward_kinematic(q)
# visualization
manip.vis_model()

📝 Usage

Dimensionality Reduction

cd adf
python calib_eef.py

Expected output:

• calib_eef.yaml
• pca.pkl
• pca.pth
• stats.npy

Collect Demo

cd rl_scripts
# collect_demo: <task_name> <manip_src>
python collect_demo.py table_door ergocub_hand_right

Registered key:

• q: quit
• a: reset env
• z: toggle finger lock
• x: toggle recording
• c: save episode

Typical Procedure:

• xrecord
• move-palm-finger-env
• xstop-record
• csave
• areset-env
• repeat ...
• q quit

Expected output:

• teleop_collection/<task_name>/*.pkl

Replay Demo

# replay_demo: <task_name>
python replay_demo.py table_door

Expected output:

• Sapien visualization of the collected demos

Bake Demo

# bake_demo: modify data to bake in bake_demo.py 
python bake_demo.py

Expected output:

• rl_scripts/demo/<manip_src>/<task_name>_<n_pc>.pkl
• rl_sim/env/norm/<manip_src>/<task_name>_<n_pc>.pkl

Train RL

# training: modify training params via argv
SAPIEN_RENDER='0' python train_rl.py

Expected output:

• < rl-algo > _ < task > _ < manip-tgt > _ < n-pc > _ < datetime >
  • policy_xxxx.pickle: checkpoint
  • cfg.json : experiment setting
  • log.csv : values-log

🔧 Hotfix

1. If you encounter errors in loading of URDF, try modifying $CONDA_PREFIX/lib/python3.11/site-packages/xacro/__init__.py:

   - 103         ...yaml.load...
   + 103         ...yaml.safe_load...

2. If you encounter errors in loading mano-hand, try modifying $CONDA_PREFIX/lib/python3.11/site-packages/chumpy/ch.py:

   - 1203        ...inspect.getargspec...
   + 1203        ...inspect.getfullargspec...
   - 1246        ...inspect.getargspec...
   + 1246        ...inspect.getfullargspec...

3. If you encounter Sapien errors while training with CPUs, try modifying $CONDA_PREFIX/lib/python3.11/site-packages/sapien/wrapper/urdf_loader.py:

   + 68          self.no_visual = False
   + 294         if self.no_visual:
   + 295             break
   + 801         ..., no_visual = False
   + 803         self.no_visual = no_visual

🏋️ Acknowledgement

This research was supported by:

• PNRR MUR project PE0000013-FAIR
• National Institute for Insurance against Accidents at Work (INAIL) project ergoCub-2.0
• Brain and Machines Flagship Programme of the Italian Institute of Technology

⚖️ License

The code is released under the BSD 3-Clause License. See LICENSE for further details. This code adapts multiple sources in different sections, see:

• mjrl - Apache 2.0 License
• dex-hand-teleop - MIT License
• LEAP_Hand_API - CC BY-NC 4.0 License

📑 Citing this paper

@inproceedings{puang2025pchands,
  author={Puang, En Yen and Ceola, Federico and Pasquale, Giulia and Natale, Lorenzo},
  booktitle={2025 IEEE-RAS 24th International Conference on Humanoid Robots (Humanoids)}, 
  title={PCHands: PCA-Based Hand Pose Synergy Representation on Manipulators with N-DoF}, 
  year={2025},
  pages={475-482},
  doi={10.1109/Humanoids65713.2025.11203193}
}

🧔 Maintainer

This repository is maintained by:

	@enyen