#moon_icc

#这个库解决什么问题

#安装

moon add qqq66668/moon_icc

import {
  "qqq66668/moon_icc",
}

#用法

#解析 ICC profile

let data = @fs.read_file_to_bytes("sRGB Color Space Profile.icc")
let header = @moon_icc.parse_header(data)
println(header.device_class)   // "mntr"
println(header.color_space)    // "RGB "
println(header.pcs)            // "XYZ "
println(header.date_time.to_iso_string())  // "1998-02-09T06:49:00"

let tags = @moon_icc.parse_tag_table(data, header)
for tag in tags {
  println("\{tag.signature} 偏移=\{tag.offset} 长度=\{tag.size}")
}

#变换到 PCS（XYZ / Lab）

let data = @fs.read_file_to_bytes("sRGB Color Space Profile.icc")
let profile = @moon_icc.Profile::parse(data)
let transform = profile.matrix_trc()

// sRGB 中灰 (0.5, 0.5, 0.5) → PCS XYZ
let xyz = transform.to_pcs(0.5, 0.5, 0.5)
// xyz = (0.20640003241890215, 0.21403939749252843, 0.17660683523992873)

// 再转到 Lab
let lab = @moon_icc.xyz_to_lab(xyz)
println(lab.l)  // 53.585...

#源 profile → 目标 profile（多 profile 链接）

let src = @moon_icc.Profile::parse(@fs.read_file_to_bytes("sRGB Color Space Profile.icc"))
let dst = @moon_icc.Profile::parse(@fs.read_file_to_bytes("display.icc"))

// 媒体相对比色意图
let link = @moon_icc.ColorTransform::new(src, dst)
let (r, g, b) = link.transform(0.5, 0.5, 0.5)

#跨类型链接（matrix/TRC ↔ LUT）

let rgb = @moon_icc.Profile::parse(@fs.read_file_to_bytes("sRGB Color Space Profile.icc"))
let cmyk = @moon_icc.Profile::parse(@fs.read_file_to_bytes("printer.icc"))
let link = @moon_icc.ColorTransform::new(rgb, cmyk)

// 源 3 通道 → 目标 4 通道，用通道数无关的 transform_values
let out = link.transform_values([ 0.5, 0.5, 0.5 ])   // 4 个 CMYK 分量

moon run cmd/main --target wasm-gc -- link testdata/srgb.icc testdata/display.icc
moon run cmd/main --target wasm-gc -- link testdata/srgb.icc testdata/cmyk_printer.icc

src_channels 3
dst_channels 3
link 0 0 0 0
link 1 9 9 9
...

src_channels 3
dst_channels 4
link 0 0 0 0 255
link 1 1 2 1 255
...

### 命令行示例

仓库自带一个可运行的示例程序：

`parse` 输出 profile 的头部与 tag 表：

`transform` 输出固定样本点的变换结果（含中间调，便于对拍）：

## 当前进度

| 功能 | 状态 |
|---|---|
| ICC profile 二进制解析（头部 + tag 表，含边界校验） | ✅ 已完成并验证 |
| tag 数据解析（`XYZ ` / `curv` / `para`） | ✅ 已完成并验证 |
| matrix/TRC 类型 profile → PCS XYZ 变换 | ✅ 已完成并验证 |
| XYZ ↔ Lab 转换与 CIE76 色差 | ✅ 已完成并验证 |
| 逆变换（PCS XYZ → 设备 RGB）与矩阵求逆 | ✅ 已完成并验证 |
| 多 profile 链接（源设备 → PCS → 目标设备） | ✅ 已完成并验证 |
| 媒体相对比色意图 | ✅ 已完成并验证 |
| CLUT 型 profile 变换（`mft1` / `mft2`，CMYK 打印机等） | ✅ 已完成并验证 |
| 跨类型链接（matrix/TRC ↔ LUT 任意组合） | ✅ 已完成并验证 |
| 渲染意图：感知 / 媒体相对比色 / 饱和度 | ✅ 已完成并验证 |
| 渲染意图：绝对比色 | **已知限制**，见下文（与相对比色相同路径） |
| `mAB` / `mBA`（ICC v4 LUT） | ✅ 已完成并验证 |
| PCS 为 `XYZ ` 的 LUT 型 profile | ✅ 已完成并验证（v4 样本；v2 路径无样本，见「明确不做」） |

## CLUT 型 profile 变换

大量真实世界的 profile（印刷、CMYK、扫描仪）不是矩阵/TRC 型，而是把整个
变换存在一张多维查找表里。本库支持 ICC v2 的两种 LUT 类型：

| 类型 | 名称 | 表值位深 |
|---|---|---|
| `mft1` | lut8Type | 8 位（表固定 256 项） |
| `mft2` | lut16Type | 16 位（表项数在文件里显式给出） |

处理顺序：**输入表 → 矩阵（仅 3 输入通道时）→ CLUT（多线性插值）→ 输出表**。

用法：

```moonbit
let profile = @moon_icc.Profile::parse(@fs.read_file_to_bytes("printer.icc"))
// 设备值按 profile 输入色空间的通道顺序给出，0..1
let lab = profile.device_to_lab(1, [ 0.0, 0.0, 0.0, 0.5 ])  // CMYK 50% 黑

moon run cmd/main --target wasm-gc -- lut testdata/cmyk_printer.icc

#实现中容易错的三处

#ICC v4 的 LUT（mAB / mBA ）

mAB：A 曲线 → CLUT → M 曲线 → 矩阵 → B 曲线
mBA：B 曲线 → 矩阵 → M 曲线 → CLUT → A 曲线

#实测（testdata/test4.icc，40 个样本，8 位域）

#关于 B2A 的对拍口径

#PCS 为 XYZ 的 LUT 型 profile

#样本是合成的

A2B0：XYZ = 设备值 × D50
B2A0：设备值 = XYZ / 1.99997…
组合：设备输出 = 设备输入 × D50 / 1.99997…

#与 lcms2 的交叉核对（重要）

1. 完全一致率 ≥ 98%（实测 98.68%）；
2. 最大偏差 ≤ 3 级（8 位量化）；
3. 偏差 ≥2 级的通道，其 lcms2 输出必须 ≤ 8——把成因钉在极暗区。

python tools/gen_golden.py             # 生成链接金标（lcms2 NOOPTIMIZE）
python tools/gen_clut_golden.py        # 生成 CLUT 金标（网格节点 + lcms2）
python tools/gen_cross_link_golden.py  # 生成跨类型链接金标
python tools/gen_intent_golden.py      # 生成四种渲染意图金标
python tools/gen_v4lut_golden.py       # 生成 ICC v4 LUT（mAB/mBA）金标
python tools/gen_xyz_lut_profile.py    # 合成 PCS 为 XYZ 的 LUT profile（并用 lcms2 复核）
python tools/gen_xyz_golden.py         # 生成合成 XYZ profile 的金标
python tools/lcms2_flags_check.py      # 复现 flags 对比表
python tools/lcms2_deviation_report.py # 复现链接偏差分布表
python tools/lcms2_intent_check.py     # 复现"哪些 profile 能区分意图"
python tools/diff_oracle.py wasm-gc    # 独立 Python 规范实现差分
python tools/make_demo_video.py        # 重新生成演示视频

#渲染意图

moon run cmd/main --target wasm-gc -- link testdata/srgb.icc testdata/cmyk_printer.icc saturation

#matrix/TRC 型 profile 四种意图等价

#含多张 LUT 的 profile 意图确实可区分

#绝对比色是已知限制

#变换顺序与白点（实现要点）

#1. TRC 必须先于矩阵

linear = TRC(encoded)     # 先线性化
XYZ    = M · linear       # 再乘矩阵

#2. PCS 是 D50，但不能自己再做一次色适应

#明确不做

• 绝对比色的白点缩放：编号 3 当前与媒体相对比色（编号 1）相同。本项目按标准形式实现过白点缩放，但实测与 lcms2 的偏差从 20 级恶化到 107 级，说明该形式与参考实现的语义不符；在无法确定参考语义前不发布猜测实现。详见上文「渲染意图」。
• 感知 / 饱和度意图的 gamut mapping：本库通过选取 A2B0/A2B2 表来体现意图，与 lcms2 在这两种意图下交叉核对通过；但不自行做色域映射（映射规则由 profile 内的 LUT 承载）。
• PCS 为 XYZ 的 LUT 型 profile：已实现并通过验证，但只覆盖了 v4（mAB /mBA ）样本—— 本机与参考实现的测试套件里带 LUT 的 profile 全是 Lab PCS，XYZ PCS 的样本是合成的 （testdata/xyz_lut.icc）。v2 的 mft1/mft2 + XYZ PCS 组合走同一段解码代码， 但没有真实样本，未建立判据。另：PCS 为其他取值时会显式报错，不静默给出错误颜色。
• 黑点补偿（BPC）：不做。
• 图像文件读写（PNG / JPEG / TIFF）：本库只处理色彩数值，不碰图像容器。4 通道（CMYK）的求值本身已可用。
• 软打样、色貌模型：不做。

#设计要点

#外部不可信输入

• 每一处读取都做边界检查，越界返回结构化错误而不是 panic；
• 头部声明的 size 若大于实际字节数会被拒绝（此后所有 tag 偏移都不可信）；
• 每个 tag 的 offset + size 必须落在文件范围内；
• tag 条目数必须能装进剩余空间，且乘法做了溢出检查。

#大端序与定点数

实测教训：用错误的字节序读 sRGB Color Space Profile.icm，会把 3144 字节读成 1208745984，且 acsp 签名读成乱码。

#测试与验证

moon test --target wasm-gc     # 78 项测试
moon test --target js          # 同一套测试，js 后端
moon test --target native      # 同一套测试，native 后端
python tools/diff_oracle.py wasm-gc    # 外部 oracle 差分
python tools/diff_oracle.py js         # 同上，js 后端

1. 合成字节流：精确构造每个字段，验证解析逻辑本身（含畸形输入）；
2. 真实 profile：Windows 系统自带的 3 个真实 profile（matrix/TRC 型 sRGB、 真实显示器、CMYK/LUT 打印机），外加 Little-CMS 测试套件里的 ICC v4 profile test4.icc（覆盖 mAB / mBA ，来源与许可见 testdata/README.md）；
3. 外部 oracle：六个来源——
   • tools/diff_oracle.py：Python struct 独立按规范解析并独立重做 matrix/TRC 变换，与本库逐字段、逐样本比对；并对 v4 的 mAB /mBA 做独立结构对拍（网格、精度、各段曲线条数、矩阵项数）；
   • link_golden_wbtest.mbt：lcms2 生成的 4096 个彩色样本金标（matrix/TRC → matrix/TRC）；
   • clut_golden_wbtest.mbt：625 个 CLUT 网格节点 + 300 个 lcms2 CMYK 样本；
   • cross_link_golden_wbtest.mbt：lcms2 生成的跨类型链接金标（sRGB ↔ CMYK 各 300 个随机样本）；
   • intent_golden_wbtest.mbt：lcms2 生成的四种渲染意图金标（200 个随机 RGB 样本，四意图共用输入）；
   • v4lut_golden_wbtest.mbt：lcms2 生成的 v4 LUT 金标（A2B0/A2B1/B2A0/B2A1 × 40 样本）；
   • xyz_lut_golden_wbtest.mbt：lcms2 生成的合成 XYZ-PCS profile 金标（RGB→LAB 与 RGB→RGB 各 26 样本）；
4. 网格节点：CLUT 节点值不依赖插值细节，任何正确实现在节点上都必须 返回存储值。这一层单独钉住解析、索引步长、Lab 解码； v4lut_wbtest.mbt 里还有一条同类的 v4 节点判据。

• matrix/TRC 差分：3 个 profile × 15 个样本 × 3 个分量，最大偏差 0.0（逐位一致）， wasm-gc 与 js 双后端相同。容差因此设为 1e-15。
• 与 lcms2 交叉核对（matrix/TRC → matrix/TRC）：一致率 98.68%，判据见上文。
• CLUT 网格节点：625 个节点与独立解析的偏差 < 1e-6（金标精度上限）。
• CLUT 对 lcms2：最大偏差恰为 1 级（8 位），无 2 级及以上； L 通道平均有符号差 −0.11 级，即无系统性偏移。
• 跨类型链接对 lcms2（各 300 个随机样本，8 位域）：
  • sRGB → CMYK：完全一致 297/300（99%），最大偏差 ≤ 2 级；
  • CMYK → sRGB：完全一致 173、差 1 级 125、差 2 级 2，最大偏差 2 级。
• 渲染意图对 lcms2（200 个随机样本，8 位域）：感知 / 相对比色 / 饱和度 三种意图最大偏差 ≤ 2 级、一致率 ≥ 60%；绝对比色见上文「已知限制」。
• ICC v4 LUT 对 lcms2（test4.icc，40 个样本，8 位域）：A2B0 与 A2B1 均 40/40 完全一致（偏差 0），B2A0 38/40、B2A1 39/40，最大偏差 1 级。
• PCS 为 XYZ 的 LUT（合成 xyz_lut.icc，26 个样本，8 位域）：设备→PCS Lab 与 组合变换均 26/26 完全一致（偏差 0）。
• v4 结构差分（tools/diff_oracle.py）：Python 独立解析的网格、精度、曲线条数与 矩阵项数，与库的输出全部吻合（含合成 XYZ profile 的 A3/M0/B3 结构）。

#参考与移植说明

lcms2 采用 MIT 许可证，与本项目 Apache-2.0 兼容。本项目未链接、未编译、未复制其代码； 仓库内只包含它的测试用 profile testdata/test4.icc（用于建立 ICC v4 LUT 判据）， 其来源、许可与 MIT 声明全文见 testdata/README.md。

#许可证