# sieMedia

**Repository Path**: sieding/sie-media

## Basic Information

- **Project Name**: sieMedia
- **Description**: 图像超分、修复、去噪、补帧工具集成
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-07
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sieMedia 多媒体处理工具集

图像超分、修复、去噪、补帧工具集合，统一使用自包含 Python 环境，即插即用。

## 目录

```
sieMedia\
├── run_gui.bat        唯一保留在根目录的入口
├── cli\               命令行启动器（run_*.bat）
├── core\              修复内核（ops 原子操作 / registry 注册表 / runner 工作流 / vendor 第三方网络）
├── gui\               本地网页控制台（server.py + index.html + app.js）
├── tools\             项目集成的外部工具
│   ├── ffmpeg\        ffmpeg / ffprobe（shared + GPL 构建，视频抽帧/合帧）  ← 不入库
│   ├── exec\          ncnn 可执行程序（Real-ESRGAN 超分 + RIFE 补帧）
│   ├── faceid\        人脸识别（自写编排：检测 / 对齐 / 特征 / 聚类 / 检索）
│   └── vrt\           VRT 网络定义（CC-BY-NC，只保留 models/network_vrt.py）  ← 不入库
├── scripts\           第三方适配层（gpen_run / ddcolor_run / vrt_run）
├── model_zoo\         统一权重目录  ← 不入库
├── docs\              文档
├── python-embed\      自包含 Python 3.13.15（torch 2.14.1+cu132 等）  ← 不入库
├── out\               默认输出目录  ← 不入库
├── LICENSE            AGPL-3.0 全文
└── NOTICE             第三方组件声明
```

**`tools/` 里两类东西性质不同**：

| 子目录 | 内容 | 是否入库 | 说明 |
|---|---|---|---|
| `ffmpeg/` | ffmpeg + ffprobe + DLL | ✗ | 外部二进制，`subprocess` 调用 |
| `exec/` | realesrgan / rife 的 exe + DLL | ✓ | 外部二进制，体积小、内容固定 |
| `faceid/` | 本项目自己写的人脸识别代码 | ✓ | 模型在 `model_zoo/insightface/` |
| `vrt/` | VRT 官方网络定义（CC-BY-NC） | ✗ | 只留 `models/network_vrt.py`，其余已删 |

## 仓库说明（git）

本仓库**只存代码与文档**，克隆后需要自行补齐运行时资源。

```bat
git clone <repo-url> sieMedia
cd sieMedia
:: 按下表补齐目录 → 双击 run_gui.bat
```

### 入库内容

约 230 个文件 / 5.8 MB：`gui/` `cli/` `core/` `tools/faceid/` `scripts/` `docs/`、`core/vendor/` 下的第三方网络定义、**ncnn 可执行程序**（`tools/exec/` 下的 exe + DLL）、**GPEN 预编译 CUDA 扩展**（`fused.pyd` / `upfirdn2d.pyd`）、`README.md` `LICENSE` `NOTICE`。

### 克隆后必须补齐

| 目录 | 体积 | 说明 |
|---|---|---|
| `python-embed/` | 3.4 GB | 自包含 Python 3.13.15 + torch cu132（见下节「环境」） |
| `tools/ffmpeg/` | 123 MB | Windows **shared + GPL** 构建（须含 `libx264`），`ffmpeg.exe` / `ffprobe.exe` + 10 个 DLL。仅视频任务需要 |
| `model_zoo/` | 3.7 GB | **统一权重目录**，按来源分五个子目录，见下表 |
| `tools/vrt/` | 约 90 KB | **VRT 网络定义**（`models/network_vrt.py`），CC-BY-NC，不入库。只保留推理需要的这一个文件，其余（utils / testsets / .git 等）已删 |

VRT 网络定义的获取方式（只取需要的两个文件，在项目根目录执行）：

```bat
git clone --depth 1 https://github.com/JingyunLiang/VRT tools/vrt-tmp
move tools\vrt-tmp\models\network_vrt.py tools\vrt\models\
move tools\vrt-tmp\LICENSE tools\vrt\
rmdir /s /q tools\vrt-tmp
```


模型权重统一放在 `model_zoo/` 下，按来源分目录：

| 子目录 | 体积 | 内容 |
|---|---|---|
| `model_zoo/kair/` | 1.9 GB | SwinIR 9（彩色去噪 3 + 真实超分 2 + 去伪影 4）、DnCNN 3、FFDNet 4、DRUNet 4、USRNet 2、VRT 8 |
| `model_zoo/gpen/` | 375 MB | `GPEN-512.pth`、`RetinaFace-R50.pth` |
| `model_zoo/ddcolor/` | 870 MB | `ddcolor_modelscope.pth` |
| `model_zoo/realesrgan/models/` | 44 MB | `realesrgan-x4plus` 等 5 个 ncnn 模型（`.param` + `.bin`） |
| `model_zoo/rife/` | 77 MB | `rife-v4.6`、`rife-v4`、`rife-anime` 三个模型目录 |
| `model_zoo/scunet/` | 343 MB | 5 个彩色权重（真实噪声 ×2 + 高斯 σ=15/25/50） |
| `model_zoo/codeformer/` | 900 MB | `codeformer.pth` + `codeformer_colorization.pth` + facelib 的检测 / 解析权重 |
| `model_zoo/rmbg/` | 844 MB | `model.safetensors`（RMBG-2.0，移除背景用，CC BY-NC） |
| `model_zoo/birefnet/` | 424 MB | `model.safetensors`（BiRefNet 原版，MIT 可商用，**未接入代码**，见 [权重文档](docs/模型权重使用参考.md) 6.4） |
| `model_zoo/restormer/` | 700 MB | 7 个 `.pth`：去雨 / 运动去模糊 / 散焦去模糊 / 高斯降噪（彩+灰）/ 真实降噪 / 双像素散焦 |

`model_zoo/realesrgan/` 下面多一层 `models/` 是**上游 exe 的硬性要求**——
`realesrgan-ncnn-vulkan` 靠路径里是否含 `models` 子串来判断模型类型，
不含就报 `unknown model dir type`。

目录名保持原样放回即可，脚本全部用 `__file__` 相对定位，不依赖绝对路径。

### 按功能的最小依赖

不必一次性补齐全部，按要做的事取：

| 要做的事 | 需要补齐 |
|---|---|
| 启动 GUI / 用 CLI | `python-embed/`（其余按需） |
| 人像修复（GPEN） | + `model_zoo/gpen/`（op 扩展已入库） |
| 上色修复 | + `model_zoo/ddcolor/` |
| 超分放大 / 视频超分 | + `model_zoo/realesrgan/` |
| 去噪 / SwinIR 超分 | + `model_zoo/kair/` |
| 真实噪声去噪（SCUNet） | + `model_zoo/scunet/` |
| CodeFormer 人脸修复 / 人脸上色 | + `model_zoo/codeformer/` |
| 移除背景（RMBG-2.0） | + `model_zoo/rmbg/`（权重为 CC BY-NC 4.0，**仅限非商业用途**；需要商用授权用 `model_zoo/birefnet/`，MIT） |
| 去雨 / 去模糊 / Restormer 降噪 | + `model_zoo/restormer/` |
| 视频补帧 | + `model_zoo/rife/` |
| VRT 视频复原 | + `model_zoo/kair/`（VRT 权重）+ `tools/vrt/models/network_vrt.py` |
| 任何视频任务 | + `tools/ffmpeg/`（须为 shared + GPL 构建，否则合帧时缺 `libx264`） |
| 输出尺寸 / 格式转换 | 无额外依赖（cv2 即可） |

### 可选，不补齐也能跑

| 路径 | 说明 |
|---|---|
| `out/` | 输出目录，首次运行自动创建 |
| `realesrgan/*.jpg` `*.mp4` | ncnn 官方示例素材 |

### 补齐后验证

```bat
:: 1. 环境与 CUDA
python-embed\python.exe -c "import torch; print(torch.__version__, torch.cuda.is_available())"
:: 期望：2.14.1+cu132 True

:: 2. 模型文件是否到位
dir model_zoo\gpen\GPEN-512.pth
dir model_zoo\ddcolor\ddcolor_modelscope.pth

:: 3. 跑通一次最小流程
cli\run_gpen.bat --image 任意照片.jpg --output out
:: 期望：out\<原名>_gpen.png
```

全部通过后，`run_gui.bat` 打开控制台即可使用。

## 环境

`python-embed\` 是基于 **Python 3.13.15 embeddable** 改造的自包含环境，不依赖任何系统 Python。

| 包 | 版本 |
|---|---|
| Python | 3.13.15 |
| torch | 2.14.1+cu132 |
| torchvision | 0.29.1+cu132 |
| numpy | 2.5.3 |
| opencv-python | 5.0.0.93 |
| scikit-image | 0.26.0 |
| scipy | 1.18.1 |
| matplotlib | 3.11.2 |
| pillow | 12.3.0 |
| safetensors | 0.8.0 |

验证：

```bat
python-embed\python.exe -c "import torch; print(torch.__version__, torch.cuda.is_available())"
```

> **不含** `transformers` / `diffusers` / `accelerate` / `modelscope` —— 2026-11-06 已清理，环境只保留推理必需依赖。`timm` 也不需要（SwinIR 已内联）。

## 图形界面（推荐入口）

```bat
run_gui.bat
```

浏览器自动打开 <http://127.0.0.1:8765/>。本地网页版：不装任何依赖、不需要联网，服务只监听 `127.0.0.1`。

**部分工具支持实时预览**（偏色校正 / 亮度对比度 / 去尘 / 补颗粒），其余工具的效果需在「结果」视图查看。

| 分组 | 工具 | 预设 |
|---|---|---|
| 图像 | **人像修复** | 仅人脸区域 / 人脸增强 + 背景锐化 / 超分精修 |
| 图像 | **上色修复** | 仅上色 / 上色 + 人脸清晰 / 上色 + 人脸清晰 + 超分放大 |
| 图像 | **模糊伪影** | JPEG 方块 / 运动模糊 / 失焦模糊 / 雨丝，四选一（选错会更差） |
| 图像 | **移除背景** | 透明 PNG（保留发丝）/ 硬边证件照 / 白·蓝·红·绿·黑底 |
| 图像 | 超分放大 | — |
| 视频 | 补帧、视频超分 | — |

**原图 / 预览 / 结果 / 并排**四种视图。载入文件即显示原图；「预览」看预处理效果（与是否已出结果无关）；处理完成后自动切到并排对比（左原图、右结果，同尺寸对齐）。

视频结果可以直接在页面里播放。

使用要点：

- 输入可以粘贴路径、点「浏览」挑目录、**Ctrl+V 贴图**，或直接把文件拖进窗口
- **支持相机 RAW**（NEF / CR2 / CR3 / ARW / DNG / RW2 / ORF / RAF 等）：粘贴路径、拖拽或浏览都行，
  服务端会把原件存到 out\_cache\_raw、转出内嵌 JPEG 到 _inbox，
  立刻能看；再点工具区的「**RAW 加载**」选择完整解码方式（可预览效果）后，输入会换成新的 PNG
- 任务进队列**串行**执行（6 GB 显存即可运行），带进度条和日志，可取消
- **点右栏已完成的任务条目**即可切换查看那次的结果对比
- GPEN / DDColor / SwinIR 模型常驻，从第二单起不用再等权重加载
- 拖拽 / 粘贴的图落在 `out\_cache\_inbox`，**关闭控制台即清空**；处理结果在 `out\`，不受影响
- 关闭控制台窗口即停止服务（显存同时释放）

> 命令行入口都在 `cli\` 下（根目录只保留 `run_gui.bat`），批量脚本化时更方便。

---

## 工具

### 1. Real-ESRGAN（免环境）

```bat
cd exec
realesrgan-ncnn-vulkan.exe -i 输入.jpg -o 输出.png -n realesrgan-x4plus -s 4 -m ..\model_zoo\realesrgan\models
```

模型：`realesrgan-x4plus`（照片）/ `realesrgan-x4plus-anime`（二次元）/ `realesr-animevideov3`（动画视频）。

### 2. RIFE（免环境）

```bat
cd exec
rife-ncnn-vulkan.exe -i 输入帧目录 -o 输出帧目录 -m ..\model_zoo\rife\rife-v4.6
```

### 3. GPEN 人脸增强（已集成）

```bat
:: 单张
cli\run_gpen.bat --image "人像.jpg" --output out --strength 0.8

:: 整个目录
cli\run_gpen.bat --image "照片目录" --output out
```

| 参数 | 说明 |
|---|---|
| `--image` | 图片或目录 |
| `--output` | 输出目录 |
| `--strength` | 0~1 增强强度，小脸建议 0.7~0.85 |
| `--threshold` | 人脸检测阈值，默认 0.9 |

输出：`<原名>_gpen.png`。

> `core\vendor\gpen\op\ext\` 里是预编译 CUDA 扩展（`fused.pyd` / `upfirdn2d.pyd`），无需编译器。

### 4. DDColor 上色（已集成）

```bat
cli\run_ddcolor.bat --image "人像.jpg" --output out --size 512 --sat 1.2
```

| 参数 | 说明 |
|---|---|
| `--image` | 图片或目录 |
| `--output` | 输出目录 |
| `--size` | 模型输入尺寸（256/512/1024），默认 512 |
| `--sat` | 饱和度倍数，默认 1.0；1.2 更鲜艳 |

输出：`<原名>_color.png`。

> 上色前建议先裁掉白边、增强对比度（CLAHE），否则模型会把主体判断错。

### 5. 自建工具（`core/ops/`）

本项目自己实现的图像处理，不依赖额外模型权重。GUI 里是工具区的各个按钮，
CLI 走 `run_workflow.bat` 的 steps 或对应的预设。

**亮度 / 对比度** —— 整体偏暗或发灰（雾感）时用，两个 -100~100 滑块：

| 调整 | 实现 | 效果 |
|---|---|---|
| 亮度 | 线性光乘增益（±1 stop） | 暗部提亮均匀，不像直接加常量那样糊成灰雾 |
| 对比度 | Rec.709 亮度上叠 `-k·sin(2πx)/2π` | 阴影更沉、高光更亮，黑白场和中性灰不动 |

按亮度比例缩放 RGB（而非逐通道曲线），**色相不变**——实测对比度 +50 时色相偏移仅 0.9/179（0.5%）。

**蒙尘与划痕** —— 去孤立灰尘点/短划痕，只动 0.02%~0.05% 像素，纹理不变。
实现在 `core/ops/dust.py`，GUI「去尘」工具，或写进工作流 `{"cap":"dust","params":{"threshold":25}}`。
`threshold`：15 强 / 25 中（默认）/ 30 弱。算法与 Photoshop「蒙尘与划痕」同构（阈值保护的中值滤波），10M 像素约 1 秒。

**完整修复链路** —— 蒙尘 → 修脸 → 超分 → 合成 → 颗粒：

```bat
cli\run_oldphoto.bat --image "照片.jpg"
```

| 预设 | 链路 |
|---|---|
| `run_oldphoto.bat` | 去尘 → 人脸 → 上色 → 超分 → 颗粒 |
| `run_portrait.bat` | 人脸 → 锐化 → 颗粒 |
| `run_workflow.bat` | 自定义 steps（可单独调 dust / face / upscale / grain 的参数） |

### 6. 人脸识别（独立工具）

按人分类海量照片 / 找出与样例同一个人。**与修复工作流完全独立**——不经过 GUI 任务队列，
不读 registry，单独一个入口。

```bat
:: 建索引（递归扫描目录，产出 face.npz）
cli\run_faceid.bat index D:\照片 --index face.npz

:: 找与样例同一个人，按相似度排序
cli\run_faceid.bat find 样例.jpg --index face.npz --top 20 --threshold 0.4

:: 按人分组，输出 groups.json（每个人一组照片路径）
cli\run_faceid.bat group --index face.npz --eps 0.4 --out groups.json
```

| 参数 | 说明 |
|---|---|
| `--device cuda` | 默认 CUDA；实测 onnxruntime-gpu 1.31 在 CUDA 13.4 上可用 |
| `--no-gender-age` | 建索引时跳过性别年龄，快约 30% |
| `--eps` | 聚类阈值，0.4 对应相似度 ≥ 0.6；分太细调小，混在一起调大 |
| `--min-samples` | 成簇最少人脸数，默认 2 |

依赖：`onnxruntime-gpu`（已装进 python-embed）+ `model_zoo/insightface/buffalo_l/`（onnx 权重，不入库）。
代码在 `tools/faceid/`（`engine.py` 检测+对齐+特征 / `index.py` 索引检索 / `cluster.py` 聚类 / `cli.py` 命令），
入口是 `cli\run_faceid.bat`。
**预训练模型仅限非商业研究用途**，见 [NOTICE](NOTICE) 第 13 条。
参数细节、实测速度、阈值建议见 [权重文档](docs/模型权重使用参考.md) 第 10 章。


## 已验证（2026-11-06）

| 测试 | 结果 |
|---|---|
| 环境 import（torch/cv2/skimage/scipy/matplotlib） | 全部 OK，CUDA True |
| KAIR SwinIR 导入（无 timm） | OK |
| KAIR DnCNN 实跑 | PSNR 30.43 dB / SSIM 0.8617，10.5 秒 |
| GPEN 实跑 | 检测到 1 张脸，输出 `<输入图>_gpen.png` |
| DDColor 实跑 | 输出 `<输入图>_color.png` |
| 清理依赖后回归 | 卸载 24 个包后 torch/CUDA 正常，GPEN、DDColor 模型构建通过，KAIR 人脸脚本 14 张图 36.4 秒跑通 |
| 图形界面 | 7 个工具端到端通过；补帧 362 帧 @47.96fps、视频超分 1280×960，音轨保留；前后对比与视频播放正常 |

## 免责声明

**本项目按「原样」提供，不附带任何明示或暗示的担保。**

使用本项目（包括其代码、文档，以及通过本项目调用的任何第三方模型与程序）所产生的一切后果，
由使用者自行承担。**作者不对因使用或无法使用本项目而产生的任何损失、损害、责任或费用承担任何责任，
包括但不限于：**

- **处理结果不正确、失真或不符合预期**——AI 修复会「脑补」细节，人脸增强可能使人物与原貌不符，
  超分/上色可能产生事实上不存在的纹理与颜色
- 数据损坏、丢失或被覆盖
- 业务中断、利润损失、商誉损害
- 因使用处理后的图像 / 视频引发的法律纠纷（肖像权、著作权、隐私权、名誉权等）
- **第三方组件**（KAIR、GPEN、DDColor、Real-ESRGAN、RIFE、ncnn、FFmpeg）的缺陷、行为或输出
- **上游模型权重**的许可问题、使用限制或由此产生的任何后果
- **任何其他因使用、误用、无法使用本项目，或依赖本项目输出而产生的直接、间接、附带、特殊、
  惩罚性或后果性损害**，无论该责任源于合同、侵权（含过失）、严格责任或其他事由，
  亦无论作者是否已被告知该等损害的可能性

**使用者有责任**（包括但不限于）：

- 确保对处理的素材拥有合法权利，或已取得权利人授权
- 不使用本工具制作虚假身份、伪造证件、伪造证据或其他违法内容
- 在商业场景中自行评估输出结果的准确性、可用性与合规性
- 遵守所在司法辖区的法律法规

本免责声明不排除或限制依适用法律不可排除或限制的责任（例如作者**自身**因故意或重大过失
造成的责任）。**为免歧义**：上述免责与责任限制适用于使用者自身的行为及其后果——使用者
违反法律法规、侵害第三方权益，或因使用、误操作、二次分发本项目而产生的任何责任，
均由使用者自行承担，与本项目作者及贡献者无关。

> 本项目采用 AGPL-3.0，其 **§15（Disclaimer of Warranty）** 与 **§16（Limitation of Liability）**
> 构成法律层面的免责与责任限制条款；本节是面向使用者的通俗说明，二者并行适用。
## 许可证

**GNU Affero General Public License v3.0**（AGPL-3.0），全文见 [LICENSE](LICENSE)。

选择 AGPL 而非 MIT / GPL 的原因很具体：本项目自带 Web 界面，很容易被部署成网站。
AGPL 第 13 条要求「通过网络向他人提供服务时必须提供源码」，正好堵住「拿去做闭源付费站」这条路。

**你可以**

- 自由使用、修改、分发
- 商用（只要遵守 AGPL：分发或提供网络服务时公开源码）
- 自建、自用、内部部署

**你必须**

- 分发时附带源码与许可证
- 修改后分发或部署成公开服务时，以 AGPL 公开修改后的源码
- 保留原作者署名

**你不可以**

- 拿去做闭源的付费服务
- 去掉许可证声明后当作自己的作品发布

### 第三方组件与权重

- 第三方组件（KAIR、RIFE、Real-ESRGAN、ncnn、GPEN、DDColor）各自保留原许可证，详见 [NOTICE](NOTICE)
- **模型权重不在本仓库内**，也不在 AGPL 覆盖范围内；权重遵循各自上游条款，部分可能限制商业用途
- FFmpeg 是 GPL 构建，本仓库**不分发**它，需自行获取
## 注意

- **首次加载模型较慢**：KAIR 权重集 4.2 GB、DDColor 870 MB、GPEN 271 MB、RetinaFace 104 MB，需要从磁盘读入显存。机械盘上约 20~60 秒，SSD 上明显更快。模型加载后常驻进程，第二单起不再等待。
- 中文路径下 `cv2.imread` / `cv2.imwrite` 会失败，脚本里已用 `imdecode` / PIL 规避
- 如果以后要加 PASD，需要重新给 `python-embed` 装 `diffusers 0.28`、`transformers 4.48.3`、`accelerate`、`open-clip`（本轮不集成 PASD，这些包已移除）