12.2 图像 digest 与误差度量

A. digest 的适用边界
   整数类重跑 sha256 稳定 : True  复现卷二基线 = True
   浮点镜像 sha256 与基线 : 相同 = False  (但 MAE 0.4963 属噪声地板)

B. MAE 的盲区（两张 256 像素图）
   整幅 +1  MAE    1.0  本卷 PSNR  48.13 dB  RMSE   1.0  RMSE-PSNR  48.13 dB  最大通道差   1
   4px +64  MAE    1.0  本卷 PSNR  48.13 dB  RMSE   8.0  RMSE-PSNR  30.07 dB  最大通道差  64

# snippet: sim/cg_shade_12_2_metrics.py（节选：RMSE / 教科书 PSNR / 合成剪影）
def rmse(a, b):
    d = np.asarray(a, dtype=np.int64) - np.asarray(b, dtype=np.int64)
    return float(np.sqrt(np.mean(d.astype(np.float64) ** 2)))


def rmse_psnr(a, b):
    """教科书 PSNR：20*log10(255 / RMSE)，对误差分布敏感（与 cgshade.psnr 不同）。"""
    r = rmse(a, b)
    return float("inf") if r == 0.0 else 20.0 * math.log10(255.0 / r)

# 方向二：合成剪影平移——覆盖不一致但颜色误差极小
s = 16
e1 = np.zeros((s, s), dtype=np.uint8)
e2 = np.zeros((s, s), dtype=np.uint8)
e1[:, 8:] = 128
e2[:, 7] = 4
e2[:, 8:] = 128
cov1, cov2 = e1 != 0, e2 != 0

C. 覆盖一致性与颜色误差是两条独立判据
   方向一 逐顶点vs逐像素 : 覆盖 0.0‰  MAE 3.5764  PSNR 37.06 dB  ← 覆盖一致、颜色有误差
   方向二 剪影平移       : 覆盖 62.5‰  MAE 0.25  ← 覆盖不一致、颜色误差极小

// file: lantern/core/src/lantern/cg_shade_12_metrics.ts
// tier: P
// verify: node --test 'core/test/cg_shade_12_2_metrics.test.ts'
// 12.2 的误差度量：把「一组标量」定义清楚，并显式标出各自的盲区。
//
// 三条纪律：
//   1. 没有单一标量能替代全部 —— 「整幅偏 1」与「4 个像素偏 64」的 MAE 都是 1.0。
//   2. 分布敏感的是 RMSE 与最大通道差；psnrFromMae 是 MAE 的单调变换，不提供独立信息。
//   3. 覆盖归属差异与颜色误差是两条独立判据，必须分两栏报告。
//
// 累加用 double：8 位差的平方最大 65025，乘 76800×3 个样本仍在 2^53 内，无精度损失；
// 只有最后转 dB 时用一次 Math.log10。

/** 逐通道误差统计：MAE / RMSE / 最大通道差 / 差值直方图。 */
export interface ErrorStats {
  readonly samples: number;
  readonly mae: number;
  readonly rmse: number;
  readonly maxChannelDiff: number;
  readonly hist: ReadonlyMap<number, number>;
}

/** 一次扫完四个标量与直方图。a、b 是等长的 8 位通道序列。 */
export function errorStats(a: ArrayLike<number>, b: ArrayLike<number>): ErrorStats {
  if (a.length !== b.length) throw new Error(`长度不一致: ${a.length} vs ${b.length}`);
  let sumAbs = 0;
  let sumSq = 0;
  let maxDiff = 0;
  const hist = new Map<number, number>();
  for (let i = 0; i < a.length; i += 1) {
    const d = Math.abs(a[i] - b[i]);
    sumAbs += d;
    sumSq += d * d;
    if (d > maxDiff) maxDiff = d;
    hist.set(d, (hist.get(d) ?? 0) + 1);
  }
  return {
    samples: a.length,
    mae: sumAbs / a.length,
    rmse: Math.sqrt(sumSq / a.length),
    maxChannelDiff: maxDiff,
    hist,
  };
}

/** 本卷口径：由 MAE 推出。与 MAE 互为单调变换，故不提供独立信息，只为可读性保留。 */
export function psnrFromMae(mae: number): number {
  return mae === 0 ? Infinity : 20 * Math.log10(255 / mae);
}

/** 教科书口径：由 RMSE 推出，对误差分布敏感。 */
export function psnrFromRmse(rmse: number): number {
  return rmse === 0 ? Infinity : 20 * Math.log10(255 / rmse);
}

/** 非背景即覆盖。背景色取自配置的 backgroundQ8，与 S 层同一口径。
 *
 * `channels` 必须显式对齐数据：渲染缓冲是 3 通道，而合成的单通道掩码图是 1。
 * 写死 3 会在单通道图上把每 3 个像素并成一个，算出的覆盖差异毫无意义。
 */
export function coveredMask(buf: ArrayLike<number>, bg: readonly number[], channels = 3): Uint8Array {
  const m = new Uint8Array(buf.length / channels);
  for (let p = 0; p < m.length; p += 1) {
    const i = p * channels;
    let isBg = true;
    for (let c = 0; c < channels; c += 1) if (buf[i + c] !== bg[c]) { isBg = false; break; }
    m[p] = isBg ? 0 : 1;
  }
  return m;
}

/** 覆盖归属差异（‰）：两幅覆盖掩码的异或像素数除以总像素数。 */
export function coverageDiffPermille(a: Uint8Array, b: Uint8Array): number {
  if (a.length !== b.length) throw new Error(`掩码长度不一致: ${a.length} vs ${b.length}`);
  let diff = 0;
  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) diff += 1;
  return (diff * 1000) / a.length;
}

/** 报告格式固定为这一组：颜色四项 + 覆盖一栏。不许只挑一个数上报。 */
export interface Comparison {
  readonly coveragePermille: number;
  readonly mae: number;
  readonly rmse: number;
  readonly psnrMaeDb: number;
  readonly psnrRmseDb: number;
  readonly maxChannelDiff: number;
}

export function compare(
  a: ArrayLike<number>, b: ArrayLike<number>, bg: readonly number[], channels = 3,
): Comparison {
  const e = errorStats(a, b);
  return {
    coveragePermille: coverageDiffPermille(coveredMask(a, bg, channels), coveredMask(b, bg, channels)),
    mae: e.mae,
    rmse: e.rmse,
    psnrMaeDb: psnrFromMae(e.mae),
    psnrRmseDb: psnrFromRmse(e.rmse),
    maxChannelDiff: e.maxChannelDiff,
  };
}

✔ ① MAE 的盲区：整幅 +1 与 4 像素 +64 的 MAE 相同，RMSE 与最大通道差分得开
✔ ② 覆盖与颜色独立：两个方向的数字必须反向
✔ ③ digest 的边界：整数类够用，浮点实现不够用
tests 3 / pass 3 / fail 0