Genesis-Intelligence/functional-grasp-demos

# Selected Grasp Demos

## Contents

Each case folder contains:
- `grasp_data.npz` — Top-1 ranked grasp (pre_grasp_dofs, grasp_target_dofs, reward, z_lift)
- `image_grasp.png` — AI-generated grasp image (input to perception pipeline)
- `debug_retarget.png` — WujiHand retarget visualization (if available)

## Cases

| Case | Object | Scale | Reward | z_lift |
|------|--------|-------|--------|--------|
| paper_coffee_cup_rot090__grasp_06 | Paper Coffee Cup | 1.0 | 0.742 | 0.196 |
| paper_cup_8_oz_rot000__grasp_06 | Paper Cup 8 Oz | 1.0 | 0.696 | 0.201 |
| bowl_rot000__grasp_03 | Bowl | 0.95 | 0.764 | 0.211 |
| simple_mug_rot090__grasp_06 | Simple Mug | 1.0 | 0.660 | 0.179 |
| simple_mug_rot090__grasp_05 | Simple Mug | 1.0 | 0.674 | 0.192 |

## Replay

### Setup
```bash
pip install genesis-world numpy scipy imageio Pillow trimesh
```

### Run replay (generates video)
```bash
cd selected_demos
python replay_dynamics.py --case bowl_rot000__grasp_03 --save_video
python replay_dynamics.py --case paper_coffee_cup_rot090__grasp_06 --save_video
```

### Grasp data format
```python
import numpy as np
data = np.load("bowl_rot000__grasp_03/grasp_data.npz")
pre_grasp = data["pre_grasp_dofs"] # (26,) = [xyz(3), euler(3), fingers(20)]
grasp_target = data["grasp_target_dofs"] # (26,) = pre_grasp + closing delta
reward = float(data["reward"]) # composite reward score
z_lift = float(data["z_lift"]) # how much the object lifted (meters)
```

### Replay logic
1. Place hand at `pre_grasp_dofs` (set_pos, set_quat, set_dofs_position)
2. PD-control fingers to `grasp_target_dofs` for 100 steps (closing action)
3. PD-control wrist z += 0.2m for 100 steps (lifting)

### Physics settings
- dt=0.01, substeps=5, gravity=(0,0,-9.8)
- friction=5.0, noslip_iterations=10
- PD gains: kp=[800]*6+[500]*20, kv=[100]*6+[50]*20
- Object mass: 0.05 per link