Version: 1.2.1
把从大图里裁出的局部，经 AI 修复后，自动找回它在原图中的位置并贴回去； 同时输出与原图裁剪区完全同尺寸的对齐图，方便直接做前后对比。
本工具是 大云壁画工具箱的一员（相柳网格 · 精卫 · 白泽评审 · 重明 DiffEye）。
你在超大壁画扫描图上裁下一小块，交给 AI 修复。修完之后，那块图往往被放大过、缩小过、 边缘被改写过——你很难再用眼睛对上它原来的位置。
精卫做的事情只有一件：用 SIFT 特征匹配把那块修复图自动对回原位，然后
- 给你一张标了红框的定位预览，确认找得对不对；
- 把修复图按原尺寸贴回大图，输出硬贴版和羽化版；
- 同时裁出「原图对应区域」和「修复对齐图」两张同尺寸 PNG，可以直接拖进 PPT 叠着做对比。
定位靠图像本身的特征，不需要你提供任何坐标。
这个小工具是在大云禅院壁画修复与重现工作中做出来的。整面墙的扫描图被切成几十块， 分给不同的人和不同的 AI 分别修复；修好的局部要回到大图上，靠人工对位既慢又容易错。 精卫把这一步自动化：只要修复图还留着一点原始边缘纹理，它就能自己找到家。
「精卫」出自《山海经·北山经》。炎帝之女溺于东海，化为精卫鸟，衔西山之木石，誓要填平大海， 一喙一石，日复一日。
这个意象和工具的职责完全重合：把一块一块修复好的局部，准确衔回它们原本的位置上去。
- 自动找回原位：SIFT 特征匹配 + FLANN 加速 + RANSAC，无需人工给坐标。
- 容忍缩放：修复图被放大或缩小过也能对上，可容忍 2~3 倍缩放变化。
- 小角度自动忽略：旋转角小于 6° 时自动回退到「平移 + 等比缩放」的最小二乘解，结果更稳。
- 两种贴合方式：硬贴（边界清晰）与羽化贴（接缝柔和，可调羽化半径）。
- 同尺寸对比导出：原图裁剪区与修复对齐图分辨率完全一致，可直接叠放对比。
- 区域裁剪工作台：上传修复前/后两张同尺寸大图，在可缩放画布上拖框，按同一坐标裁出并保存。
- 历史记录：每次运行自动归档，可随时回看之前的定位结果。
- 全本地运行：图片只在本机内存与磁盘中处理，不访问任何网络服务。
需要 Python 3.9 或更高版本：https://www.python.org/downloads/
安装时请勾选 Add python.exe to PATH。
双击：
run.bat
第一次启动会询问是否自动安装依赖（Pillow / numpy / opencv-python），选 Y 即可。
也可以直接在 PowerShell 里运行：
.\run.ps1浏览器会自动打开：
http://127.0.0.1:8786
使用期间请不要关闭那个命令行窗口，关掉工具就停了。
Pillow
numpy
opencv-python
手动安装：
python -m pip install -r requirements.txt- 左侧「原始大图」选整张扫描图，「局部修复图」选 AI 修复好的那一块。
- 一般不用改参数。默认「大图搜索长边 4000 / 补丁检测长边 2600 / 羽化 40」适用于绝大多数情况。
- 点 开始自动对齐。
- 右侧会给出：
- 定位预览：整图缩略 + 红框标出找到的位置；
- 匹配参数：位置 X / Y、对应宽高、缩放比例、残留旋转、特征内点、用时；
- 下载硬贴合并图 / 下载羽化合并图。
跑过一次定位后，切到这一页，会看到：
- 原图对应裁剪 与 AI 修复对齐 两张同尺寸图；
- 可单独下载两张 PNG，或下载并排合成图，或下载全部结果 ZIP。
把两张同尺寸 PNG 拖进 PPT / Keynote，按相同位置叠放，就能做前后对比。
- 上传「修复前」和「修复后」两张像素完全一致的大图。
- 点 加载预览，画布上鼠标操作：
- 左键拖 = 画选框；
- 右键拖 或 空格 + 左键 = 平移画布；
- 滚轮 = 以鼠标位置为中心缩放，可放大到像素级；
- 红框可以再次拖动微调。
- 点 裁剪并保存，两张图会按同一坐标全分辨率裁出，存到导出目录。
- 保存后红框自动清空，可以接着框下一块。
| 参数 | 默认 | 说明 |
|---|---|---|
| 大图搜索长边 (px) | 4000 | 特征检测时大图会降采样到这个长边。图越大越慢但越准；找不到位置时可调到 6000~8000。 |
| 补丁检测长边 (px) | 2600 | 修复图降到这个长边，让两边关键点处于相近视觉尺度。 |
| 羽化像素 | 40 | 羽化贴合时接缝的过渡半径。接缝明显就加大。 |
| 导出目录 | 留空 | 留空则用工具目录下的 exports/。每次运行建一个时间戳子目录。 |
| 导出长边 (px) | 0 | 0 = 原始分辨率。填 3000 则所有导出图缩到长边 3000。 |
每次运行保存在 runs\<日期时间-随机ID>\，同时会打包一份到导出目录。
| 文件 | 含义 |
|---|---|
source_crop.png |
原图对应区域的裁剪（与对齐修复图同尺寸） |
aligned_patch.png |
缩放到对应尺寸的修复图 |
merged_hard.png |
硬贴回大图 |
merged_feather.png |
羽化贴回大图 |
preview_match.png |
带红框的定位预览 |
compare_crop_patch.png |
原图裁剪 + 修复图的并排对比 |
report.json |
匹配参数与选项 |
exports.zip |
以上全部打包 |
区域裁剪工作流的输出：
<导出目录>\YYYYMMDD-HHMMSS[-前缀]\before.png
<导出目录>\YYYYMMDD-HHMMSS[-前缀]\after.png
Q：提示「特征点不足」或「鲁棒匹配点不够」怎么办？
修复图被 AI 大幅改写、把原始边缘纹理全抹掉了。请让 AI 修复时保留一圈原始边缘， 或者调高「大图搜索长边」再试。清晰度太低也会匹配不上。
Q：位置找错了 / 红框跑偏了。
先看红框里的内容是不是和修复图对不上。常见原因是修复图内部被改得太多，特征点主要来自 被改写的区域。解决同样靠保留原始边缘。
Q：修复图尺寸和原位置不一样，能贴对吗？
能。工具估计的是「平移 + 等比缩放」，修复图被放大缩小过都能对上。但它不支持大角度旋转和透视变形。
Q：导出的图太大 / 太小。
用「导出长边」控制。填 0 保留原始分辨率（壁画修复一般都填 0）；只想放到 PPT 里看就填 3000。
Q：区域裁剪提示「两张图尺寸不一致」。
这一页要求两张图像素完全一致。请先在外部软件里把其中一张对齐到另一张的尺寸。
Q：端口 8786 被占用了。
python server.py 8899然后用 http://127.0.0.1:8899 打开。
Q：exports\ 和 runs\ 越来越大。
这两个目录不会自动清理，确认不再需要的结果可以直接删掉，不影响工具运行。
见 CHANGELOG.md。
源代码使用 MIT License 发布。
The name 精卫 / Jingwei, as well as the project logo and visual identity, are reserved by the project author and are not granted as branding or trademark rights under the MIT License.
精卫 / Jingwei 的名称、项目 logo 和视觉识别保留为项目作者的品牌资产，不随 MIT 协议授予商标或品牌使用权。