CacheFlow: Fast Human Motion Prediction by Cached Normalizing Flow

This repository contains the official PyTorch implementation of the paper:

CacheFlow: Fast Human Motion Prediction by Cached Normalizing Flow
Takahiro Maeda, Jinkun Cao, Norimichi Ukita, and Kris Kitani
TMLR 2025
[paper]

Installation

1. Environment

uv sync
source .venv/bin/activate

pip install -r requirements.txt

2. Datasets

We follow the BeLFusion data preparation except for the 3DPW.

> Human3.6M

Extract the Poses-D3Positions* folders for S1, S5, S6, S7, S8, S9, S11 into ./datasets/Human36M. Then, run:

python -m data_loader.parsers.h36m

> AMASS

Download the SMPL+H G files for 22 datasets: ACCAD, BMLhandball, BMLmovi, BMLrub, CMU, DanceDB, DFaust, EKUT, EyesJapanDataset, GRAB, HDM05, HUMAN4D, HumanEva, KIT, MoSh, PosePrior (MPI_Limits), SFU, SOMA, SSM, TCDHands, TotalCapture, and Transitions. Then, move the tar.bz2 files to ./datasets/AMASS (DO NOT extract them).

Now, download the 'DMPLs for AMASS' from here, and the 'Extended SMPL+H model' from here. Move both extracted folders (dmpls, smplh) to ./auxiliar/body_models. Then, run:

python -m data_loader.parsers.amass --gpu

Note 1: remove the --gpu flag if you do not have a GPU.

Note 2: this step could take a while (~2 hours in CPU, ~20-30 minutes in GPU).

> 3D Pose in the Wild (3DPW)

Download the sequenceFiles.zip. Then, extract and move files to ./datasets/3DPW/sequenceFiles.

python -m data_loader.parsers.3dpw --gpu

3. Checkpoints (link)

Replace the folder 'checkpoints' in the root of the repository with the downloaded one. If you want to train the models from scratch, you can skip this step and go to the training section.

Evaluation

Run the following scripts to evaluate BeLFusion and the other state-of-the-art methods.

Human3.6M:

# CacheFlow
python eval_precompute.py --config checkpoints/ours/h36m/ConditionalBase/dim256_SLD08_KL1e-2/ --precompute_samples stride_1 --selection_algorithm sample_NN --augmentation --ema --FPC 50 -i 300

# Baselines --> {ThePoseKnows, DLow, GSPS, DiverseSampling}
python eval_baseline.py -c checkpoints/baselines/h36m/<BASELINE_NAME>/exp -m stats --batch_size 512

AMASS:

# CacheFlow
python eval_precompute.py --config checkpoints/ours/amass/ConditionalBase/align_rotation_dim256_SLD08_KL1e-2_joint_KL1e-1/ --precompute_samples stride_10 --selection_algorithm sample_NN --ema --FPC 10 -i 300

# Baselines --> {ThePoseKnows, DLow, GSPS, DiverseSampling}
python eval_baseline.py -c checkpoints/baselines/amass/<BASELINE_NAME>/exp -m stats --batch_size 512 --multimodal_threshold 0.4

Zero-shot 3DPW:

# CacheFlow
python eval_precompute.py --config checkpoints/ours/3dpw/ConditionalBase/align_rotation_dim256_SLD08_KL1e-2_joint_KL1e-1/ --precompute_samples stride_10 --selection_algorithm sample_NN --ema --FPC 50 -i 300

• Add --stats_mode all to also compute the MMADE, MMFDE (increased computation time).
• Add -cpu to run the evaluation in CPU (recommended for low-memory GPUs).
• (only for BeLFusion) Use --dstride S to compute the evaluation metrics every S denoising steps (increased computation time). If S=10, the metrics will be computed for step 1 (BeLFusion_D), and 10 (BeLFusion).

Training

For training CacheFlow from scratch, you need to first train the Behavioral Latent Space (BLS) and the observation autoencoder (<DATASET> in {h36m, amass}).

# Observation autoencoder --> 500 epochs
python train_auto.py -c checkpoints/ours/<DATASET>/ConditionalBase/<model>/autoencoder_obs/config.json

# BLS --> 2x500 epochs
python train_bls.py -c checkpoints/ours/<DATASET>/ConditionalBase/<model>/behavioral_latent_space/config.json

Once they finish, you can train the CacheFlow model (the unconditional flow matching model and the lightweight conditional Gaussian Mixture):

# Unconditional Flow Matching --> 300 epochs
python train_flow_matching.py -c checkpoints/ours/<DATASET>/ConditionalBase/<model>/uncond_flow_matching/config.json

# Conditional Gaussian Mixture --> 300 epochs
python train_conditional_base_joint.py -c checkpoints/ours/<DATASET>/ConditionalBase/<model>/config.json

Citation

If you find our work useful in your research, please consider citing our paper:

@article{maeda2025cacheflow,
  author       = {Takahiro Maeda,
                  Jinkun Cao,
                  Norimichi Ukita, and                  
                  Kris Kitani},
  title        = {CacheFlow: Fast Human Motion Prediction by Cached Normalizing Flow},
  journal      = {Trans. Mach. Learn. Res.},
  volume       = {2025},
  year         = {2025}
}

Note: project is based on BeLFusion GitHub repository.