#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
...

#软打样（soft proofing）

源设备值 → PCS → 打样设备值 → PCS → 显示设备值
             A2B    B2A         A2B    B2A

let chain = @moon_icc.ColorTransform::proofing(
  @moon_icc.Profile::parse(@fs.read_file_to_bytes("sRGB Color Space Profile.icc")),
  @moon_icc.Profile::parse(@fs.read_file_to_bytes("printer.icc")),   // 打样：CMYK 印刷机
  @moon_icc.Profile::parse(@fs.read_file_to_bytes("display.icc")),   // 显示设备
  1,   // 源/显示侧意图：媒体相对比色
  1,   // 打样意图：也可用 3（绝对比色）
)
let (proof_values, shown) = chain.evaluate([ 0.5, 0.5, 0.5 ])
// proof_values = 印这张图会用到的 CMYK 四个分量
// shown        = 屏幕上应显示的 RGB

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

proof_intent 1
proof_channels 4
display_channels 3
proof 0 | 0 0 0 255 | 41 41 40
proof 51 | 13 17 16 224 | 61 60 59

#色域判断（gamut check）

let source = @moon_icc.Profile::parse(@fs.read_file_to_bytes("sRGB Color Space Profile.icc"))
let target = @moon_icc.Profile::parse(@fs.read_file_to_bytes("printer.icc"))

// 源设备值 → PCS XYZ（统一入口：matrix/TRC 型与 LUT 型 profile 都适用）
let xyz = source.device_to_pcs(1, [ 0.0, 1.0, 0.0 ])   // sRGB 纯绿
let de = target.round_trip_delta_e(1, xyz)             // 往返 ΔE76
let inside = target.in_gamut(1, xyz)                   // 按自适应容差判定
println(de)      // 55.83...
println(inside)  // false —— SWOP CMYK 覆盖不了 sRGB 纯绿

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

tolerance 5.591375629781349
gamut 0 0 0 0 de=12.88 out      ← 纸张到不了 L*=0
gamut 1 255 255 255 de=3.42 in  ← 纸白可表达
gamut 3 0 255 0 de=55.83 out    ← SWOP CMYK 覆盖不了 sRGB 纯绿
gamut 12 68 68 68 de=5.19 in    ← 中性灰在色域内

#命令行示例

moon run cmd/main --target wasm-gc -- parse testdata/srgb.icc
moon run cmd/main --target wasm-gc -- transform testdata/srgb.icc
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
moon run cmd/main --target wasm-gc -- link testdata/srgb.icc testdata/cmyk_printer.icc saturation
moon run cmd/main --target wasm-gc -- link testdata/srgb.icc testdata/cmyk_printer.icc absolute
moon run cmd/main --target wasm-gc -- proof testdata/srgb.icc testdata/cmyk_printer.icc testdata/display.icc
moon run cmd/main --target wasm-gc -- gamut testdata/srgb.icc testdata/cmyk_printer.icc
moon run cmd/main --target wasm-gc -- lut testdata/cmyk_printer.icc
moon run cmd/main --target wasm-gc -- lut testdata/test4.icc

size 3144
version 2.1
class mntr
colorspace RGB 
pcs XYZ 
datetime 1998-02-09T06:49:00
intent 0
illuminant 0.964202880859375 1 0.8249053955078125
tagcount 17
cprt 336 51
desc 388 108
wtpt 496 20
...

sample 0.25 0.049063689759460294 0.050879655743278275 0.041981500061132944 ...
sample 0.5 0.20640003241890215 0.21403939749252843 0.17660683523992873 ...
sample 1 0.9642791748046875 0.999969482421875 0.8250885009765625 ...

#当前进度

#CLUT 型 profile 变换

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 意图确实可区分

#绝对比色的 PCS 白点缩放

• 没有 wtpt tag → D50；
• v2 且设备类为 mntr → D50（老显示器 profile 的 wtpt 记的是器件白 D65， 而它的矩阵列已经适应到 D50。用 D65 会让 Z 分量多乘约 1.32 倍）；
• 其余取 wtpt 原值（CMYK 打印机记的是纸张白，显著低于 D50）。

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

#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）的求值本身已可用。
• 色貌模型（CAM）：不做。ICC 的 PCS 已隐含观察条件，超出 PCS 的色貌预测（CIECAM02 等）不在本库范围。
• 黑点补偿（BPC）：不做。软打样链与色域判断已完成；BPC 是相对比色之上的可选项， 其黑点检测依赖 lcms2 那样的迭代反查，本库尚未实现，测试中也不声称支持。

#设计要点

#外部不可信输入

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

#大端序与定点数

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

#测试与验证

moon test --target wasm-gc     # 85 项测试
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 后端
python tools/verify_publish.py         # 在全新工程里实拉已发布包并跑真实变换
python tools/check_readme_examples.py  # 把本文件的示例代码逐块实跑并核对其中公布的数值
python tools/gen_proof_golden.py       # 重新生成软打样金标（需要 MSYS2 gcc 编译 lcms2）

check_readme_examples.py 与 verify_publish.py 不放进 CI 的 push 门禁： 它们从 mooncakes.io 拉取已发布版本，而 push 门禁跑的是当前源码—— 若改了示例但尚未发布，二者会不一致而产生误报。这两个脚本用于发布前后的人工验证。

#核心功能 → 判据对照

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 样本）；
   • proof_golden_wbtest.mbt：C 版 lcms2 生成的软打样金标。Pillow 不暴露 proofing 接口，因此 tools/gen_proof_golden.py 用 MSYS2 gcc 编译 _research 下的 Little-CMS 源码，调用 cmsCreateProofingTransform（SOFTPROOFING | NOOPTIMIZE）；
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%；绝对比色 197/200 完全一致、 最大偏差 1 级。
• 软打样对 lcms2 cmsCreateProofingTransform（16 个灰阶样本，8 位域）： 相对/相对 7/16 完全一致、相对/绝对打样 9/16，两者最大偏差均为 1 级。
• 色域判断（sRGB → CMYK 打印机）：中性轴基线 4.47 ΔE，自适应容差 5.59； 灰阶与纸白判 in，纯黑（ΔE 12.88）与 sRGB 原色（12.48–103.12）判 out。
• 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。

#许可证