印刷前图片颜色修正
对一张或多张 RGB/CMYK 图片执行印刷级校色，完成五项处理并输出检验报告：
- 色彩平衡通透：Lab 中性轴偏色归零 + 黑场/白场设置 + 中间调 S 曲线 + 中间调饱和度 + 局部清晰度
- 灰平衡正常：中性像素 (Δa, Δb) → 0；CMYK 分色后中性灰 M/C、Y/C 比例对照随网点变化的参考比例
- 人脸肤色一致：肤色像素统一拉向目标肤色轨迹（保留个体明暗与局部起伏），多图可锚定同一目标
- 符合印刷标准：ICC 配置文件分色（无 ICC 时内置 GCR 回退）、总墨量 TAC 限制（可选 GCR 降墨）、灰平衡对照、色域警告、Clipping 检测
- 可付印交付：输出带 ICC 与正确分辨率的 CMYK TIFF，附逐项 PASS/WARN 质量门禁报告
环境准备
依赖 Pillow、numpy（兼容 Pillow 10–12）。务必在隔离虚拟环境中安装，不要污染系统 Python：
# Windows
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
# macOS / Linux
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
下文用 $PY 代指该虚拟环境 python 的路径（Agent 环境优先使用平台自带的隔离 venv），$SKILL 代指本技能目录。
本技能自带常用 ICC（assets/icc/：sRGB、ISOcoated_v2/FOGRA39、GRACoL2006、SWOP2006、PSO Uncoated/FOGRA52），无需系统配置即可分色；脚本仍会按 ICC_PROFILE_DIR 环境变量、系统目录查找同名文件。设 ICC_ONLY=1 可强制只用 ICC_PROFILE_DIR。
工作流程
- 确认需求：承印物（涂布/非涂布）、目标印刷标准、题材（人像 / 风景 / 产品）、是否要求肤色统一。
- 分析：先跑
--analyze-only，读 JSON 判断偏色强度、肤色占比、输入模式与 DPI。 - 修正：按承印物选
--standard，按题材选参数或--preset landscape。 - 验证：读报告的「质量门禁」区，逐项确认；打开
<stem>_before_after.png目检。 - 交付：用
present_files交付*_corrected_rgb.png（预览）、*_print_cmyk.tif（印刷稿）、*_before_after.png、*_report.txt。
任何一步失败都停下来向用户报告原因，不要带病交付。不达标项如实报告，不宣称"完全符合"未通过项。
命令
# 分析（不修正）
$PY $SKILL/scripts/correct_image.py 输入图.png --analyze-only
# 默认修正（涂布纸 / ISO Coated v2 FOGRA39 / TAC 300%）
$PY $SKILL/scripts/correct_image.py 输入图.png --outdir 输出目录
# 指定标准与参数
$PY $SKILL/scripts/correct_image.py 输入图.png --standard gracol --tac 300 --skin-strength 0.8 --outdir 输出目录
# 风景/风光类：通透、饱和度均衡、反差加大、提亮阴影、加大白度，按 GRACoL2006
$PY $SKILL/scripts/correct_image.py 输入图.png --preset landscape --outdir 输出目录
# 艺术暖色调场景：减弱偏色去除，避免误中和
$PY $SKILL/scripts/correct_image.py 输入图.png --balance off --outdir 输出目录
# 组图（合影分图/画册跨页）：按第一张的肤色目标锚定全部，得到真正一致的肤色
$PY $SKILL/scripts/correct_image.py 01.jpg 02.jpg 03.jpg --skin-anchor first --outdir 输出目录
# 非涂布纸 + GCR 降墨（保留暗部密度，印厂常用）
$PY $SKILL/scripts/correct_image.py 输入图.png --standard fogra52 --tac 270 --tac-mode gcr --outdir 输出目录
# 用印厂/客户自有 ICC 分色；输入是 AdobeRGB 可显式指定（默认也会自动读内嵌 ICC 转换）
$PY $SKILL/scripts/correct_image.py 输入图.png --cmyk-profile 客户印刷机.icc --input-profile AdobeRGB1998.icc --outdir 输出目录
# 自检（回归验证，建议改动脚本后执行）
$PY $SKILL/scripts/selftest.py
预设
--preset landscape（风景）：自动按 GRACoL2006 分色，提亮阴影（target_black 0.045）、加大白度（target_white 0.985）、反差 0.12、中间调饱和度 +10% 并对过饱和像素回拉（色度上限 48）、清晰度 55、自动关闭肤色统一。- 显式传入的同名参数以用户传入为准，
--flag=value写法同样生效。
参数说明
| 参数 | 默认 | 说明 |
|---|---|---|
--standard |
fogra39 |
fogra39=ISO Coated v2(FOGRA39)；fogra52=PSO Uncoated v3(非涂布)；gracol=GRACoL2006；swop=US Web Coated SWOP；china=国标 GB/T 17934.2（采用 ISO 12647-2，按涂布纸处理）；none=仅 RGB 修正不分色 |
--tac |
300 | 总墨量限值 %。涂布 300-330；非涂布 260-280；新闻纸 240-260 |
--tac-mode |
scale |
TAC 超限处理：scale 按比例削 CMY（暗部会变浅）；gcr 把超出量转成 K（保留暗部密度，印厂常用） |
--gcr |
0.55 | 内置 GCR 分色的灰成分替代量，仅在无 ICC 时使用 |
--balance |
auto |
偏色去除：auto 自动 / off 关闭（保留艺术色调） |
--cast-strength |
自动 | 偏色去除强度 0-1（强偏色自动 0.9，弱偏色 0.35） |
--contrast |
0.05 | 中间调 S 曲线强度，0–0.159（超上限自动钳制）。0.05≈中间调斜率×1.31，0.159≈×2 |
--saturation |
0.06 | 中间调饱和度增量 |
--chroma-cap |
0（关） | 饱和度均衡：超出该色度的像素轻微回拉（风景建议 48） |
--gamut-fit |
on |
超出 sRGB 色域的像素：on 回拉色度保住层次；off 直接裁通道 |
--level-lo |
0.35 | 黑场百分点 |
--level-hi |
99.65 | 白场百分点 |
--target-black |
0.02 | 黑场输出亮度；提亮阴影可调高（如 0.045） |
--target-white |
0.96 | 白场输出亮度；加大白度可调高（如 0.985） |
--clarity |
40 | 局部清晰度 %（0 关闭；在 Lab 亮度通道做 USM，不破坏色相） |
--clarity-radius |
1.0 | 清晰度半径 |
--skin |
auto |
肤色统一：auto / off |
--skin-strength |
0.55 | 肤色统一强度 0-1（组图需要强一致时调 0.8） |
--skin-anchor |
each |
多图肤色目标：each 每图各自算；first 以第一张的目标锚定全部（组图肤色真正一致） |
--target-skin |
无 | 强制肤色目标 a*,b*（如 14,19），覆盖自动轨迹 |
--dpi |
自动 | 输出分辨率。默认沿用输入 DPI，输入无分辨率则按 300 写入并提示；印刷交付物必须带分辨率，故总会写入 |
--cmyk-profile |
无 | 指定输出 CMYK 的 ICC（印厂/客户自有配置文件），优先于 --standard 查找 |
--input-profile |
无 | 指定输入 RGB 所在色彩空间（如 AdobeRGB）。默认自动读内嵌 ICC，非 sRGB 时先转 sRGB |
--preset |
none |
landscape=风景预设 |
--outdir |
输入同目录 | 输出目录 |
--analyze-only |
关 | 仅分析并输出 *_analysis.json |
可一次传入多个输入文件批量处理，参数对全部文件生效。
输出文件
| 文件 | 内容 |
|---|---|
<stem>_corrected_rgb.png |
修正后 RGB 预览（带 DPI） |
<stem>_print_cmyk.tif |
印刷稿（LZW 压缩，内嵌 ICC，带 DPI） |
<stem>_before_after.png |
前后对比图 |
<stem>_report.txt |
人读报告（含质量门禁逐项判定） |
<stem>_report.json |
机读报告（含全部门禁与中间量） |
<stem>_analysis.json |
仅 --analyze-only 时输出 |
质量门禁（报告逐项判定 PASS / WARN / N-A）
| 项目 | 合格标准 | 说明 |
|---|---|---|
| 中性灰偏差 | 修正后中性偏差 |Δa|, |Δb| ≤ 2.0 |
灰平衡正常 |
| 肤色一致 | 修正后肤色均值更贴近目标轨迹（a* 8-20、b* 12-26），且标准差未增大 | 肤色一致 |
| 灰平衡比例 | 中间调（C 网点 30-62%）M/C、Y/C 与随网点变化的参考比例偏差 ≤ 0.05 | CMYK 灰平衡 |
| 总墨量 | tac_max ≤ --tac |
防过墨 |
| 色域警告 | gamut_warning_pct < 5% |
防印刷色偏色；内置 GCR 模式无法评估，记为 N-A |
| 裁剪 | 输出 RGB 任一通道贴 0/255 的像素 ≤ 1% | 防细节丢失 |
标准与参考
- 印刷标准体系、承印物/TAC、灰平衡表、肤色目标、ICC 分色要点：见
references/print-standards.md。 - 输入 CMYK 图：有内嵌 ICC 时按 ICC 转 RGB，无 ICC 时普通转换并在报告中标记。
- 找不到 CMYK ICC 时自动回退内置 GCR 分色，报告中
method=builtin_gcr，应提示用户安装官方 ICC 以获得最佳分色质量。
常见问题处理
- 强偏色或艺术暖色调：用
--cast-strength 0.3或--balance off，不要强行中和。 - 肤色要更强一致：
--skin-strength 0.8；完全不改肤色用--skin off。 - 多人组图肤色统一：把各图一次传入并加
--skin-anchor first，即可得到一致的肤色目标（逐张单独跑时目标会按各图明度自动变化，不完全一致）。 - 非人像题材（食物、木质、产品图）：
--skin off。报告里「肤色一致」一项会提示掩膜占比，占比过高即在提醒误判。 - 过饱和/欠通透：降低
--saturation、--contrast，或提高--clarity。 - TAC 超限：改用
--tac-mode gcr（保住暗部密度）或降低--tac、改用 GCR 更强的分色方式。 - 高光/暗部丢细节（裁剪 WARN）：把
--target-white调低（如 0.96）、--target-black调高（如 0.03），或降低--contrast/--clarity。 - 饱和色印刷发暗：色域本身收不下，接受压缩（
--gamut-fit on已按色度回拉处理）或降低该色饱和度。 - 大图慢：约 12MP 需 20s、23MP 需 40s（纯 CPU）。批量前先单图验证参数。
版本变更（1.0.x → 1.1.0）
行为有变化，重跑旧图会得到不同结果：
- 中间调对比度修正为真正的 S 曲线。1.0.x 用的是
y = x + k·sin(πx)，那是"整体提亮"（中间调抬亮最高 +k）而非加反差，且高光斜率反而下降。现改为y = x − k·sin(2πx)，并在图像自身黑白场范围内归一化（枢轴取范围中点而非固定 L*=50）。旧版在大反差/黑白场已拉开的图上会造成高光与暗部大面积裁切。 - 新增色域回拉（
--gamut-fit，默认开）：超出 sRGB 可表示范围的像素按比例回拉色度，不再硬裁通道。实测产品图裁切由 2.15% 降到 0.04%。 - 清晰度收口：USM 后的亮度被限制回目标黑白场，不再重新制造暗部/高光裁切。
- 灰平衡参考比例改为随网点变化（0.76→0.90 插值，仅中间调参与判定）。旧版固定 0.78 会在 L*25/L*80 误报 WARN。
- 输出 DPI 恒写入（TIFF 缺省是 1 dpi，印厂会误判尺寸）；新增
--dpi。 - 修复 CMYK 带 ICC 输入路径。Pillow ≥10 的
profileToProfile第 4 个位置参数由outputMode改为renderingIntent，旧写法抛异常后被静默降级为普通转换 —— 相当于 ICC 从未生效。已改用关键字参数。 - 修复
--flag=value写法被--preset忽略（如--preset landscape --standard=swop之前会静默保留 gracol）。 - 新增：多图批处理、
--skin-anchor/--target-skin、--tac-mode gcr、--cmyk-profile/--input-profile、非 sRGB 输入自动转 sRGB、裁剪检测与门禁汇总、Windows 控制台 UTF-8 输出、scripts/selftest.py自检。
