#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 rate = @lib.extract_dots(back, dcfg)   // ≥0.9 判定点阵水印存在

#命令行工具（文件模式 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            # 点阵命中率
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. 溯源验证：
   • extract_dots 命中率 1 → PASS（点阵在 JPEG q85 后完整保留）；
   • extract_dct 提取 UID UID-00421 → 定位观众 421（DCT 域水印在亮度域嵌入，与 JPEG 量化域一致，转码后仍可提取）；
   • trace_dots 对候选 [seed 1, 2, 421] 溯源 → 命中索引 2 → 锁定观众 C。

→

#性能基准（实测）

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）决定，这是提取与溯源的基础。
• 归一化网格：点阵落点按比例坐标（单元 = 图宽 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.11 已发布（mooncakes，https://mooncakes.io/docs/yuzhiblue/moon-watermark）；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 字节填充提速。101 测试全过，moon check --deny-warn 零警告，CI 绿。

#License