StableAnimator

<a href='https://francis-rings.github.io/StableAnimator'><img src='https://img.shields.io/badge/Project-Page-Green'></a> <a href='https://arxiv.org/abs/2411.17697'><img src='https://img.shields.io/badge/Paper-Arxiv-red'></a> <a href='https://huggingface.co/FrancisRing/StableAnimator/tree/main'><img src='https://img.shields.io/badge/HuggingFace-Model-orange'></a> <a href='https://www.youtube.com/watch?v=7fwFyFDzQgg'><img src='https://img.shields.io/badge/YouTube-Watch-red?style=flat-square&logo=youtube'></a> <a href='https://www.bilibili.com/video/BV1X5zyYUEuD'><img src='https://img.shields.io/badge/Bilibili-Watch-blue?style=flat-square&logo=bilibili'></a>

StableAnimator：高质量身份保持的人体图像动画 <br/> Shuyuan Tu¹, Zhen Xing¹, Xintong Han³, Zhi-Qi Cheng⁴, Qi Dai², Chong Luo², Zuxuan Wu¹ <br/> [¹复旦大学; ²微软亚洲研究院; ³虎牙公司; ⁴卡内基梅隆大学]

<p align="center"> <img src="assets/figures/case-47.gif" width="256" /> <img src="assets/figures/case-61.gif" width="256" /> <img src="assets/figures/case-45.gif" width="256" /> <img src="assets/figures/case-46.gif" width="256" /> <img src="assets/figures/case-5.gif" width="256" /> <img src="assets/figures/case-17.gif" width="256" /> <br/> <span>由 StableAnimator 生成的姿态驱动人体图像动画，展示了其合成<b>高保真</b>和<b>身份保持视频</b>的能力。所有动画均<b>由 StableAnimator 直接合成，未使用任何与人脸相关的后处理工具</b>，如换脸工具 FaceFusion 或人脸修复模型 GFP-GAN 和 CodeFormer。</span> </p>

<p align="center"> <img src="assets/figures/case-35.gif" width="384" /> <img src="assets/figures/case-42.gif" width="384" /> <img src="assets/figures/case-18.gif" width="384" /> <img src="assets/figures/case-24.gif" width="384" /> <br/> <span>StableAnimator 与最先进（SOTA）人体图像动画模型的对比结果，突出了 StableAnimator 在提供<b>高保真、身份保持的人体图像动画</b>方面的卓越性能。</span> </p>

概述

<p align="center"> <img src="assets/figures/framework.jpg" alt="model architecture" width="1280"/> </br> <i>StableAnimator 框架概述。</i> </p>

当前用于人体图像动画的扩散模型难以确保身份（ID）一致性。本文提出了 StableAnimator，<b>这是首个端到端的身份保持视频扩散框架，在给定参考图像和姿态序列的条件下，无需任何后处理即可合成高质量视频。</b>StableAnimator 基于视频扩散模型构建，包含为训练和推理精心设计的模块，致力于实现身份一致性。具体而言，StableAnimator 首先使用现成的提取器分别计算图像嵌入和人脸嵌入，并通过全局内容感知的人脸编码器使人脸嵌入与图像嵌入进行交互，从而进一步优化人脸嵌入。然后，StableAnimator 引入了一种新颖的分布感知 ID 适配器，通过对其来防止时间层造成的干扰，同时保持身份信息。在推理过程中，我们提出了一种基于 Hamilton-Jacobi-Bellman（HJB）方程的优化方法来进一步提升人脸质量。我们证明，求解 HJB 方程可以集成到扩散去噪过程中，所得解能够约束去噪路径，从而有利于身份保持。在多个基准测试上的实验从定性和定量两个角度证明了 StableAnimator 的有效性。

新闻

• [2024-12-10]：🔥 Gradio 界面已发布！非常感谢 @gluttony-10 的贡献！其他代码将很快发布。敬请期待！
• [2024-12-6]：🔥 所有数据预处理代码（人体骨架提取和人脸掩码提取）已发布！训练代码和详细的训练教程将在 2024.12.13 之前发布。敬请期待！
• [2024-12-4]：🔥 我们很高兴发布一个有趣的舞蹈演示（🔥🔥APT 舞蹈🔥🔥）！生成的视频可以在 YouTube 和 Bilibili 上观看。
• [2024-11-28]：🔥 数据预处理代码（人体骨架提取）已发布！其他代码将很快发布。敬请期待！
• [2024-11-26]：🔥 项目页面、代码、技术报告和基础模型检查点已发布。进一步的训练代码、数据预处理代码、评估数据集和 StableAnimator-pro 将很快发布。敬请期待！

待办事项

• [x] StableAnimator-basic
• [x] 推理代码
• [x] 评估样本
• [x] 数据预处理代码（骨架提取）
• [x] 数据预处理代码（人脸掩码提取）
• [ ] 评估数据集
• [ ] 训练代码
• [ ] StableAnimator-pro
• [ ] 基于 HJB 的人脸优化推理代码

快速开始

对于基础版本的模型检查点，支持以 576x1024 或 512x512 分辨率生成视频。如果遇到内存不足的问题，可以适当减少动画帧数。

环境配置

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install torch==2.5.1+cu124 xformers --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

下载权重

如果在连接 Hugging Face 时遇到问题，可以通过设置环境变量使用镜像端点：export HF_ENDPOINT=https://hf-mirror.com。 请按以下方式手动下载权重：

cd StableAnimator
git lfs install
git clone https://huggingface.co/FrancisRing/StableAnimator checkpoints

所有权重应按以下方式组织： 本项目的整体文件结构应按如下方式组织：

StableAnimator/
├── DWPose
├── animation
├── checkpoints
│   ├── DWPose
│   │   ├── dw-ll_ucoco_384.onnx
│   │   └── yolox_l.onnx
│   ├── Animation
│   │   ├── pose_net.pth
│   │   ├── face_encoder.pth
│   │   └── unet.pth
│   ├── SVD
│   │   ├── feature_extractor
│   │   ├── image_encoder
│   │   ├── scheduler
│   │   ├── unet
│   │   ├── vae
│   │   ├── model_index.json
│   │   ├── svd_xt.safetensors
│   │   └── svd_xt_image_decoder.safetensors
│   └── inference.zip
├── models
│   │   └── antelopev2
│   │       ├── 1k3d68.onnx
│   │       ├── 2d106det.onnx
│   │       ├── genderage.onnx
│   │       ├── glintr100.onnx
│   │       └── scrfd_10g_bnkps.onnx
├── app.py
├── command_basic_infer.sh
├── inference_basic.py
├── requirement.txt 

评估样本

论文中展示的评估样本可以从 OneDrive 或 checkpoints 中的 inference.zip 下载。请按以下方式手动下载评估样本：

cd StableAnimator
mkdir inference

所有评估样本应按如下方式组织：

inference/
├── case-1
│   ├── poses
│   ├── faces
│   └── reference.png
├── case-2
│   ├── poses
│   ├── faces
│   └── reference.png
├── case-3
│   ├── poses
│   ├── faces
│   └── reference.png

人体骨架提取

我们利用预训练的 DWPose 来提取人体骨架。在初始化 DWPose 时，预训练权重应在 /DWPose/dwpose_utils/wholebody.py 中配置：

onnx_det = 'path/checkpoints/DWPose/yolox_l.onnx'
onnx_pose = 'path/checkpoints/DWPose/dw-ll_ucoco_384.onnx'

给定包含多个 .png 文件的目标图像文件夹，您可以使用以下命令获取相应的人体骨架图像：

python skeleton_extraction.py --target_image_folder_path="path/test/target_images" --ref_image_path="path/test/reference.png" --poses_folder_path="path/test/poses"

需要注意的是，目标图像文件夹中的 .png 文件应以 frame_i.png 格式命名，例如 frame_0.png、frame_1.png 等。 --ref_image_path 指的是给定参考图像的路径。获得的人体骨架图像保存在 path/test/poses 中。特别重要的是，目标骨架图像应与参考图像在体型上保持一致。

如果您只有目标 MP4 文件，我们建议您使用 ffmpeg 将 MP4 文件无损转换为多帧（.png 文件）。

ffmpeg -i target.mp4 -q:v 1 path/test/target_images/frame_%d.png

获得的帧保存在 path/test/target_images 中。

人脸掩码提取

给定包含多个 RGB .png 文件的图像文件夹路径，您可以运行以下命令提取相应的人脸掩码：

python face_mask_extraction.py --image_folder="path/StableAnimator/inference/your_case/target_images"

path/StableAnimator/inference/your_case/target_images 包含多个 .png 文件。获得的掩码保存在 path/StableAnimator/inference/your_case/faces 中。

模型推理

我们提供了 command_basic_infer.sh 作为测试的示例配置。您也可以根据需要轻松修改各种配置。

bash command_basic_infer.sh

StableAnimator 支持两种不同分辨率设置的人体图像动画：512x512 和 576x1024。您可以在 command_basic_infer.sh 中修改 "--width" 和 "--height" 来设置动画的分辨率。command_basic_infer.sh 中的 "--output_dir" 指的是生成动画的保存路径。command_basic_infer.sh 中的 "--validation_control_folder" 和 "--validation_image" 分别指给定的姿态序列和参考图像的路径。 command_basic_infer.sh 中的 "--pretrained_model_name_or_path" 是预训练 SVD 的路径。command_basic_infer.sh 中的 "posenet_model_name_or_path"、"face_encoder_model_name_or_path" 和 "unet_model_name_or_path" 指的是预训练 StableAnimator 权重的路径。 如果您有足够的 GPU 资源，可以增加 command_basic_infer.sh 中 "--decode_chunk_size" 的值（4=>8=>16）来提升动画的时间平滑度。

提示：如果您的 GPU 内存有限，可以减少动画帧数。此命令将生成两个文件：<b>animated_images</b> 和 <b>animated_images.gif</b>。 如果您想获得高质量的 MP4 文件，我们建议您在 <b>animated_images</b> 上使用 ffmpeg，如下所示：

cd animated_images
ffmpeg -framerate 20 -i frame_%d.png -c:v libx264 -crf 10 -pix_fmt yuv420p /path/animation.mp4

"-framerate" 指的是 fps 设置。"-crf" 表示生成的 MP4 文件的质量，数值越小对应的质量越高。 此外，您也可以运行以下命令启动 Gradio 界面：

python app.py

显存需求与运行时间

对于 15 秒的演示视频（512x512，fps=30），16 帧基础模型需要 8GB 显存，在 4090 GPU 上 5 分钟内完成。

pro 模型 16 帧 U-Net 的最低显存需求为 10GB（576x1024，fps=30）；但是，VAE 解码器需要 16GB。您可以选择在 CPU 上运行 VAE 解码器。

联系方式

如果您有任何建议或发现我们的工作对您有帮助，欢迎与我联系

邮箱：francisshuyuan@gmail.com

如果您觉得我们的工作有用，<b>请考虑给这个 GitHub 仓库点个星并引用它</b>：

@article{tu2024stableanimator,
  title={StableAnimator: High-Quality Identity-Preserving Human Image Animation},
  author={Shuyuan Tu and Zhen Xing and Xintong Han and Zhi-Qi Cheng and Qi Dai and Chong Luo and Zuxuan Wu},
  journal={arXiv preprint arXiv:2411.17697},
  year={2024}
}