文件
dayu-color/research/ColorTableNotes.md
T

7.8 KiB
原始文件 Blame 文件历史

颜色查表与接入核验

本记录区分发布二进制静态证据、公开源码和本项目的实现验证。没有将静态调用关系当作实际宿主运行结果。

参考身份

  • LumiGrade 3.0,构建 56。
  • 参考服务:/Library/Plug-Ins/FxPlug/LumiGrade.app/Contents/PlugIns/LumiGrade XPC Service.pluginkit/Contents/MacOS/LumiGrade XPC Service。
  • 原始 universal Mach-O SHA-256:33c273d6a58314f5068959fcda911d741884a1937077b41a969a990dd40d0b6d。
  • 只读抽取 arm64 SHA-256:c04e911e449e888eb0d8c10f7bcf2b6bc2c4153b9ba86c1952ddf210c96c5e97。
  • 本记录的地址属于该 arm64 slice,image base 为 0x100000000。使用现有 otool -arch arm64 -tvV 输出核对具体 ARM 指令,不需要重新打开 REA 会话。
  • REA/Ghidra 提供的相关函数伪代码属于还原结果,不是原始 Swift 源码。关键结论同时以 ARM 调用或资源字节校验确认。

MIT 查表数据

参考包的 THIRD-PARTY-NOTICES.txt 声明,Camera Raw 查表数据与组合行为来自 Compositor,MIT,Copyright 2026 Wonder Assembly LLC。

核对公开源提交 92f5225afe7e921dbfa4c563462980e45db345fc 的 Compositor/Resources/CameraRawTables.bin,与参考包文件逐字节相同。项目中的 DayuColorTables.bin 保存这份必要数学数据,保留 MIT 许可;没有复制参考应用的图标、品牌、授权代码或原始应用程序。

数据 SHA-256:e67ff4dbcce35cb7765752acff4405be5c934d913ef1396b2ca3fc6dc8a85190。

格式经公开 Compositor/Document/CameraRawTables.swift 和参考 loadSourceTables / sample 核对:

  • CRT3 头;维度 17,763 张表,差值量化步长 3。
  • 10 字节头之后为 LZMA/xz;解压长度 11,245,857 字节。
  • 每张表逐通道保存 running delta,累计值按有符号 Int8 解释;还原到 round(axis * 255 / 16) + signedDelta * 3 并钳制 0–255。原 ARM 0x10009bf28 的 frinta 确认这里要四舍五入,不能直接截断。
  • 源表顺序为红轴最慢、蓝轴最快;每格 RGB8。读取采用 17³ 三线性插值。
  • 组合结果为 33³ RGBA32Float,Metal 纹理红轴最快,alpha 固定 1。
  • 白平衡:温度、色调各 -100…100、间隔 25,四张相邻表双线性混合。
  • 8 色 HSL:明亮度、饱和度、色相依次组合;表起点 285 + (kind * 8 + color) * 5,每项 -100…100、间隔 50。逐项运算保留 low + (high - low) * fraction。
  • 分级:先阴影、中间调、高光、全局的明度,再全局、中间调、高光、阴影色轮;色轮在相邻色相、饱和度、混合档位间混合。分级 balance 对阴影、高光饱和度份额的系数按公开源及二进制一致恢复。

已确认的字段与旁路依赖

944 字节 CPU/GPU ABI 的每字段偏移有 DYUniforms.h 的静态断言。

白平衡

原 fragment 无条件读取已生成的白平衡 3D 纹理,因此组旁路必须在 CPU 构造纹理时落实。

原渲染器 0x100077054…0x10007708c:

  1. 从 uniforms +104/+108 读取 temperatureEnabled/tintEnabled,分别决定是否使用对应数值。
  2. 从 uniforms +140 读取 colorSectionEnabled,作为 whiteBalanceTexture(... enabled:) 的 enabled 参数。
  3. 0x10007708c 调用白平衡纹理生成方法;未启用时采用中性 LUT。

DYColorTables 已按此处理。为使自定义检查器的组旁路与实际字段含义一致,本项目把白平衡与鲜艳度、饱和度放在“白平衡与颜色”组;这是明确的界面分组适配。

HSL 与颜色分级分别以 hslSectionEnabled、colorGradingSectionEnabled 生成有效或中性纹理,旁路不能复用此前非中性的缓存结果。

纹理、清晰度、去朦胧由原 fragment 的 baseSectionEnabled 分支控制,属于基础组。肤色保护 shader 只检查 skinProtection.x,应保持独立开关,不能暗示它自动跟随颜色组。

肤色保护

原 applySkinProtection:

  • .x:开关,阈值 0.5。
  • .y:保护程度,乘 0.01 后钳制到 0–1。
  • .z:中心色相,除以 360 后与像素 HSL 色相做圆周距离计算。

原 addParameters 对参数 0x468 设置默认 60、范围 0–100;对 0x469 设置默认 28、范围 0–60。两项不是色相范围和饱和度范围。对应静态伪代码在 addParameters.c:504…510,数值十六进制为 0x404e000000000000、0x403c000000000000。

黑白混色

原 addParameters 从 DAT_1000dc7e8 读取黑白参数默认值。该 slice 对应文件偏移的 8 个 double 是:

40, 60, 40, 60, 20, 80, 0, 0

依次对应红、黄、绿、青、蓝、洋红,以及着色色相、着色饱和度。原 applyBlackWhite 直接读取这些六色系数参与灰度计算;六项设成 100 会改变启用黑白后的明度。

分级与三原色

  • colorGradingHueSatA.xy 为中间调 H/S,.zw 为阴影 H/S;HueSatB.xy 为高光 H/S。
  • colorGradingLuma 为中间调、阴影、高光明度;colorGradingGlobal 为全局 H/S/L。原包装方法 0x100083320…0x1000833e8 的向量重排确认此顺序。
  • 三原色矩阵是列向量。GPU 将 r*M0 + g*M1 + b*M2 相加,无需转置。
  • 色相沿灰轴旋转,幅度为 hue / 100 * 0.5235987305641174;饱和度沿对应原色相对中性灰的轴变化,系数 sat / 100 * 0.55。矩阵保持 D65 白点,并沿用原版过大矩阵偏移的限制。

自动调色预览确实应用输入 LUT

这是已确认的静态调用与数学流程,不再只是从函数名称作推测:

  1. capturePreviewFrameIfNeeded 位于 0x1000833ec。它缓存原始预览图,并保存输入 LUT、路径、强度;LUT 路径或强度改变时更新版本、清除已转换缓存。此方法本身没有直接转换图像。
  2. currentPreviewFrame 位于 0x10007f4f4。缓存不命中且有输入 LUT 时,0x10007f5ec 明确调用 imageByApplyingInputLUT(to:lut:strength:);s0 在前一条指令从保存的强度装入。
  3. 自动调色闭包 0x100075e00 在 0x100075e44 调用 currentPreviewFrame,在 0x100075e54 把该结果传给 autoGradeResult。
  4. imageByApplyingInputLUT 位于 0x100090a34。0x100090a68/6c 指定 320×180 的 RGB8 缓冲;0x100090aec…0x100090b0c 将 RGB8 除以 255;0x100090b40 调用 CubeLUT.sample;0x100090b48…0x100090b50 计算 original + (sample - original) * strength;0x100090b78 起钳制、四舍五入回 RGB8。

因此,本项目的自动调色输入应在标准线性→sRGB 编码之后应用输入 LUT 与强度,再进入统计。使用未转换的 Log 原图统计会偏离参考行为。GPU 缩略采样与原版 NSImage/CoreGraphics 320×180 重采样仍可能有量化或重采样差异,不声明逐字节相同。

LUT 导出与验证边界

原 lutExportKernel 输出 cubeSize³ * 3 个 float,红轴最快;texture0–8 为输入 LUT、五层风格 LUT、HSL、白平衡、分级,buffer0 uniforms、buffer1 RGB 输出、buffer2 cubeSize。当前接入按此布局,不能按 float4 分配后误读。

导出核接收、输出的是 LUT 的编码域 RGB,空间纹理和清晰度操作不写入 3D LUT。画面相关统计与导出核固定处理也不等同于任意素材的逐帧渲染。

tools/verify_color_tables.mm 已通过严格 -Wall -Wextra -Werror 编译。验证覆盖数据 SHA、损坏拒绝、独立 double 三线性对照、四表白平衡、纹理轴顺序、24 项 HSL 端点、4 色轮、色相环绕、4 明度端点、6 个三原色控制及 D65 保持。带资源的 CLI 测试 bundle 另验证真实 Metal 纹理接口与非中性缓存后的 WB/HSL/分级旁路;没有运行未公证 GUI 应用。

宿主的半透明表示、图像原点、色彩空间和最终视觉结果仍须用正式安装的已公证版本验收;数学和静态结构验证不能替代宿主验证。