waifu2x 实战指南：基于 Torch7 的动漫风格图像超分辨率与降噪完整教程

• 计算机视觉
• 深度学习

waifu2x 是一个使用深度卷积神经网络（DCNN）对动漫风格插画进行图像超分辨率放大的开源项目，同时支持照片处理。本指南将带你从零搭建其命令行环境，掌握降噪、2x 放大、批量转换与视频处理等完整工作流，并深入讲解如何基于仓库源码训练属于自己的定制模型。读完本文，你将能够在本仓库（Torch7 版本）上完成从环境安装、日常图像处理到自定义模型训练的端到端实操。

项目概览与技术背景

waifu2x 的核心定位是Image Super-Resolution for Anime-style Art——针对动漫插画这类线条清晰、色块分明的图像，利用深度卷积神经网络实现高质量的 2x 放大，同时降低 JPEG 压缩带来的噪声。该项目受 SRCNN（Image Super-Resolution Using Deep Convolutional Networks）启发，其训练与推理管线全部基于 Torch7 实现。

需要特别说明的是：根据仓库 README.md 的说明，waifu2x 的开发工作已于2023 年 2 月迁移至 nunif（PyTorch 版本）仓库，本仓库保留的是经典的 Torch7 实现，对于希望了解早期深度学习超分辨率实现、或在旧环境中复现训练流程的读者仍有重要参考价值。

仓库目录结构概览：

• waifu2x.lua：命令行推理入口
• web.lua：Web 服务入口（turbo 异步 HTTP 框架）
• train.lua：模型训练入口
• convert_data.lua：训练数据预处理（压缩为 images.t7）
• install_lua_modules.sh：一键安装 Lua 依赖
• lib/：核心库（w2nn、reconstruct、iproc、image_loader、settings 等）
• appendix/：预训练模型的训练脚本与部署配置文件
• images/：效果展示与训练测试图片

环境依赖与安装

硬件与平台要求

• 硬件：NVIDIA GPU（CUDA 加速是必须的，代码在启动时会强制加载cutorch/cunn，见 lib/w2nn.lua 中的load_cunn逻辑）
• 平台：Torch7 + NVIDIA CUDA 工具链

LuaRocks 依赖包

除 Torch7 默认包外，还需要以下 LuaRocks 包：

系统层面还需要libsnappy-dev、libgraphicsmagick1-dev（需链接 little-cms2 的 GraphicsMagick，macOS/Homebrew 用户需额外处理）、libssl1.0-dev（Web 服务使用）。

安装步骤（以 Ubuntu 16.04 为例）

1. 安装 CUDA

下载 CUDA 发行包后执行：

sudo dpkg -i cuda-repo-ubuntu1404_7.5-18_amd64.deb sudo apt-get update sudo apt-get install cuda

不同 CUDA 版本（8.x/9.x/10.x）对应不同的 Torch7 兼容处理方式，请以实际安装版本为准。

2. 安装系统依赖包

sudo apt-get install libsnappy-dev sudo apt-get install libgraphicsmagick1-dev sudo apt-get install libssl1.0-dev # for web server

3. 安装 Torch7

按照 Torch 官方入门指南完成 Torch7 安装。

4. 获取 waifu2x 并安装 Lua 模块

git clone --depth 1 https://github.com/nagadomi/waifu2x.git cd waifu2x ./install_lua_modules.sh

install_lua_modules.sh 会依次安装 graphicsmagick、lua-csnappy、md5、uuid、csvigo、turbo，并额外从 cudnn.torch 仓库的R7分支编译安装 cuDNN 绑定（luarocks make cudnn-scm-1.rockspec）。

5. 验证安装

th waifu2x.lua

如果环境正确，程序会使用默认参数对images/miku_small.png执行处理并输出结果文件。

命令行工具：核心参数与四种处理模式

命令行入口是 waifu2x.lua，通过torch.CmdLine解析参数（见 waifu2x.lua 中waifu2x()函数的完整选项定义）。完整参数可通过th waifu2x.lua -h查看，核心参数如下：

从 waifu2x.lua 源码可以看出，四种模式分别加载不同命名的模型文件（model_dir下）：

• 降噪：noise%d_model.t7（%d 为 noise_level）
• 放大：scale%.1fx_model.t7（如 scale2.0x_model.t7）
• 降噪+放大：优先加载融合模型noise%d_scale%.1fx_model.t7；若不存在则依次加载独立的降噪模型与放大模型串联执行
• 用户模型：%s_model.t7（%s 为-name指定的模型名）

降噪（Noise Reduction）

th waifu2x.lua -m noise -noise_level 1 -i input_image.png -o output_image.png

不同噪声等级 0～3 分别对应不同强度（等级 0 即轻微处理，等级 3 针对重度压缩噪声）：

th waifu2x.lua -m noise -noise_level 0 -i input_image.png -o output_image.png th waifu2x.lua -m noise -noise_level 2 -i input_image.png -o output_image.png th waifu2x.lua -m noise -noise_level 3 -i input_image.png -o output_image.png

2x 放大（Upscaling）

th waifu2x.lua -m scale -i input_image.png -o output_image.png

放大倍率通过-scale 2控制（默认即为 2x）。

降噪 + 2x 放大（Noise Reduction + Upscaling）

th waifu2x.lua -m noise_scale -noise_level 1 -i input_image.png -o output_image.png

同样支持 0～3 四个噪声等级：

th waifu2x.lua -m noise_scale -noise_level 0 -i input_image.png -o output_image.png th waifu2x.lua -m noise_scale -noise_level 2 -i input_image.png -o output_image.png th waifu2x.lua -m noise_scale -noise_level 3 -i input_image.png -o output_image.png

输出文件命名规则（%s 与 %d）

批量模式下输出路径支持两种占位符（实现见 waifu2x.lua 的format_output函数）：

• %s：替换为源文件名（不含扩展名）
• %d：替换为序号，支持宽度格式如%06d

例如输入文件为piyo.png时，%s_%03d.png会被替换为piyo_001.png。若未指定-o，默认输出到源文件同目录，命名为源文件名_处理模式.png。

批量转换与断点续传

将待处理图片列表写入文本文件，配合-l参数批量处理：

find /path/to/imagedir -name "*.png" -o -name "*.jpg" > image_list.txt th waifu2x.lua -m scale -l ./image_list.txt -o /path/to/outputdir/prefix_%d.png

批量处理的内部逻辑在 waifu2x.lua 的convert_frames函数中：程序会一次性读取列表全部路径，逐张加载、处理、保存，并通过xlua.progress输出进度。两个实用技巧：

• 断点续传：加上-resume 1会跳过已经存在的输出文件，适合长时间任务中断后恢复；
• 内存回收：源码中每处理 10 张图片调用一次collectgarbage()释放内存，但超大图片仍建议配合-crop_size使用（例如-crop_size 128）避免显存溢出。

cuDNN 加速与显存控制

如果你安装了 cuDNN 库，可添加-force_cudnn 1选项切换 cuDNN 后端。cuDNN 内核比默认内核快得多。从 waifu2x.lua 源码可见，开启后还会自动设置cudnn.fastest = true，并在批量模式下启用cudnn.benchmark = true自动寻找最快算法。模型加载时通过 lib/w2nn.lua 的w2nn.load_model调用cudnn.convert将普通 cunn 模型转换为 cuDNN 模型。

若遇到 GPU 显存不足（out of memory），使用-crop_size选项缩小每次处理的图像块（例如-crop_size 128），以时间换显存。

使用 Photo 模型处理照片

waifu2x 不仅支持动漫插画，也支持照片。默认model_dir为models/cunet/art（动漫模型），切换到照片模型只需指定模型目录：

th waifu2x.lua -model_dir models/photo -m scale -i input_image.png -o output_image.png

photo 模型目录对应仓库中的models/upconv_7/photo（见 web.lua 中PHOTO_MODEL_DIR的定义）。

Web 应用

waifu2x 附带一个基于 turbo 异步框架的 Web 演示服务：

th web.lua

启动后访问http://localhost:8812/即可使用网页版处理界面（网页资源见 assets/，多语言页面模板见 webgen/templates/index.html.erb）。

web.lua 作为waifu2x-api服务，还提供了以下可调参数：

视频处理工作流

利用批量模式可以轻松实现整段视频的逐帧超分/降噪。以下示例以avconv（Ubuntu 14.04 上avconv即ffmpeg的别名）演示从 00:09:00 到 00:12:00 的 3 分钟片段处理：

1. 抽取帧与音频

mkdir frames avconv -i data/raw.avi -ss 00:09:00 -t 00:03:00 -r 24 -f image2 frames/%06d.png avconv -i data/raw.avi -ss 00:09:00 -t 00:03:00 audio.mp3

2. 生成帧列表

find ./frames -name "*.png" |sort > data/frame.txt

3. waifu2x 批量降噪（带断点续传）

mkdir new_frames th waifu2x.lua -m noise -noise_level 1 -resume 1 -l data/frame.txt -o new_frames/%d.png

4. 合成视频

avconv -f image2 -framerate 24 -i new_frames/%d.png -i audio.mp3 -r 24 -vcodec libx264 -crf 16 video.mp4

训练自定义模型

训练入口是 train.lua，全部训练参数定义在 lib/settings.lua 中（可通过th train.lua -h查看）。核心参数如下：

此外还内置了丰富的数据增强选项：-random_color_noise_rate（颜色噪声）、-random_overlay_rate（翻转折叠）、-random_half_rate（半分辨率）、-random_unsharp_mask_rate（反锐化掩模）、-random_blur_rate（高斯模糊，配合-random_blur_size/-random_blur_sigma_min/-random_blur_sigma_max）、-nr_rate（降噪与保细节的权衡，0.0～1.0）等，这些增强由 lib/pairwise_transform.lua 系列模块在训练线程池中实现（见 train.lua 的transform_pool_init）。

数据准备

首先生成无噪声训练图像的列表（README 中提到作者使用约 6000 张高清无噪声 PNG 训练）：

find /path/to/image/dir -name "*.png" > data/image_list.txt

然后执行 convert_data.lua 将原始图像转换为训练用的images.t7（内部使用 Snappy 压缩存储，并支持-max_training_image_size对大图随机裁剪）：

th convert_data.lua

训练降噪（level1）模型

mkdir models/my_model th train.lua -model_dir models/my_model -method noise -noise_level 1 -test images/miku_noisy.png # 使用训练出的模型 th waifu2x.lua -model_dir models/my_model -m noise -noise_level 1 -i images/miku_noisy.png -o output.png

训练过程中会持续用-test指定的测试图验证效果，最终模型保存在models/my_model/noise1_best.png（最佳模型对应noise1_model.t7）。

训练降噪（level2）模型

th train.lua -model_dir models/my_model -method noise -noise_level 2 -test images/miku_noisy.png # 使用 th waifu2x.lua -model_dir models/my_model -m noise -noise_level 2 -i images/miku_noisy.png -o output.png

最佳效果图保存在models/my_model/noise2_best.png。

训练 2x 放大模型

th train.lua -model upconv_7 -model_dir models/my_model -method scale -scale 2 -test images/miku_small.png # 使用 th waifu2x.lua -model_dir models/my_model -m scale -scale 2 -i images/miku_small.png -o output.png

最佳效果图保存在models/my_model/scale2.0x_best.png。

训练 2x 放大 + 降噪融合模型

th train.lua -model upconv_7 -model_dir models/my_model -method noise_scale -scale 2 -noise_level 1 -test images/miku_small.png # 使用 th waifu2x.lua -model_dir models/my_model -m noise_scale -scale 2 -noise_level 1 -i images/miku_small.png -o output.png

最佳效果图保存在models/my_model/noise1_scale2.0x_best.png。

模型文件命名规则（见 lib/settings.lua）：noise%d_model.t7、scale%.1fx_model.t7、noise%d_scale%.1fx_model.t7，这些命名与推理端 waifu2x.lua 的模型查找逻辑一一对应。训练时若使用 cuDNN 后端（-backend cudnn），训练出的模型是 cudnn 格式，可通过 tools/rebuild.lua 类工具转换回通用 cunn 格式。

复现官方预训练模型

官方预训练模型的实际训练命令收录在 appendix/train_upconv_7_art.sh 与 appendix/train_upconv_7_photo.sh 中，可作为训练参数参考。以动漫版为例，其关键流程为：

# 数据预处理：限制训练图像尺寸不超过 1600 th convert_data.lua -max_training_image_size 1600 # 先训练 2x 放大模型（downsampling_filters 使用 Box,Sinc，保存全部历史模型便于人工挑选） th train.lua -save_history 1 -scale 2 -model upconv_7 -method scale \ -model_dir models/test/upconv_7_rev5 -downsampling_filters "Box,Sinc" \ -test query/pixel-art-small.png -backend cudnn -thread 4 -oracle_rate 0.0 \ -inner_epoch 2 -epoch 100 # 再以放大模型为起点微调 noise_scale 融合模型（-resume 加载已有权重） th train.lua -save_history 1 -model upconv_7 -method noise_scale -noise_level 1 \ -model_dir models/test/upconv_7_rev6 -downsampling_filters "Box,Sinc" \ -test query/noise_test.jpg -backend cudnn -thread 4 \ -resume models/test/upconv_7_rev5/scale2.0x_model.t7 -style art

降噪模型（-method noise）则使用vgg_7结构、-crop_size 32训练，等级 3 时配合-nr_rate 1强化去噪。从脚本注释可以看出，作者会通过-save_history 1保留全部 epoch 的历史模型，再通过肉眼观察 mesh 伪影等视觉质量来挑选最优 checkpoint。

Docker 部署

仓库提供了 Dockerfile，基于nagadomi/torch7:cuda10.1-cudnn7-devel-ubuntu18.04基础镜像构建，内置了全部 Lua 依赖。使用 Docker 需要先安装 nvidia-docker（注意：README 与 Dockerfile 面向的是较旧的nvidia-docker/--gpus all语法，请以实际 Docker 版本为准）。

构建并运行：

docker build -t waifu2x . docker run --gpus all -p 8812:8812 waifu2x th web.lua docker run --gpus all -v `pwd`/images:/images waifu2x th waifu2x.lua -force_cudnn 1 -m scale -scale 2 -i /images/miku_small.png -o /images/output.png

重要注意事项——CUDA JIT 缓存：在 Docker 中运行 waifu2x 时，若没有启用 CUDA JIT 缓存（fat binary 编译缓存），首次运行会非常慢。解决方法是将宿主机的缓存目录挂载进容器，例如：

docker run --gpus all -v $PWD/ComputeCache:/root/.nv/ComputeCache waifu2x th waifu2x.lua --help

源码导读：从加载到重建的内部原理

理解推理主流程有助于更好地调参。以 waifu2x.lua 的convert_image函数为例，单图处理链为：

1. 图像加载：image_loader.load_float读取图像并解析元数据（含透明通道 alpha）；
2. 模型加载：w2nn.load_model(model_path, opt.force_cudnn, opt.load_mode)加载.t7模型，若force_cudnn为真则执行cudnn.convert转换为 cuDNN 格式，最后model:cuda():evaluate()切换到 GPU 推理模式（见 lib/w2nn.lua）；
3. 边界处理：放大前用alpha_util.make_border扩充边界，补偿卷积网络的感受野偏移；
4. 分块重建：reconstruct.scale/reconstruct.image按-crop_size分块前向推理；开启-tta 1时改用reconstruct.scale_tta/image_tta，对 8 个方向（-tta_level 8）的变换结果取平均，换取更高质量；
5. Alpha 合成：alpha_util.composite将处理结果与原始透明通道重新合成；
6. 保存输出：image_loader.save_png按-depth（8/16 位）写出 PNG。

训练侧的 lib/reconstruct.lua、lib/srcnn.lua 与 lib/ 下的一系列自定义 Criterion（如 ClippedWeightedHuberCriterion、SSIMCriterion、L1Criterion）和网络模块（LeakyReLU、ShakeShakeTable、RandomBinaryConvolution 等）共同支撑了训练管线；这些模块在w2nn加载时统一注册，因此train.lua与waifu2x.lua都能复用。

结语

本文完整覆盖了 waifu2x（Torch7 版）从环境搭建、命令行推理、Web 服务、视频处理到自定义模型训练与 Docker 部署的实战全流程，并给出了 waifu2x.lua、lib/settings.lua、appendix/train_upconv_7_art.sh 等关键源码与配置的对照关系。无论是快速上手图像增强，还是基于 train.lua 训练自己的动漫/照片超分模型，本文中的命令与参数均可直接复制运行。若需最新特性，可关注其 PyTorch 继任项目 nunif。

• 计算机视觉
• 深度学习