11.3 SDF 的法线与软阴影

#!/usr/bin/env python3
# file: lantern/sim/cg_trace_11_sdf_probe.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_trace_11_sdf_probe.py
"""平面偏置探针：解析 min(k*sin(theta),1) 与实测 soft_shadow 可见度（‰）逐档对照。"""
import os
import sys

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

ONE = cglib.ONE
cfg = sdf.load_sdf_config()
scene = sdf.make_scene(cfg)
LDIR = cglib.v_norm(tuple(cfg["light"]["dirQ16"]))
SO = cglib.v_add((-3 * ONE, 0, -3 * ONE), (0, sdf.EPS, 0))
print("k(Q16)   解析 min(k*sinθ,1)‰   实测探针‰")
for _k in cfg["softShadow"]["kSweepQ16"]:
    _a = min(cglib.fmul(_k, LDIR[1]), ONE)
    _v = sdf.soft_shadow(scene, SO, LDIR, cfg, k=_k)
    print(f"{_k:>7d}   {1000.0 * _a / ONE:>12.4f}   {1000.0 * _v / ONE:>12.4f}")

// snippet: web/build_trace11.mjs（着色器源，此处按 GLSL 呈现，文件里是 JS 字符串数组）
// verify: NODE_PATH=/opt/homebrew/lib/node_modules node web/verify_trace11.mjs
vec3 normalCentral(vec3 p) {
  vec3 g = vec3(
    sdScene(p + vec3(uNormH, 0.0, 0.0)) - sdScene(p - vec3(uNormH, 0.0, 0.0)),
    sdScene(p + vec3(0.0, uNormH, 0.0)) - sdScene(p - vec3(0.0, uNormH, 0.0)),
    sdScene(p + vec3(0.0, 0.0, uNormH)) - sdScene(p - vec3(0.0, 0.0, uNormH)));
  return normalize(g);
}
float softShadow(vec3 ro, vec3 rd) {
  float res = 1.0;
  float t = uMinStep;
  for (int i = 0; i < 512; i++) {
    if (float(i) >= uSteps) break;
    float h = sdScene(ro + rd * t);
    if (h < 0.0) return 0.0;
    float r = floor(uK * floor(h / t * ONE)) / ONE;
    if (r < res) res = r;
    t += min(max(h, uMinStep), uMaxStep);
    if (t > uTMax) break;
  }
  return res;
}

// file: lantern/web/verify_trace11.mjs
// tier: W
// verify: NODE_PATH=/opt/homebrew/lib/node_modules node web/verify_trace11.mjs
// 卷三第 11 章《符号距离场》的 W 层验证：WebGL2 片元着色器的 SDF ray marching 与
// S 层 CPU 定点金标对账。
//
// 对账结构（每一对只差一个自变量，这是本章「可归因」的全部含义）：
//   gl     vs S 层金标 → 只差「数的表示」：定点 Q16.16 vs 浮点（量化步骤已照抄）
//   glBad  vs S 层金标 → 负例：步长放大到 1.5 倍，`|grad f| > 1` 时步长越界
//
// 判据口径（为什么不能用「逐位相等」）：着色器是浮点，CPU 是 Q16.16 定点；两侧在
// **表面判定边界**（`f < eps` 的临界像素）与**软阴影步进边界**上必然有少量像素分歧。
// 故只用对舍入不敏感的统计量（MAE / PSNR），并把「覆盖归属差异」（非背景像素判据）
// 单独设上限。判据必须配负例，否则 PASS 不可信。
// 本机 headless 后端是 ANGLE/SwiftShader **软件**实现，不是真实 GPU；脚本如实打印
// 后端名，且**不得**把任何差异归因于真实硬件。

import { createRequire } from "node:module";
import { createHash } from "node:crypto";
import { mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

const require = createRequire(import.meta.url);
const { chromium } = require("playwright");
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
const OUT = join(ROOT, "out");
mkdirSync(join(OUT, "shots"), { recursive: true });

const cfg = JSON.parse(readFileSync(join(ROOT, "config", "cg_trace_11_sdf.json"), "utf8"));
const golden = new Uint8Array(readFileSync(join(OUT, "cg_trace_11_3_frame.rgb")));
const BG = cfg.render.backgroundQ8;
const W = cfg.render.width;
const H = cfg.render.height;
const TOL = { mae: 1.0, psnr: 30, coverPermille: 20 };
const sha = (b) => createHash("sha256").update(Buffer.from(b)).digest("hex");

const covered = (rgb) => {
  const m = new Uint8Array(rgb.length / 3);
  for (let p = 0; p < m.length; p += 1) {
    const o = p * 3;
    if (rgb[o] !== BG[0] || rgb[o + 1] !== BG[1] || rgb[o + 2] !== BG[2]) m[p] = 1;
  }
  return m;
};

function stats(actual, expect, acov, ecov) {
  let diffPx = 0;
  let coverDiff = 0;
  let maxDiff = 0;
  let sumAbs = 0;
  let sumSq = 0;
  const pixels = expect.length / 3;
  for (let i = 0; i < expect.length; i += 3) {
    const p = i / 3;
    let pxDiff = 0;
    for (let c = 0; c < 3; c += 1) {
      const d = Math.abs(actual[i + c] - expect[i + c]);
      if (d > pxDiff) pxDiff = d;
      sumAbs += d;
      sumSq += d * d;
    }
    if (pxDiff > 0) diffPx += 1;
    if (pxDiff > maxDiff) maxDiff = pxDiff;
    if (acov[p] !== ecov[p]) coverDiff += 1;
  }
  const mse = sumSq / expect.length;
  return {
    pixels, diffPx, coverDiff, maxDiff,
    mae: sumAbs / expect.length,
    psnr: mse === 0 ? Infinity : 10 * Math.log10((255 * 255) / mse),
  };
}

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`file://${join(ROOT, "web", "dist", "trace11.html")}`);
await page.waitForFunction(() => globalThis.__lantern && globalThis.__lantern.canvasDrawn, null, { timeout: 60000 });
const data = await page.evaluate(() => globalThis.__lantern);
const shot = join(OUT, "shots", "trace11_gl.png");
await page.screenshot({ path: shot });
await browser.close();

const cpu = Uint8Array.from(data.cpu.rgb);
const gl = Uint8Array.from(data.gl.rgb);
const glBad = Uint8Array.from(data.gl.bad);

let cpuVsS = 0;
for (let i = 0; i < cpu.length; i += 1) if (cpu[i] !== golden[i]) cpuVsS += 1;

const goldCov = covered(golden);
const sMain = stats(gl, golden, covered(gl), goldCov);
const sBad = stats(glBad, golden, covered(glBad), goldCov);

const per = (n, total) => `${n} / ${total} (${((n / total) * 1000).toFixed(2)}‰)`;

console.log(`canvasDrawn     : ${data.canvasDrawn}（非背景 ${data.drawnPixels} 像素，判据是「>= 1」）`);
console.log(`场景            : ${data.meta.width}x${data.meta.height} / 法线步长 h=${data.meta.normH} / k=${data.meta.k} / 软阴影 ${data.meta.steps} 步`);
console.log(`GL 后端         : ${data.gl.unmaskedRenderer}`);
console.log(`GL 版本         : ${data.gl.version}   glError : ${data.gl.glError}`);
console.log(`S 层金标 sha256 : ${sha(golden).slice(0, 16)}…  命中 ${data.cpuHits} 像素`);
console.log(`① 页面内 CPU 定点 vs S 层金标：不同字节 = ${cpuVsS}  ← 必须为 0`);
console.log(`   着色器自报命中 ${data.glHitPixels} 像素 vs 页面内 CPU ${data.cpuHits} 像素（差 ${Math.abs(data.glHitPixels - data.cpuHits)}，判据 |差| <= 8）`);
console.log(`② WebGL2（浮点着色器，量化步骤照抄）vs S 层金标:`);
console.log(`   任一通道差>0 : ${per(sMain.diffPx, sMain.pixels)}`);
console.log(`   覆盖归属不同 : ${per(sMain.coverDiff, sMain.pixels)}  ← 主判据`);
console.log(`   最大通道差   : ${sMain.maxDiff}   MAE : ${sMain.mae.toFixed(4)}   PSNR : ${sMain.psnr.toFixed(2)} dB`);
console.log(`③ 负例（步长 x1.5，Lipschitz 被违反）:`);
console.log(`   覆盖归属不同 : ${per(sBad.coverDiff, sBad.pixels)}`);
console.log(`   最大通道差   : ${sBad.maxDiff}   MAE : ${sBad.mae.toFixed(4)}   PSNR : ${sBad.psnr.toFixed(2)} dB  ← 必须被同一判据拒绝`);
console.log(`   截图         : ${shot}`);

const fail = [];
if (data.error) fail.push(`页面报错：${data.error}`);
if (!data.gl) fail.push("WebGL2 上下文不可用");
if (cpuVsS !== 0) fail.push(`① 页面内 CPU 与 S 层金标不同（${cpuVsS} 字节）`);
if (Math.abs(data.glHitPixels - data.cpuHits) > 8) fail.push(`① 着色器命中数 ${data.glHitPixels} 与页面内 CPU ${data.cpuHits} 相差超过 8 像素`);
if (sMain.mae > TOL.mae) fail.push(`② MAE ${sMain.mae.toFixed(4)} 超出 ${TOL.mae}`);
if (sMain.psnr < TOL.psnr) fail.push(`② PSNR ${sMain.psnr.toFixed(2)} dB 低于 ${TOL.psnr} dB`);
if ((sMain.coverDiff / sMain.pixels) * 1000 > TOL.coverPermille) fail.push(`② 覆盖归属差异超出 ${TOL.coverPermille}‰`);
if (sBad.mae <= TOL.mae && sBad.psnr >= TOL.psnr) fail.push("③ 负例未被判据拒绝 —— 判据无区分力");
if (fail.length) {
  console.log(`\nFAIL:\n  ${fail.join("\n  ")}`);
  process.exit(1);
}
console.log("\nPASS");

# snippet: 本机实跑（工作区 lantern/）
NODE_PATH=/opt/homebrew/lib/node_modules /opt/homebrew/bin/node web/verify_trace11.mjs

canvasDrawn     : true（非背景 1997 像素，判据是「>= 1」）
场景            : 64x48 / 法线步长 h=64 / k=131072 / 软阴影 32 步
GL 后端         : ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (LLVM 10.0.0) (0x0000C0DE)), SwiftShader driver)
GL 版本         : WebGL 2.0 (OpenGL ES 3.0 Chromium)   glError : 0
S 层金标 sha256 : 476c7337167f6fda…  命中 1995 像素
① 页面内 CPU 定点 vs S 层金标：不同字节 = 0  ← 必须为 0
   着色器自报命中 1997 像素 vs 页面内 CPU 1995 像素（差 2，判据 |差| <= 8）
② WebGL2（浮点着色器，量化步骤照抄）vs S 层金标:
   任一通道差>0 : 67 / 3072 (21.81‰)
   覆盖归属不同 : 2 / 3072 (0.65‰)  ← 主判据
   最大通道差   : 45   MAE : 0.0778   PSNR : 46.41 dB
③ 负例（步长 x1.5，Lipschitz 被违反）:
   覆盖归属不同 : 53 / 3072 (17.25‰)
   最大通道差   : 198   MAE : 5.8344   PSNR : 20.91 dB  ← 必须被同一判据拒绝
   截图         : /Users/plumephp/.cgbook/lantern/out/shots/trace11_gl.png

PASS