FlowMotion

Official implementation of FlowMotion and TCFM (Target-Predictive Conditional Flow Matching), from:

Manolo Canales Cuba, Vinícius do Carmo Melício, and João Paulo Gois.
FlowMotion: Target-predictive conditional flow matching for Jitter-Reduced text-driven human motion generation.
Computers & Graphics, 132:104374, 2025.
Project page · Paper · GitHub

The recommended HumanML3D checkpoint is pretrained/model000620000.pt. Sampling uses version=tcfm by default.

Training

HumanML3D

CUDA_VISIBLE_DEVICES=0 python train.py \
  name=humanml_tcfm dataset=humanml \
  training.eval_during_training=1 model.cond_mask_prob=0.1 guidance_param=2.5 \
  training.overwrite=1 training.log_interval=1000 batch_size=128 \
  training.num_steps=600000 num_workers=4 \
  input_text=./assets/example_text_prompts.txt is_debug=0 \
  version=tcfm sigma_min=0.0

KIT-ML

CUDA_VISIBLE_DEVICES=0 python train.py \
  name=kit_tcfm dataset=kit \
  training.eval_during_training=1 model.cond_mask_prob=0.1 guidance_param=2.5 \
  training.overwrite=1 training.log_interval=1000 batch_size=128 \
  training.num_steps=600000 num_workers=4 \
  input_text=./assets/example_text_prompts.txt is_debug=0 \
  version=tcfm sigma_min=0.0

Generation

python generate.py dataset=humanml \
  model_path=./pretrained/model000620000.pt \
  input_text=./assets/example_text_prompts.txt \
  version=tcfm sigma_min=0.0 guidance_param=2.5 \
  num_repetitions=3 batch_size=128

python generate.py dataset=kit \
  model_path=./pretrained/kit_trans_enc_512/model000400000.pt \
  input_text=./assets/example_text_prompts.txt

Evaluation

python eval_humanml.py dataset=humanml dynamic=flow \
  model_path=./pretrained/model000620000.pt \
  guidance_param=2.5 eval_mode=wo_mm diffusion_steps_sample=-1 \
  version=tcfm sigma_min=0.0 is_debug=0

python eval_humanml.py dataset=kit dynamic=flow \
  model_path=./outputs/kit_trans_enc_512_4gpu/model000200000.pt \
  guidance_param=2.5 eval_mode=mm_short ode_kwargs.step_size=0.02 is_debug=0

Visualize

python -m visualize.render_mesh --input_path path/to/sample00_rep00.mp4

Environment

conda create -n tcfm python=3.10
conda install -c "nvidia/label/cuda-11.8.0" cuda-toolkit
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
pip install pytorch-lightning torchdiffeq h5py diffusers accelerate loguru blobfile ml_collections ipdb
pip install hydra-core einops scikit-learn --upgrade
conda install -c conda-forge ffmpeg
pip install numpy==1.23.0
pip install clearml wandb sentencepiece transformers
pip install spacy clip smplx chumpy
python -m spacy download en_core_web_sm
pip install matplotlib==3.2.0
pip install git+https://github.com/openai/CLIP.git
pip install gdown
pip install wandb==0.14.2

Dataset preparation

Follow MDM to prepare:

HumanML3D
./pretrained
./body_models
./glove
./kit
./t2m

Acknowledgments

This codebase extends MotionFM (Hu et al., 2024). We also thank guided-diffusion, MotionCLIP, text-to-motion, ACTOR, joints2smpl, MoDi, and MDM.

License

This code is distributed under an MIT LICENSE.

Note that our code depends on other libraries, including CLIP, SMPL, SMPL-X, PyTorch3D, and uses datasets that each have their own respective licenses that must also be followed.

Citation

@article{CANALESCUBA2025104374,
  title   = {FlowMotion: Target-predictive conditional flow matching for Jitter-Reduced text-driven human motion generation},
  journal = {Computers \& Graphics},
  volume  = {132},
  pages   = {104374},
  year    = {2025},
  issn    = {0097-8493},
  doi     = {10.1016/j.cag.2025.104374},
  url     = {https://www.sciencedirect.com/science/article/pii/S0097849325002158},
  author  = {Manolo {Canales Cuba} and Vinícius {do Carmo Melício} and João Paulo Gois},
}