amathislab / terra

# TERRA
**Terrain-aware motion retargeting and muscle-actuated control with MyoFullBody.** TERRA
takes human motion recordings, estimates supporting terrain, retargets motion to a
musculoskeletal model, and uses the resulting trajectories to train terrain-conditioned
PPO policies.
The repository contains the method implementation, command-line tools, configuration
presets, and end-to-end workflow guides. The code covers conversion, terrain
reconstruction, retargeting, policy training, core evaluation, and visualization.
Project website · Installation · Data and model setup · Citation
## Method at a glance
| Component | Input → output | Start here |
|---|---|---|
| **1. Motion file handling and transformation** | AMASS SMPL-H or C3D/TRC/MAT markers → parsed or fitted body motion with explicit units and frame rate | Motion files |
| **2. Terrain reconstruction** | Motion landmarks and contact evidence → terrain geometry and a validation report | Terrain reconstruction |
| **3. Motion retargeting** | Motion plus terrain → MyoFullBody trajectory, analysis, and terrain sidecar | Motion retargeting |
| **4. Policy training** | Verified trajectory cohort → terrain-conditioned PPO checkpoint | Policy training |
`terra retarget` runs components 2 and 3 together for one motion. The standalone
reconstruction command handles selected cohorts; `terra train select` accepts either
a validated retargeting cache or completed dataset runs.
For collection processing and motion metrics, see the dataset workflows
guide for `terra run` and `terra evaluate`.
Watch short examples of terrain reconstruction,
stair retargeting comparison, and a
ramp policy rollout.
## Requirements and installation
Use **Linux**, **Python 3.11**, Git, and
uv. Run commands from the repository root. The lockfile
pins TERRA's Python dependencies and the MuscleMimic `terra` branch. On Linux x86-64, the
locked PyTorch wheel is a CUDA 12.6 build even when fitting on CPU, so allow
roughly 8 GB for the base environment, plus download-cache space. A GPU is required for PPO training and policy evaluation; it
is not required for motion loading or artifact checks.
 [code] 
Install the extras needed for your work; uv updates the same `.venv`:
 [code] 
Pass all needed `--extra` flags together in your final `uv sync` command. See the
installation notes for environment checks and setup errors.
## First result: retarget one SMPL-H motion
This path needs **one AMASS-compatible SMPL-H `.npz` motion** and the licensed **neutral
SMPL-H model**. Data setup explains where to obtain them and how to
check the file layout. AMASS motions need no marker conversion. For this tutorial,
use **`KIT/3/upstairs04_poses.npz`** from the KIT SMPL-H collection. The TERRA-4B
checkpoint completed all five sampled attempts on this staircase motion in the saved
evaluation results, with 47 mm mean tracking error. You can also choose another
downloaded motion by changing `MOTION_FILE`:
 [code] 
The command prints JSON paths for the t