Photo Cinematic Grade

---
name: photo-cinematic-grade
description: 照片电影感调色、低饱和冷暖分离、先保原片再调色。用确定性像素处理而不是生成式重绘；先确认用途与色彩输入，输出带 sRGB ICC 的新图和隐私优先的参数/QA 边车。支持 8-bit SDR JPEG/PNG 的 render、固定三选候选小样 candidates 与数值 QA，以及原尺寸前后对比 compare；card、LUT 尚未实现。不负责 RAW 显影、修图换景、冲印交付或精确复刻电影/胶片。
category: photography
version: 0.21.0
status: draft
priority: P2
compatible_agents:
  - claude-code
  - codex
  - cursor
  - codebuddy
  - nestudy
---

# Photo Cinematic Grade

把摄影者已拍下的像素调成克制的电影感，不替摄影者换掉画面。
脚本负责像素、参数和数值，摄影者决定氛围与是否接受。

## 当前能力与未完成项

当前完成 render 基础、候选小样、前后对比，以及供后续管线使用的浮点色彩内核。新内核尚未接管 CLI render，不代表整个 skill 已验收完成。

- **已实现**：`scripts/cinegrade.py render`、`looks`、`candidates`（中性基线 + 两个风格的固定三选小样）、`compare`（左原图、右调色的原尺寸并排）、确定性整数调色、三份基础配方、独立 `image_io.py`、数值 QA、隐私边车、原件与已有输出保护。
- **尚未实现**：`card`、`lut` 命令，以及相应的集成测试；计划中的 analyze/sheet、浮点线性光与 OkLCh 的端到端管线、六个规定风格、完整 QA、JPEG/16 位输出仍待补齐。不得暗示它们已经可用，不能用生成图或口头描述冒充实际小样。候选固定列出而不自动排名或替摄影者选定。
- CLI 不提供局部蒙版、人物/肤色识别、白平衡或曝光自动矫正、颗粒、暗角、锐化、降噪、裁剪。避免把调色变成无法追溯的整图修饰。

## 新增浮点色彩内核（0.4.0）

`scripts/color_core.py` 重建计划 3.4 的基础像素运算，供六风格管线后续接入。
已实现扩展 sRGB 传递函数、线性 sRGB 与 Oklab 双向转换、OkLCh 极坐标转换，以及端点固定的 Oklab 亮度曲线。
调色阶段保持 float64，不做中间量化、不钳位色域外数值。独立终端 quantize_srgb8 显式转成 uint8，
拒绝超色域输入，只饱和处理新增噪声造成的越界。纯数值 API 不读照片、不写文件、不改 ICC。
需要 numpy，当前测试环境为 numpy 2.0.2；原有 CLI 读写仍按既有流程执行。

曲线是本轮重新设计的工程实现，历史 0.4.1 原型未找回，也未移植。
公式与标准矩阵来源见 `references/grading-research.md` 的浮点内核一节。
contrast、strength 都要调用者显式传入；此 API 的 strength 为 0..1，与旧 CLI 的 0..100 分开。
不增加默认配方。工程曲线尚未经摄影者视觉确认，不把数学测试当作六风格效果验收。

目前 render/candidates/compare 仍用原有整数算法和三份配方，输出像素契约不变。
亮部色度滚降、分色相变换、分离色调与减法密度均已有独立浮点实现，见下节；最终抖动量化已有独立 API，见 0.9.0 一节；色域映射与占比已有独立 API，见 0.10.0 一节；显式选区肤色限幅已有独立 API，见 0.11.0 一节；线性光 bloom 已有独立 API，见 0.12.0 一节；有色边缘光晕已有独立 API，见 0.13.0 一节；线性光单色颗粒已有独立 API，见 0.14.0 一节；自动肤色选区、暗角和六风格集成仍待完成。
此内核不恢复输入已丢失的高光，也不让当前 CLI 支持 RAW、HDR 或 16 位文件。

## 高光色度滚降（0.5.0）

`color_core.highlight_rolloff_oklab(lab, start=..., strength=...)` 补齐计划 3.4 的高光去色阶段。
将经过亮度曲线的 Oklab 送入此函数，高光的 a/b 同比例缩小，保持 L 和非零色度的色相。
低于或等于 start 的像素原样返回；strength=0 对全部像素恒等；满强度在 L=1 时色度降为零。
这一步直接计算颜色，不量化、不读写图片，不代替色域映射或肤色保护。

start 必须显式给出，范围 [0,1)；strength 必须显式给出，范围 [0,1]。
start 是曲线后 Oklab L 的起点，不能当作编码 sRGB 码值或曝光 EV。
计划未规定起点与完整配方，脚本不猜默认值，也不自动选择一组参数。
新函数的工程曲线及推导见 `references/grading-research.md`，尚待真实照片与摄影者确认。
它没有接管 CLI，render/candidates/compare 仍使用原有整数管线和三份配方。

16 项新增合成数学测试覆盖手算值、高光单调去色、色相/亮度不变、强度恒等、端点平滑、
极窄肩部与接近白点的数值稳定性，以及与现有浮点内核串接。测试取值仅用于数学验证，
不把通过测试当作六风格区分度、肤色或 LUT 验收；不声称移植了历史 0.4.1 原型。

## 分色相调色内核（0.6.0）

`color_core.hue_band_adjust_oklch` 实现计划 3.4 的分色相调整。在调用者明确给出的
环形色相窗口内旋转 hue、缩放 chroma，保持 Oklab L；窗口外和恰好中性的像素不动。
窗口跨越 0°/360° 时仍连续，中心与两端的权重斜率为零。没有中间量化或 RGB 钳位。
这使后续风格能够分别处理蓝、绿、红等色相，而不必对整幅照片统一染色。

所有创意参数均为必填：center 是窗口中心角，width 是支撑半宽 (0,180]°，
hue_shift 是 [-180,180]° 的转角，chroma_scale 为非负倍率，strength 为 [0,1]。
强度为零或转角零且倍率一时精确恒等；C=0 不染色。只改色度时保持输入 hue 表示，
发生旋转时将 hue 归一到 [0,360)。色度变成零后 hue 无物理定义，不要求数值为零。
多次调用依次作用于上一次输出的色相，顺序可能影响重叠窗口。

这是依据计划重新实现的工程曲线，参数没有默认值，未找回或移植历史 0.4.1 原型。
21 项新增测试使用明确标注的合成数学输入，只验证数值契约，不代表摄影者确认配方。
窗口外的暖色能保持原值；脚本仍不识别人脸或肤色，不能据此承诺肤色护栏已通过。
函数尚未接管 CLI；六风格配方、真实照片与完整管线验收仍待完成。
推导、串接方式与边界见 `references/grading-research.md` 的同名一节。

## 分离色调内核（0.7.0）

`color_core.split_tone_oklab` 补齐计划 3.4 的分离色调像素运算。按显式给定的 Oklab
亮度分界 balance，把暗部和亮部推向各自的色相；保持 L，不量化、不钳位 RGB。
每区的色度增量在区间中点最大，向黑点、分界和白点平滑降到零，因此中性黑白不被染色。
区间内部的中性灰可以染色。新增量以 a/b 向量相加，原有彩色像素也可能改变色相。

六个参数全部必填，没有默认配方：shadow_hue、highlight_hue 为周期角度，
shadow_chroma、highlight_chroma 为非负的峰值新增 Oklab 色度，balance 为 (0,1) 内的
Oklab L，strength 为 [0,1]。色度参数是增量，不是目标饱和度；balance 不是 EV 或像素百分位。
strength=0 或两个色度增量都为零时返回精确副本，输入验证仍执行。

这是按计划重新实现的工程变换。四次包络系数由端点与斜率约束推导，细节见
`references/grading-research.md`。它没有恢复历史 0.4.1 原型或复现原型配方/评分。
20 项新增合成数学测试只验证像素数学，测试参数未获确认为摄影配方。
函数不自动识别人脸或保护暖色主体；真实肤色护栏、六风格及完整管线仍须单独验收。
原 CLI、输入/输出格式和三份整数配方不变；没有向原片应用测试参数。

## 减法密度内核（0.8.0）

`color_core.subtractive_density_oklch(lch, density=..., strength=...)` 推进计划 3.4 的
减法密度像素运算。正 density 让有色像素变深，负 density 让它变亮；C 与原 hue 表示不变。
黑白端点、恰好中性、density=0 或 strength=0 保持原坐标，返回独立 float64 数组。
参数全部必填，没有默认摄影配方。density 是每单位 OkLCh 色度对应的亮度 log-odds 减量，
strength 为 [0,1]；它不代表曝光 EV、测得的胶片光学密度或最终饱和度。

本函数按计划重新实现，数学定义与数值稳定分支见 `references/grading-research.md`。
历史 0.4.1 原型未找回，未移植其公式或复现其成绩；新公式尚待真实照片与摄影者确认。
20 项新增合成数学测试覆盖正负密度、强度、恒等、端点、色相/色度保持、独立高精度参考、
极端数值、微小负密度不能反向压暗的回归，以及已有色彩路径串接。测试参数不作为已确认配方。
函数尚未接管 CLI，不做肤色识别、RGB 色域映射或量化；保持 C 的同时降低 L 仍可能超出 sRGB。
真实照片、六风格完整配方与端到端验收仍待完成。

## sRGB 三角抖动与最终量化（0.9.0）

`color_core.quantize_srgb8(encoded, amplitude_lsb=..., seed=...)` 补齐计划 3.4 的
编码 sRGB 域三角分布抖动与最终 8-bit 量化。它把已经完成色域处理的浮点 RGB 转成 uint8，
不会接管现有 CLI，不在中间调色阶段提前量化。历史 0.4.1 原型未找回，此函数为重新实现。

amplitude_lsb 和 seed 都必填。幅度以 8-bit 码值为单位，范围 [0,1]，表示三角噪声峰值；
0 表示关闭抖动。没有默认摄影配方，也不把测试幅度当成摄影者已确认的设置。
种子为非负整数，使用独立 PCG64，不影响 NumPy 全局随机状态。
同一输入形状、参数和 NumPy 环境下返回相同像素字节；不承诺任意分块后仍与整图相同。

输入必须是已编码且落在 [0,1] 的 sRGB，包括一 ULP 越界也拒绝，不暗中裁掉调色色域损失。
仅饱和处理由新增噪声引起的端点越界，再最近整数舍入，半整数向上。输入不变、返回独立数组。
开启抖动可使纯黑或纯白向内改变一码；强度零或原图恒等路径须明确使用 amplitude_lsb=0。
不保证端点附近的无偏性，不把抖动当作胶片颗粒，也不凭本测试承诺断层护栏已经通过。

20 项新增合成测试覆盖手算舍入与半码边界、全部 256 个码值恒等、局部随机流、三角分布概率、
幅度和越界拒绝、重复像素字节、只读/非连续输入，以及已有浮点颜色路径串接。
完整套件共 181 项独立测试；重复入口不重复计数。数学夹具不代表真实照片或完整六风格验收。
色域映射、肤色保护、空间纹理、六风格配方与 CLI 集成、真实照片和 LUT 仍待完成。

## 线性 sRGB 色域映射与占比（0.10.0）

`color_core.gamut_map_linear_srgb(linear)` 返回映射后的独立 float64 RGB 数组及 QA 字典，
补上计划 3.5 的色域映射像素占比能力，也让已有浮点调色结果可以显式进入最终量化阶段。
它接受有限的线性 sRGB D65 三元组或图像数组，保留所有已在 [0,1] 内的像素。
超色域像素向相同相对亮度 Y 的中性灰收缩，取射线与 sRGB 立方体的首个交点。
Y 超出 [0,1] 时整次调用拒绝，要求上游明确处理明暗，不悄悄改曝光。

这是依据标准亮度系数与几何约束重新实现的工程方法，无默认摄影配方。
历史 0.4.1 原型未找回，未移植或复现其成绩。该方法在浮点误差内保持线性相对亮度与
RGB 色差向量方向，不保证 Oklab L/h 恒定；视觉效果与肤色仍须验证。
解析压缩后的浮点端点修正会单独报告通道样本数与最大修正量，不能把原始越界直接裁掉后报零。

QA 按像素计数，每个像素最多一次，包含一 ULP 的越界。返回 `pixels_total`、`pixels_mapped`、
`mapped_fraction` 及端点修正统计。占比严格大于 10% 时警告，恰为 10% 不警告，阈值来自计划 3.5。
统计只覆盖本次映射，不追溯 ICC 阶段的损失，不生成整项验收通过结论。
该纯数值函数不读写照片、不做 gamma/ICC 隐式转换、不使用随机数、不接管旧 CLI。

21 项新增合成测试使用精确有理数参考、RGB 网格和浮点边界验证映射与占比，完整套件 202 项通过。
测试过程中发现 Fortran/转置图像展平后写入副本、返回数组未映射的问题，补充失败回归后以连续独立
工作数组修复；原断言未削弱。测试材料与参数均非真实照片或已确认配方。
肤色保护、空间纹理、六风格与 CLI 集成、真实照片和 LUT 仍需按计划继续，整个 skill 尚未验收。

## 显式选区肤色保护（0.11.0）

`color_core.protect_skin_oklch(original, graded, skin_mask)` 实际限制调色后的颜色，
推进计划 3.3、3.5 的肤色保护能力。输入为对齐的原始与调后 OkLCh，以及调用者明确提供的
布尔选区。保持调后 L 和选区外像素，只限制选区内的色相漂移与色度增加。

阈值直接取计划的 6° 与 1.15 倍，工程实现保守地逐像素限制；不会把所有肤色拉成同一种颜色。
原色度为零时去掉新增染色，色相保持未定义；调后已经去色时不强行上色。空选区明确警告。
无近中性色阈值、肤色推断或检测器，调用者须提供选区依据，不能把合成选区当成人脸检测结果。
返回独立 float64 数组与阶段计数，受影响像素按并集统计，QA 不含整体通过结论。

这是重新实现的限幅方法，未找回或移植历史 0.4.1 原型。21 项合成测试验证手算边界、环形色相、
零色度、选区/亮度保持、非连续数组、重复性及分离色调到量化的串接。测试参数和选区未获确认为
摄影配方，真实肤色、选区边缘与视觉效果仍须验证。本函数不改旧 CLI、不读写照片。
后续色域映射和量化可能再改变色相/色度，必须对最终输出重算护栏；不能用本阶段限幅冒充成片验收。
自动肤色选区、六风格集成、真实照片、完整 QA、card 和 LUT 仍待完成。

## 线性光高光 bloom（0.12.0）

`color_core.bloom_linear_srgb(linear, threshold=..., sigma_fraction=..., truncate=..., strength=...)`
实现计划 3.4 的空间 bloom。先按线性 sRGB 相对亮度提取超过阈值的光，再用归一高斯核扩散，
最后把扩散光加回原像素。保留光源本来的 RGB 颜色，不预设暖色染色；模糊半径按当前图像短边计算。

四个参数全部必填，没有默认摄影配方。threshold 为 [0,1] 的线性相对亮度；sigma_fraction 为
(0,1] 的短边比例，代表高斯标准差；truncate 为正的标准差倍数，决定有限核支撑；strength 为
[0,1] 的新增光倍率。核半径向上取整且至少 1 像素，超过短边时拒绝，这是资源限制，不静默缩核。

输入只接受 H×W×3、[0,1] 内的有限线性 sRGB，须先完成明确的颜色归一与色域处理。
输出为独立 float64 数组及阶段统计。零强度或没有超过阈值的像素时精确恒等；使用 reflect101
边界，不循环绕回画面另一端、不混合 RGB 通道、不量化。实际模糊使用本机 OpenCV，不自动安装，
不修改全局 OpenCV 设置。相同环境与参数可重复；分块或不同分辨率不保证相同像素。

新增光可能使输出超过 1，函数保留并逐像素计数、警告，后续必须明确处理亮度；不能直接裁掉
或把它送进拒绝亮度越界的色域映射器来冒充通过。bloom 会改变附近皮肤颜色，最终肤色护栏须重算。
本实现没有红色胶片卤化层光晕、颗粒或暗角，也不恢复源图已丢失的高光。

此方法为重新实现，未找回或移植历史 0.4.1 原型。23 项新增合成测试覆盖独立标量卷积、
亮度阈值、短边缩放、RGB 顺序、边界与有限支撑、零强度、越界不裁切、缺依赖和最终量化串接。
测试参数未获确认为摄影配方，真实照片、视觉效果、六风格与端到端 CLI 仍待验收；原 CLI 不变。
数学定义及证据边界见 `references/grading-research.md` 的同名一节。

## 线性光有色边缘光晕（0.13.0）

`color_core.halation_linear_srgb` 补齐计划 3.4 的另一项空间像素变换。按线性亮度提取高光，
高斯扩散后减去本地高光，只把正的扩散余量按显式 RGB 色彩加回。孤立光源中心保持原值，
周围较暗位置形成有色光晕。均匀亮场保持恒等，避免给整幅图叠加染色雾。

threshold、sigma_fraction、truncate、strength 与 tint_linear_rgb 全部必填。前四项的单位
和资源边界与 bloom 相同；tint_linear_rgb 为三个 [0,1] 内的线性 RGB 通道增益，不归一化，
不把编码 sRGB 数字或测试中的红品色向量当成已确认配方。尺度按当前短边计算。

输出独立 float64 数组及阶段 QA。零强度、零 tint、均匀高光提取图精确恒等；越过 1 的输出
保留并按像素计数，要求后续明确处理亮度和色域。采用本机 OpenCV 的 reflect101 高斯卷积，
不安装依赖、不读写照片、不改全局状态。缺少依赖时仅实际需要模糊的路径报错。

这是按计划重新实现的工程效果，未移植历史 0.4.1 原型，也未模拟真实胶片层或复现其评分。
23 项合成测试覆盖独立标量卷积、手算邻域、色彩增益、光源中心、恒等、边界、资源限制、
重复性与 bloom 到最终量化的串接。测试参数未经摄影者确认为配方，真实夜景和肤色待验收。

该变换不能写进逐像素 LUT；最终肤色与剪切必须重新检查。旧 CLI 保持不变，颗粒、暗角、
六风格配方、CLI 集成、card/LUT、16 位和真实成片仍待按计划推进。详细公式见调色研究参考。

## 线性光单色颗粒（0.14.0）

`color_core.grain_linear_srgb` 实现计划 3.4 的空间颗粒。使用显式种子的单色随机场，按当前
短边比例作高斯相关，再以同一个增益乘在线性 RGB 三通道上。只平滑噪声，不模糊原照片。
黑色与零通道保持零，RGB 通道比例在浮点误差内保持；亮度与绝对色度仍会改变。

amount、sigma_fraction、truncate、strength、seed 全部必填。amount 为 [0,1] 的平滑前
相对增益最大偏移，strength 为 [0,1] 倍率；amount 不代表平滑后的 RMS、EV 或量化码值。
高斯 σ 按短边计算，支撑与 bloom 相同。增大 σ 会降低实际噪声方差，不自动重新归一强度。
局部 PCG64 随机流不改变 NumPy 全局状态；相同形状、值、参数及依赖环境得到相同像素字节。
分块、不同分辨率或不同依赖版本不保证同字节，随机空间纹理不能装进逐像素 .cube。

输入为 H×W×3、[0,1] 的有限线性 sRGB。返回独立 float64 数组与阶段 QA，统计变化、变亮、
变暗和超过 1 的像素，每个像素只计一次。零 amount、零 strength 或全黑精确恒等；参数仍
全部验证，不生成噪声或导入 OpenCV。实际需要模糊而缺 OpenCV 时拒绝，不自动安装。
输出超过 1 时保留并警告，后续须明确处理亮度，再重算成片肤色和剪切，不能裁掉后报通过。

本方法为重新实现的工程纹理，未移植历史 0.4.1 原型，不模拟胶片乳剂，也未获真实照片
视觉确认。25 项新增测试采用明确标注的合成输入和参数，只验证像素数学、随机流、边界和
最终量化串接。测试设置未经摄影者确认为配方；此处不提供默认六风格参数。
旧 CLI 仍不加颗粒，暗角、自动肤色选区、六风格与 CLI 集成、完整 QA、card/LUT、16 位及
真实照片验收仍待完成。数学定义、参数来源与限制见调色研究参考的同名一节。

## 触发与分流

适用：“把这张照片调成电影感”“想要低饱和、暖亮部、冷暗部”“保留原片，给我一个可复现的调色版”。

- 只写图注：`photo-caption-writer`；加 EXIF 信息带：`photo-exif-frame`。
- 排多张成组：`photo-series-layout`；拼出版式跨页：`photo-spread-composer`。
- 社交尺寸、压缩、PPI、冲印 ICC 等交付准备不在本增量内。`photo-export-prep` 尚在开发队列，不能声称已可调用。
- RAW、HEIC、HDR、16-bit、CMYK、透明图、调色后输出某个打印机色域：停止，要求先由合适的色彩管理工具导出一份 **新的** 8-bit SDR sRGB JPEG/PNG。不要覆盖或强制改标签。

## 开始前：只问会改变输出的内容

1. 确认有权处理的原图、输出位置与用途，是否为需要忠实色彩的记录、产品、艺术品或新闻图片。此类图片先建议 `neutral`，不默认风格化。
2. 摄影者想要的方向，以及必须保持的颜色（肤色、衣服、品牌色等）。没有回答时先提议 `warm-muted`、强度 60，而不是当作已确认。
3. 是否已转成 SDR sRGB、有没有 ICC。**没有 ICC 就追问，不能为了让脚本跑通擅加 `--assume-srgb`。** 有 ICC 时总是实际转换，坏 ICC 必须拒绝，不允许改为“假定 sRGB”继续。

不从照片推断人的身份、真实情绪、地点或拍摄动机。处理只在本地；不得为分析或调色而上传照片。

## 运行条件

Python 3.10+、Pillow 11.3+（含 LittleCMS；已实测 Pillow 11.3.0 / LittleCMS 2.17）。
本增量不自动安装依赖或调用云端服务。运行前检查运行环境；缺依赖就说明未执行，按用户授权在合适环境补齐后再试。

只接受不超过 64 MiB、2400 万像素的单帧、8-bit、不透明 RGB/L JPEG/PNG。
这是避免内存与运行时间失控的工程上限，不是画质门槛。
拒绝 palette、alpha/tRNS、多帧、PNG 高位深及 cICP/HDR 信号，不静默降位深或丢透明层。
JPEG HDR/增益图没有全面自动识别能力，输入必须由用户确认为 SDR。

在 skill 目录下执行；路径由用户指定，不要扫描整个人的照片库：

```bash
python3 scripts/cinegrade.py --help
python3 scripts/cinegrade.py looks

# 有有效嵌入 ICC 的原图：run-warm-01 必须不存在，父目录必须已存在。
python3 scripts/cinegrade.py render source.jpg \
  --output run-warm-01 --look warm-muted --strength 60

# 仅在用户明确确认无 ICC 的输入确实是 sRGB 后：
python3 scripts/cinegrade.py render source.png \
  --output run-neutral-01 --look neutral --strength 0 --assume-srgb
```

`render` 输出目录中只有：

- `render.png`：EXIF 转正后的原分辨率、不透明 8-bit RGB、嵌入 sRGB ICC；不复制来源 EXIF、XMP、GPS、文本或缩略图。
- `report.json`：完整性收据与数值 QA，最后写入。包括输入内容 SHA-256、尺寸、原 Orientation、ICC 处理动作/散列、技术 EXIF 白名单、配方与强度、输出像素/文件散列、依赖版本。

边车白名单只有曝光秒数、f-number、ISO、焦距；缺失就省略，不补造。**不保存**原始路径、原文件名、GPS、拍摄时间、相机/镜头型号、设备序列号、作者、原始 ICC 文本或完整 EXIF。
内容散列和技术参数仍可关联原片，边车默认私用；对外分享前询问是否需要附带。
去掉元数据不等于视觉匿名，画面内的人脸、地址、车牌等仍需人工检查。

输出必须是一个全新的目录；已有文件、空目录、链接都拒绝，不提供 `--force`。
脚本先在内存中完成解码、调色、编码，再原子占用新目录。写盘失败可能留部分文件，**保留现场**，用新目录重试；不要删旧目录或改写原片。
只有命令有可靠的成功退出记录，同时 `report.json` 可解析、`status` 为 `complete` 且每个输出的 `png_sha256` 与实际文件一致才视为完成（render/compare 检查 `output`；candidates 检查 `candidates` 中全部三项；compare 另按 `panels` 的矩形裁出两幅核验像素散列）。退出码 0 为成功，2 为输入/写盘拒绝；未通过时不能宣称已交付。

## 候选小样：先看方向，不自动选片

用户同意比较方向后，运行 `candidates`。源图的权限、SDR、ICC 与隐私要求和 `render` 完全相同；
没有 ICC 仍要先确认，不为了生成小样绕过颜色管理。忠实色彩用途仍优先中性，不默认推荐风格化。

```bash
# 有有效嵌入 ICC 的原图；run-candidates-01 必须不存在。
python3 scripts/cinegrade.py candidates source.jpg --output run-candidates-01

# 可显式改变两个风格共同的强度和预览长边；不会放大原图。
python3 scripts/cinegrade.py candidates source.jpg \
  --output run-candidates-02 --strength 40 --max-edge 768
```

固定顺序与文件名，不由图像内容或模型随机决定：

| 文件 | 配方 | 强度 |
|---|---|---|
| `01-neutral.png` | `neutral` | 永远 0，作为小样尺寸的中性基线 |
| `02-warm-muted.png` | `warm-muted` | `--strength`，默认 60 |
| `03-cool-muted.png` | `cool-muted` | 同上 |

- 一次读取输入快照，一次 EXIF 转正/ICC 归一；先缩小，再将同一份小样像素送入三份配方。
- `--max-edge` 为 1..2048 整数，默认 1024。长边不超过该值；较小图片不放大、不裁切。
  缩小时每条边按 `max(1, floor((原边长 × max_edge + floor(原长边/2)) / 原长边))` 求整，
  即最近整数、半整数向上、至少 1 像素。比例只受整像素取整影响，极细长图片可能有较明显的取整偏差。
- 缩放固定用 Pillow LANCZOS，`reducing_gap=None`，在编码 sRGB 上执行；不是线性光缩放。
  报告记录处理顺序、缩放参数与实际尺寸；未缩放时 `resampling` 为 `none`。
- `--strength` 为 0..100 整数，只作用于两个风格。设为 0 时三张小样像素相同，仍保留固定三项，不冒充三种不同效果。
- 三张 PNG 都重新嵌入 sRGB ICC，不复制来源元数据；所有图像编码完成后才占用一个全新目录。
  最后写入唯一 `report.json`：输入溯源、缩放契约、逐张完整配方/强度、文件与像素散列、依赖版本及数值 QA。
  任一写入失败，保留部分文件，不宣称完成、不补写收据、不重用目录。
- 顶层 `qa.before` 对应**缩放后、调色前**基线，各候选 `qa.after` 与越界计数只针对该小样。
  `selection.automatic_selection=false`、`selected_look=null`：脚本没有选择赢家。

**小样不是最终交付图。** 先缩后调与先全尺寸调色再缩小的像素一般不同，不能承诺两者散列相同。
小样 QA 不能证明全尺寸高光/暗部细节、肤色或色带已通过。请摄影者明确选择配方和强度，再对**原始输入**
运行 `render` 到另一个新目录并做全尺寸 QA；不要把候选 PNG 当原片再次调色，也不要直接放大小样交付。
显示环境不可用时，如实写“已生成三张候选，视觉未验收”，不代用户选定或声称好看。
本命令只输出独立 PNG 与收据，不生成拼卡、滑块对比、LUT，也不扩展到社交/冲印导出。

## 前后对比：原尺寸像素并排

摄影者已选定方向与强度后，使用原始输入运行 `compare`。这一步对应计划 3.2 的前后对比交付。
本版从现有安全读写和调色函数重新实现，没有移植历史 0.4.1 原型的对比排版，也没有复现其视觉评分。

```bash
python3 scripts/cinegrade.py compare source.jpg \
  --output run-compare-01 --look warm-muted --strength 60
```

`--look` 与 `--strength` 都必填，不隐式替摄影者选定方向。无 ICC 时仍须先确认，才能加 `--assume-srgb`。

- 输出 `compare.png` 与 `report.json`，目录必须全新。只读一次原片快照，先转正并归一 sRGB，再调色。
- 左边为归一后的原图，右边为同一原图的调色结果。每幅保持 W×H，整图为 2W×H。
  不缩放、不放大、不裁切、不加间隔或文字，不需要系统字体。左右含义写在收据与交付说明中。
- 右边与同一输入快照、配方、强度及解码/ICC 环境下 `render` 的输出像素逐字节一致。
  左边用于隔离创意调色的差别，无法展示 ICC 转换之前的宽色域源像素。
- 收据 `panels` 按 before、after 排列，逐项给出 `box_xywh`（左上 x、y、宽、高）及像素 SHA-256；
  `output` 记录整图的像素与文件散列。比较的是像素，PNG 文件字节不作跨运行恒等保证。
- `qa.scope=full_resolution_panels`。before/after 端点计数、通道样本数各按一幅原尺寸图计算，
  不把两幅重复计数。完整配方与现有护栏限制保留。
- 复用隐私白名单、ICC 编码、全新目录占用和最终收据发布。编码先于写盘；失败保留现场。
  对比图最多为输入像素上限的两倍，内存用量高于单幅 render。查看器可能自动缩小，请按 1:1 检查细节。

此版本是无装饰的像素对比，不提供 2.39:1 剧照卡、中文标题或滑块。合成像素测试用于检查结构和对应关系，
不能据此宣称真实照片肤色、电影感或整项 skill 验收通过。

## 调色契约

配方在 `references/look-library.json`，选择说明见 `references/look-library.md`。

1. 对输入读一次快照；内容散列与解码使用同一批字节。
2. 应用 EXIF Orientation，绝不通过丢 EXIF 假装转正。
3. 嵌入 ICC → LittleCMS 相对色度转换到 sRGB，无隐式感知映射；无 ICC 必须显式确认 sRGB。带冲突 gamma/chromaticity 的未标记 PNG 拒绝。
4. **在编码 sRGB 值上**做整数分段曲线 → 冷暖偏移 → 饱和度 → 钳位 → 与原像素按强度混合。顺序固定，不使用随机数、生成模型、外部网络或隐式自动增强。
5. `neutral` 对归一后的像素恒等；任何配方强度 0 也恒等。注意“归一后恒等”不等于保留 JPEG 字节、宽色域源像素或 EXIF 旋转前的排列。

确定性承诺是：同一解码/ICC 环境、同一输入、配方与强度，输出像素一致。
跨 Pillow/LittleCMS 版本可能不同；PNG 文件字节不作跨运行恒等承诺（ICC/编码器可能变化）。报告记录环境及实际散列。
本变换不是线性光处理、胶片物理仿真或特定电影的精确复刻，8-bit 调色有色带风险。
具体数学与规范参考见 `references/grading-research.md`，其中工程参数与来源规则明确分开。

## QA 与交付

脚本自动报告：

- 输入与输出每个通道处在 0 / 255 的像素数；以及总像素数。
- 满强度配方在最终钳位之前超出 0..255 的通道样本数。强度 0 不执行配方，此项为 0；其他强度时这个数反映满强度配方，不是实际输出的剪切像素数。
- 明确要求人工检查的项目及数值警告。

端点数不是“已剪切”的证明，也不是“细节完好”的证明；真正的细节可能在相机或 ICC 归一时已经丢失。
数值 QA 不检测宽色域源的色域损失，不会判断肤色自然、审美成功、印刷可用或屏幕颜色准确。

交付前在能显示图像的环境中检查：肤色与记忆色、云/灯的高光细节、暗部层次、平滑渐变色带。不能查看图像时，只报告“脚本与数值已检查，视觉未验收”，不评价好看与否。
如果用户认为太强，保留当前结果，降低强度写入另一个新目录，不覆盖上一版。

简短交付单：

- 用途与用户确认的方向；配方 / 强度。
- ICC 处理动作、是否用了明确的 sRGB 假设。
- 新输出图与边车；原片未改写。
- QA 警告、实际完成的视觉检查、未验证项。

## 测试

```bash
PYTHONDONTWRITEBYTECODE=1 python3 scripts/cinegrade.py --selftest
PYTHONDONTWRITEBYTECODE=1 python3 scripts/image_io.py --selftest
PYTHONDONTWRITEBYTECODE=1 python3 scripts/test_cinegrade.py
```

测试只使用合成小图、合成数学网格与可核对的标准色彩向量，临时文件局限本 skill 的 `scripts/` 内，结束清理自己创建的夹具；不读取真实照片、系统字体或其他技能。
交互验收场景位于仓库的 `tests/cases/photo-cinematic-grade.md`。
实测范围是合成 RGB/L、sRGB ICC 与模拟 ICC 调用；**真实 Display P3/Adobe RGB 照片与跨平台视觉验收尚未完成**。

## 后续验收顺序

以下为本 skill 尚未完成的功能；实际开发顺序以每轮同步后只读的 AUDIT-AND-IDEAS.md 时间表为准，不在本文件固定全仓项目顺序：

1. `card` 与对应可视校验，复用已完成的候选参数和像素收据；`compare` 已具备无装饰的原尺寸并排输出。
2. 再做 `lut`、LUT 与 render 数值对账、综合色彩/隐私/QA 验收。

## 变更记录

| 版本 | 日期 | 变更 | 类型 |
|---|---|---|---|
| 0.14.0 | 2026-10-16 | 新增显式种子线性光单色颗粒、短边高斯相关、增益与超范围阶段 QA；25 项合成测试，旧 CLI 和真实照片未接管或验收 | minor |
| 0.13.0 | 2026-10-16 | 新增显式参数线性光有色边缘光晕、短边高斯正余量与阶段 QA；23 项合成测试，原 CLI 与真实效果仍待集成验收 | minor |
| 0.12.0 | 2026-10-14 | 新增显式参数线性光高光 bloom、短边高斯扩散、超范围保留与统计；23 项合成测试，原 CLI 与真实效果仍待集成验收 | minor |
| 0.11.0 | 2026-10-14 | 新增显式布尔选区 OkLCh 肤色保护，按计划 6°/1.15 倍限幅、保持调后亮度及选区外像素；21 项合成测试，自动选区与成片验收待完成 | minor |
| 0.10.0 | 2026-10-13 | 新增保持线性相对亮度的 sRGB 色域映射、逐像素占比与 >10% 警告、21 项合成测试；修复非连续图像写回，CLI 与真实效果待集成验收 | minor |
| 0.9.0 | 2026-10-13 | 新增编码 sRGB 三角抖动与最终 RGB8 量化、显式幅度/种子、20 项合成测试；CLI 未切换，真实断层与六风格待验收 | minor |
| 0.8.0 | 2026-10-13 | 新增 OkLCh 减法密度，显式正负密度与强度、端点/中性保持、20 项合成测试及微小负密度舍入修复；CLI 与配方未切换，真实效果待验收 | minor |
| 0.7.0 | 2026-10-12 | 新增 Oklab 分离色调，暗部/亮部独立色相与色度增量、端点平滑包络、20 项合成测试；CLI 与配方未切换，真实效果待验收 | minor |
| 0.6.0 | 2026-10-10 | 新增 OkLCh 环形分色相调色，显式窗口/转角/色度/强度、21 项合成测试；保持既有 CLI，真实效果与六风格待验收 | minor |
| 0.5.0 | 2026-10-10 | 新增高光色度滚降浮点阶段，显式起点/强度、保持亮度与色相、16 项合成测试；CLI 与配方未切换，真实效果待验收 | minor |
| 0.4.0 | 2026-10-09 | 新增 float64 sRGB/Oklab/OkLCh 内核及端点固定亮度曲线，新增 22 项数学测试；未接管 CLI、未复现历史原型或完成六风格视觉验收 | minor |
| 0.3.0 | 2026-10-08 | 新增 compare：显式配方/强度、原尺寸左右像素对账、单幅 QA 计数、隐私与失败保护；新增 13 项合成测试；核心六风格管线及真实效果仍未验收 | minor |
| 0.2.0 | 2026-10-07 | 新增 candidates 固定三选小样：一次颜色归一、确定性限边缩放、逐图配方/散列/QA、整组新目录保护及隐私/失败测试；card/compare/lut 仍待实现 | minor |
| 0.1.0 | 2026-10-07 | 首个独立增量：确定性 render、三份基础配方、安全 I/O、技术 EXIF 白名单边车与数值 QA；小样/card/compare/lut 待后续 | minor |

### 收据发布与文件系统边界

PNG 写完后，先将报告写为 `.report.pending`，成功 flush/fsync/close 后，以同目录硬链接、不覆盖的方式发布 `report.json`。此前任一步失败均保留现场，不发布最终收据。若文件系统不支持硬链接则安全失败，不改用会覆盖目标的发布方式。发布成功后尝试移除临时别名；此可选清理失败时可能多留 `.report.pending`，但最终收据与本次 PNG 仍有效。

只在可信、不会被其他进程并发替换的输出父目录运行；这不是恶意路径替换防护，也不承诺任意断电后的目录持久性。恢复时必须同时核对成功退出、最终收据和全部输出散列，不能凭孤立的 complete 字段判定成功。