# APR Project

This repository contains an APR-based training and evaluation workflow built on RoboPianist.

## Demo

- Demo video: [demo.mp4](./demo.mp4)

## Structure

- `robopianist/`: core RoboPianist codebase
- `robopianist/single_task/`: single-task APR training and evaluation
  - `train_apr_ppo.py`: main APR training entrypoint
  - `run_apr_ppo.sh`: training and evaluation launcher
  - `apr/`: APR feature extraction, networks, and module logic
  - `apr_callback.py`: SB3 callback integration for APR
  - `wrappers/apr_wrapper.py`: APR environment wrappers
- `retarget_quest_to_shadowhand.py`: retarget Quest CSV hand tracking data and export APR expert features
- `dataapr/`: APR expert data directory (for example: `improvised.csv`, `improvised_left.npy`, `improvised_right.npy`)

## Quick Start

```bash
cd path_to_your_project/robopianist/single_task
```

## Environment Setup

Create and activate the conda environment:

```bash
conda env create -f environment.apr.yml
conda activate apr
```

If the environment already exists, update it with:

```bash
conda env update -n apr -f environment.apr.yml --prune
```

## Training

Using the launcher script:

```bash
export WANDB_API_KEY="<your_wandb_api_key>"
export WANDB_ENTITY="<your_entity>"
export WANDB_PROJECT="robopianist-apr"

bash robopianist/single_task/run_apr_ppo.sh
```

With explicit arguments:

```bash
bash run_apr_ppo.sh <TASK> <W_G> <W_S> <NUM_ENVS> <TOTAL_ITERS> <SEED>
```

Example:

```bash
bash run_apr_ppo.sh GlimpseOfUs 0.7 0.3 24 2000 42
```

Without W&B:

```bash
python robopianist/single_task/train_apr_ppo.py --mode disabled --use_wandb false
```

## Run APR PPO Eval

There is no separate `runaprppoeval` file in this repo. Evaluation is handled by
`run_apr_ppo.sh` with `EVAL=1`.

Evaluate an APR checkpoint:

```bash
cd robopianist/single_task
EVAL=1 \
CKPT=/absolute/path/to/checkpoint \
CAM=piano/right \
bash run_apr_ppo.sh
```

Evaluate a non-APR checkpoint:

```bash
cd robopianist/single_task
EVAL=1 NO_APR=1 \
CKPT=/absolute/path/to/checkpoint \
CAM=piano/right \
bash run_apr_ppo.sh
```

Optional arguments still work in eval mode:

```bash
bash run_apr_ppo.sh <TASK> <W_G> <W_S> <NUM_ENVS> <TOTAL_ITERS> <SEED>
```

## Quest Retargeting and Expert Feature Export

Process all CSV files in `dataapr/`:

```bash
python retarget_quest_to_shadowhand.py
```

Process specific CSV file(s):

```bash
python retarget_quest_to_shadowhand.py dataapr/improvised.csv
```

This generates `*_left.npy` and `*_right.npy` expert feature files in `dataapr/`.

## Acknowledgements

The simulation environment is based on RoboPianist [RoboPianist](https://github.com/google-research/robopianist)

The diffusion policy is adapted from [Diffusion Policy](https://github.com/real-stanford/diffusion_policy)

The inverse-kinematics controller is adapted from [Pink](https://github.com/stephane-caron/pink)

The human demonstration videos are downloaded from YouTube channel [PianoX](https://www.youtube.com/channel/UCsR6ZEA0AbBhrF-NCeET6vQ)

The pianomime is from [pianomime](https://github.com/sNiper-Qian/pianomime)

## Notes

- W&B `offline` mode is disabled; only `online` or `disabled` is supported.