# PixSharp

**Repository Path**: ginkdu/PixSharp

## Basic Information

- **Project Name**: PixSharp
- **Description**: PixSharp:基于 Avalonia 的 Windows 桌面批处理工具，用 upscayl 引擎对图像和 PDF 做超分辨率放大（2x/3x/4x），AI-PDF_Upscaler 的 GUI 重写版。AGPL-3.0
- **Primary Language**: C#
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-12
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Real-ESRGAN

## README

# PixSharp++

批量**图片 / PDF 超分辨率**工具。基于 **.NET 10 + Avalonia + NativeAOT** 构建，超分引擎为 `upscayl-bin`（ncnn / Vulkan）。

> 本项目是 `https://gitee.com/ginkdu/ai-pdf-upscaler` 的 GUI 重写版，算法逐条移植。

---

## ✨ 功能特性

- **图片超分**：拖拽或浏览批量输入（`png / jpg / jpeg / webp / bmp`），支持模型选择与 2/3/4 倍放大，输出到源目录 `upscaled_x{N}\`
- **PDF 超分**：单个 PDF 一键流程「提取图片 → 超分 → 缩放超大图 → 合并为新 PDF」，支持灰度页无损编码、SMask 软掩码合成、A4 画布排版
- **模型测试**：遍历全部模型跑样张，横向对比各模型耗时与效果，内置滑块 / 双窗**对比查看器**
- **GPU 加速**：自动探测 Vulkan 设备，支持单卡 / 多卡并行
- **深色主题**：跟随 Windows 应用模式，运行时即时切换

## 🧰 技术栈

| 项 | 选型 |
|----|------|
| 语言 / 框架 | C# · .NET 10 |
| UI | Avalonia 11.3.22（Fluent） |
| 数据处理 | SkiaSharp 3.119.4 · MuPDF.NET 3.28.2 |
| 状态管理 | CommunityToolkit.Mvvm 8.4.2 |
| 发布形态 | NativeAOT（`PublishSingleFile=false`，exe + 外挂 dll） |

## 📁 项目结构

```
src\PixSharp\
├── Core\          文件收集、任务管理、GPU 探测、超分 Runner、模型扫描、基准
├── Pdf\           PDF 提取 / 合并 / 写入 / 流水线 / 自检
├── ViewModels\    MVVM 视图模型
├── Views\         图片 / PDF / 模型测试 / 帮助 / 对比 / 确认窗口
├── App.axaml      全局主题与控件样式
docs\              可行性分析、项目计划、验收报告
AGENTS.md          开发约束
```

---

## 1. 环境要求

| 项 | 要求 |
|----|------|
| 操作系统 | Windows x64 |
| .NET SDK | 10.0 及以上 |
| 构建 AOT | Visual Studio 2022/2026 的「使用 C++ 的桌面开发」工作负载（提供 MSVC 链接器 + Windows SDK） |
| 运行 | 支持 Vulkan 的显卡（ncnn 后端；无可用设备时程序会禁用执行按钮） |

---

## 2. 构建与发布

```cmd
:: 只做 AOT 发布，产物在 src\PixSharp\bin\Release\net10.0\win-x64\publish
publish.cmd

:: 额外生成一份可整目录拷贝的交付包 dist\PixSharp-win-x64\（含 Models\，已剔除 pdb）
publish.cmd portable
```

直接使用 dotnet CLI 亦可：

```cmd
dotnet publish src\PixSharp\PixSharp.csproj -c Release -r win-x64
```

> `publish.cmd` 为两段式：先跑普通 `dotnet publish`；若因链接器找不到 Windows SDK 导入库而失败（`LNK1181 / advapi32.dll`），会自动定位本机最新的 MSVC 与 Windows SDK 并注入环境变量后重试一次。
>
> 约束：`PublishSingleFile` 恒为 `false`，AOT 产物是「exe + 外挂 dll」的形式。

---

## 3. 运行时目录要求

```
PixSharp.exe            主程序
bin\upscayl-bin.exe     超分引擎（必需）
libSkiaSharp.dll 等      AOT 外挂依赖（随发布自动带出）
Models\                 模型目录：同名 .bin + .param 配对（必需）
```

**Models 目录的查找顺序**（程序启动时自动解析）：

1. 环境变量 `PIXSHARP_MODELS_DIR`
2. 可执行文件同目录下的 `Models\`
3. 自可执行文件目录逐级向上最多 8 层，找第一个含 `.param` 的 `Models\`

> 交付包 `dist\PixSharp-win-x64\` 已把 `Models\` 放在 exe 同级，整目录拷到任意位置双击即可运行。
>
> 注意：引擎对模型目录名做**字面量**比较（必须是 `models`），程序内部会自动把路径叶子名改写为小写以满足该要求（Windows 文件系统大小写不敏感，指向同一目录）。

---

## 4. 使用说明

### 4.1 图片 Tab

- 输入：拖拽（单个 / 多个 / 整个文件夹，文件夹递归）或点「浏览…」→ 选择图片文件 / 选择文件夹
- 支持格式：`png / jpg / jpeg / webp / bmp`（**已按引擎实测能力校正**：`tga` 实测会被引擎静默忽略——退出码 0 但不产出文件，故不列入白名单）
- 参数：模型（下拉展开时重新扫描 `Models\`）、倍数（2 / 3 / 4）
- 输出：**源文件同目录** `upscaled_x{N}\<原名>.png`

### 4.2 PDF Tab

- 输入：拖拽或浏览，仅支持**单个 PDF**
- 参数：模型（固定白名单两项）、倍数**固定 2 倍**
- 流程：提取图片 → 超分 → 缩放超大图 → 合并为 PDF，中间产物落在 `<提取目录>_2x\`
  - 提取目录 = PDF 同目录、去扩展名同名文件夹
  - 提取规则：`jpg/jpeg/png` 原样落盘，其余格式转 **JPEG**；命名 `image_i{n}`（单页多图）/ `image_p{页}_i{图}`（多页）
  - 带**软掩码（SMask）**的图片会先与掩码合成，避免透明区域退化成黑块：
    `jpg/jpeg/png` 合成后改存 PNG（保留 alpha）；其余格式合成到白底后转 JPEG
  - 重复执行时，目标文件已存在且大小一致则**跳过**
  - **缩放超大图**：`_2x` 中长边超过 3508 px 的图等比缩小并覆盖（对应原版 `resize_large_images`）
  - **合并为 PDF**：按自然排序（`image_p2` 在 `image_p10` 之前）逐页判定灰度/彩色后组装
    - 灰度页用无损灰度编码，彩色页用 JPEG
    - 输出到原 PDF 同级目录，文件名 `<原PDF名>(<模型名>).pdf`
    - 页面尺寸按 300 DPI 由像素换算为点
- **「合并为 A4 画布」勾选项（默认开启）**：对应原版 `resize_to_a4_canvas`，把每页等比缩放并居中放到标准 A4 画布（2480×3508 @ 300 DPI，横向图用横向 A4）。关闭后按图片自身尺寸建页
- 删除保护：
  - 提取目录创建时会写入标记文件 `.pixsharp_extract`（内容 = PDF 路径 + 时间戳）
  - 「删除提取文件夹」按钮与「超分完成后删除」勾选项，删除前都会校验该标记
  - **目录缺少标记（非本程序创建）时删除请求会被拒绝**，避免误删用户自己的同名文件夹
  - 勾选自动删除但存在失败图时**不删除**（安全优先）
  - 仅删除提取目录，`_2x` 输出目录始终保留

### 4.3 模型测试 Tab

- 输入：**单张**样张（多文件 / 文件夹会被拒绝）
- 遍历 `Models\` 全部模型顺序执行，输出到 **样张同目录** `model_test\<样张名>_<模型名>_x<N>.png`
- 结果列表显示每个模型的耗时（0.1s 精度）/ 输出大小 / 状态；完成后可点「对比」打开**应用内对比查看器**
  - 滑块对比：左侧原图、右侧结果图，拖动分割线对照
  - 双窗对比：左右并排，缩放与平移严格同步
  - 窗口内下拉可切换结果图；滚轮缩放、拖拽平移、双击复位
- 「清空结果」会弹确认框，确认后删除 `model_test\` 目录

> 注意：本页会**跑满 Models 目录下的全部模型**。当前为 19 组模型，即便样张很小，单模型也约需数秒（引擎启动 + 模型加载开销）；真实照片耗时按每模型几十秒计。

---

## 5. 状态栏

- `主题:跟随系统(浅色/深色)` —— 跟随 Windows 应用模式，运行时切换即时生效
- `引擎:upscayl-bin ✓/✗`
- GPU 下拉：`自动(默认单卡)` = 不传 `-g`；单卡环境置灰；≥2 卡时可选单卡或 `多卡并行(0,1)`

---

## 6. 无头自检

主程序内置自检入口，便于排查环境问题（WinExe 无控制台，结果写入报告文件，以退出码表示成败）：

```cmd
PixSharp.exe --selftest <报告文件> [测试PDF] [提取输出目录]
```

自检覆盖：环境与模型目录解析、图片尺寸解析与文件夹展开、引擎进度行解析断言、MuPDF 提取、PDF 提取与跳过逻辑、批量超分与输出规则、GPU 探测、基准队列、对比器逻辑、PDF 流水线（加权进度 / 自动删除 / 防误删 / 合并产物页数与 A4 页面尺寸）、灰度判定与 A4 画布算法断言、超大图缩放、SMask 合成、主题资源明暗一致性、异常路径（加密 / 损坏 PDF、中文空格特殊字符路径）。全部在 AOT 发布产物上执行。

---

## 7. 已知限制

- 含 JBIG2 编码图片的 PDF 未做本机验证（无编码器可生成样张）；此类图片提取失败时会跳过并记日志，不中断流程
- 任务栏进度依赖 ITaskbarList3，远程会话或旧系统上不可用时静默降级
- `resize_large_images` 的格式白名单含 `bmp/tiff`（沿用原版），但 Skia 无这两种格式的编码器；本流水线产物只有 `jpg/png`，不受影响，若手工放入会跳过并记日志

---

## 📄 许可

AGPL-3.0