PDF 印前色彩管理与打样调图工具

概述

PDF 印前色彩审计与设备重分离

纯 Python 引擎，直接读写 PDF 内容流与色彩空间定义，走真实 ICC（littleCMS）。不依赖 Adobe 软件、不依赖 GUI。

什么时候用 / 不用

用：

• 「这份 PDF 有什么色彩问题？」→ 审计
• 「这文件里有哪些专色？面积多少？」→ 审计
• 「TAC 超了吗 / 颜色印得出来吗？」→ 审计
• 「把它重分离到我们那台数码机的 ICC」→ 重分离
• 「送这个设备印，外观要跟 FOGRA39 一致」→ 重分离
• 「这个专色能不能用四色替代」→ 审计报告里有「四色逼近 ΔE」入口指标

不用（走别的路子）：

• 在 Photoshop / Illustrator 里改图 → 用 色彩管理 技能（ExtendScript 路线）
• 位图内部逐像素改色 → 本工具不做（会明确标注，不静默跳过）
• 只想预览 / 打印 PDF → 普通 PDF 工具即可

环境准备（第一步，必须做）

需要 Python 3.9+ 和两个包：pymupdf、pillow。先拿手边的 python 自检：

python -c "import pymupdf, PIL; print('ok')"

按结果走：

• 打印 ok → 就用这个解释器，不必再装。
• 报 ModuleNotFoundError → 试 WorkBuddy 自带的托管环境（Windows 一般在

~/.workbuddy/binaries/python/envs/default/Scripts/python.exe，macOS / Linux 在 ~/.workbuddy/binaries/python/envs/default/bin/python）。

• 仍不行 → 建一个专用 venv（一次性）：

python -m venv ~/.workbuddy/binaries/python/envs/default
~/.workbuddy/binaries/python/envs/default/bin/pip install pymupdf pillow
# Windows 改为：~/.workbuddy/binaries/python/envs/default/Scripts/pip.exe install pymupdf pillow

下文用两个简写。执行时展开成你自己机器上的真实路径（见「已知坑 #1」，不要用 shell 变量）：

• PY = 上面自检通过的解释器
• SD = 本技能目录下的 scripts/

脚本之间靠同目录 import 协作，因此从任何工作目录调用都可以，只有输出文件走当前目录。

ICC 目录：程序会自动在 Windows / macOS / Linux 的标准色彩目录里找 profile，也可用环境变量 PREPRESS_ICC_DIR 覆盖。看本机有哪些：

PY SD/colorlib.py --list-profiles

默认基准条件是 CoatedFOGRA39.icc（ISO Coated v2）——本机若没有，需自行安装，或用 --ref / --profile 换一个。

一、印前色彩审计

PY SD/prepress_audit.py "稿件.pdf" --all-pages 
    --json "audit.json" --html "audit.html"

产出 JSON（机读）+ HTML（可交付体检报告）。报告含：

• 逐页色彩清单 —— 矢量 / 文字 / 图像 / 专色分开列，带色块与原始色空间值
• 专色盘点 —— 色板名、备色空间、网点档位集合、出现页、面积占比、100% 色值(LAB/hex)、四色逼近 ΔE
• 超色域标记 —— RGB→目标 CMYK→RGB 往返 ΔE 超阈值即判印不出来
• TAC 总墨量 —— 逐色 + 逐页峰值，超阈值告警
• 附加预检 —— 图像有效 DPI、字体嵌入、色板名一致性（PANTONE 285 C vs PANTONE285C）、未使用的专色声明

关键参数：

专色参考库（需自备，技能包不带数据）

本技能不附带任何第三方商用色值（Pantone 等品牌的色值属第三方专有数据，不适合随包分发），只带一个空模板。查找顺序，先命中先用：

1. 环境变量 PREPRESS_SPOT_LIB → 指向你的色库文件
2. 技能根目录的 library/spot_ref.json（或 pantone_ref.json）—— 此目录不会被打包分发
3. SD/pantone_ref.json —— 空模板

三处都没有真实条目时，报告会在 warnings 里明确写出（library_entries: 0），不会静默变成「专色没问题」。色库结构：

{ "colors": { "色板名": { "hex": "#RRGGBB", "lab": [50.9, 74.8, 5.6], "cmyk": [0.09, 0.87, 0.25, 0.03] } } }

hex 是主数据；若有实测 lab 或指定条件下的 cmyk，会优先采用（精度更高，绕开 sRGB 折算误差）。也可用 --library 临时指定一次。

二、设备重分离（送自定义输出设备前）

问题：同一份按 ISO Coated v2 (FOGRA39) 组织的「四色 + 专色」PDF，送到不同设备（数码机、宽幅机）结果各不相同。

做法：送设备之前把色彩数据重算成该设备的分离值，使设备输出外观 ≈ FOGRA39；同时把设备 profile 以 OutputIntent 嵌入，RIP 据此按设备原生值解释。

PY SD/device_remap.py "稿件.pdf" "送印.pdf" 
    --device "你的设备.icc" 
    --all-pages --json "remap.json"

PY SD/remap_report.py "remap.json" "remap_report.html"     # 逐档位 ΔE + ICC 模拟色块

--device 与 --ref 既可以给绝对路径，也可以只给 ICC 文件名或关键词（如 --device EpsonWideCMYK_Ver2.icc），程序会自动在标准 ICC 目录里匹配；找不到时会列出已探测的目录而不是抛一句看不懂的异常。

输出设备的 ICC 有什么要求（每个作业都可能不同）

能用的档：ICC class=prtr（输出档）、数据色彩空间=CMYK。每个作业换一个档只需换 --device，无需改任何代码；程序会先读 ICC 头部做体检，不合格的档在前置阶段就拦下并说明原因，不会让 lcms 抛出 cannot build transform。

每次作业用的是哪个档，会同时写进控制台日志与 JSON 的 device_profile（档名 / class / 数据空间 / PCS），并嵌为 PDF 的 OutputIntent，可追溯。

覆盖结构：k/K 四色算子、/DeviceCMYK 别名的 scn/sc、DeviceN 单色专色版、/Indexed /DeviceCMYK 调色板、sh 渐变的分离色空间、g/G 灰度显式化、专色 tintTransform（256 级 Type 0 采样，全档位而非端点）。

⚠️ 文字块（BT..ET）内的直接 k/K 四色着色不在覆盖内（见「已知坑 #10」）。

灰度文字与专色文字有覆盖（分别走流级显式化、专色定义改写）。

关键参数：

三、精确改造（换专色 / 按 LAB 调色，可选）

PY SD/pdf_recolor.py spot-swap in.pdf out.pdf --name "PANTONE 285 C" --to-spot "PANTONE 275 C"
PY SD/pdf_recolor.py spot-lab  in.pdf out.pdf --name "PANTONE 285 C" --lab "38,5,-50"
PY SD/pdf_recolor.py recolor   in.pdf out.pdf --bbox 270,330,490,530 --from "#218C59" --to "#5B2D8E"
PY SD/pdf_recolor.py inspect   in.pdf --all-pages          # 颜色盘点

LAB 一律 D50。改动会给出前后 ΔE2000、目标 CMYK 分色值、sRGB 色域提示。

已知坑（每次都过一遍，别省）

1. 解释器：WorkBuddy 的托管 Python 通常没有 pymupdf，要用手边自检通过的解释器

（多半是 envs/default 里的 venv，见「环境准备」）。沙箱下 PY=...; "$PY" xxx 这种「赋值 + 立即展开」有时报 decisionRecord missing→ 直接写全路径，不要用 shell 变量。

1. 输出文件被占用（Windows 文件锁）：预览器开着旧输出时保存会报

cannot remove file ...: Permission denied。先删旧文件再重跑（rm -f 通常能解开瞬时锁），或换输出文件名。

1. DeviceGray 极性：PDF 里 DeviceGray 0.0=黑、1.0=白，故 K 版网点 = 1 − 灰值。

已按此实现（曾反色，v3 修复）。换新文件后仍应核验一次：输出里 0 g 必须变成 0 0 0 1 k，不应出现 0 0 0 0 k。

1. 专色定义内联在字典里（v3 修复）：Resources/ColorSpace 可能写成

<< /CSA /DeviceCMYK /CS1 [/Separation …] >>。写回必须按键替换，不能整体覆盖该字典对象，否则同级条目（CSA）消失、文件渲染报cannot find ColorSpace resource。脚本已按此处理，若见该报错就是回归了。

1. K-only（纯黑）数值不变是刻意的：0 0 0 v k 代表文字 / 线稿，靠单块黑版成像；

走 ICC 设备链会被 lcms 重建成 CMY 三色灰（实测 K25% → 0.216 0.165 0.161 0），细字 / 细线因套印误差出彩边。代价是外观微移（K25% ΔE 0.78 … K100% ΔE 3.37，报告逐条记录）。要严格外观一致用 --no-preserve-k。另有 1 LSB 写入门槛（|Δ|≤0.004 不写），所以部分非 K 色也保持原值——这不是漏改。

1. 重分离后的 PDF 不能用普通看图软件验外观：PyMuPDF / Acrobat 会拿通用

CMYK→RGB 解释设备值（实测整页平均像素差 39/255）。验证以报告的 ICC 模拟色块或 RIP / 打样为准。

1. ICC 输出档的 B2A 表会重做分色（GCR）：即便「设备 = 基准」，CMYK 数值也会变

（K100 还原成四色黑）。恒等只在外观层成立，同 profile 往返残差约 1~2 ΔE。

1. 中文路径：脚本内部处理中文没问题，但命令行传中文路径必须加引号。
2. 设备 ICC 必须「输出档 + CMYK」（每个作业都可能换档，最容易踩）：

传错档型以前只会得到 lcms 的 cannot build transform（毫无信息量），现已在 colorlib.check_cmyk_profile() 前置体检并说明原因。要点：显示器档（mntr/RGB）、设备链接档（link）、GRAY/RGB 输出档、5 通道以上多色档都不行。设备链接档本身已是一条完整 CMYK→CMYK 转换，应在 GMG/厂商 RIP 侧应用。--device 接受绝对路径或文件名/关键词；中文名、临时目录都可。

1. 文字块（BT..ET）内的直接 k/K 四色着色未覆盖：文字靠 Tj 着色、无路径，

不进入算子列表。灰度文字与专色文字有覆盖（走流级显式化 / 定义改写），唯独四色文字没有 → 详见 references/known-issues.md 的「已知缺口 G1」。换新文件后用 scripts/probe_text_colors.py 数一次，先把风险量出来再交付。

判据口径与边界

• ΔE2000 ≤ 2 为印刷级一致（>2 报告标红）；最终以设备打样为准。
• 超色域是相对判据：换输出 profile 结论会变，不等价于 Adobe 的绝对判定。
• 面积占比 = 着色算子包围盒面积和 ÷ 页面面积，重叠未去重，是估算值。
• 覆盖范围：页面内容流 + 全部 Form XObject（递归下钻）+ 软蒙版透明组（SMask→G）
  • 图像 XObject 的 /ColorSpace（Indexed→Separation 分色版位图承载的专色）+ 渐变端点色。
• 不做：位图内部逐像素分析、渐变中间色逐点判定、多色 DeviceN（≥2 色版）的二维采样重分离、

GMG 多通道分色（MultiChannelImage，整页位图色版）的重分离、文字块（BT..ET）内直接 k/K 的四色着色（见「已知缺口 G1」）（均如实记录，不静默跳过；用 scripts/probe_text_colors.py 可量化）。

• 专色承载有三种形态，盘点时必须三种一起看，否则会漏：

① 内容流 CS/SCN 算子；② 图像 XObject 的 /ColorSpace（分色位图，无算子）；③ 只被渐变引用的色彩空间。审计与 device_remap 的专色个数对不上，就是漏了一种。

• 专色参考库由使用者自备（技能包只带空模板）。有库时，「四色逼近 ΔE」是库中参考值与

文件实际外观的差；库为空时不给出该指标，并在 warnings 里说明。生产定稿以官方色卡 / 光谱为准。

交付习惯

一次完整处理给三件套，并明确区分验证程度：

1. 审计报告 audit.html
2. 重分离验证报告 remap_report.html（逐档位 ΔE + ICC 模拟色块）
3. 送印文件 out_*.pdf（已嵌 OutputIntent）

汇报时说清：脚本算出的（ΔE / TAC / 面积）vs 需真机或打样确认的（最终外观）。另外必须问用户要实际输出设备的 ICC——不要拿演示设备当真机设备。

自检（改动脚本后必跑）

PY SD/make_audit_sample.py && PY SD/verify_audit.py     # 审计器 22 项断言
PY SD/test_guard.py                                     # 备色空间归一 + 退化曲线护栏 19 项断言
PY SD/make_remap_sample.py                              # 生成重分离样例
PY SD/device_remap.py sample_remap.pdf out.pdf --device "<某设备.icc>" --all-pages --json t.json
PY SD/verify_out2.py sample_remap.pdf out.pdf           # 输出结构证据
PY SD/probe_text_colors.py "稿件.pdf"                    # 文字块着色风险量测（G1）

verify_audit.py 全 PASS 才说明审计判据没被改坏。test_guard.py 全 PASS 才说明「备色空间识别不了时会拦下、不会把专色写成不上墨」。verify_out2.py 重点看：原文件 tintTransform 是 Type 2 / 输出应变成 Type 0 采样 16-bit 4 输出，且 Resources/ColorSpace 里的同级条目（如 CSA）仍在。

换新稿件的第一道闸：device_remap.py … --dry-run 看 ΔE。任何专色出现 ΔE ≈ 100 或均匀的大偏移，先怀疑备色空间没被识别 —— 别直接出文件。

参考

• references/methodology.md —— 完整方法学、真实文件实测数据、设计取舍（长文，需要背景时读）
• references/known-issues.md —— 已修缺陷清单与边界（排查回归时读）
• scripts/colorlib.py —— 色彩引擎，可直接当 CLI 查色：

PY SD/colorlib.py --spot "PANTONE 285 C" / --hex "#0072CE" / --list-profiles