更新

• 2023.11.09：集成至 :man_artist: OpenXLab。快来体验在线演示吧！
• 2023.11.09：集成至 :hugs: Hugging Face。快来体验在线演示吧！
• 2023.09.24：我们正式移除了水印去除演示，以防止我们的工作被用于不道德的目的。
• 2023.09.21：新增了内存高效推理功能。请查看我们的GPU内存要求。🚀
• 2023.09.07：我们的代码和模型已公开发布。🐳
• 2023.09.01：本仓库创建。

待办事项

• 制作Colab演示。
• 制作交互式Gradio演示。
• 更新内存高效推理功能。

结果

👨🏻‍🎨 物体移除

🎨 视频补全

概述

依赖与安装

1. 克隆仓库

   git clone https://github.com/sczhou/ProPainter.git
   

2. 创建Conda环境并安装依赖

   # 创建新的Anaconda环境
   conda create -n propainter python=3.8 -y
   conda activate propainter
   
   # 安装Python依赖
   pip3 install -r requirements.txt
   

   • CUDA ≥ 9.2
   • PyTorch ≥ 1.7.1
   • Torchvision ≥ 0.8.2
   • requirements.txt中列出的其他必要包

开始使用

准备预训练模型

从Releases V0.1.0下载我们的预训练模型，并将其放置在weights文件夹中。（所有预训练模型也可以在首次推理时自动下载。）

目录结构应如下所示：

weights
   |- ProPainter.pth
   |- recurrent_flow_completion.pth
   |- raft-things.pth
   |- i3d_rgb_imagenet.pt（用于评估VFID指标）
   |- README.md

🏂 快速测试

我们在inputs文件夹中提供了一些示例。运行以下命令即可尝试：

# 第一个示例（物体移除）
python inference_propainter.py --video inputs/object_removal/bmx-trees --mask inputs/object_removal/bmx-trees_mask 
# 第二个示例（视频补全）
python inference_propainter.py --video inputs/video_completion/running_car.mp4 --mask inputs/video_completion/mask_square.png --height 240 --width 432

结果将保存在results文件夹中。如需测试您自己的视频，请准备输入的mp4视频（或分割后的帧）以及逐帧掩码。

若要指定视频处理分辨率或避免内存不足，可以设置--width和--height参数：

# 处理分辨率为576×320的视频；设置--fp16以在推理过程中使用半精度（fp16）。
python inference_propainter.py --video inputs/video_completion/running_car.mp4 --mask inputs/video_completion/mask_square.png --height 320 --width 576 --fp16

💃🏻 交互式演示

我们还提供了物体移除的交互式演示，用户可以选择视频中任何想要移除的对象。您可以在Hugging Face上试用该演示，或在本地运行它（详见GitHub）。

请注意，演示界面和使用方法可能与上方的GIF动画有所不同。有关详细说明，请参阅用户指南。

🚀 内存高效的推理

视频修复通常需要大量的显存。在此，我们提供了多种功能来实现内存高效的推理，从而有效避免“显存不足”（OOM）错误。您可以使用以下选项进一步降低显存占用：

• 通过减少 --neighbor_length 参数值（默认为10）来减少局部邻域的数量。
• 通过增加 --ref_stride 参数值（默认为10）来减少全局参考帧的数量。
• 设置 --resize_ratio 参数（默认为1.0）以调整处理视频的分辨率。
• 通过指定 --width 和 --height 参数来设置更小的视频尺寸。
• 设置 --fp16 参数，在推理过程中使用半精度浮点数（FP16）。
• 减少子视频的帧数 --subvideo_length（默认为80），这可以有效地解耦显存消耗与视频长度之间的关系。

下表展示了在FP32和FP16精度下，不同子视频长度所需的显存估算：

分辨率	50帧	80帧
1280 x 720	28G / 19G	OOM / 25G
720 x 480	11G / 7G	13G / 8G
640 x 480	10G / 6G	12G / 7G
320 x 240	3G / 2G	4G / 3G

数据集准备

数据集	YouTube-VOS	DAVIS
描述	用于训练（3,471个）和评估（508个）	仅用于评估（90个视频中的50个）
图像	[官方链接]（下载训练和测试的所有帧）		[官方链接]（2017年，480p，训练验证集）
掩码	[Google Drive] [百度网盘]（用于复现论文结果；由ProPainter论文提供）

训练和测试划分文件位于 datasets/<dataset_name> 目录中。对于每个数据集，您应将 JPEGImages 文件夹放置到 datasets/<dataset_name> 中。训练时，请将所有视频帧调整为 432x240 的分辨率。并将下载的掩码文件解压到 datasets 目录中。

datasets 目录结构如下：（请注意仔细检查）

datasets
   |- davis
      |- JPEGImages_432_240
         |- <video_name>
            |- 00000.jpg
            |- 00001.jpg
      |- test_masks
         |- <video_name>
            |- 00000.png
            |- 00001.png   
      |- train.json
      |- test.json
   |- youtube-vos
      |- JPEGImages_432_240
         |- <video_name>
            |- 00000.jpg
            |- 00001.jpg
      |- test_masks
         |- <video_name>
            |- 00000.png
            |- 00001.png
      |- train.json
      |- test.json   

训练

我们的训练配置分别位于 train_flowcomp.json（用于循环流完成网络）和 train_propainter.json（用于ProPainter）。

运行以下命令之一进行训练：

 # 训练循环流完成网络
 python train.py -c configs/train_flowcomp.json
 # 训练ProPainter
 python train.py -c configs/train_propainter.json

您可以使用相同的命令来恢复您的训练。

为了加快训练速度，您可以使用以下命令为训练数据集预先计算光流：

 # 计算训练数据集的光流
 python scripts/compute_flow.py --root_path <dataset_root> --save_path <save_flow_root> --height 240 --width 432

评估

运行以下命令之一进行评估：

 # 评估流完成模型
 python scripts/evaluate_flow_completion.py --dataset <dataset_name> --video_root <video_root> --mask_root <mask_root> --save_results
 # 评估ProPainter模型
 python scripts/evaluate_propainter.py --dataset <dataset_name> --video_root <video_root> --mask_root <mask_root> --save_results

分数和结果也将保存在 results_eval 文件夹中。请务必使用 --save_results 选项，以便后续评估时间扭曲误差。

引用

如果您发现我们的仓库对您的研究有所帮助，请考虑引用我们的论文：

@inproceedings{zhou2023propainter,
   title={{ProPainter}: Improving Propagation and Transformer for Video Inpainting},
   author={Zhou, Shangchen and Li, Chongyi and Chan, Kelvin C.K and Loy, Chen Change},
   booktitle={Proceedings of IEEE International Conference on Computer Vision (ICCV)},
   year={2023}
}

许可证

仅限非商业用途声明

ProPainter仅允许用于非商业目的的使用、复制和分发。代码和模型根据NTU S-Lab许可证1.0授权。再分发和使用必须遵守该许可协议。

如需咨询或获得商业用途许可，请联系周尚辰博士（shangchenzhou@gmail.com）。

使用ProPainter的项目

如果您在项目中开发或使用了ProPainter，请随时告知我。同时，请包含此ProPainter仓库链接、作者信息以及我们的S-Lab许可证（附链接）。

社区贡献的项目/应用

• 流式ProPainter：https://github.com/osmr/propainter
• 更快的ProPainter：https://github.com/halfzm/faster-propainter
• ProPainter WebUI：https://github.com/halfzm/ProPainter-Webui
• ProPainter ComfyUI：https://github.com/daniabib/ComfyUI_ProPainter_Nodes
• Cutie（视频分割）：https://github.com/hkchengrex/Cutie
• Cinetransfer（角色迁移）：https://virtualfilmstudio.github.io/projects/cinetransfer
• Motionshop（角色迁移）：https://aigc3d.github.io/motionshop

PyPI

• propainter：https://pypi.org/project/propainter
• pytorchcv：https://pypi.org/project/pytorchcv

联系方式

如有任何问题，请随时通过 shangchenzhou@gmail.com 与我联系。

致谢

本代码基于E²FGVI和STTN。部分代码来自BasicVSR++。感谢他们的出色工作。

特别感谢Luo Yihang，他为构建和维护ProPainter的Gradio演示做出了重要贡献。

ProPainter 快速上手指南

ProPainter 是一款基于 ICCV 2023 论文的视频修复（Video Inpainting）开源工具，擅长处理视频物体移除和视频补全任务。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 Windows
• GPU: NVIDIA 显卡，显存建议 8GB 以上（支持内存优化模式可降低需求）
• CUDA: >= 9.2
• Python: 3.8
• PyTorch: >= 1.7.1
• Torchvision: >= 0.8.2

国内加速提示：安装 Python 依赖时，建议使用清华源或阿里源以加快下载速度。

2. 安装步骤

2.1 克隆项目

git clone https://github.com/sczhou/ProPainter.git
cd ProPainter

2.2 创建虚拟环境并安装依赖

# 创建名为 propainter 的 conda 环境
conda create -n propainter python=3.8 -y
conda activate propainter

# 安装依赖 (推荐使用国内镜像源)
pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3 准备预训练模型

模型文件通常会在首次推理时自动下载。如果需要手动下载，请从 Releases V0.1.0 获取文件并放入 weights 文件夹。

预期的目录结构如下：

weights
   |- ProPainter.pth
   |- recurrent_flow_completion.pth
   |- raft-things.pth
   |- i3d_rgb_imagenet.pt
   |- README.md

3. 基本使用

3.1 快速测试（使用示例数据）

项目自带了示例视频和掩码（mask），位于 inputs 文件夹。

示例 1：物体移除 (Object Removal)

python inference_propainter.py --video inputs/object_removal/bmx-trees --mask inputs/object_removal/bmx-trees_mask

示例 2：视频补全 (Video Completion)

python inference_propainter.py --video inputs/video_completion/running_car.mp4 --mask inputs/video_completion/mask_square.png --height 240 --width 432

运行完成后，结果将保存在 results 文件夹中。

3.2 处理自定义视频

要处理自己的视频，请准备以下两个输入：

1. 视频文件：.mp4 格式或拆分后的帧图像文件夹。
2. 掩码文件：对应每一帧的黑白掩码图（白色区域为需要修复的部分）。

命令格式：

python inference_propainter.py --video <视频路径> --mask <掩码路径>

3.3 显存优化（低显存用户必读）

如果遇到显存不足（OOM）错误，或希望处理更高分辨率视频，可通过以下参数降低显存占用：

• --fp16: 启用半精度推理（显著降低显存）。
• --height / --width: 调整输入视频分辨率。
• --subvideo_length: 减少子视频长度（默认 80，可设为 50 或更低）。
• --neighbor_length: 减少局部邻居数量（默认 10）。
• --ref_stride: 增加全局参考步长（默认 10）。

低显存运行示例：

# 将视频调整为 576x320，启用 fp16，缩短子视频长度至 50 帧
python inference_propainter.py --video inputs/video_completion/running_car.mp4 --mask inputs/video_completion/mask_square.png --height 320 --width 576 --fp16 --subvideo_length 50

3.4 交互式演示 (可选)

如果您希望通过网页界面交互式地涂抹去除物体，可以运行本地 Gradio 演示：

# 进入 web-demos 目录并运行 (需额外安装 gradio 等依赖)
cd web-demos/hugging_face
# 具体运行命令请参考该目录下的 README.md

或者直接访问在线 Demo：Hugging Face Space