README.md

---
license: apache-2.0
library_name: generic
tags:
- motion-generation
- diffusion
- 3d
- humanml3d
- babel
---

# FloodDiffusion Downloads

This repository contains the datasets, dependencies, and pretrained models for **FloodDiffusion: Tailored Diffusion Forcing for Streaming Motion Generation**.

Code repository: [GitHub](https://github.com/ShandaAI/FloodDiffusion)

## Repository Structure

The files in this repository are organized to match the directory structure required by FloodDiffusion.

### 1. Model Checkpoints
The `outputs.zip` and `outputs_tiny.zip` archives contains the pretrained model weights.

*   **Target**: Unzip into your project root. It should create an `outputs/` folder.

```
outputs/
├── vae_1d_z4_step=300000.ckpt          # VAE model (1D, z_dim=4)
├── 20251106_063218_ldf/
│   └── step_step=50000.ckpt            # LDF model checkpoint (HumanML3D)
├── 20251107_021814_ldf_stream/
│   └── step_step=240000.ckpt           # LDF streaming model checkpoint (BABEL)
├── 20251217_023720_ldf_tiny/
│   └── step_step=60000.ckpt            # LDF tiny model checkpoint
└── 20251219_01492_ldf_tiny_stream/
    └── step_step=200000.ckpt           # LDF tiny streaming model checkpoint
```

### 2. Datasets
Due to the large number of files, datasets are provided as ZIP archives.

*   **`HumanML3D.zip`**: Contains the HumanML3D dataset (extracted features and texts).
    *   **Target**: Unzip into `raw_data/`. It should create `raw_data/HumanML3D/` containing `new_joint_vecs`, `texts`, etc.
*   **`BABEL_streamed.zip`**: Contains the BABEL dataset processed for streaming generation.
    *   **Target**: Unzip into `raw_data/`. It should create `raw_data/BABEL_streamed/`.

### 3. Dependencies (`deps.zip`)
*   **`deps.zip`**: Contains necessary dependencies like the T5 text encoder, evaluation models (T2M), and GloVe embeddings.
    *   **Target**: Unzip into your project root. It should create a `deps/` folder.

```
deps/
├── t2m/                     # Text-to-Motion evaluation models
├── glove/                   # GloVe word embeddings
└── t5_umt5-xxl-enc-bf16/    # T5 text encoder
```

## How to Download & Setup

We recommend using the python script below to automatically download and place files in the correct structure.

### Python Script (Recommended)

Save this as `download_assets.py` in your `FloodDiffusion` project root:

```python
from huggingface_hub import hf_hub_download
import zipfile
import os

REPO_ID = "ShandaAI/FloodDiffusionDownloads"

def download_extract_zip(filename, target_dir="."):
    print(f"Downloading {filename}...")
    path = hf_hub_download(repo_id=REPO_ID, filename=filename, repo_type="model")
    print(f"Extracting {filename} to {target_dir}...")
    with zipfile.ZipFile(path, 'r') as zip_ref:
        zip_ref.extractall(target_dir)

# 1. Download and extract Dependencies (creates ./deps/)
download_extract_zip("deps.zip", ".")

# 2. Download and extract Datasets (creates ./raw_data/HumanML3D and ./raw_data/BABEL_streamed)
os.makedirs("raw_data", exist_ok=True)
download_extract_zip("HumanML3D.zip", "raw_data")
download_extract_zip("BABEL_streamed.zip", "raw_data")

# 3. Download Models (creates ./outputs/)
download_extract_zip("outputs.zip", ".")
download_extract_zip("outputs_tiny.zip", ".")

print("Done! Your project is ready.")
```

## Data License & Acknowledgements

This repository provides pre-processed motion features (263-dim) to facilitate the reproduction of FloodDiffusion.

- **HumanML3D**: The motion features are derived from the [HumanML3D](https://github.com/EricGuo5513/HumanML3D) pipeline, originally built upon [AMASS](https://amass.is.tue.mpg.de/) and [HumanAct12](https://github.com/EricGuo5513/Action2Motion).
- **BABEL**: The streaming motion features are derived from the [BABEL](https://babel.is.tue.mpg.de/) dataset, which also builds upon AMASS.

**Important Note**: 
We only distribute the **extracted motion features and text annotations**, which is standard practice in the research community. We do **not** distribute the raw AMASS data (SMPL parameters/meshes). If you require the raw motion data or plan to use it for commercial purposes, you must register and agree to the licenses on the [AMASS website](https://amass.is.tue.mpg.de/).