ComfyUI-PhotoDeblur：HI-Diff / MISCFilter 照片去模糊节点，分块处理、支持 TTA，修复手抖运动模糊

11 0

ComfyUI-PhotoDeblur 是一款专为 ComfyUI 环境设计的照片去模糊自定义节点。该工具原生集成了 HI-Diff 和 MISCFilter 两种去模糊模型，支持原尺寸分块处理、重叠融合、可选的测试时增强（TTA）以及官方权重的自动化下载。其主要目标是改善照片中的手抖和运动模糊，建议在后期调色或裁剪前作为预处理步骤介入工作流。

GitHub：https://github.com/porfeng/ComfyUI-PhotoDeblur
网盘：https://pan.quark.cn/s/24c22fc7832e

ComfyUI-PhotoDeblur：HI-Diff / MISCFilter 照片去模糊节点，分块处理、支持 TTA，修复手抖运动模糊

适用场景与工程边界

该节点在处理特定类型的模糊时表现优异，但需明确其技术边界，以管理输出预期。

推荐应用场景：

夜景与室内手持照片：重点改善招牌、窗框、家具等结构边缘的拖影。
建筑与街景：修复线条、文字轮廓及重复纹理的模糊。
人像与活动照片：恢复轻中度抖动造成的五官、发丝和衣物边缘细节。
动物与运动主体：消除主体上的运动拖影（需与原本清晰的区域对比观察）。
高像素照片：利用分块处理机制保持原始分辨率，处理后再进行裁剪或缩图。

技术局限性说明：

难以恢复的细节：光学失焦、饱和高光中已丢失的细节、画面中极小的人脸，通常比普通手抖更难恢复。
噪声放大风险：在噪点较多的图像中，需检查暗部是否被过度涂抹或噪声被放大。
景深与摇拍：浅景深照片中的背景模糊或摇拍效果通常是摄影意图，若仅需修复主体，建议在后期使用蒙版与原图进行混合，而非全局应用去模糊。

环境配置与安装部署（核心重点）

正确的环境配置是节点正常运行的前提。请严格按照以下步骤在 ComfyUI 环境中部署依赖。

1. 克隆仓库

在 ComfyUI 的 custom_nodes 目录下执行以下命令：

cd ComfyUI/custom_nodes
git clone https://github.com/porfeng/ComfyUI-PhotoDeblur.git

2. 安装基础依赖

进入节点目录，使用 ComfyUI 实际运行的 Python 环境安装基础依赖：

cd ComfyUI-PhotoDeblur
python -m pip install -r requirements.txt
python -m pip install -r requirements-download.txt

3. 安装可选扩展依赖

MISCFilter 模型支持（需 NVIDIA / CUDA 12 环境）：
```
python -m pip install -r requirements-misc-cu12.txt
```
色调修正功能支持（依赖 OpenCV）：
若运行提示缺少 cv2 模块，请执行：
```
python -m pip install -r requirements-tone.txt
```

环境适配说明：

Windows 便携版：请将上述命令中的 python 替换为便携版自带的 python_embeded/python.exe 绝对路径。
Desktop 桌面版：请确保激活并使用其虚拟环境中的 Python 解释器。
安装完成后，必须重启 ComfyUI 服务以使节点生效。

工作流配置与参数调优

1. 节点连接逻辑

将 example_workflows/ComfyUI-PhotoDeblur.json 拖入画布后，标准连接顺序如下：

加载图像 节点输出 → 连接至 Deblur Image (Tiled) 的 image 输入。
Download Deblur Models 节点的 download_ready 输出 → 连接至 模型加载器（HI-Diff 或 MISCFilter）。
模型加载器 输出 → 连接至 Deblur Image (Tiled) 的 deblur_model 输入。
Deblur Image (Tiled) 的图像输出 → 连接至 保存图像 节点。
注：若权重已手动部署至本地，可省略或断开下载节点。

2. 核心参数配置建议

variant（模型变体）：建议优先使用 RealBlur_J，随后对比 RealBlur_R 和 GoPro 以观察局部细节差异。
tile_size（分块尺寸）：起始建议设为 768。若显存不足，可降至 512。
overlap（重叠像素）：必须小于分块尺寸。建议 768 分块配 96 重叠，512 分块配 64 重叠。
blend（融合算法）：默认 comfy_linear，亦可选 cosine、gaussian 或 average。
tta（测试时增强）：默认关闭。开启后，系统会进行 8 种翻转与旋转推理并取平均值。这会显著提升细节质量，但模型计算量将增加约 8 倍，适合另存一版进行质量对比。
steps（采样步数）：仅 HI-Diff 模型使用。建议初始设为 0，系统将自动选择 J/R 版本的 16 步或 GoPro 版本的 8 步。MISCFilter 为单次网络前向恢复，无需设置采样步数。
seed（随机种子）：默认 100，用于控制 HI-Diff 的随机先验。
sigma（色调修正）：仅在使用 Match Input Tone 节点时生效。建议设为 16，设为 0 则关闭该功能。

模型权重管理与部署

系统支持自动下载与手动部署两种权重管理方式。模型提供 RealBlur_J、RealBlur_R（R 代表权重版本，非相机 RAW 格式）和 GoPro 三种训练变体。

方式 A：自动化下载（推荐）

在工作流中使用 Download Deblur Models 节点。该节点会从官方 Google Drive 资源下载并校验 SHA256。若本地已存在且校验通过，则直接复用。权重将自动保存至 ComfyUI 配置的 models 目录下。

方式 B：手动下载与部署

若网络受限，可从 HI-Diff 或 MISCFilter 官方仓库手动下载压缩包，并按以下严格目录结构解压（避免多套一层解压目录）：

ComfyUI/models/
├── HI-Diff/
│   ├── HI_Diff_RealBlur_J/  # 需包含 net_g.pth, net_le_dm.pth, net_d.pth
│   ├── HI_Diff_RealBlur_R/  # 需包含上述三个同名文件
│   └── HI_Diff_GoPro/       # 需包含上述三个同名文件
└── MISCFilter/
    ├── RealBlur_J.pth
    ├── RealBlur_R.pth
    └── GoPro.pth

注：MISCFilter 的三个版本权重包含在同一个 checkpoints.zip 压缩包中，解压后需按文件名分别放置。手动安装后，可在模型加载器中直接选择对应版本并运行，无需连接下载节点。

精度控制与常见问题排查

1. 精度与色彩管理

推理精度：模型推理与分块融合均在 FP32 精度下进行，接收 RGB/RGBA 图像并保持原始尺寸，输出值域为 0～1。
输入规范：建议使用普通显示用的 sRGB 图像。若处理 RAW 照片，请先在专业软件中完成基础显影，导出为 sRGB 格式的 TIFF 或 PNG 后再输入本节点。后续调色可保存为 16 位 PNG。
16 位输出：普通“保存图像”节点输出 8 位 PNG。若需保留更高动态范围，请使用“保存图像（高级）”节点，选择 PNG → 16-bit → sRGB。若 TIFF 缩略图显示空白，可连接“预览图像”节点进行校验。
色调修正原理：该可选后处理通过从恢复图中减去经过高斯模糊的“恢复图与原图之差”，以约束大范围的颜色偏移，保持原图色调一致性。

2. 常见故障排查

缺少 CuPy：确保在 ComfyUI 的 Python 环境中执行了 requirements-misc-cu12.txt 的安装命令。
CUDA / NVRTC 报错：检查已安装的 CuPy 版本是否与系统 CUDA 版本匹配，并确认 CUDA_PATH 环境变量及 CUDA Toolkit 配置正确。
缺少权重文件：检查 ComfyUI/models 目录下的文件层级是否正确，或直接使用工作流中的下载节点自动获取。
显存不足 (OOM)：优先尝试将 tile_size 降至 512，overlap 降至 64，并确保 tta 参数处于关闭状态。