#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"))

// 建边界：CMYK 用 9 层采样 = 6561 个设备值 → A2B → Lab
let boundary = target.gamut_boundary(1, 9)
println(boundary.samples())    // 6561
println(boundary.coverage())   // 0.83...（CMYK 色域不填满 Lab 的所有方向）

// 判一个颜色（sRGB 纯绿）
let lab = @moon_icc.xyz_to_lab(source.device_to_pcs(1, [ 0.0, 1.0, 0.0 ]))
println(boundary.contains(lab))          // false —— SWOP CMYK 覆盖不了
println(boundary.signed_distance(lab))   // 18.70...（越界了多少，Lab 单位）

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

sectors 16
samples 6561
coverage 0.94140625
gamut 0 0 0 0 boundary=out dist=8.59 mapping_de=12.88     ← 纸到不了 L*=0
gamut 1 255 255 255 boundary=out dist=5.69 mapping_de=3.42   ← 超出纸白边界
gamut 3 0 255 0 boundary=out dist=18.70 mapping_de=55.83  ← SWOP 覆盖不了 sRGB 纯绿

#命令行示例

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
moon run cmd/main --target wasm-gc -- named testdata/named_lab.icc
moon run cmd/main --target wasm-gc -- conformance

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，但不能自己再做一次色适应

#命名色（nmcl 类、ncl2 tag）

class nmcl
pcs Lab 
version 4
vendor_flag 0
n_device_coords 3
prefix PANTONE 
suffix  C
count 5
named 0 PANTONE Red C lab=54.0002 80.8016 69.8988 device=255 0 0
named 3 PANTONE Gray C lab=50.0008 0 0 device=128 128 128
lookup PANTONE Red C -> 54.0002 80.8016 69.8988
lookup Red -> 未命中

#不作为目标（明确边界）

• MPE 多处理元素变换（mped）：MPE 是把 curve / matrix / lut 等元素串成链的 容器。本库已实现其全部 constituent 元素的解码与求值（curv、para、矩阵、 mft1/mft2、mAB/mBA），但不提供任意元素链容器。
• 黑点补偿（BPC）：非 ICC.1 强制要求，属 CMM 扩展选项；与 lcms2 默认行为一致。
• 感知 / 饱和度意图的色域映射算法：映射结果由 profile 内 A2B0/A2B2 承载， 本库忠实执行 LUT，不自造映射（与 lcms2 同）。
• iccMAX（ICC.2）：架构不同（多 PCS、光谱、材质），需要独立设计。
• 色貌模型（CAM）：超出 ICC PCS 范围；PCS 已隐含观察条件。
• 图像容器读写（PNG / JPEG / TIFF）：本库只处理色彩数值，不碰图像容器； 4 通道（CMYK）的求值本身已可用。
• 不完全色适应（AdaptationState != 1）：与 lcms2 默认（AdaptationState = 1） 保持一致；绝对比色只做媒体白点缩放，chad 不参与。

#已实现但判据覆盖不完整（诚实清单）

• PCS 为 XYZ 的 LUT 型 profile：v4（mAB /mBA ）已用合成样本 testdata/xyz_lut.icc 验证（26 样本双向对拍 + u1Fixed15 编码常数判据）； v2 的 mft1/mft2 + XYZ PCS 走同一段解码代码，但没有真实样本、未建立判据。
• abst（PCS→PCS）与 link（设备→设备）：用恒等与解析式合成样本验证 （生成时经 lcms2 复核可读），但没有真实世界的该类 profile。
• 色域判定的外部 oracle：lcms2 自带的 GDB API 实测不可用 （cmsGDBCheckPoint 对全部查询返回 out），改用独立第二实现 （lcms2 取 Lab + Python 重写球面直方图）交叉验证，一致率 91.7%； 没有与 CMM 内部算法逐位对拍的 oracle。

• 命名色（nmcl 类）：ncl2 全字段解析与查表已交付，第三方对拍用 lcms2 cmsNamedColorInfo（PCS u16 与设备坐标逐条相同）；但夹具是合成样本 （testdata/named_lab.icc / named_xyz.icc），本机没有真实世界的 nmcl 类 profile。

#一致性与标准覆盖

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

#开发回顾

#关键架构决策

1. 纯 MoonBit 重写，不用 extern 封装 lcms2：lcms2 需要 C 工具链、无法编到 wasm-gc， 且是黑盒——封装它等于把「实现」这一层让出去。代价是必须自己啃规范（ICC.1:2010-12 §7–§10）。
2. 解析层与变换层分离：reader.mbt（大端读取 + 边界防护）→ header.mbt/tag.mbt （结构）→ transform.mbt/clut.mbt/v4lut.mbt（求值）。外部输入一律先过边界检查， 畸形输入返回 IccError 六种结构化错误，不 panic。
3. PCS 固定 D50，不重复做色适应：profile 里的矩阵列已适应到 D50（见「变换顺序与白点」）， 再加一次会让白点偏离 17.3 ΔE。
4. 色域判定用几何边界而非往返误差：往返法把「映射误差」与「真实越界」混为一谈， 1296 个设备值样本误判 53.7%；改用只由设备值构成的球面直方图边界后为 0。

#AI 参与环节与边界

• AI 参与：规范条文的检索与交叉核对、代码与测试骨架的初稿、变异测试的构造、 文档措辞的收敛。
• 人工负责：架构选型与范围声明（哪些属于项目终点）、每条判据的取舍、 与 lcms2 对拍结果的判断、全部对外材料的最终定稿。
• 验证纪律：所有产出都先过本地门禁（fmt --check / check --deny-warn / 双后端测试） 与第三方对拍（lcms2、Python 独立实现）才入库；判据本身用变异测试检验判别力 （见 MUTATION.md）。命名色的第一版曾因「生成器与解析器犯同一个错」自洽通过， 是 lcms2 逐条对拍抓出来的——这条已写进 MUTATION.md。

#参考来源与许可

• 规范：ICC.1:2010-12（ISO 15076-1:2010），公开标准文本。
• 参考实现：Little-CMS（lcms2，MIT）——只用于行为对拍与规范解读，未移植任何源码； 其测试 profile testbed/test4.icc 作为测试夹具引入，来源与许可见 testdata/README.md。
• 数据与夹具：testdata/ 下第三方 profile 的来源、文件内 cprt/desc 原文、 MIT 许可全文均记录在 testdata/README.md；本仓库合成的 profile 由 tools/gen_*.py 确定性生成（生成器路径与输入即脚本本身）。
• 本项目许可：Apache-2.0（根目录 LICENSE 全文）。

#设计要点

#外部不可信输入

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

#大端序与定点数

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

#测试与验证

moon test --target wasm-gc     # 104 项测试
moon test --target js          # 同一套测试，js 后端
moon test --target native      # 同一套测试，native 后端（本机 Windows 缺 MSVC，以 CI 为准）
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）
python tools/gen_abst_link_profiles.py # 重新生成 abst / link 合成样本（生成时用 lcms2 复核）
python tools/compare_gamut.py          # 色域边界的独立对拍（lcms2 取 Lab + Python 重写，一致率 91.7%）
# 判据有效性（刻意植入错误看测试是否变红）见 MUTATION.md
moon run cmd/main -- conformance       # 打印设备类覆盖矩阵（标准版本与必需行为）

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 打印机，几何边界）：
  • 设备值样本（边界 9 层、验证 7 层，2401 个）误判 0； 旧往返 ΔE 法在 1296 个同类样本上误判 696（53.7%），平均映射误差 6.78、最大 19.73；
  • 纸白与「设备能产生的最深黑」判 in；PCS 纯黑（L*=0）与 sRGB 纯绿/纯蓝判 out；
  • 边界采样覆盖率 0.94（9 层采样；CMYK 色域不填满 Lab 的所有方向）；
  • 面向不同设备：3 通道（显示器）与 4 通道（CMYK）设备都能建边界；同一颜色结论随设备不同 （sRGB 纯红：显示器界内、CMYK 界外）。采样密度需匹配设备——3 通道要 17³ 样本、 4 通道要 9⁴ 样本才达到 0 误判（9 层建 3 通道边界时实测 3/343 误判）。
• 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。

#许可证