docs: organize Color Finale migration research and remove prior target descriptions from current tree
这个提交包含在:
1 父节点
29dc4d385c
当前提交
719229ddd8
24 个文件已更改
+1012
-3028
没有与搜索条件相匹配的文件
+18
-81
@@ -1,97 +1,34 @@
|
||||
# 颜色查表与接入核验
|
||||
|
||||
本记录区分发布二进制静态证据、公开源码和本项目的实现验证。没有将静态调用关系当作实际宿主运行结果。
|
||||
|
||||
## 参考身份
|
||||
|
||||
- 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 调用或资源字节校验确认。
|
||||
本记录说明当前 CPU/GPU 数学契约和已有核验范围。Color Finale 相关迁移研究、第三方来源及历史记录入口见 [ALGORITHM_SOURCES.md](ALGORITHM_SOURCES.md)。
|
||||
|
||||
## MIT 查表数据
|
||||
|
||||
参考包的 `THIRD-PARTY-NOTICES.txt` 声明,Camera Raw 查表数据与组合行为来自 [Compositor](https://github.com/robbietilton/Compositor),MIT,Copyright 2026 Wonder Assembly LLC。
|
||||
Camera Raw 查表数据和组合行为来自 [Compositor](https://github.com/robbietilton/Compositor),MIT,Copyright 2026 Wonder Assembly LLC。已核对提交 `92f5225afe7e921dbfa4c563462980e45db345fc` 的 `Compositor/Resources/CameraRawTables.bin`;项目资源 `DayuColorTables.bin` 的 SHA-256 为 `e67ff4dbcce35cb7765752acff4405be5c934d913ef1396b2ca3fc6dc8a85190`。完整许可位于正式资源 `THIRD-PARTY-NOTICES.txt`。
|
||||
|
||||
核对公开源提交 `92f5225afe7e921dbfa4c563462980e45db345fc` 的 `Compositor/Resources/CameraRawTables.bin`,与参考包文件逐字节相同。项目中的 `DayuColorTables.bin` 保存这份必要数学数据,保留 MIT 许可;没有复制参考应用的图标、品牌、授权代码或原始应用程序。
|
||||
- `CRT3` 头;维度17、763张表、差值量化步长3。10字节头后为LZMA/xz,解压长度11,245,857字节。
|
||||
- 每张表按通道累计有符号Int8差值,还原为 `round(axis * 255 / 16) + signedDelta * 3`,钳制0–255。
|
||||
- 源表红轴最慢、蓝轴最快,RGB8;采用17³三线性插值。组合输出33³ RGBA32Float,Metal纹理红轴最快,alpha固定1。
|
||||
- 白平衡:温度和色调各−100…100、间隔25,四张相邻表双线性混合。
|
||||
- 八色HSL:依次组合明度、饱和度、色相;表起点 `285 + (kind * 8 + color) * 5`;各项−100…100、间隔50。
|
||||
- 分级:先阴影、中间调、高光、全局明度,再组合全局、中间调、高光、阴影色轮;保留公开实现的插值及平衡系数。
|
||||
|
||||
数据 SHA-256:`e67ff4dbcce35cb7765752acff4405be5c934d913ef1396b2ca3fc6dc8a85190`。
|
||||
## 字段与旁路
|
||||
|
||||
格式经公开 `Compositor/Document/CameraRawTables.swift` 和参考 `loadSourceTables` / `sample` 核对:
|
||||
CPU/Metal共用944字节 `DYUniforms`,字段偏移由静态断言检查。白平衡、HSL和颜色分级由CPU生成有效或中性3D纹理,停用时不能复用非中性的缓存。基础分组同时控制光影与颜色子组;纹理、清晰度和去雾遵循基础组旁路,肤色保护独立启停。
|
||||
|
||||
- `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 对阴影、高光饱和度份额的系数按公开源及二进制一致恢复。
|
||||
肤色保护开关阈值0.5,保护程度为0–100,内部乘0.01并钳制;中心色相除以360后参与HSL圆周距离。默认保护程度60、中心色相28。黑白六色默认系数依次为 `40,60,40,60,20,80`,着色色相与饱和度默认0。
|
||||
|
||||
## 已确认的字段与旁路依赖
|
||||
三原色矩阵为列向量,GPU使用 `r*M0 + g*M1 + b*M2`。色相沿灰轴旋转,幅度 `hue / 100 * 0.5235987305641174`;饱和度系数 `sat / 100 * 0.55`,矩阵保持D65白点并限制极端偏移。
|
||||
|
||||
944 字节 CPU/GPU ABI 的每字段偏移有 `DYUniforms.h` 的静态断言。
|
||||
## 自动调色与导出
|
||||
|
||||
### 白平衡
|
||||
当前自动调色在320×180、RGB8数值域中计算分位数、饱和度和中性样本权重;先做输入转换和强度混合,再进行统计。阈值与计算式见 `DYAutoGrade.mm`。该实现与同系列 Color Finale 迁移工程的 `Core/DYAuto.hpp` 使用不同参数和公式,来源分别保存。
|
||||
|
||||
原 fragment 无条件读取已生成的白平衡 3D 纹理,因此组旁路必须在 CPU 构造纹理时落实。
|
||||
LUT导出输出 `cubeSize³ * 3` 个float,红轴最快。输入为输入LUT、五层风格LUT、HSL、白平衡及分级纹理;参数、RGB输出和cubeSize分别绑定buffer0/1/2。空间纹理、清晰度及逐画面统计无法完整表达为3D LUT。
|
||||
|
||||
原渲染器 `0x100077054…0x10007708c`:
|
||||
## 验证范围
|
||||
|
||||
1. 从 uniforms `+104/+108` 读取 temperatureEnabled/tintEnabled,分别决定是否使用对应数值。
|
||||
2. 从 uniforms `+140` 读取 colorSectionEnabled,作为 `whiteBalanceTexture(... enabled:)` 的 enabled 参数。
|
||||
3. `0x10007708c` 调用白平衡纹理生成方法;未启用时采用中性 LUT。
|
||||
`tools/verify_color_tables.mm` 覆盖数据摘要、损坏拒绝、独立double三线性对照、白平衡、纹理轴序、24项HSL端点、四色轮、色相环绕、明度端点、三原色控制和D65保持。真实Metal纹理接口与非中性缓存后的组旁路由原生集成检查覆盖。
|
||||
|
||||
`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 应用。
|
||||
|
||||
宿主的半透明表示、图像原点、色彩空间和最终视觉结果仍须用正式安装的已公证版本验收;数学和静态结构验证不能替代宿主验证。
|
||||
GPU数学、CPU表、自动分析、宿主交互和实际导出各自保留报告。有限数值检查与静态结构检查不能替代所有宿主、素材、图像原点、alpha和色彩空间的实际验收。
|
||||
在新工单中引用
屏蔽一个用户