#moon-watermark

#功能矩阵

#可见水印（已实现）

#不可见水印（已实现）

#提取、验证与溯源（已实现）

#图像 IO（基于 mizchi/image）

#不可见性度量（已实现）

#配置持久化（已实现）

#典型应用场景

#安装

moon add yuzhiblue/moon-watermark

#Quick Start

// 依赖：moon add yuzhiblue/moon-watermark
// import：
//   import "yuzhiblue/moon-watermark" @lib
//   import "moonbitlang/core/encoding/utf8" @utf8   // 中文 payload 转 UTF-8 字节
//   import "moonbitlang/core/bytes" @bytes           // Bytes 切片（decode_png 结果）
//
// 注意：String::to_bytes 在 MoonBit 中返回 UTF-16，不可直接作 payload，
// 必须经 @utf8.encode 转码（含 ASCII：@utf8.encode("UID-001")）。

// 1. 生成测试图（或 decode_png 解码真实图片）
let img = @lib.RgbaImage::new(320, 240, 0xFFFF_FFFF)

// 2. 组合嵌入：文本（右下角 45° 斜向）+ 点阵（seed=接收者 ID）+ LSB（观众 ID）
//    embed_all 返回 Result（任一通道失败即 Err，不产生半成品）
//    v0.1.12 起 with_font 可直接设 angle（45° 斜向防盗播水印）
let tcfg = @lib.TextConfig::with_font("LIVE", 8, 200, 2, 0.6, 0xFF00_00FF, "ascii5x7", angle=45.0)
let dcfg = @lib.DotConfig::default()
let opts : @lib.EmbedOptions = {
  text_cfg: Some(tcfg),
  dot_cfg: Some(dcfg),
  lsb_payload: Some(@utf8.encode("UID-001")),
  lsb_key: Some(42L),
  dct_payload: None,
  dct_delta: 24,
}
let marked = match img.embed_all(opts) {
  Ok(m) => m
  Err(e) => { println("embed failed: \{e}"); abort() }
}

// 3. 盲检测 → 提取验证（溯源链路：先 detect 再 extract）
if @lib.detect_lsb(marked) { println("marked ✓") }
let back = @lib.decode_png(marked.encode_png().unwrap_or(Bytes::new())).unwrap_or(img)
let contrast = @lib.dot_contrast(back, dcfg)   // 成对对照信号：目标命中率 − 对照命中率
let ok = @lib.verify_dots(back, dcfg)          // ≥0.4 判定点阵水印存在（v0.1.15）

#命令行工具（文件模式 CLI）

# 嵌入：文本 + 点阵 + LSB 不可见水印，输出 PNG/JPEG（按扩展名）
moon run cmd/main -- embed in.png out.png --text "LIVE 2026-10-03" --font cjk16 --lsb "UID-001" --key 42

# 只嵌 DCT 域水印（抗 JPEG），delta 加大可抗更强压缩
moon run cmd/main -- embed in.jpg out.jpg --dct "UID-001" --delta 48

# 验证
moon run cmd/main -- verify-dots out.png            # 点阵成对对照信号 + 判定（contrast / verify）
moon run cmd/main -- verify-lsb out.png --key 42    # LSB 提取（key 必须与嵌入一致）
moon run cmd/main -- verify-dct out.png --delta 48  # DCT 提取（delta 必须与嵌入一致）

# 无参数 = 内存演示（原 Quick Start 示例）
moon run cmd/main

• --lsb 与 --dct 互斥：DCT 重写亮度分量会破坏 LSB，同时指定时 CLI 保留 LSB、跳过 DCT 并警告。
• 嵌入与提取的 --delta 必须一致：DCT 提取按同一量化网格判定奇偶，两侧不一致会全部错位。
• --opacity 同时作用于文本与点阵水印；文本默认放在右下角（避开不可见水印的左上角头部区），默认文本为 LIVE。
• payload 按 UTF-8 编码：String::to_bytes 在 MoonBit 中返回 UTF-16，CLI 已用 @encoding/utf8 统一转码（含中文 payload）。
• 水印组合顺序：可见水印（文本/点阵/Logo）先嵌、不可见水印最后（避免覆盖其左上角头部区——可见水印请避开头部区位置）。embed_all 中 LSB 与 DCT 互斥返回 Err（库 API 不静默降级；CLI 因保留 LSB 的取舍是跳过 DCT 并警告，两者策略不同）。

#演示

#真实场景链路演示（E2E）

moon run cmd/e2e                 # 默认用 assets/live_frame.png
moon run cmd/e2e -- your.png     # 任意图片跑同一链路

1. 贴片三件套嵌入：可见文本 直播 UID-00421（中下部字幕条上方，防盗播震慑；cjk16 混合文本——中文+英文+数字一条水印完整渲染，v0.1.10；v0.1.11 起 48px 字号完整落在画布内）+ 点阵 seed=421（观众 ID，溯源用）+ DCT UID-00421（抗平台转码的取证载体）；
2. 模拟平台转码：encode_jpeg(85)（平台切片/分发必经的 JPEG 重压链路）→ 读回；
3. 溯源验证（v0.1.15 起点阵判定升级为成对对照）：
   • dot_contrast 0.5 + verify_dots → PASS（JPEG q85 后水印信号仍高于同图对照点位，原图暗区干扰已被扣除）；
   • extract_dct 提取 UID UID-00421 → 定位观众 421（DCT 域水印在亮度域嵌入，与 JPEG 量化域一致，转码后仍可提取）；
   • trace_dots 对候选 [seed 1, 2, 421] 溯源 → 唯一命中索引 2 → 锁定观众 C（信号最高且与次高差距 ≥ margin，无歧义不误锁）。

→

#溯源判定：输入输出案例集

#判定规则总览

#机制承诺边界（实测标定，cmd/calibrate 可复现）

#实际运行输出（moon run cmd/review）

================================================================
moon-watermark 溯源判定案例集（多对照信号 + 自标定，v0.1.18）
点阵溯源的判定情形：原图干扰 / 候选歧义 / 真实分发来源 / 结构图型虚警
================================================================

--------------------------------------------------------------
案例 A：原图干扰（未嵌入水印的暗色原图 → 必须拒判）
--------------------------------------------------------------
A1 输入：64×64 纯暗图（未嵌入任何水印），候选 seed=42
    绝对命中率（旧判据）= 1   ← 旧判据在此假阳性 verify=true
    dot_contrast（新判据）= 0   verify_dots = false
    trace_dots = -1  → -1 = 无候选达标，不误锁（正确）
A2 输入：64×64 暗纹理图（亮度 20/150 伪随机，未嵌入），候选 seed=42
    绝对命中率（旧判据）= 1   ← 暗纹理系统抬高命中率
    dot_contrast（新判据）= 0   verify_dots = false
    trace_dots = -1  → 原图干扰被对照项扣除，正确拒判
结论：原图干扰由成对对照机制自动扣除——未嵌入图 contrast ≈ 0，
      verify_dots=false、trace_dots=-1；假阳性在回归测试中固化。

--------------------------------------------------------------
案例 B：候选歧义（信号不可区分 → -2 拒绝误锁；可区分 → 唯一命中）
--------------------------------------------------------------
B1 输入：嵌入 seed=42 的图，候选 = [cfg42, cfg42]（信号并列）
  候选[0] seed=42  dot_contrast=1  达标（阈值 0.4）
  候选[1] seed=42  dot_contrast=1  达标（阈值 0.4）
    最高 − 次高 = 0 < margin(0.15)  →  trace_dots = -2
    → -2 = 候选歧义，无法唯一确定来源，转人工复核（不误锁）
B2 输入：同一张图，候选 = [cfg46(错误seed), cfg42(正确seed)]
  候选[0] seed=46  dot_contrast=0  未达标（阈值 0.4）
  候选[1] seed=42  dot_contrast=1  达标（阈值 0.4）
    →  trace_dots = 1  → 唯一命中索引 1（正确 seed）
结论：能区分时差距 > margin 即锁定；不能区分时返回 -2——
      「歧义」与「命中」由同一阈值体系统一判定，无中间模糊态。

--------------------------------------------------------------
案例 C：真实分发来源（分发独立 seed → 泄漏帧唯一锁定）
--------------------------------------------------------------
C 输入：嵌入 seed=421（观众C）的图 → JPEG q85 转码 → 读回
        候选 = [seed=1(观众A), seed=2(观众B), seed=421(观众C)]
  候选[0] seed=1  dot_contrast=0  未达标（阈值 0.4）
  候选[1] seed=2  dot_contrast=0  未达标（阈值 0.4）
  候选[2] seed=421  dot_contrast=1  达标（阈值 0.4）
    verify_dots = true（JPEG q85 后仍通过）
    trace_dots = 2（0=观众A 1=观众B 2=观众C）→ 锁定观众 C（seed 421）——泄漏来源唯一确定
结论：分发时为每个接收者分配独立 seed，泄漏帧的 contrast 只在
      真实来源候选上显著 >0 → trace_dots 返回其索引，溯源到人。

--------------------------------------------------------------
案例 D：盲检测（溯源第一问：先判「是否被标记」再提取）
--------------------------------------------------------------
D1 输入：未嵌入的原图
    detect_lsb=false  detect_dct=false  → 未标记，溯源终止
D2 输入：嵌入 DCT 水印（UID-00421, delta=24）的图
    detect_dct=true  detect_lsb=false  → 已标记（DCT）→ extract_dct = UID-00421
D3 输入：嵌入 LSB 水印（UID-001, key=42）的图
    detect_lsb(无key)=false  ← 带 key 混淆的帧头不可见（已文档化语义）
    extract_invisible(错误key=43) None（magic 校验拒绝，错误 key 提取失败）；extract_invisible(正确key=42) = UID-001
结论：盲检测回答「是否被标记」（第一问，无需参数）；提取回答
      「标记内容是什么」（需正确 key/delta）。带 key 的 LSB 帧
      以持有方嵌入记录为溯源入口，边界已在 README 安全边界声明。

--------------------------------------------------------------
案例 E：结构图型虚警（渐变原图 → 多对照 + 自标定两级拒判）
--------------------------------------------------------------
输入：128×128 水平渐变图（0→255，未嵌入），候选 seed=12 / 8
E1 seed=12  单对照=0.4444444444444444（≥0.4 虚警）  多对照(k=8)=0.18308080808080807 → verify_dots=false（修复）
E2 seed=8   单对照=0.6666666666666666（≥0.4 虚警）  多对照(k=8)=0.4833333333333333（仍达标——目标点位自身偏斜）
    calibrated=true 自标定：0.4833333333333333 未显著高于本图 null 本底 + 0.15 → verify_dots=false（修复）
    verify_dots(calibrated=true) = false
结论：单对照在结构图型上存在 ~1.3% 虚警（1024 样本实测 13 例）；
      多对照压至 0.5%，自标定压至 0.1%。残余虚警由显著性检验兜底——
      机制的承诺边界以 cmd/calibrate 标定数据为准，不做绝对化表述。
================================================================
判定规则速查（trace_dots 返回值语义）：
  >= 0  唯一命中 → 锁定该候选对应的分发来源（输入索引）
  = -1  无候选达标 → 原图未嵌入或候选均不匹配（原图干扰已扣除）
  = -2  候选歧义（最高 − 次高 < margin 0.15）→ 不误锁，转人工复核
================================================================

#关键数值解读

• 案例 A（原图干扰）：纯暗图 / 暗纹理图未嵌入时，旧判据「绝对命中率 ≥ 0.9」= 1 → 必然假阳性（v0.1.14 及以前的已知缺陷）；成对对照 contrast = 0 → 正确拒判。修复已在 verify_wbtest.mbt 的暗图假阳性测试组中固化（纯黑图、20/150 暗纹理图均 verify=false、trace=-1）。
• 案例 B（候选歧义）：两个相同候选 contrast 并列 = 1，最高 − 次高 = 0 < margin(0.15) → -2；对照组中错误 seed contrast = 0 vs 正确 seed = 1，差距 > margin → 唯一命中。「歧义」与「命中」由同一阈值体系统一判定，不存在"大致锁定"的中间态。
• 案例 C（真实分发来源）：JPEG q85 平台转码后，错误候选 contrast = 0（多对照中位数下，错误 seed 的目标命中率与对照命中率持平；单对照下甚至出现 −0.11 的负值——对照点位比目标点位更暗），真实来源 contrast = 1 → trace_dots = 2，指向观众 C。判据依赖"信号强度排序 + 差距"双条件，而非简单比零。
• 案例 D（盲检测）：未嵌入图全部无参检出为 false；DCT 帧可无参检出并提取内容；带 key 的 LSB 帧无 key 检不出（帧头被 keystream 混淆掩盖，已文档化语义，非缺陷）——此类帧以持有方嵌入记录为溯源入口，边界见「设计说明·安全边界」。
• 案例 E（结构图型虚警）：渐变图上 seed=12/8 单对照 contrast = 0.444 / 0.667 ≥ 0.4（虚警）——原图未嵌入却被判"存在水印"，这是 v0.1.17 单对照机制的实测弱点。多对照（k=8）把 seed=12 修到 0.183；seed=8 因偏差出在目标点位自身仍 0.483，由 calibrated=true 自标定兜底拒判。这是"用数据校准承诺"的直接体现：机制能做什么、不能做什么，以 cmd/calibrate 的实测数据为准。

#性能基准（实测）

moon run cmd/bench            # 320×240 … 1920×1080 四档
moon run cmd/bench -- 640 360 # 指定尺寸

• 嵌入成本与画面尺寸基本无关、与 payload 长度线性：DCT/LSB 只改写 payload 所需区域（12 字节帧 = 4B 头 + 8B payload = 96 bit：DCT 96 个 8×8 块 / LSB 32 像素），文本只渲染文本区域——贴片工坊逐帧调用 embed_all 的成本稳定在 ~100 µs 级，不随分辨率放大；
• DCT 是最重路径（~110 ms，全 DCT-II 逐块变换，wasm 解释模式）；逐帧实时流建议走 LSB/点阵组合，DCT 用于关键帧取证；
• 编码 IO 随尺寸线性（PNG 1080p ~0.5 s），生产链路建议编码走并行或选择 JPEG（encode_jpeg(85) 远快于 PNG，且 DCT 水印本就抗 JPEG）。

#鲁棒性测试矩阵（实测）

符号含义：✅ 通过/可提取 · ❌ 该攻击下提取失败（水印特性，见说明列）· ⚠️ 已知边界（点阵在纯裁剪下失效）。❌ 不是功能缺失——每种水印各有适用链路，表格与说明列给出替代方案。

#设计说明

• 颜色打包：0xRRGGBBAA。MoonBit Int 为 32 位有符号，0xFFFF_FFFF 等高位字面量会表示为负数——位运算完全等价，无需担心；推荐用 (r << 16) | (g << 8) | b | (a << 24) 构造颜色。
• 确定性：点阵水印完全由 DotConfig（含 seed）决定，这是提取与溯源的基础。
• 多对照判定与自标定（v0.1.18）：v0.1.15 的单对照在结构图型上存在残余虚警（渐变/棋盘/色块等 1024 样本实测 13 例，max 0.667）。dot_contrast 升级为多对照：目标命中率 − median(k=8 组对照命中率)，controls 参数可回退 k=1（与旧实现逐位一致）。verify_dots / trace_dots 新增 calibrated 自标定模式——候选信号须显著高于本图 null 本底（8 个独立 seed 的 contrast 最大值 + margin）才输出判定。标定数据：单对照 1.3% → 多对照 0.5% → 自标定 0.1%（详见「溯源判定」章节与 cmd/calibrate）。
• 点阵适用边界（如实说明）：点阵是亮度对比通道——两类画面属拒绝域：① 原图背景暗像素占比过高（约 >60%，如整图纯暗），深色点与背景对比不足、contrast 偏低；② 高频二值纹理（噪声图、密集文字截图），3×3 邻域命中统计被纹理饱和，信号淹没在本底中。拒绝域内 trace_dots 只报"无法确定"，不输出指认——请改走 DCT/LSB 通道（DCT 抗 JPEG，e2e 正是一起嵌入、互为兜底）。
• 归一化网格：点阵落点按比例坐标（单元 = 图宽 8%），点坐标对齐偶数像素，因此缩放后仍可提取；代价是纯裁剪会因参考尺寸改变而错位（见鲁棒性矩阵）。
• PNG 无损往返：PNG 编码/解码不损失 LSB 信息，是不可见水印的可靠载体（见鲁棒性矩阵）。
• DCT 域设计：亮度域（BT.601 Y=0.299R+0.587G+0.114B） 8×8 分块 DCT-II + 中频系数 (4,1) QIM 量化嵌入，delta 默认 24（越大越抗 JPEG、可见性略升）。亮度域与 JPEG 编码的 Y 分量一致，DCT 系数才能经受色度量化往返（在 G 通道嵌入会被 YCbCr 色度量化破坏——v0.1.7 起改为亮度域）。注意：纯白/纯黑等饱和区域的正扰动会被像素 clamp 截断（系数跌到 Δ/2 边界），鲁棒性弱——真实图像纹理区不受影响；若已知图片大面积饱和，调大 delta 或改用 LSB。
• 安全边界：LSB 与 DCT 水印提供隐蔽性与 JPEG 鲁棒性，不提供强加密/抗伪造——嵌入格式（magic、布局、系数位置）为公开知识，知道算法者可提取或覆盖水印；需要鉴权/防伪时，依赖持有方按 secret 管理嵌入参数（LSB 的 key、DCT 的 delta），并在上层做密钥分发与吊销。
• embed_* 统一返回 Result[RgbaImage, String]（v0.1.9 起）：可见水印当前无失败路径（Ok 恒成立），不可见水印容量超限返回 Err；调用方统一一种错误处理模式。extract_* 返回 Bytes?（提取失败 None），extract_dots 返回命中率（0.0~1.0）。
• 旋转实现：逆映射最近邻 + 像素中心坐标（round 定位源像素），90/180/270 为精确像素搬运；源范围外像素透明。embed_text 对 >512 字符返回 Err——超长文本旋转会分配 GB 级中间位图（资源保护，见「非目标」）。
• GlyphProvider 字形接口：trait GlyphProvider { cell_width / cell_height / glyph }，内置 Ascii5x7（拉丁，A-Z/0-9/常用符号）与 Cjk16（16×16 中文点阵，GB2312 一级字 3755 个 + ASCII/符号 96 个，Noto CJK 生成；未收录的字形返回 None → 渲染为空白）。混合文本（如 直播 LIVE 2026-10-04 UID-00421）单条水印完整渲染——直播贴片“中文平台名+英文标识+时间戳/观众 ID”不再需要拆两条文本。自定义字形：实现 trait 后走 render_text_with，或用 BitmapFont::new(w, h, pairs) 一行构造自带字表、BitmapFont::with_cjk16(extra) 在汉字+ASCII 基础上补充生僻字/品牌字形（v0.1.10 起含 ASCII 段）；亦可经 TextConfig.font（JSON 兼容）切换内置字体。

#非目标（明确边界）

• 不提供强加密/防伪认证：LSB/DCT 提供隐蔽性与 JPEG 鲁棒性；鉴权、防伪、密钥分发与吊销由上层负责（见「设计说明·安全边界」）。
• 不可见水印不抗几何攻击（缩放/裁剪后提取失败是水印原理边界，非 bug）：可见点阵水印抗缩放、LSB 抗裁剪已覆盖主流链路（见鲁棒性矩阵）。
• 不做视频/流式封装：逐帧应用（如直播贴片）在上层组合本库能力——embed_all 即面向逐帧复用设计。
• 载体格式仅 PNG/JPEG：GIF/WebP/AVIF/BMP 不在计划内；多格式需求请在调用方转码后嵌入。
• 不做超长文本水印：embed_text 对 >512 字符返回 Err（旋转中间位图可至 GB 级内存，边界测试固化）。

#状态

• 当前：v0.1.18 已发布（mooncakes，https://mooncakes.io/docs/yuzhiblue/moon-watermark）：判定机制标定升级——针对标定实验发现的单对照残余虚警（结构图型 1024 样本实测 13 例，max 0.667），dot_contrast 升级为多对照组（k=8 median，controls 可回退 k=1 向后兼容），verify_dots / trace_dots 新增 calibrated 自标定显著性检验（候选须显著高于本图 null 本底）；误报率实测 1.3% → 0.5%（多对照）→ 0.1%（自标定）。新增 cmd/calibrate 标定实验（误报率 / 锁定质量可复现测量）与案例 E（结构图型虚警两级修复）；溯源输出语义明确为「唯一强指向候选 / 无法确定」两种统计证据出口，最终归属判定结合分发台账交叉核验。114 测试全过（含 5 个标定回归测试），README 如实记录机制承诺边界与拒绝域。
• v0.1.17：README 文案中性化与版本状态修正（章节更名「溯源判定：输入输出案例集」，版本状态与 mooncakes / GitHub Release 三方对齐）。
• v0.1.16：moon.mod 版本号补位至 0.1.16 并发布 mooncakes（发布内容与 0.1.15 代码一致，解决 0.1.15 提交时 moon.mod 未同步的问题）。
• v0.1.15：点阵判定从"绝对命中率"升级为成对对照信号（dot_contrast = 目标点位命中率 − 对照点位命中率）——对照点位由 seed 确定性派生（同密度、未画点处），同一图上同阈值统计，原图暗区/纹理干扰被自动扣除。修复暗色原图假阳性（纯黑/深纹理未嵌入图此前 verify=true、trace 误锁，现 contrast=0、verify=false）；trace_dots 新增歧义防护（信号最高但与次高差距 < margin 返回 -2，不误锁）；verify_dots 默认阈值 0.4、trace_dots 新增 margin 参数。同步升级 e2e/gen_demo/CLI 输出与回归测试（109 测试全过），并如实文档化点阵适用边界（整图过暗时点阵信号不可分辨，暗色画面走 DCT/LSB 通道兜底）。
• v0.1.14：全项目代码审查修复——修复 Cjk16 中文渲染错位（渲染循环按每行字节数通用化，此前 16×16 中文/宽字形左半恒空、右半错位，"啊/防"等汉字首次正确显示）；旋转方向文档统一为顺时针（与实现一致）；DCT delta<=0 拒绝（此前静默产生无法提取的水印并改坏像素）；LSB/DCT payload >65535 拒绝（2 字节长度字段防静默截断）；点阵 density clamp 到 [0,1]；DCT 余弦表预计算（消除每块上万次 math.cos 调用）。106 测试全过，moon check --deny-warn 零警告。
• v0.1.13：工具链兼容与依赖修复——适配新版 moonc（Int → Int32、moon fmt 规范）；移除多余依赖 mizchi/json；显式声明 moonbitlang/async@0.22.4，覆盖传递依赖的旧格式 async@0.16.6，使新版工具链下 CI 恢复全绿。
• v0.1.12：代码审查修复轮——embed_text 除零防护（font_size=0 + 超宽 + auto_shrink 不再崩溃）、CLI 文本水印失败显式警告、TextConfig::with_font 新增可选 angle（库外可设 45° 斜向水印）、LSB/DCT 重复逻辑合并（lsb_shift / default_delta / block_origin / map_from_pairs）、RgbaImage::new 字节填充提速；附带 Noto CJK（SIL OFL 1.1）许可全文与归属声明。

#License