迈向基于码本查找 Transformer (Codebook Lookup Transformer) 的鲁棒盲人脸修复 (NeurIPS 2022)

论文 | 项目页面 | 视频

Shangchen Zhou, Kelvin C.K. Chan, Chongyi Li, Chen Change Loy

S 实验室，南洋理工大学

:star: 如果 CodeFormer 对您的图片或者项目有帮助，请帮忙给这个仓库点个星。谢谢！:hugs:

更新

• 2023.07.20: 集成到 :panda_face: OpenXLab。试用在线演示！
• 2023.04.19: :whale: 训练代码和配置文件现已公开可用。
• 2023.04.09: 为裁剪和对齐的人脸图像添加了修复 (inpainting) 和上色 (colorization) 功能。
• 2023.02.10: 将 dlib 作为新的人脸检测选项包含在内，它能产生更准确的人脸身份识别。
• 2022.10.05: 支持视频输入 --input_path [YOUR_VIDEO.mp4]。尝试用它来增强您的视频！:clapper:
• 2022.09.14: 集成到 :hugs: Hugging Face。试用在线演示！
• 2022.09.09: 集成到 :rocket: Replicate。试用在线演示！
• 更多

待办事项

• 添加训练代码和配置文件
• 添加人脸修复 (inpainting) 的检查点 (checkpoint) 和脚本
• 添加人脸上色 (colorization) 的检查点 (checkpoint) 和脚本
• 添加背景图像增强

:panda_face: 尝试增强老照片 / 修复 AI 艺术

人脸修复

人脸色彩增强与修复

人脸修复 (Inpainting)

依赖与环境安装

• Pytorch >= 1.7.1
• CUDA >= 10.1
• requirements.txt 中的其他所需包

# git clone this repository
git clone https://github.com/sczhou/CodeFormer
cd CodeFormer

# create new anaconda env
conda create -n codeformer python=3.8 -y
conda activate codeformer

# install python dependencies
pip3 install -r requirements.txt
python basicsr/setup.py develop
conda install -c conda-forge dlib (only for face detection or cropping with dlib)

快速推理

下载预训练模型：

从 [Releases | Google Drive | OneDrive] 下载 facelib 和 dlib 预训练模型到 weights/facelib 文件夹。您可以手动下载预训练模型，或运行以下命令下载：

python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py dlib (only for dlib face detector)

从 [Releases | Google Drive | OneDrive] 下载 CodeFormer 预训练模型到 weights/CodeFormer 文件夹。您可以手动下载预训练模型，或运行以下命令下载：

python scripts/download_pretrained_models.py CodeFormer

准备测试数据：

您可以将测试图像放入 inputs/TestWhole 文件夹。如果您想测试裁剪和对齐的人脸，可以将它们放在 inputs/cropped_faces 文件夹中。您可以通过运行以下命令获取裁剪和对齐的人脸：

# you may need to install dlib via: conda install -c conda-forge dlib
python scripts/crop_align_face.py -i [input folder] -o [output folder]

测试：

[注意] 如果您想在论文中比较 CodeFormer，请运行以下命令并指定 --has_aligned（针对裁剪和对齐的人脸），因为整张图像的命令涉及人脸 - 背景融合过程，这可能会破坏边界处的头发纹理，导致不公平的比较。

保真度权重 w 位于 [0, 1] 之间。通常，较小的 w 倾向于产生更高质量的结果，而较大的 w 会产生更高保真度的结果。结果将保存在 results 文件夹中。

🧑🏻 人脸修复（裁剪和对齐的人脸）

# For cropped and aligned faces (512x512)
python inference_codeformer.py -w 0.5 --has_aligned --input_path [image folder]|[image path]

:framed_picture: 整图增强

# For whole image
# Add '--bg_upsampler realesrgan' to enhance the background regions with Real-ESRGAN
# Add '--face_upsample' to further upsample restorated face with Real-ESRGAN
python inference_codeformer.py -w 0.7 --input_path [image folder]|[image path]

:clapper: 视频增强

# 对于 Windows/Mac 用户，请先安装 ffmpeg (FFmpeg 多媒体框架)
conda install -c conda-forge ffmpeg

# For video clips
# Video path should end with '.mp4'|'.mov'|'.avi'
python inference_codeformer.py --bg_upsampler realesrgan --face_upsample -w 1.0 --input_path [video path]

🌈 人脸着色（裁剪并对齐的人脸）

# For cropped and aligned faces (512x512)
# Colorize black and white or faded photo
python inference_colorization.py --input_path [image folder]|[image path]

🎨 人脸修复（裁剪并对齐的人脸）

# For cropped and aligned faces (512x512)
# Inputs could be masked by white brush using an image editing app (e.g., Photoshop) 
# (check out the examples in inputs/masked_faces)
python inference_inpainting.py --input_path [image folder]|[image path]

训练：

训练命令可以在文档中找到：英文 | 简体中文。

许可证

本项目采用 NTU S-Lab License 1.0 许可。重新分发和使用应遵循此许可证。

---

🐼 生态系统应用与部署

CodeFormer 已被广泛采用并部署在广泛的在线应用、平台、API (应用程序接口) 服务和独立网站（超过 20 个）上，并已集成到许多开源项目和工具包中。

仅在 Hugging Face Space、Replicate 和 OpenXLab 上的演示是作者维护的官方部署。以下列出的所有其他演示、API、应用、网站和集成均为第三方（非官方），与 CodeFormer 作者无关。请核实其合法性以避免潜在的经济损失。

网站（非官方）

⚠️⚠️⚠️ 以下网站不是官方网站，也不是由我们运营的。它们未经任何许可或授权使用了我们的模型。请核实其合法性以避免潜在的经济损失。

网站	链接	备注
CodeFormer.net	https://codeformer.net/	非官方网站
CodeFormer.cn	https://www.codeformer.cn/	非官方网站
CodeFormerAI.com	https://codeformerai.com/	非官方网站

在线演示 / API 平台

平台	链接	备注
Hugging Face	https://huggingface.co/spaces/sczhou/CodeFormer	由作者维护
Replicate	https://replicate.com/sczhou/codeformer	由作者维护
OpenXLab	https://openxlab.org.cn/apps/detail/ShangchenZhou/CodeFormer	由作者维护
Segmind	https://www.segmind.com/models/codeformer	非官方
Sieve	https://www.sievedata.com/functions/sieve/codeformer	非官方
Fal.ai	https://fal.ai/models/fal-ai/codeformer	非官方
VaikerAI	https://vaikerai.com/sczhou/codeformer	非官方
Scade.pro	https://www.scade.pro/processors/lucataco-codeformer	非官方
Grandline	https://www.grandline.ai/model/codeformer	非官方
AI Demos	https://aidemos.com/tools/codeformer	非官方
Synexa	https://synexa.ai/explore/sczhou/codeformer	非官方
RentPrompts	https://rentprompts.ai/models/Codeformer	非官方
ElevaticsAI	https://elevatics.ai/models/super-resolution/codeformer	非官方
Anakin.ai	https://anakin.ai/apps/codeformer-online-face-restoration-by-codeformer-19343	非官方
Relayto	https://relayto.com/explore/codeformer-yf9rj8kwc7zsr	非官方

开源项目与工具包

项目 / 工具包	链接	备注
Stable Diffusion GUI	https://nmkd.itch.io/t2i-gui	集成
Stable Diffusion WebUI	https://github.com/AUTOMATIC1111/stable-diffusion-webui	集成
ChaiNNer	https://github.com/chaiNNer-org/chaiNNer	集成
PyPI	https://pypi.org/project/codeformer/ ; https://pypi.org/project/codeformer-pip/	Python 包
ComfyUI	https://stable-diffusion-art.com/codeformer/	集成

---

致谢

本项目基于 BasicSR。部分代码来自 Unleashing Transformers、YOLOv5-face 和 FaceXLib。我们还采用了 Real-ESRGAN 来支持背景图像增强。感谢他们的出色工作。

引用

如果我们的工作对您的研究有用，请考虑引用：

@inproceedings{zhou2022codeformer,
    author = {Zhou, Shangchen and Chan, Kelvin C.K. and Li, Chongyi and Loy, Chen Change},
    title = {Towards Robust Blind Face Restoration with Codebook Lookup TransFormer},
    booktitle = {NeurIPS},
    year = {2022}
}

联系方式

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

CodeFormer 快速上手指南

CodeFormer 是一款基于 Transformer 架构的鲁棒盲人脸修复工具（NeurIPS 2022），支持老照片修复、AI 绘画修复、人脸上色及补全等功能。

1. 环境准备

• 操作系统: Windows / macOS / Linux
• Python 版本: 3.8+
• GPU 驱动: CUDA >= 10.1
• 深度学习框架: PyTorch >= 1.7.1
• 其他依赖: ffmpeg (用于视频处理), dlib (可选，用于更精准的人脸检测)

2. 安装步骤

2.1 克隆代码库

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

2.2 创建并激活虚拟环境

conda create -n codeformer python=3.8 -y
conda activate codeformer

2.3 安装依赖包

pip3 install -r requirements.txt
python basicsr/setup.py develop
# 如需使用 dlib 进行人脸检测，请额外安装
conda install -c conda-forge dlib

2.4 下载预训练模型

运行以下脚本自动下载所需权重文件到对应目录：

# 下载基础库模型 (facelib & dlib)
python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py dlib

# 下载 CodeFormer 核心模型
python scripts/download_pretrained_models.py CodeFormer

3. 基本使用

3.1 准备测试数据

将待处理的图片放入 inputs/TestWhole 文件夹（整图）或 inputs/cropped_faces 文件夹（已裁剪对齐的人脸）。

3.2 执行推理

场景 A：整图增强（推荐）

适用于包含背景的图片，会自动识别人脸并进行修复。

python inference_codeformer.py -w 0.7 --input_path [image folder]|[image path]

• -w: 保真度权重 (0~1)。值越小画质越高，值越大越接近原图。
• 结果保存在 results 文件夹。

进阶选项：

• 增强背景：添加 --bg_upsampler realesrgan
• 放大人脸：添加 --face_upsample

场景 B：人脸修复（已裁剪/对齐）

适用于已经裁剪好的人脸图片（512x512）。

python inference_codeformer.py -w 0.5 --has_aligned --input_path [image folder]|[image path]

场景 C：视频增强

需先安装 ffmpeg (conda install -c conda-forge ffmpeg)。

python inference_codeformer.py --bg_upsampler realesrgan --face_upsample -w 1.0 --input_path [video path]

场景 D：人脸上色与补全

# 黑白照片上色
python inference_colorization.py --input_path [image folder]|[image path]

# 人脸补全（需预先用画笔涂抹遮罩区域）
python inference_inpainting.py --input_path [image folder]|[image path]

---

💡 在线体验 如果不想本地部署，可尝试官方维护的在线 Demo：

• OpenXLab (国内访问较快)
• Hugging Face
• Replicate