README.md

---
license: other
tags:
  - human-motion-generation
  - human-human-interaction
  - text-to-motion
  - diffusion
library_name: pytorch
---

# SocialStructureHHI — Executor

Pretrained executor weights for **SocialStructureHHI**: *Social Structure Matters in 3D
Human–Human Interaction Generation*.

The **solo-to-social motion executor** is the full social-planning model — a
HunyuanMotion-Lite backbone with variable-length **partner conditioning** plus a pinned
**self-history prefix** — that generates two-person interactions phase-by-phase in a
Ping-Pong manner.

## Files

| file | description |
|------|-------------|
| `ckpts/best.pt` | solo-to-social motion executor, ~1.86 GB |

## Usage

```python
# In the SocialStructureHHI repo:
#   https://github.com/EngineeringAI-LAB/SocialStructureHHI
from huggingface_hub import hf_hub_download
ckpt = hf_hub_download("EngineeringAI-LAB/SocialStructure", "ckpts/best.pt")
```

```bash
python inference/run_inference.py --ckpt $ckpt --demo_id 5 \
    --llm_model qwen3.5:35b --llm_base_url http://localhost:11435/v1 \
    --out_dir outputs/handshake --render
```

The HunyuanMotion backbone, Qwen3-8B and CLIP-L are additional external dependencies — see
the code repository for setup. Dataset normalization stats
(`data/motion_norm_stats.npz`) ship with the code repo and are required to load the model.

## Links

- 📄 Paper: https://arxiv.org/abs/2606.24255
- 💻 Code: https://github.com/EngineeringAI-LAB/SocialStructureHHI
- 🌐 Project page: https://engineeringai-lab.github.io/SocialStructureHHI/
- 🤗 Dataset: https://huggingface.co/datasets/EngineeringAI-LAB/SocialStructure

## Citation

```bibtex
@misc{wang2026socialstructure,
  title  = {Social Structure Matters in 3D Human--Human Interaction Generation},
  author = {Zhongju Wang and Beier Wang and Yatao Bian and Pichao Wang and Zhi Wang
            and Daoyi Dong and Hongdong Li and Huadong Mo and Zhenhong Sun},
  year   = {2026},
  eprint = {2606.24255},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CV}
}
```