PDF 转图片（全能版 · 跨平台）

PDF 转图片的万能工具：整份转、截取单页、按页拼接、保留公章、缺章自动修复、控制体积——一句话搞定。
不装 Adobe、不付费，基于业界最成熟的 PyMuPDF 渲染引擎，Windows / macOS / Linux 三平台通用，
全程只用 Python（pymupdf + pypdf + Pillow），无任何系统独占依赖。

> 定位：任何"把 PDF 变成图片"的需求都归这个技能管。
> 电子签章/公章保留只是它最强的一点，不是全部。

怎么用它（新手三步走）

这是一个"交给 AI 干活"的工具：你不需要记命令，把 PDF 交给 AI，说人话就行。

对 AI 说一句话就触发（直接复制即可）：
- "帮我把 合同.pdf 转成图片"
- "把 手册.pdf 的第 3 页截出来当封面"
- "把 合同.pdf 前 8 页拼成一张长图，要带公章"
- "备案材料.pdf 转图后公章丢了，帮我补上"

你是开发者/想手动跑 → 用命令行（见下方"完整用法"），三平台命令一致。

> 不用背参数。AI 会根据你的话自动填好页码、格式、拼接选项。

核心能力全景

何时使用（命中即用）

对 AI 说了以下任何一句，就命中本技能：

• 「把这份 PDF 转成图片」→ 能力 1
• 「把第 3 页转成一张图片 / 截图出来用」→ 能力 2
• 「把合同第 1 页和第 5 页拼一起」→ 能力 5
• 「把这几份 PDF 拼成一张长图」→ 能力 4
• 「合同转图片要带公章 / 公章丢了 / 没章」→ 能力 6、7
• 「拼出来太大了，压到 10MB 以内」→ 能力 8
• 「转出来的图模糊」→ 提高 DPI（200~300）
• 任意「PDF → 图片」类需求，包括：手册、说明书、课件、投标文件、电子书、
  合同、盖章文件、备案材料、报表、扫描件存档、做文章配图、做封面图

快速开始（三平台统一）

第一步：装依赖（只装一次，任一系统都一样）

python scripts/install_deps.py        # 一键安装 pymupdf pypdf pillow
python scripts/install_deps.py --check  # 只检查缺不缺

> Windows 若 python 不可用，试试 py -3；Linux 可用 python3。

第二步：一条命令搞定（推荐用一站式入口）

python scripts/pdf_to_image.py 合同.pdf ./out 1 22 150 --stitch 长图.jpg

自动完成：渲染每页 → 保留/自动修复电子签章 → 空白页提示 → 拼成长图。

完整用法

脚本在本技能 scripts/ 下。执行时以技能根目录为基准：python scripts/xxx.py ...。

1. 整份转图片（每页一张）

python scripts/pdf_to_image.py 手册.pdf ./out 1 50 150
# → ./out/page_001.png ... page_050.png

2. 截取某一页转单图（做封面/配图/预览）

# 只要第 3 页，转成 JPG（更小更通用）
python scripts/pdf_to_image.py 合同.pdf ./out 3 3 150 --format jpg
# → ./out/page_003.jpg

3. 截取几页

python scripts/pdf_to_image.py 合同.pdf ./out 3 8 150 --format png
# → ./out/page_003.png ~ page_008.png

4. 整份拼接长图

python scripts/pdf_to_image.py 手册.pdf ./out 1 50 150 --stitch ./手册长图.jpg
# 或分开做：
python scripts/render_with_mupdf.py 手册.pdf ./out 1 50 150
python scripts/stitch.py ./手册长图.jpg ./out --pages "1-50" --quality 90

5. 指定页拼接（只要 1、3、5-8 页）

python scripts/pdf_to_image.py 合同.pdf ./out 1 8 150 --stitch ./精选页.jpg --pages "1,3,5-8"

6. 保留公章 + 缺章自动修复（自动，无需额外操作）

• PyMuPDF 默认渲染就包含数字签名域外观，公章/骑缝章直接带出；
• 万一渲染器没画出来：入口脚本自动检测「页面有签名域但图上无章」，
  换用 annots=False 渲染干净底图 + 提取印章位图合成，全程跨平台，
  不需要 macOS 专属方案。Windows 用户同样享受缺章自动修复。
• 出图后可在 _sealbase/ 子目录查看修复用的底图（可删）。

7. 控制体积（微信等平台 ≤10MB）

stitch 输出若超 10MB 会自动警告，降质量重跑：

python scripts/stitch.py ./长图.jpg ./out --pages "1-50" --quality 85   # 或 80/75

8. 输出格式

--format png|jpg|webp：
- 默认 png（无损、清晰）
- 单页交付常用 --format jpg（体积小、到处能用）
- --format webp 体积最小（网页/存储）
- 拼接输出固定 JPG（平台上传最通用）

9. 空白页检测（自动）

渲染时自动提示疑似空白页，例如：[提示] 疑似空白页: [14, 27]，拼图前可用 --pages
排除，或直接删掉对应 page_014.png。

能力边界与限制（先说清"不能做什么"）

> 原则：本工具只做"PDF → 图片"，不做 OCR 识别、不做 PDF 编辑、
> 不破解加密文件、不联网调用任何服务。

故障排查（报错了？一步步来）

症状 1：提示"找不到 PDF 文件"
1. 检查路径是否写对（中文/空格路径直接写即可）
2. 把文件拖进命令行窗口，自动带出完整路径
3. 确认文件在指定位置（没被移动/删除）

症状 2：提示"无法打开 PDF"
1. 文件加密？→ 需要密码，向文件提供方索取
2. 文件损坏？→ 用 WPS/预览打开试试，能开就"另存为"一份新的再转
3. 后缀是 .pdf 但其实是图片/Word？→ 转成真 PDF 再操作

症状 3：页码输错了
- 不用重来：脚本会自动修正超出范围的页码并提示（如"已自动修正为第 1 页"）
- 只想要一页：start 和 end 填同一个数字，如 3 3

症状 4：转出来模糊
- DPI 太低 → 用 200~300 重跑（150 改成 300）
- 注意 DPI 越高文件越大，微信传图建议 150~200

症状 5：拼接图超过 10MB（微信传不上）
- 降质量：--quality 85 → 80 → 75
- 减少页数：用 --pages 只拼关键的页

症状 6：章丢了 / 没章
- 不用手动处理：入口脚本会自动检测并补章，输出会有 [缺章自动修复] 提示
- 若提示"未能自动补章"：把 PDF 样本反馈给作者（一般是个别厂商的特殊文件）

症状 7：Windows 下命令报编码错误
- 正常不会发生（脚本已做 UTF-8 兼容）；若出现乱码，把终端切到 UTF-8 编码即可

安全与隐私

• 🔒 完全本地运行：所有脚本在你自己电脑上执行，不联网、不上传任何文件
• 🔒 最小权限：只读取你指定的 PDF，只在你指定的输出目录写图片
• 🔒 不收集数据：不发送日志、不统计使用、不调用任何外部 API
• 🔒 不覆盖原文件：源 PDF 永远只读不改，单页图按页码命名不会互相覆盖

FAQ

• Q: 我不会用命令行，能用吗？ A: 能。直接把 PDF 给 AI，说"转成图片"，AI 帮你执行，见开头"新手三步走"。
• Q: Windows 上能跑吗？能处理带章的 PDF 吗？ A: 能。装好 Python 后跑一次 install_deps.py，
  命令与 Mac/Linux 完全一致；带章 PDF 的缺章自动修复在 Windows 同样生效。
• Q: 会不会把章弄丢？ A: 不会。默认渲染即带章；万一缺章，自动检测并用
  「干净底图 + 印章合成」补上（跨平台实现，不依赖 macOS）。
• Q: 支持加密 PDF 吗？ A: 支持，但需要密码。向用户要密码后由 AI 处理；不破解。
• Q: 扫描件（图片型 PDF）能转吗？ A: 能，转出的图就是扫描件本身。
• Q: 拼接长图太长怎么办？ A: 用 --pages 只拼需要的页；或降质量。
• Q: 输出在哪个目录？ A: 你指定的输出目录；渲染单页与拼接图都在那里。
• Q: 转出来模糊怎么办？ A: 提高 DPI（如 300），见"故障排查-症状 4"。
• Q: 大文件会卡吗？ A: 只转需要的页可大幅提速；几百页大文件建议分批渲染。
• Q: 这个工具会联网吗？ A: 不会，纯本地运行，见"安全与隐私"。

参数速查

pdf_to_image.py（一站式，推荐）：<pdf> <outdir> [start] [end] [dpi]
[--format png|jpg|webp] [--quality N] [--stitch OUT.jpg] [--pages "1,3,5-8"] [--margin N] [--no-seal-check] [--no-check-blank] [--verbose]

render_with_mupdf.py（底层渲染）：<pdf> <outdir> [start] [end] [dpi] [--format f] [--quality N] [--no-check-blank]

stitch.py（拼接）：<输出.jpg> <文件列表|渲染目录> [--pages "1,3,5-8"] [--margin N] [--quality N]

install_deps.py（装依赖）：[--check]

决策树（用户说 → 怎么做）

> 拿不准就按最直接的字面需求做；两种都可时（单张 vs 拼接）问一句。

输出规范

• 单页图命名：page_001.png（页码 3 位补零），放用户指定目录
• 拼接图命名：用户要求的名字，默认 长图.jpg 放输出目录
• 修复底图：_sealbase/ 子目录（可删，属中间产物）
• 绝不覆盖源 PDF；单页图不会覆盖同目录同名文件（页码唯一）
• 交付时汇报：出了几张图 / 长图尺寸与大小 / 是否有空白页提示 / 是否自动补章

质量校验（交付前）

1. 公章校验（涉及合同/盖章文件时）：确认红章页签名域区域有红色像素
   （入口脚本已自动做区域红检，修复失败会明确警告）
2. 空白页：看渲染输出的 [提示] 疑似空白页，主动告诉用户
3. 体积：拼接图 >10MB 主动降质并告知

版本说明

v2.1.0（2026-08-10，TRACE 评测优化版）：
- 新手三步走引导：明确"把 PDF 给 AI 说人话"即可使用，一句话触发示例
- 能力边界与限制：加密/损坏/超大文件/模糊/扫描件等特殊情况的预期表现与处理
- 故障排查：7 类常见症状，一步步给出原因与解决（不崩溃、不甩专业术语）
- 脚本边界加固：页码输错自动修正；文件不存在/损坏/加密给出明确修复指引；图片读取失败友好提示
- Windows 缺章处理强调：文档多处明确 Windows 同样支持带章 PDF 与自动补章
- 安全与隐私声明：本地运行、最小权限、不联网不收集
- 扩充触发词（PDF截图/转图模糊/加密PDF/转图失败）

v2.0.0（2026-08-10，跨平台版）：
- 新增一站式入口 pdf_to_image.py：渲染 → 缺章自检 → 自动补章 → 可选拼接，一条命令完成
- 缺章修复跨平台化：不再依赖 macOS Quartz，改用 PyMuPDF annots=False 渲染干净底图 + pypdf/Pillow 印章合成，Windows/macOS/Linux 通用
- 签名域区域红检：窄骑缝章也能准确检出（全页采样会漏检）
- 新增 install_deps.py：跨平台一键装依赖
- 全部脚本加 Windows 控制台 UTF-8 兼容、去 emoji 提示
- 修复：WebP 输出（PyMuPDF 不支持直接保存，自动走 Pillow）、stitch 目录模式自动拼全部页

v1.1.0（2026-08-08，成品版）：新增 --format 输出格式、空白页检测、stitch --pages 指定页拼接、--margin 页间距。