RealESRGAN 命令行工具

这是一个功能强大的 RealESRGAN 命令行工具，支持递归目录搜索、多并发处理、覆盖原图片保存等高级功能。

特别注意 需要下载 Real-ESRGAN 打包好的可执行文件，解压和脚本放到同一级目录。

功能特性

• ✅ 递归目录搜索: 自动搜索指定目录及其所有子目录中的图像文件
• ✅ 多并发处理: 支持多线程并发处理，大幅提升处理速度
• ✅ 覆盖原图片: 可选择覆盖原图片文件，保持原文件名和位置
• ✅ 灵活输出: 支持指定输出目录，保持目录结构
• ✅ 配置管理: 支持保存和管理常用配置
• ✅ 多种模型: 支持所有 RealESRGAN 模型
• ✅ 多种格式: 支持 JPG、PNG、WebP 等多种输出格式
• ✅ 进度显示: 实时显示处理进度和统计信息
• ✅ 错误处理: 完善的错误处理和日志记录

安装要求

• Python 3.6 或更高版本
• RealESRGAN 可执行文件 (realesrgan-ncnn-vulkan.exe)

快速开始

Windows 用户

1. 双击 cli_tool.bat 查看使用说明
2. 或者在命令行中使用：

# 递归处理目录中的所有图像
cli_tool.bat -i "C:\Images" -r

# 指定输出目录
cli_tool.bat -i "C:\Images" -o "C:\Output"

# 覆盖原图像文件
cli_tool.bat -i "C:\Images" --overwrite

直接使用 Python

# 查看帮助
python cli_tool.py --help

# 递归处理目录
python cli_tool.py -i /path/to/images -r

# 使用8个并发线程
python cli_tool.py -i /path/to/images -j 8

详细用法

基本参数

参数	长参数	说明
-i	--input	输入图像文件或目录路径（必需）
-o	--output	输出目录路径（可选）
-r	--recursive	递归搜索子目录中的图像文件
	--overwrite	覆盖原图像文件

处理参数

参数	长参数	可选值	说明
-m	--model	realesr-animevideov3, realesrgan-x4plus, realesrgan-x4plus-anime	使用的模型名称
-s	--scale	2, 3, 4	缩放比例
-f	--format	jpg, png, webp	输出图像格式
-x	--tta	-	启用TTA模式（提高质量但速度较慢）
-j	--jobs	数字	并发处理的线程数

配置管理

参数	说明
--config	显示当前配置
--set-config KEY VALUE	设置配置项

使用示例

1. 基本用法

# 处理单个图像文件
python cli_tool.py -i image.jpg

# 处理目录中的图像（非递归）
python cli_tool.py -i /path/to/images

# 递归处理目录及子目录
python cli_tool.py -i /path/to/images -r

2. 指定输出

# 指定输出目录
python cli_tool.py -i /path/to/images -o /path/to/output -r

# 覆盖原文件（保持原位置和文件名）
python cli_tool.py -i /path/to/images --overwrite -r

3. 自定义处理参数

# 使用特定模型和缩放比例
python cli_tool.py -i /path/to/images -m realesrgan-x4plus -s 2 -r

# 指定输出格式
python cli_tool.py -i /path/to/images -f jpg -r

# 启用TTA模式（更高质量）
python cli_tool.py -i /path/to/images -x -r

4. 并发处理

# 使用8个线程并发处理
python cli_tool.py -i /path/to/images -j 8 -r

# 使用16个线程（适合高性能机器）
python cli_tool.py -i /path/to/images -j 16 -r

5. 配置管理

# 查看当前配置
python cli_tool.py --config

# 设置默认模型
python cli_tool.py --set-config default_model realesrgan-x4plus

# 设置默认并发数
python cli_tool.py --set-config max_workers 8

# 设置RealESRGAN可执行文件路径
python cli_tool.py --set-config realesrgan_path "/path/to/realesrgan-ncnn-vulkan.exe"

配置选项

工具会自动创建 cli_config.json 配置文件，支持以下配置项：

配置项	类型	默认值	说明
realesrgan_path	字符串	""	RealESRGAN可执行文件路径
default_model	字符串	"realesr-animevideov3"	默认使用的模型
default_scale	整数	4	默认缩放比例
default_format	字符串	"png"	默认输出格式
max_workers	整数	4	默认最大并发数
overwrite_original	布尔	false	默认是否覆盖原文件
recursive	布尔	true	默认是否递归搜索
tta_mode	布尔	false	默认是否启用TTA模式

支持的图像格式

输入格式: .jpg, .jpeg, .png, .webp, .bmp, .tiff, .tif

输出格式: jpg, png, webp

可执行文件检测顺序

工具会按以下优先级自动检测 RealESRGAN 可执行文件：

1. 环境变量 REALESRGAN_PATH
2. 系统 PATH 中的 realesrgan-ncnn-vulkan.exe
3. 用户配置 中设置的路径
4. 当前目录 中的 realesrgan-ncnn-vulkan.exe

性能优化建议

并发数设置

• CPU密集型: 设置为 CPU 核心数
• GPU加速: 可以设置为 CPU 核心数的 1.5-2 倍
• 内存限制: 注意监控内存使用，避免设置过高

批处理策略

# 小图像文件，高并发
python cli_tool.py -i /path/to/small_images -j 16 -r

# 大图像文件，低并发
python cli_tool.py -i /path/to/large_images -j 4 -r

# 启用TTA模式，降低并发
python cli_tool.py -i /path/to/images -j 2 -x -r

常见问题

Q: 找不到 RealESRGAN 可执行文件

A: 请确保：

1. realesrgan-ncnn-vulkan.exe 在当前目录
2. 或者在系统 PATH 中
3. 或者设置 REALESRGAN_PATH 环境变量
4. 或者使用 --set-config 设置路径

Q: 处理速度很慢

A: 尝试：

1. 增加并发数 -j 8
2. 关闭TTA模式（去掉 -x 参数）
3. 使用更快的模型（如 realesrgan-x4plus）

Q: 内存不足

A: 尝试：

1. 降低并发数 -j 2
2. 分批处理大量图像
3. 关闭其他占用内存的程序

Q: 某些图像处理失败

A: 检查：

1. 图像文件是否损坏
2. 文件路径是否包含特殊字符
3. 磁盘空间是否充足
4. 查看详细错误信息

输出示例

使用 RealESRGAN: D:\tools\realesrgan-ncnn-vulkan-20220424-windows\realesrgan-ncnn-vulkan.exe
找到 150 个图像文件
使用模型: realesr-animevideov3
缩放比例: 4x
输出格式: png
并发数: 8
覆盖原文件: 否
TTA模式: 否
--------------------------------------------------
✓ 处理完成: D:\Images\photo1.jpg -> D:\Output\photo1.png
✓ 处理完成: D:\Images\photo2.jpg -> D:\Output\photo2.png
✓ 处理完成: D:\Images\subfolder\photo3.jpg -> D:\Output\subfolder\photo3.png
...
--------------------------------------------------
处理完成!
成功: 148 个
失败: 2 个
总耗时: 5 分 23.45 秒

许可证

本工具基于原始 RealESRGAN 项目开发，遵循相同的许可证条款。

相关链接

• RealESRGAN GitHub
• RealESRGAN 论文