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

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.

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.

uv sync --locked --python 3.11
source .venv/bin/activate
terra --version
terra --help

Install the extras needed for your work; uv updates the same .venv:

# C3D marker files and comparison retargeters
uv sync --locked --python 3.11 --extra c3d --extra baselines

# JAX CUDA 12 support for GPU training and evaluation
uv sync --locked --python 3.11 --extra cuda

# Tests and linting
uv sync --locked --python 3.11 --extra dev

Pass all needed --extra flags together in your final uv sync command. See the installation notes for environment checks and setup errors.

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:

export TERRA_DATA_ROOT="$HOME/terra-data"
export TERRA_MODEL_ROOT="$HOME/terra-models/smplh"
export TERRA_ARTIFACT_ROOT="$HOME/terra-results"
export MOTION_FILE="$TERRA_DATA_ROOT/AMASS/KIT/3/upstairs04_poses.npz"

test -f "$MOTION_FILE"
test -f "$TERRA_MODEL_ROOT/SMPLH_NEUTRAL.pkl"
mkdir -p "$TERRA_ARTIFACT_ROOT"

terra retarget "$MOTION_FILE" \
  --smpl-model-path "$TERRA_MODEL_ROOT" \
  --output-root "$TERRA_ARTIFACT_ROOT/quickstart" \
  --name FirstRun/motion

The command prints JSON paths for the trajectory (.npz), analysis (_analysis.npz), and, when present, reconstructed terrain (_terrain.json). The first run also fits and caches the MyoFullBody body shape, so it can take longer than later runs. A flat motion may have no terrain sidecar. Validate the published artifacts with the same read-side API used by downstream workflows:

python - <<'PY'
import os
from pathlib import Path
from terra import validate_retarget_artifacts

root = Path(os.environ["TERRA_ARTIFACT_ROOT"]) / "quickstart"
result = validate_retarget_artifacts(root, "FirstRun/motion")
print(f"{result.num_frames} frames at {result.frequency:g} Hz")
print(f"non-flat terrain: {result.nonflat_terrain}")
print(result.trajectory_path)
PY

The default terrain="auto" estimates support geometry from the motion. To use a known terrain, pass its metadata JSON path with --terrain; to place the result on flat ground, pass --terrain none. See Motion retargeting for the Python API, marker inputs, configuration choices, artifact layout, and video review.

1. Motion files covers input formats, archive checks, and dataset-specific conversion.
2. Terrain reconstruction explains its evidence, standalone cohort command, output records, and validation.
3. Motion retargeting covers the CLI, Python API, configuration, and paired output artifacts.
4. Policy training covers validated motion selection, materialization, CUDA preflight, a one-update smoke run, and PPO launch.

For development, run uv sync --locked --python 3.11 --extra dev, then uv run --locked --extra dev pytest -q. Distribution builds and wheel CLI checks run with uv run --locked --extra dev pytest -q --runslow. Real method checks additionally use the licensed inputs described in installation notes. Build release artifacts with uv build. TERRA is licensed under Apache-2.0; NOTICE lists adapted code. The required smplx dependency uses MPI's non-commercial research license. SMPL-H/MANO models and motion datasets also have their own provider terms. Check those terms for your intended use; installing TERRA does not grant additional rights to these dependencies or assets.

Cite the preprint:

@misc{simos2026terra,
  title  = {{TERRA}: Terrain-Aware Reconstruction, Retargeting and Control for Musculoskeletal Locomotion},
  author = {Simos, Merkourios and Li, Chengkun and Ziliotto, Bianca and Mathis, Alexander},
  year   = {2026},
  eprint = {2609.38653},
  archivePrefix = {arXiv},
  primaryClass = {cs.RO},
  url    = {https://arxiv.org/abs/2609.38653}
}