14.2 覆盖率与线框

画布              : 320x240，正面 606 三角形（剔除 290 背面）
不变量(1) 双重计数 : 像素侧 47673 == 三角形侧 47673
不变量(2) 二值覆盖 : 43731（== 卷一基线 43731）
计数直方图         : 0次:33069px  1次:40193px  2次:3141px  3次:390px  4次:7px
最大计数           : 4（重叠像素 3538 个，占覆盖像素 80‰）

#!/usr/bin/env python3
# file: lantern/sim/cg_raster_14_2_coverage_wireframe.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_raster_14_2_coverage_wireframe.py
"""14.2 覆盖率与线框：整数覆盖计数、双重计数不变量、第 7 章 Bresenham 画的线框叠加。

二值覆盖掩码只能回答「这个像素被画过吗」；调试时需要的是「被画了几次」——
共享边、T 型接缝、退化三角形的病征全藏在计数值里。故覆盖率图存的是整数计数，
两条不变量把它钉住：
  (1) 像素侧求和 == 三角形侧求和（双重计数）；
  (2) 计数 > 0 的像素集合 == cglib.rasterize 的二值掩码，且总数 == 第 6 章的基线 43731。
线框用第 7 章的整数 Bresenham 画每个正面三角形的三条边，叠加在成片之上。
产物：out/cg_raster_14_2_{coverage,wireframe,overlay}.png 与 .json。
"""

import json
import os
import sys

import numpy as np

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import cglib  # noqa: E402
import cg_raster_14_buffers as B  # noqa: E402

BASELINE_COVERED = 43731  # 卷一基线：sim/render_raster.py 的《烛影山谷》覆盖像素数
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))


def main():
    spec = cglib.load_spec()
    w, h = spec["width"], spec["height"]
    b = B.buffers(spec)
    counts, covered, per_tri = b["counts"], b["covered"], b["per_tri"]

    # 不变量 (1)：像素侧求和 == 三角形侧求和
    pixel_side = int(counts.sum())
    tri_side = int(sum(per_tri))
    assert pixel_side == tri_side, "像素侧与三角形侧的覆盖计数必须相等（双重计数）"
    # 不变量 (2)：二值化后与基线一致
    binary = int((counts > 0).sum())
    assert binary == int(covered.sum()) == BASELINE_COVERED, "二值覆盖必须等于卷一基线 43731"
    assert int(counts.min()) == 0 and int(counts.max()) >= 2, "必须有未覆盖像素与至少一处重叠"

    # 计数直方图（count -> 像素数）
    hist = np.bincount(counts.ravel())
    hist = [(int(k), int(v)) for k, v in enumerate(hist) if v]

    # 线框：第 7 章的整数 Bresenham，只画正面三角形的边
    mask, segs = B.wireframe_mask(b["rtris"], w, h)
    wf_px = int(mask.sum())
    inside = int((mask.astype(bool) & covered).sum())

    out = os.path.join(ROOT, "out")
    cov_gray = np.clip(counts * 64, 0, 255).astype(np.uint8)
    png_cov = cglib.save_gray_png(os.path.join(out, "cg_raster_14_2_coverage.png"), cov_gray.astype(np.int64))
    wf_gray = (mask * 255).astype(np.uint8)
    png_wf = cglib.save_gray_png(os.path.join(out, "cg_raster_14_2_wireframe.png"), wf_gray.astype(np.int64))
    overlay = np.clip(b["color"], 0, 255).astype(np.uint8).copy()
    overlay[mask == 1] = (255, 255, 255)
    png_ov = cglib.save_png(os.path.join(out, "cg_raster_14_2_overlay.png"), overlay.astype(np.int64))

    stat = {"canvas": [w, h], "covered_binary": binary, "baseline": BASELINE_COVERED,
            "pixel_side_sum": pixel_side, "tri_side_sum": tri_side,
            "triangles_drawn": len(per_tri), "triangles_culled": b["culled"],
            "max_count": int(counts.max()), "histogram": hist,
            "wireframe_pixels": wf_px, "wireframe_segments": segs,
            "wireframe_inside": inside, "wireframe_inside_permille": inside * 1000 // max(1, wf_px),
            "png_bytes": {"coverage": png_cov, "wireframe": png_wf, "overlay": png_ov}}
    with open(os.path.join(out, "cg_raster_14_2_coverage_wireframe.json"), "w", encoding="utf-8") as fh:
        json.dump(stat, fh, ensure_ascii=False, indent=2)

    print(f"画布              : {w}x{h}，正面 {len(per_tri)} 三角形（剔除 {b['culled']} 背面）")
    print(f"不变量(1) 双重计数 : 像素侧 {pixel_side} == 三角形侧 {tri_side}")
    print(f"不变量(2) 二值覆盖 : {binary}（== 卷一基线 {BASELINE_COVERED}）")
    print(f"计数直方图         : " + "  ".join(f"{k}次:{v}px" for k, v in hist))
    print(f"最大计数           : {int(counts.max())}（重叠像素 {int((counts > 1).sum())} 个，"
          f"占覆盖像素 {int((counts > 1).sum()) * 1000 // binary}‰）")
    print(f"线框              : {segs} 条边，落笔 {wf_px} 像素，其中 {inside} 落在覆盖区内"
          f"（{inside * 1000 // max(1, wf_px)}‰）")
    print(f"产物              : coverage {png_cov}B / wireframe {png_wf}B / overlay {png_ov}B")
    return 0


if __name__ == "__main__":
    sys.exit(main())

# snippet: 覆盖率通道：关掉深度测试 + 加法混合，每次覆盖加 1/255（摘自 lantern/web/build_raster14.mjs）
const FRAG_COUNT = `#version 300 es
precision highp float;
out vec4 o;
void main() { o = vec4(1.0 / 255.0, 0.0, 0.0, 0.0); }`;

  // pass() 内：加法通道开混合、普通通道关掉
  if (o.additive) { gl.enable(gl.BLEND); gl.blendFunc(gl.ONE, gl.ONE); } else { gl.disable(gl.BLEND); }
  ...
  const cnt1 = flip(pass({ pr: P.count, depthTest: false, fbo: true, additive: true }), 1);

# snippet: 覆盖率与负例判据：GPU 计数 vs S 层整数缓冲；反例必须被拒绝（摘自 lantern/web/verify_raster14.mjs）
let cSum = 0, sSum = 0, cMax = 0, cDiffPx = 0;
for (let p = 0; p < PX; p += 1) {
  cSum += gl.cnt[p];
  sSum += sCounts[p];
  if (gl.cnt[p] !== sCounts[p]) cDiffPx += 1;
  if (gl.cnt[p] > cMax) cMax = gl.cnt[p];
}
...
if (!posUp) fail.push("① 正向深度映射不是非降于距离");
if (revUp) fail.push("① 负例（映射方向反了）未被单调性判据拒绝");
if (Math.abs(cSum - sSum) / sSum * 1000 > 20) fail.push("③ 覆盖率计数和差异超出 20‰");
if (rBad === 0) fail.push("② 负例（法线未归一化）未被模长判据拒绝 —— 判据无区分力");

③ 覆盖率        : GPU 和 47659 vs S 层 47673（差 -0.29‰）；最大 4 vs 4
   计数不同像素   : 40 / 76800
② 法线图        : 8 位通道差 MAE 0.6696 / PSNR 44.33 dB / 最大 246  ← 判据：MAE <= 1.0 且 PSNR >= 30
   负例(×2)      : 模长 [65537, 113512]，越界上 2310/43729 px，被拒绝 = true
① 深度 Q16.16   : 覆盖 43729 vs S 层 43731（掩码不同 6 px）
   单调性        : 正向非降 = true；反向映射被拒绝 = true（271 段均值口径）