Track: Reference Motion Tracking for Humanoid Robots

Track is a motion-tracking task package built on top of active-adaptation. It trains a PPO policy that drives a 29 Dof Unitree G1 humanoid to imitate human reference motions in Isaac Lab. This package contributes:

• Task components (Track/src/track/): command, observation, reward, and termination modules specialized for motion tracking.
• Learning algorithm (Track/src/track_learning/): a PPO variant ppo_track registered with the active-adaptation Hydra config search path.
• Motion preprocessing scripts (Track/scripts/): tools to convert raw motion files (.pkl, .npz) into the format consumed by the training task.

Repository Layout

The two packages are expected to sit side-by-side, with a shared Isaac Lab installation:

<workspace>/
  active-adaptation/   # core RL framework + envs + assets (G1)
  Track/               # this package: motion tracking task + ppo_track
  IsaacLab/            # Nvidia Isaac Lab simulator

Installation

1. Install Isaac Sim 5.1.0 by downloading the latest release and unzipping it to $ISAACSIM_PATH.

2. Clone Isaac Lab and set up a conda environment:

   git clone https://github.com/isaac-sim/IsaacLab.git
   cd IsaacLab
   git checkout <commit-from-2026-02-28> 
   ln -s $ISAACSIM_PATH _isaac_sim
   ./isaaclab.sh -c lab                     # creates conda env "lab"
   conda activate lab
   ./isaaclab.sh -i none                    # install IsaacLab without bundled RL libs
   echo $PYTHONPATH                         # should now include isaac-sim deps

3. Install PyTorch and TorchRL:

   pip install -U torch torchvision tensordict torchrl==0.10

4. Install active-adaptation (must be installed before Track, because Track relies on its Hydra search-path plugin to discover task/algo configs):

   cd active-adaptation
   pip install -e .

5. Install Track:

   cd Track
   pip install -e .

   The pip install -e . step registers the entry-points active_adaptation.projects = track and active_adaptation.learning = track_learning, which is how Hydra finds task=motion and algo=ppo_track from the active-adaptation scripts directory.

Reference Motion Data

The task config (Track/cfg/task/motion.yaml) consumes a set of preprocessed motion datasets and an occlusion file:

• Datasets (29-DoF G1 retargeted): accad_29dof, bmlhandball_29dof, bmlmovi_29dof, bmlrub_29dof, cmu_29dof, dancedb_29dof, dfaust_29dof, ekut_29dof, eyes_japan_29dof, hdm05_29dof, human4d_29dof, humaneva_29dof, kit_29dof, lafan1, mosh_29dof, poseprior_29dof, sfu_29dof, soma_29dof, ssm_29dof, tcdhands_29dof, totalcapture_29dof, transitions_29dof.
• Occlusion file: amass_copycat_occlusion_v3.pkl.

Data preparation

The 29-DoF G1 motion subsets above are produced by retargeting raw motion-capture data to the G1 kinematic model. We follow the retargeting pipeline of GMR — please refer to the GMR codebase for the upstream retargeting procedure that turns AMASS-style motion sources into G1-compatible trajectories.

The two helper scripts in Track/scripts/ adapt the retargeted output (or LAFAN1 raw data) into the per-dataset .pkl format consumed by the MotionLibG1 command:

• load_pkl.py — processes the .pkl files produced by GMR retargeting (i.e., the *_29dof AMASS subsets). It loads an existing GMR-retargeted pkl, replays each motion in Isaac Lab to collect simulation-side fields, and writes them back to the same pkl.

  python Track/scripts/load_pkl.py \
      --input_file <path/to/gmr_retargeted>.pkl \
      --input_fps 50 --output_fps 50 --headless

• load_npz.py — processes the LAFAN1 dataset (distributed as .npz per motion). It reads a directory of .npz files and packs them into a single .pkl for lafan1.

  python Track/scripts/load_npz.py \
      --npz_dir <path/to/lafan1_npz_dir> \
      --output_file <path/to/lafan1>.pkl \
      --input_fps 50 --output_fps 50 --headless

Training

All training commands are launched from active-adaptation/scripts/. Hydra picks up the motion task and ppo_track algo from this Track package automatically.

cd active-adaptation/scripts
python train_ppo.py \
    task=motion \
    algo=ppo_track \
    task.num_envs=<num_envs> \
    total_frames=<total_frames> \
    checkpoint_path=<checkpoint_path>   # optional: resume from a checkpoint

Useful overrides:

• wandb.mode=disabled — disable W&B logging for local debugging.
• headless=true — run without a viewer (default for training).
• seed=<int> — set a deterministic seed.

Playing a Trained Policy

cd active-adaptation/scripts
python play.py \
    task=motion \
    algo=ppo_track \
    task.num_envs=<num_envs> \
    checkpoint_path=<checkpoint_path> \
    export_policy=<true|false>          # export the policy to ONNX after rollout