---
base_model:
- Wan-AI/Wan2.1-T2V-1.3B
license: apache-2.0
pipeline_tag: image-to-video
---
[](https://hyokong.github.io/worldwarp-page/)
[](https://arxiv.org/abs/2512.19678)
[](https://huggingface.co/imsuperkong/worldwarp) [](https://www.youtube.com/watch?v=rfMHxb--cKs)
[Hanyang Kong](https://hyokong.github.io/),
[Xingyi Yang](https://adamdad.github.io/),
Xiaoxu Zheng,
[Xinchao Wang](https://sites.google.com/site/sitexinchaowang/)
**TL;DR**: đ Single-image long-range view generation via an asynchronous chunk-wise autoregressive diffusion framework that utilizes explicit camera conditioning and online 3D cache for geometric consistency.
This repository contains the weights for **WorldWarp**, presented in [WorldWarp: Propagating 3D Geometry with Asynchronous Video Diffusion](https://arxiv.org/abs/2512.19678).
## đŦ Demo Video
âļī¸ **Click the GIF to watch the full video with sound.**
## đ ī¸ Installation
> â ī¸ **Hardware Note:** The current implementation requires high GPU memory (~40GB VRAM). We are currently optimizing the code to reduce this footprint.
### đ§Ŧ Cloning the Repository
The repository contains submodules, thus please check it out with
```bash
git clone https://github.com/HyoKong/WorldWarp.git --recursive
cd WorldWarp
```
### đ Create environment
Create a conda environment and install dependencies:
```
conda create -n worldwarp python=3.12 -y
conda activate worldwarp
```
### đĨ Install PyTorch
Install PyTorch with CUDA 12.6 support (or visit [PyTorch Previous Versions](https://pytorch.org/get-started/previous-versions/) for other CUDA configurations):
```bash
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu126
```
### đĻ Install Dependencies & Compile Extensions
These packages require compilation against the specific PyTorch version installed above.
```bash
# Core compiled dependencies
pip install flash-attn --no-build-isolation
pip install "git+https://github.com/facebookresearch/pytorch3d.git" --no-build-isolation
# Local modules
pip install src/fused-ssim/ --no-build-isolation
pip install src/simple-knn/ --no-build-isolation
# Remaining python dependencies
pip install -r requirements.txt
```
### đī¸ Build Other Extensions
```bash
cd src/ttt3r/croco/models/curope/
python setup.py build_ext --inplace
cd - # Returns to the project root
```
## âī¸ Download checkpoints
```
mkdir ckpt
hf download Wan-AI/Wan2.1-T2V-1.3B-Diffusers --local-dir ckpt/Wan-AI/Wan2.1-T2V-1.3B-Diffusers
hf download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ckpt/Qwen/Qwen2.5-VL-7B-Instruct
hf download imsuperkong/worldwarp --local-dir ckpt/
cd src/ttt3r/
gdown --fuzzy https://drive.google.com/file/d/1Asz-ZB3FfpzZYwunhQvNPZEUA8XUNAYD/view?usp=drive_link
cd ../..
```
## đ¨ GUI Demo
```bash
python gradio_demo.py
```
The web interface will open at `http://localhost:7890`.
---
### đ Quick start:
**1ī¸âŖ Choose Starting Image**
- **đ Examples Tab**: Click a pre-made example image (prompt auto-fills)
- **đ¨ Generate Tab**: Click "Generate First Frame" from your prompt
- **đ¤ Upload Tab**: Upload your own image
**2ī¸âŖ Select Camera Movement** (Recommended: đš From Video)
- **From Video** (Easiest and most reliable)
- Click **"đš From Video"** mode
- Select an example video from the gallery OR upload your own
- Click **"đ¯ Load Poses"** to extract camera trajectory
- Poses are automatically cached for reuse
- **Preset Movements**
- Select **"đ¯ Preset"** mode
- Choose movements: `DOLLY_IN`, `PAN_LEFT`, `PAN_RIGHT`, etc.
- Can combine: e.g., `DOLLY_IN + PAN_RIGHT`
- **Custom** (Advanced)
- Select **"đ§ Custom"** mode
- Manually control rotation and translation parameters
**3ī¸âŖ Configure & Generate**
**Essential Parameters:**
- đĒ **Strength (0.5 - 0.8)**
- **Higher (0.7-0.8)**: More generated details, richer content
- â ī¸ May introduce content changes due to higher creative freedom
- **Lower (0.5-0.6)**: More accurate camera control, closer to input
- â ī¸ May produce blurry results due to limited diffusion model freedom
- **Trade-off**: Higher strength = more details but less control; Lower strength = better control but potentially blurry
- ⥠**Speed Multiplier**
- **Purpose**: Adjust camera movement velocity to match your scene scale
- **Why needed**: Reference video's camera movement scale may not match your scene (e.g., drone video moving 10 meters may be too fast for a small room)
- **< 1.0**: Slower camera movement (e.g., 0.5 = half speed)
- **= 1.0**: Original speed from reference
- **> 1.0**: Faster camera movement (e.g., 2.0 = double speed)
- **Tip**: Start with 1.0, then adjust based on whether motion feels too fast or too slow
---
#### đ Best Practices
- đī¸ **Generate one chunk at a time**
- Lets you preview each chunk's quality before continuing
- Easier to identify issues early
- âŠī¸ **Use Rollback for iteration**
- If a chunk is unsatisfactory, enter its number in **"Rollback to #"**
- Click **"âī¸ Rollback"** to remove it
- Adjust parameters and regenerate
- đī¸ **Adjust Speed Multiplier per scene**
- If camera moves too fast â decrease value (e.g., 0.5-0.7)
- If camera moves too slow â increase value (e.g., 1.5-2.0)
## đ Acknowledgements
Our code is based on the following awesome repositories:
- [DFoT](https://github.com/kwsong0113/diffusion-forcing-transformer)
- [TTT3R](https://github.com/Inception3D/TTT3R)
We thank the authors for releasing their code!
## đ Citation
If you find our work useful, please cite:
```bibtex
@misc{kong2025worldwarp,
title={WorldWarp: Propagating 3D Geometry with Asynchronous Video Diffusion},
author={Hanyang Kong and Xingyi Yang and Xiaoxu Zheng and Xinchao Wang},
year={2025},
eprint={2512.19678},
archivePrefix={arXiv},
primaryClass={cs.CV}
}
```