CodeFormer 项目完整使用指南：从安装到高级应用

CodeFormer 是一个基于 Codebook Lookup Transformer 的鲁棒盲人脸修复项目，发表在 NeurIPS 2022。该项目能够有效处理各种人脸修复任务，包括人脸修复、颜色增强、修复和背景图像增强等。

项目概述

CodeFormer 利用先进的深度学习技术，通过编码本查找变换器实现高质量的人脸修复。项目支持多种功能：

• 人脸修复：修复模糊、损坏的人脸图像
• 颜色增强：为黑白或褪色照片上色
• 人脸修复：修复被遮挡或损坏的人脸区域
• 全图像增强：提升整个图像的质量

环境安装与配置

系统要求

• Python 3.8 或更高版本
• PyTorch >= 1.7.1
• CUDA >= 10.1（推荐使用 GPU 加速）

安装步骤

1. 克隆项目仓库

git clone https://gitcode.com/gh_mirrors/co/CodeFormer
cd CodeFormer

2. 创建虚拟环境

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

3. 安装依赖包

pip install -r requirements.txt
python basicsr/setup.py develop

4. 安装 dlib（可选，用于人脸检测）

conda install -c conda-forge dlib

依赖包说明

项目主要依赖以下 Python 包：

• torch>=1.7.1：深度学习框架
• torchvision：计算机视觉库
• opencv-python：图像处理
• Pillow：图像处理
• numpy：科学计算
• scikit-image：图像处理算法
• requests：HTTP 请求库

预训练模型下载

自动下载方式

# 下载 facelib 模型
python scripts/download_pretrained_models.py facelib

# 下载 dlib 模型（可选）
python scripts/download_pretrained_models.py dlib

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

手动下载

如果自动下载失败，可以从项目发布页面手动下载预训练模型，并放置到对应的目录：

• facelib 模型：weights/facelib/
• CodeFormer 模型：weights/CodeFormer/

快速开始

准备测试数据

将测试图像放置在 inputs/whole_imgs 文件夹中，或者将裁剪对齐的人脸图像放在 inputs/cropped_faces 文件夹中。

人脸修复示例

裁剪对齐的人脸修复（512x512）

python inference_codeformer.py -w 0.5 --has_aligned --input_path inputs/cropped_faces

全图像增强

python inference_codeformer.py -w 0.7 --input_path inputs/whole_imgs

视频增强

python inference_codeformer.py --bg_upsampler realesrgan --face_upsample -w 1.0 --input_path [视频路径]

高级功能

人脸颜色化

python inference_colorization.py --input_path inputs/gray_faces

人脸修复

python inference_inpainting.py --input_path inputs/masked_faces

参数说明

保真度权重（-w 参数）

保真度权重 w 的范围为 [0, 1]，用于平衡修复质量和保真度：

• 较小的 w（如 0.5）：产生更高质量的修复结果
• 较大的 w（如 0.7）：产生更高保真度的结果

其他重要参数

• --bg_upsampler realesrgan：使用 Real-ESRGAN 增强背景区域
• --face_upsample：对修复后的人脸进行进一步上采样
• --input_path：输入图像或视频路径

训练自定义模型

数据集准备

项目支持使用自定义数据集进行训练。详细的数据集准备和训练流程请参考官方训练文档：

• 英文训练文档
• 中文训练文档

训练命令示例

# 训练阶段1：VQGAN
python basicsr/train.py -opt options/VQGAN_512_ds32_nearest_stage1.yml

# 训练阶段2：CodeFormer
python basicsr/train.py -opt options/CodeFormer_stage2.yml

# 训练阶段3：联合训练
python basicsr/train.py -opt options/CodeFormer_stage3.yml

常见问题解决

环境配置问题

问题： 依赖包安装失败 解决： 确保 Python 版本为 3.8+，尝试使用 conda 创建干净的虚拟环境

问题： CUDA 版本不兼容 解决： 安装与 CUDA 版本匹配的 PyTorch，或使用 CPU 版本

模型下载问题

问题： 自动下载失败 解决： 手动下载预训练模型并放置到正确目录

人脸检测问题

问题： dlib 检测不准确 解决： 尝试使用其他检测器或调整检测参数

性能优化建议

1. 使用 GPU 加速：确保安装正确版本的 CUDA 和 PyTorch
2. 批量处理：对于大量图像，建议使用脚本批量处理
3. 内存优化：调整图像大小和批量大小以优化内存使用

应用场景

CodeFormer 在多个场景中都有出色表现：

1. 历史照片修复：修复老照片中模糊或损坏的人脸
2. 影视制作：提升低分辨率视频中的人脸质量
3. 安全监控：增强监控视频中的人脸清晰度
4. 艺术创作：修复 AI 生成图像中的人脸缺陷

技术特点

• 鲁棒性：能够处理各种退化情况的人脸图像
• 高质量：生成的人脸修复结果自然且细节丰富
• 灵活性：支持多种修复模式和参数调整
• 易用性：提供简单的命令行接口和预训练模型

通过本指南，您可以快速上手 CodeFormer 项目，体验先进的人脸修复技术。无论是修复老照片还是提升图像质量，CodeFormer 都能提供出色的效果。