ReAlign: Text-to-Motion Generation via Step-Aware Reward-Guided Alignment

Wanjiang Weng^*  Xiaofeng Tan^*  Junbo Wang  Guo-Sen Xie  Pan Zhou  Hongsong Wang^† 
*Equal Contribution  †Corresponding Author

TL;DR: We propose ReAlign, a plug-and-play reward-guided alignment strategy for text-to-motion generation, which explicitly enhances both semantic consistency and motion realism throughout the denoising process.

This repository offers the official code for this paper. If you have any questions, feel free to contact Wanjiang Weng (wjweng@seu.edu.cn) or Xiaofeng Tan (xiaofengtan@seu.edu.cn).

📣 News

• [2025/12] The code has been released! 🚀
• [2025/11] The paper has been publicly released.
• [2025/11] 🎉 ReAlign has been accepted by AAAI‘26. To explore accepted papers from AAAI’26, please see AAAI Abstract and Paper Portal.

📆 Plan

• Release early version.
• Release final version.
• Release environment guidance.
• Release evaluation code.
• Release training code.
• Release pretrained model weights.

Model Zoo

Model Name	Dataset	Download Link	Retrieval Performance (R@1)
Step-Aware Reward Model	HumanML3D	OneDrive, BaiduNetDisk (passwd: 1234)	T2M: 67.59%, M2T: 68.94%
	KIT-ML	OneDrive, BaiduNetDisk (passwd: 1234)	T2M: 52.84%, M2T: 52.98%

Environment Setup

1. Create Conda Environment

conda create -n realign python=3.10 -y
conda activate realign

2. Install Dependencies

# Install PyTorch (CUDA 11.8)
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118

# Install other dependencies
pip install -r requirements.txt

3. Prepare Pre-trained Models

This project requires several pre-trained models for text encoding, motion evaluation, and mesh rendering. Place the downloaded assets in the deps/ directory as follows:

deps/
├── sentence-t5-large/       # Sentence-T5: Used to extract sentence-level text features.
├── clip-vit-large-patch14/  # CLIP model: Used to extract sentence-level text features.
├── distilbert-base-uncased/ # DistilBERT: Used to extract sentence-level text features.
├── glove/                   # GloVe word embeddings: Used by the T2M evaluator for word embedding retrieval.
├── smpl/                    # SMPL model: Required for skinning skeleton-based figures onto human meshes.
└── t2m/                     # Text-to-Motion evaluation weights

For convenience, unified download links are provided below: Baidu Netdisk, OneDrive

Disclaimer: These models are provided solely for academic research and non-profit purposes. We strictly adhere to copyright regulations. If any included assets are found to be infringing, please notify us, and they will be removed immediately.

4. Prepare Dataset

Download HumanML3D or KIT-ML dataset and place in datasets/ directory:

datasets/
└── humanml3d/
    ├── new_joint_vecs/
    ├── new_joints/
    ├── texts/
    └── ...

SwanLab Logging

This project uses SwanLab for experiment tracking and visualization.

Setup SwanLab

# Install SwanLab
pip install swanlab

# Login to SwanLab (get API key from https://swanlab.cn/)
swanlab login

View Training Logs

After training starts, you can view real-time logs at:

• SwanLab Dashboard: https://swanlab.cn/

Logged metrics include:

• Train/loss: Training loss per step
• Train/lr: Learning rate
• Epoch/avg_loss: Average loss per epoch
• Val/T2M_*: Text-to-Motion retrieval metrics
• Val/M2T_*: Motion-to-Text retrieval metrics

Training

Train Step-Aware Reward Model (SPM)

# Train on HumanML3D dataset
bash run.sh 0 spm

# Or run directly with custom parameters
CUDA_VISIBLE_DEVICES=0 python -m ReAlignModule.train_spm \
    --cfg configs/spm_t2m.yaml \
    --NoiseThr 0.5 \
    --maxT 1000 \
    --step_aware M1T0 \
    --CLThr 0.9 \
    --CLTemp 0.1

Key Parameters:

• --NoiseThr: Noise threshold for training (default: 0.5)
• --maxT: Maximum timestep for noise scheduling (default: 1000)
• --step_aware: Step-aware mode, options: M1T0, M0T1, M1T1 (default: M1T0)
• --CLThr: Contrastive learning threshold (default: 0.9)
• --CLTemp: Contrastive learning temperature (default: 0.1)

Checkpoints will be saved in ./checkpoints/spm/ directory.

Evaluation

Evaluate with ReAlign

# Evaluate MLD with Step-Aware Reward Model
bash run.sh 0 eval

# Or run directly
CUDA_VISIBLE_DEVICES=0 python -m test \
    --cfg configs/mld_t2m.yaml \
    --lambda_t2m 100 \
    --lambda_m2m 100 \
    --spm_path /path/to/SPM_checkpoint.pth

Key Parameters:

• --spm_path: Path to trained SPM checkpoint
• --lambda_t2m: Weight for text-to-motion alignment (default: 100)
• --lambda_m2m: Weight for motion-to-motion alignment (default: 100)

Evaluate TMR Retrieval

bash run.sh 0 tmr

Rendering

Convert generated motion to mesh for visualization:

python fit.py --pkl /path/to/motion.pkl --num_smplify_iters 150

Project Structure

ReAlign/
├── configs/                 # Configuration files
│   ├── mld_t2m.yaml        # MLD model config
│   ├── spm_t2m.yaml        # SPM training config
│   └── modules/            # Module-specific configs
├── ReAlignModule/          # ReAlign core module
│   ├── train_spm.py        # SPM training script
│   ├── eval_tmr.py         # TMR evaluation
│   └── models/
│       ├── spm.py          # Step-aware Reward Model
│       └── utils.py        # Utility functions
├── mld/                    # MLD base model
├── datasets/               # Dataset directory
├── deps/                   # Pre-trained dependencies
├── checkpoints/            # Model checkpoints
├── run.sh                  # Training/evaluation scripts
├── test.py                 # Evaluation entry point
└── fit.py                  # Motion to mesh fitting

Update Log

2025-12-15

• Bug Fix: Fixed GPU memory leak issue in train_spm.py
  • Added del statements to explicitly release tensors after use
  • Added torch.cuda.empty_cache() calls to free cached memory
  • Prevents OOM errors during long training sessions

4. Disclaimer

Please note that this project is intended solely for academic research and is entirely non-profit. We strictly adhere to copyright regulations. All weight files are provided for research purposes only; if any included assets are found to be infringing, please notify us, and we will remove them immediately.

We hope this information helps you set up the environment. If you have further questions or encounter any issues, please feel free to reach out.

Citation

@inproceedings{wengReAlign26,
  title={ReAlign: Text-to-Motion Generation via Step-Aware Reward-Guided Alignment}, 
  author={Wanjiang Weng and Xiaofeng Tan and Junbo Wang and Guo-Sen Xie and Pan Zhou and Hongsong Wang},
  year={2025},
  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence}
}