README.md

---
license: mit
library_name: pytorch
language:
- en
tags:
- robotics
- humanoid
- unitree-g1
- diffusion-policy
- text-conditioned-control
- mujoco
- motionclip
- predictive-control
inference: false
---

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/">
    <img src="assets/predactor-readme-banner.svg" width="1400" alt="PredActor: predictive action diffusion for steerable onboard humanoid control.">
  </a>
</p>

<h1 align="center">PredActor Artifacts</h1>

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/"><img alt="Project website" src="https://img.shields.io/badge/Project_Website-E7A12B?style=flat-square&logo=googlechrome&logoColor=171817"></a>
  <a href="https://arxiv.org/abs/2609.24840"><img alt="arXiv paper" src="https://img.shields.io/badge/arXiv-2609.24840-B31B1B?style=flat-square&logo=arxiv&logoColor=white"></a>
  <a href="https://github.com/MasterYip/PredActor"><img alt="Evaluation code" src="https://img.shields.io/badge/GitHub-Evaluation_Code-5A5A57?style=flat-square&logo=github&logoColor=white"></a>
  <a href="https://huggingface.co/MasterYip/PredActor_Artifacts"><img alt="Hugging Face artifacts" src="https://img.shields.io/badge/Hugging_Face-Model_Artifacts-FFD21E?style=flat-square&logo=huggingface&logoColor=171817"></a>
  <a href="https://github.com/MasterYip/PredActor/blob/master/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/License-MIT-ECECEA?style=flat-square&labelColor=2F2F2D&color=ECECEA"></a>
</p>

<p align="center">
  <img src="assets/institution-strip.svg" width="100%" alt="Harbin Institute of Technology, Shanghai Innovation Institute, RoboParty Lab, Tsinghua University, Shanghai Jiao Tong University, HexLab, and SFTR">
</p>

Official checkpoints for
[PredActor](https://github.com/MasterYip/PredActor), a predictive action
diffusion controller for steerable Unitree G1 locomotion. The model jointly
predicts future states and actions, uses its internal state trajectory for
guidance, and directly executes the selected 29-DoF action.

## Overview

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/">
    <img src="assets/predactor-preview.png" width="100%" alt="PredActor method and hardware overview">
  </a>
</p>

This repository contains the learned artifacts used by the public evaluation
and data-collection paths:

- the released PDP051 text-conditioned PredActor policy;
- the fine-tuned G1 MotionCLIP encoder used for semantic conditioning and
  dataset labeling;
- the RLTracker teacher checkpoint used to collect the 152-motion dataset.
- the 152 retargeted G1 motion trajectories used by the public collection,
  dyeing, and BC training workflow.

Source code, the browser-based evaluator, and G1 robot assets are maintained in
the [public PredActor repository](https://github.com/MasterYip/PredActor).
Training datasets, experiment outputs, hardware deployment bundles, and
additional checkpoints are not included here.

## Quick Evaluation

Install [uv](https://docs.astral.sh/uv/), then run:

```bash
git clone https://github.com/MasterYip/PredActor.git
cd PredActor
uv sync --locked
uv run --locked python scripts/hf_download.py --filter checkpoints
uv run --locked predactor-eval
```

The downloader recreates the expected layout under the Git-ignored
`Artifacts/` directory and verifies the published byte sizes and SHA-256
identities. The evaluator opens `http://127.0.0.1:8765/`, uses CUDA when
available, and otherwise falls back to CPU.

## Released Artifacts

| Artifact | Role | Size | SHA-256 |
|---|---|---:|---|
| `checkpoints/predactor/pdp051/latest.ckpt` | Text-conditioned PredActor policy | 49,212,894 bytes | `2d963b32786f2989c6472726df9fcfe6b385590127e12e1f549a4b7d77488b2e` |
| `checkpoints/motionclip/g1-model-xyz-clip/checkpoint_0100.pth.tar` | Fine-tuned G1 MotionCLIP encoder | 542,749,069 bytes | `66a127df4958b346089b2020f2705c7456d9db0ee8b4bd9518608b708b35fc3c` |
| `checkpoints/rl_tracker/model_75000.pt` | RLTracker collection teacher | 87,408,687 bytes | `0043c99ca89b1e45e49be7fdc95dec261ab9df9a6dfeaf11cca739390421aa52` |
| `motions/g1_152fk/` | 152 retargeted G1 trajectories for collection and training | 87 MB | directory payload |

`SHA256SUMS` records the same checkpoint identities in a format accepted by
`sha256sum --check`.

## Repository Layout

```text
PredActor_Artifacts/
|-- README.md
|-- SHA256SUMS
|-- assets/
|   |-- predactor-readme-banner.svg
|   |-- predactor-preview.png
|   `-- institution-strip.svg
|-- checkpoints/
|   |-- predactor/pdp051/latest.ckpt
|   |-- motionclip/g1-model-xyz-clip/checkpoint_0100.pth.tar
|   `-- rl_tracker/model_75000.pt
|-- motions/
|   `-- g1_152fk/<motion-name>/motion.npz  (152 files)
`-- dataset/
    `-- README.md
```

`dataset/` is reserved for collected and dyed zarr releases. The raw 152
trajectory inputs are published under `motions/g1_152fk/` so a new user can
run collection, MotionCLIP dyeing, and PDP051-style training without sourcing
the motion files separately.

## Model Details

- **Policy:** PDP051 using the public `g1prdp_cond_diffuse` evaluation profile.
- **Robot:** Unitree G1 with 29 actuated degrees of freedom.
- **Inputs:** proprioceptive observation history, a 512-dimensional semantic
  condition, and optional whole-body guidance commands.
- **Outputs:** a denoised action trajectory from which the current joint action
  is selected for direct execution.
- **State prediction:** future states remain internal to the policy and provide
  a differentiable target for classifier guidance.
- **Public runtime:** local MuJoCo evaluation through the PredActor Web UI.

## Intended Use

These artifacts support local simulation evaluation and reproduction of the
public 152-motion collection, labeling, and BC training pipeline. The
MotionCLIP checkpoint supplies semantic labels, while the RLTracker checkpoint
acts as the collection teacher.

## Limitations and Safety

- MuJoCo startup demonstrates software and checkpoint compatibility; it does
  not establish hardware safety or guarantee locomotion quality in a new
  environment.
- Real-robot deployment requires separate control, safety, and hardware
  validation that is outside this repository.
- PyTorch checkpoints use pickle-compatible deserialization. Load only files
  whose hashes match the published values and only from trusted sources.
- Performance may change with simulator, driver, GPU, or dependency versions
  outside the locked public environment.

## Evaluation and Demos

The [PredActor project page](https://masteryip.github.io/predactor.github.io/)
contains the method overview and simulation and hardware demonstrations. The
[public code repository](https://github.com/MasterYip/PredActor) provides the
reproducible MuJoCo evaluation workflow.

## License

PredActor is released under the
[MIT License](https://github.com/MasterYip/PredActor/blob/master/LICENSE).
Third-party dependencies and robot assets remain subject to their respective
upstream terms.

## Citation

```bibtex
@misc{ye2026predactorpredictiveactiondiffusion,
  title={PredActor: Predictive Action Diffusion for Steerable Onboard Humanoid Control},
  author={Lei Ye and Haibo Gao and Yitang Li and Peng Xu and Zetong Jing and Junhan Sun and Fanrong Dong and Ziqi Han and Xue Wang and Jianhua Sun and Cewu Lu and Hao Zhao and Liang Ding},
  year={2026},
  eprint={2609.24840},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2609.24840},
}
```