照片转扫描件 PDF Skill（扫描全能王）
把手机/相机拍的文档/表格照片整张等比放进 A4 并生成带文字层（可 Ctrl+F 搜索、可选中复制）的 PDF，无水印；默认不做透视校正/裁切，表格表头完整保留。
两种用法
| 用法 | 触发场景 | 说明 |
|---|---|---|
| GUI（双击） | 用户自己挑照片、看预览、调模式 | 直接跑 扫描全能王.exe 或 python scan_tool.py |
| CLI（agent 自动） | 用户给了一批图，让 agent 直接产出 PDF | python scan_tool.py --cli <图片...> --out <pdf> |
CLI 批量模式（agent 推荐，无界面、可全自动）
运行环境：本机 managed python（<PY>，见 binary_context，绝对路径形如 …\binaries\python\versions\3.x.x\python.exe），或任意装好依赖的 Python(≥3.8)。不要写死用户名/绝对路径。
<PY> <本skill目录>/scripts/scan_tool.py --cli "<图片1>" "<图片2>" --out "<输出.pdf>" [--mode color|bw] [--correct] [--rotate 0|90|180|270] [--page auto|portrait|landscape|tight] [--auto-rotate]
参数：
- images（位置参数，可多个）：输入照片路径，支持 jpg/jpeg/png/bmp/tif/tiff
- --out：输出 PDF 路径（默认 ~/Desktop/扫描件.pdf）
- --mode color：彩色，保留红色印章/底色（默认）
- --mode bw：黑白文档，文字更锐利（适合纯文字合同/文件）
- --correct：开启透视校正（默认关闭）。默认整张照片直接等比放进 A4，不做任何边框检测/裁切；只有拍的文档明显歪斜、确实想去歪边时才加这个开关
- --page auto：页面策略（默认 auto）。auto=按图自动选页面横竖（横图→A4 横向，竖图→A4 纵向）；portrait=强制 A4 纵向；landscape=强制 A4 横向；tight=页面贴合图片、几乎无留白
- --rotate 0|90|180|270：顺时针旋转角度，照片拍歪/内容躺倒时用它摆正（默认 0）
- --auto-rotate：自动摆正——OCR 四个方向各试一次，自动选"能读出字"的方向（每张多花几秒，适合批量丢一堆方向各异的照片）
示例（把桌面上两张截图合成一份扫描件）：
<PY> <本skill目录>/scripts/scan_tool.py --cli "C:/Users/25080/Desktop/a.jpg" "C:/Users/25080/Desktop/b.png" --out "C:/Users/25080/Desktop/合同扫描件.pdf" --mode bw
示例（横版表格照片，内容躺倒了，自动摆正）：
<PY> <本skill目录>/scripts/scan_tool.py --cli "C:/Users/25080/Desktop/横表.jpg" --out "C:/Users/25080/Desktop/横表.pdf" --page auto --auto-rotate
正常结束打印 已生成: <路径>，exit code 0；无可用图片返回 1。OCR 失败不影响出图（只是没文字层），每张图处理失败会在桌面 扫描全能王_error.log 留完整 traceback。
GUI 用法（给用户）
界面极简，只有一条路径：
- 添加照片 → 选中列表项可看右侧预览（下方显示图片尺寸和将使用的页面方向）
- 选彩色(保留印章) 或 黑白文档
- 填/选输出PDF 路径
- 点 "确定生成扫描件 PDF"（界面中下部那个大按钮）
图像处理（v1.1.6 定稿，全自动，无需勾选）：
- 白底化（仅彩色模式自动做）：纸张的灰白/米白/泛黄等底色统一变纯白；文字、表格边框、红章等元素保留原色。
- v1.1.6 改用 「彩度 = 最亮通道 − 最暗通道」 判据（高亮(V>200) 且 彩度<45 才判为纸涂白）：任何带颜色的印章/文字/批注哪怕偏浅，只要彩度够就一律保留——修掉"浅红章被 S<60 判据当纸洗白"的 bug。
- 去阴影 / 影印脏污（彩色 + 黑白都自动做）：拍照时的阴影、影印脏斑会被自动提亮消除，红章/蓝字不洗白。
- v1.1.6 彩色改用 「每像素最亮通道归一到 255（等比缩放）」 求增益（上限 2.5、暗像素主通道<60 跳过）：等比缩放色相/饱和度完全不变，红章不会被洗成粉白——修掉旧版"灰度增益把红章去饱和"的 bug。
- 两段式锐化（v1.1.7）：① 细锐化 radius=1.5 / amount=1.8 / threshold=2（提印章小字/细线边缘锐度）；② 清晰度 radius=6 / amount=0.7 / threshold=3（大半径低强度，提局部对比，让印章整体"立"起来）。实测 PDF 渲染后印章清晰度比 v1.1.6 高 21%(150DPI) / 36%(300DPI)。
- JPEG 4:4:4（v1.1.7，关键）：彩色输出 quality=98, subsampling=0。JPEG 默认 4:2:0 把色度分辨率砍半 → 彩色边缘（红章描边、彩色小字）比黑字明显发糊（黑字走亮度通道不受影响）；改 4:4:4 保住色度细节。
- 红/粉相保护（v1.1.8 引入，v1.1.9 校准阈值）：白底化在 高亮(V>200) 且 彩度<45 基础上再加 ~(hue<15 或 hue>165)——偏红相像素（公章）无论彩度多低（浅红/浅粉、抗锯齿羽化边缘）一律保留，绝不涂白；只把"高亮+低彩度+非红相"的真纸/泛黄背景涂白。
- 诊断：v1.1.7 对标准红章只吃羽化边缘约 5.7%、对浅粉章(chroma<45)直接 100% 整章被吃；加红相保护后核心保留 95~100%、纸 100% 纯白。锐化(USM)不洗色（实测边缘饱和度反升），故排除"锐化过度"。
- 🔴 阈值必须按 OpenCV H(0~179) 量测后再定，别按 360° 写（v1.1.9 修的坑）：v1.1.8 误用 hue<30（实为 60°），把米黄/老化黄纸(H≈23~27)也一起豁免 → 印章保住了但页面又泛黄。量测得红/橙红章 H=0~10、带蓝红章 H≈174、米黄黄纸 H=23~27 → 阈值取 15（30°）正好落在缝里：只豁免真红相，黄纸照常涂白。
- 仍保留：整图等比缩放进 A4、不裁切表头、可搜索文字层。
页面怎么排版（v1.1.5 定稿，用户明确要求）：
- 按"纸张区域"的横竖决定这一页方向（v1.1.5，默认开）：GUI 勾选项"按文档方向自动排版(推荐)"（默认勾上）。
- 在 HSV 里取"高亮 + 低饱和"的纸张像素，形态学闭运算填掉文字/印章空洞，取最大连通域的包围盒，其宽高比即文档方向（竖纸张→纵向 A4、横纸张→横向 A4）。纸张区域太小(<20% 图面积)时退回按图片像素长宽比。
- 为什么不用文字框并集（v1.1.5 修的坑）：证书/公函这类文档正文常"每行很长、行数不多"，文字块本身宽 > 高 → 会被误判成横向，把竖版文档出成横版 A4 页。真正代表文档方向的是纸张，不是文字块。
- 内容被拍歪 90°（文字在图里是竖的）→ 先整页(A4+照片)一起旋转到文字横向可读，再按旋转后的纸张判方向；解决"扫描后一竖一横"。
- 照片长边对 A4 长边、短边对 A4 短边：宽 > 高 → A4 横向页；高 ≥ 宽 → A4 纵向页
- 图片整张等比缩放（能放多大放多大），不拉伸变形，不超出 A4 边界；允许留白，不强行铺满
- 绝不自动裁切/找边框：整张照片原样放进 A4，表格表头等完整保留（用户原话"不要自己去识别什么表格，表头给我整没了"）
- 没有手动旋转选项（用户反馈"还要手动旋转不合理"，已移除"方向摆正"下拉与"自动摆正"复选框）；如需强制摆正/旋转用 CLI --auto-rotate / --rotate
- 出错会弹窗并保存 ~/Desktop/扫描全能王_error.log，把该文件发我排查
关键坑（务必遵守）
⚠️ GUI 控件必须在 _build() 里一次性建全（v1.1.1 修复，超低级但后果致命）：
- v1.1.0 犯了错：_build() 只画了顶部工具栏，列表/预览/输出路径框/"生成扫描件PDF"按钮/日志区统统被写进了 on_auto_toggle() 方法体内（那个方法只在用户勾选"自动摆正"时才被调用）。
- 后果：用户打开程序 → 看不到生成按钮 → 投诉 "我怎么点确定？"（截图里界面下半截空白）。
- 教训：任何控件都必须在 _build() / __init__ 路径里创建，回调方法里只能改状态（configure/state），绝不能靠回调去"补建"界面。GUI 改完必须实测"打开就有生成按钮"，别只看代码逻辑。
⚠️ 透视校正（找边框+裁剪）必须默认关闭（v1.1.2 修，用户明确要求）：
- v1.1.0/1.1.1 默认开启"透视校正"：correct() 用 Canny+findContours 找最大四边形当文档外框再裁切。问题是它会把表格的线条/边框误判成文档外框，把表头、边缘整段裁掉 → 用户投诉"你这么识别，表头给我整没了"。
- 修：GUI 移除"透视校正"复选框，固定 correct_flag=False；CLI 默认也不校正，改用 --correct 显式开启（只给真需要去歪斜文档的人）。build_pdf 默认值改为 False。
- 默认行为（也是用户要的）：整张照片原样等比缩放居中放进 A4，不做任何裁切，表格表头/边缘一个像素都不丢。
- 教训：照片转扫描件，绝大多数场景"整图等比放进 A4"就够了；自动裁切看着高级，实则在表格/带边框内容上极易翻车，默认别开。
⚠️ 白底化必须用「彩度 = 最亮−最暗通道」判据，不能用 HSV 饱和度 S<60（v1.1.6 修，用户投诉"印章不清晰"）：
- 旧的 (V>200) & (S<60)：公章/浅红章经手机拍摄+JPEG 压缩后，红色饱和度常掉到 40~60、明度又 >200 → 被误判成纸张直接涂成纯白，印章局部消失/发虚。
- 正确做法：高亮(V>200) 且 彩度(max−min)<45 才判为纸涂白。彩度是绝对值，米黄/灰白纸的彩度本就很小(<45)仍会被涂白；而任何有颜色的印章/批注哪怕偏浅，只要彩度 ≥45 就保留。实测旧版把彩度 50 的浅章涂白、新版保留。
- 白底化在 HSV 的 V 通道上判"亮不亮"，用 RGB 彩度判"是不是灰/白"，两者结合才既白纸又不误伤浅色印章。
⚠️ 彩色去阴影用「每像素最亮通道归一」，不能用「灰度增益 255/灰度背景」（v1.1.6 修，会把红章洗成粉白/去饱和）：
- 旧做法 gain = 255 / 灰度背景 后 rgb * gain：把 RGB 三通道按同一比例放大。红章主通道已接近 255，其余通道被同比例抬升 → 章色去饱和洗成粉白、发虚。
- 正确做法：gain = min(背景增益, 255/最亮通道)，即"把每像素最亮通道抬到 255（等比缩放）"，色相/饱和度完全不变；上限 2.5、暗像素(主通道<60，即墨迹/暗章)跳过，避免噪声被放大成白。实测红章彩度 177 → 225（更饱和）。
- 效果：亮区纸上的印章完全不动（背景增益≈1）；只有在阴影里的印章才被提亮复原，且保色。
- 历史坑（v1.1.3）：更早还试过 lab[:,:,0]=归一化灰度 做光照归一化，红章被提亮成粉白(255,197,165)——L 通道替换把饱和色整体提亮、洗掉色相。别再用 L 通道替换。
- 黑白模式仍走 _illumination_norm_gray 去阴影后再二值化，不受影响。
⚠️ 印章清晰度：锐化强度 + JPEG 色彩抽样（v1.1.6 起，v1.1.7 加强）：
- 锐化绝对不能用 PIL 的 Sharpness(1.15)（几乎无效），要用 ImageFilter.UnsharpMask。v1.1.7 两段：细 radius1.5/amount1.8/th2 + 清晰度 radius6/amount0.7/th3。
- 🔴 彩色输出必须 subsampling=0（4:4:4）+ quality=98：JPEG 默认 4:2:0 抽样把色度分辨率砍半，导致彩色边缘（红章描边、彩色小字）比黑字明显发糊——这是"印章看着糊、黑字还行"的关键原因之一。PNG 无损只比 JPG444 高约 0.4%（不值那个体积），所以用 JPG444。
- 验证清晰度要用对的指标：在"色度边缘的均值梯度"这种被大片平涂色稀释的指标上，改进看不出来；要用 Laplacian 方差（在 PDF 真实渲染图上量）或边沿宽度这类敏锐指标。踩过：均值梯度指标误判"无提升"，Laplacian 方差才显出 +21%~36%。
- 四者（彩度判据 + 最亮通道归一 + 两段 USM + JPEG 4:4:4）合起来解决"拍照清晰但扫描后印章发虚/不够清晰"。
- 页面方向（v1.1.5 定稿，最容易踩）：
- 页面尺寸必须按文档方向动态决定，不能写死。老版本写死竖版 A4，横版照片（比如 1600×900 的表格）缩进竖版页面后上下大片空白、内容被压小 → 用户投诉"横向的图给我扫成这样"。
- v1.1.5 起 GUI 默认按"纸张区域"横竖排版（勾选项"按文档方向自动排版"）：page_orient_from_paper()取高亮低饱和的纸张像素、闭运算填洞、最大连通域包围盒判横竖；纸张太小则退回像素长宽比。内容被拍歪 90° 时先整页(A4+照片)一起转正（detect_content_deg，用检测框几何判，见坑 #3）。
- ⚠️ 务必用"纸张"而不是"文字框并集"判方向（v1.1.4 翻车点）：证书/公函正文常"长行、少行"，文字块宽 > 高 → 用文字框判会误判成横向，把竖版文档出成横版 A4（用户实测投诉："明显竖向排版，你给我搞成横向了"）。
- ⚠️ 纸张探测别用光照归一化预处理：_illumination_norm_gray会把任何"均匀"区域（如整块灰色背景）拉成白色 → 整个画面都被当成纸张。直接用原始亮度阈值（V>150 & S<100）即可。
---page auto（CLI 默认）：宽 > 高 → A4 横向 841.89×595.28；高 ≥ 宽 → A4 纵向 595.28×841.89。另有portrait/landscape/tight(贴合图片、几乎无留白)。CLI 用--auto-rotate复用同一"内容摆正 + 纸张判向"逻辑。
- 局限（已知）：几何法区分不了 0° 与 180°（都是横框）；90° 与 270° 用"识别文字更多的一侧"来二选一（实测多数能选对），极端情况仍可能上下颠倒（页面方向仍正确），遇到用--rotate 180纠正。 - 透视校正的宽高必须按"边"算，不能按对角线（v1.1.0 修复）：
w = |br-bl| 与 |tr-tl| 取大，h = |tr-br| 与 |tl-bl| 取大。
老代码误写成wA=|br-tl|、wB=|tr-bl|（那是两条对角线），结果横版文档被拉成近正方形、竖版 A4 文档被横向拉宽 2 倍（900×1600 变成 1834×899）。回归基线：横版 1600×900 校正后宽高比应仍在 1.7~1.9，竖版 900×1600 应仍在 0.55 附近。 - 读图统一走 PIL +
exif_transpose（v1.1.0 修复）：手机照片带 EXIF 旋转标记，各引擎处理不一致（cv2.imread 会自动应用、PIL 要显式转换），同一张图经不同路径读出来可能一个横一个竖 → "图片层"和"OCR 文字层"方向对不上，或输出莫名其妙躺倒。现在统一imread_unicode：PIL 打开 →ImageOps.exif_transpose→ numpy，与用户看图软件所见一致。 - 自动摆正（
--auto-rotate）的判据是"检测框几何"，不是"识别字数"：正向文字的行框是扁的（宽>高），内容躺倒 90° 后同一个框变竖的。实测本机 OCR 引擎自带方向分类器、关掉 cls 也能认倒置中文，所以"识别出多少字"完全区分不了方向，必须用 bbox 形状。
- 局限：几何上区分不了 0° 与 180°（两者都是横框），并列时程序保持原方向不动并在日志提示；如果是倒的，手动--rotate 180。
- 代价：每张图多跑 3 次识别（约 +2~5 秒），所以默认关闭。 - OCR 模型就在包里，不需要联网：
rapidocr_onnxruntime自带models/*.onnx（3 个共 13MB），源码跑和 exe 跑都离线可用。只有改用rapidocr(3.x) 那个包时才会去 ModelScope 下载模型；本技能用的是rapidocr_onnxruntime。 - OCR 引擎：源码优先
import rapidocr_onnxruntime（ONNXRuntime 引擎），失败再退回import rapidocr。安装命令：pip install opencv-python numpy pillow PyMuPDF rapidocr_onnxruntime。 - Python 版本：
E:\PythonRunning\python.exe（3.14.2）实测可打包可跑（本机rapidocr_onnxruntime装在这里）。 - 中文路径：源码已用
imread_unicode兜底 OpenCV 读中文路径问题；但 RapidOCR 模型缓存目录尽量放 ASCII 路径，避免中文父目录。 - 透视校正门控（仅当 CLI
--correct开启时生效）：检测到的四边形面积必须占图 ≥25% 才裁剪，且长宽比 > 5:1 的细长四边形会被跳过（那是表格线/边框线，不是文档外框）——否则会把某条线当外框裁出一条窄缝。这一项正是表格照片表头被裁掉的根因，所以默认关闭，详见上方 ⚠️ 透视校正默认关闭说明。 - 黑白模式"缺字"坑：已禁用中值模糊/高斯模糊（会把 1~2px 细笔画当噪点抹掉），改用"背景减除+Otsu+轻微 ERODE 加粗"。若仍缺字，改回
--mode color保底。 - 文字层字体：中文用
C:/Windows/Fonts/simsun.ttc（宋体）等系统字体；找不到则用默认字体，跨机器复制 PDF 可能显示异常。 - CLI 模式下 OCR 是全图识别，多张图会按顺序排进同一份 PDF 的多页（各自按自己的长宽比选页面方向），第一页之前不会插空白页。
依赖安装（仅首次）
<PY> -m pip install opencv-python numpy pillow PyMuPDF rapidocr_onnxruntime
> 注：pyinstaller 只在打包 exe时需要，运行脚本不必装。
打包成 exe（给没装 Python 的同事）
必须在带 tkinter 且装了 opencv-python numpy pillow PyMuPDF rapidocr_onnxruntime pyinstaller 的环境打包，用 python -m PyInstaller（不要用全局 pyinstaller 命令）。（本技能没有 spec 文件，直接用下面这条命令：）
python -m PyInstaller --noconfirm --onefile --windowed --name 扫描全能王 ^
--collect-data rapidocr_onnxruntime --collect-submodules rapidocr_onnxruntime ^
--hidden-import rapidocr_onnxruntime ^
--hidden-import rapidocr_onnxruntime.ch_ppocr_v3_det ^
--hidden-import rapidocr_onnxruntime.ch_ppocr_v3_rec ^
--hidden-import rapidocr_onnxruntime.ch_ppocr_v2_cls ^
--hidden-import cv2 --hidden-import numpy --hidden-import fitz ^
--hidden-import PIL --hidden-import PIL.ImageTk --hidden-import tkinter ^
--exclude-module torch --exclude-module torchvision --exclude-module torchaudio ^
<本skill目录>/scripts/scan_tool.py
> 🔴 打包环境必须有 tkinter（血泪坑，2026-09-10）
> 打包用的 Python 自己没有 tkinter 的话，collect_submodules('tkinter') 会是空操作，打出的 exe 双击必弹 ModuleNotFoundError: No module named 'tkinter'。
> - 已知可用：E:\PythonRunning\python.exe（system Python 3.14.2，自带 tkinter）。
> - 打包前先自检：python -c "import tkinter; print(tkinter.TkVersion)"，能打印版本号才可用。
> - 离屏验证 GUI：不加参数直接跑 exe，进程存活 ≥3 秒说明 GUI 起来了（缺 tkinter 时进程秒退）。
> 🔴 必须用 collect_data_files + collect_submodules 一起收 rapidocr（血泪坑，2026-09-21）
> 症状 1：exe 一点"生成"就弹 Failed to execute script 'scan_tool' ... _MEIxxxx\rapidocr_onnxruntime\config.yaml does not exist!
> 症状 2（更隐蔽）：能打开、但一跑 OCR 就崩 module 'rapidocr_onnxruntime.ch_ppocr_v3_det' has no attribute 'TextDetector'。
> 根因：rapid_ocr_api.py 用 root_dir/'config.yaml' 读配置（相对路径找 models/xxx.onnx），又用 importlib.import_module("ch_ppocr_v3_det") 动态加载三个子模块。只收数据文件（--collect-data）会让 config.yaml 到位，但子模块若没被当子模块正确收集，动态导入会落到不完整副本 → 缺 TextDetector。
> 正确写法：--collect-data rapidocr_onnxruntime 同时 --collect-submodules rapidocr_onnxruntime + 三个子模块的 --hidden-import，把配置、模型、子模块一网打尽。
> 教训：PyInstaller 打"动态 import 子模块 + 相对路径读配置"的第三方包，data 和 submodule 都要收。
> 🔴 打包环境有 torch 必须 --exclude-module torch（血泪坑，2026-09-21 v1.1.4）
> 本机 E:\PythonRunning 装了 torch/torchaudio（openvino 可能拖进来）。不打排除的话 PyInstaller 会把 torch 整包收进 exe → 体积从 ~114MB 暴涨到 400MB+ 且打包极慢。RapidOCR 走 onnxruntime，根本不需要 torch，直接 --exclude-module torch torchvision torchaudio。
> 🔴 windowed exe 没有 stdout，CLI 模式的 print() 会崩（2026-09-21）
> console=False 打的 exe，sys.stdout 可能为 None，print() 直接抛 AttributeError。
> 所以 CLI 路径统一走 _safe_print()（内部 try/except），build_pdf 的日志回调也传 _safe_print。
> 另外 main() 的 CLI 分支已用 try/except 包住：出错只写 ~/Desktop/扫描全能王_error.log，不再弹 PyInstaller 的 "Unhandled exception in script" 对话框（否则无人值守批量跑会被弹窗卡住）。
- 产物是 onefile（
扫描全能王.exe，约 114~115MB），可直接发给同事双击用，无需_internal文件夹。 - OCR 模型已随 exe 打包（
models/*.onnx共 13MB 在 exe 内），双击即用，不需要首次联网下载模型。 - 打包后务必实测 CLI（这一条能一次性验出 config.yaml 缺失、缺模块、stdout 崩溃等问题）：
扫描全能王.exe --cli <一张测试图> --out test.pdf --auto-rotate
再用fitz打开 test.pdf 检查页面尺寸是否符合预期（内容横向可读的竖文档 → 595.3×841.9 纵向）。
分发给同事
同事拿到 scan-to-pdf/ 目录后：
1. 运行环境：装了 WorkBuddy 的同事，把 scan-to-pdf/ 放到 C:\Users\<同事用户名>\.workbuddy\skills\scan-to-pdf\ 即被识别；或通过技能导入功能上传 scan-to-pdf.zip。
2. 不用 WorkBuddy 也能跑：scripts/scan_tool.py 任何装了 Python(≥3.8) 的机器都能跑（CLI 或 GUI）。
3. Python 依赖：pip install opencv-python numpy pillow PyMuPDF rapidocr_onnxruntime；脚本自带模型路径解析，直接 python scan_tool.py 即可（模型在包内）。
> 注意：SKILL.md 和脚本都不写死任何用户名/绝对路径，可直接整目录拷贝分发。
