7.2 余弦加权与光源采样

# snippet: sim/cg_trace_07_2_cosine_light_sampling.py（节选：p_light 的除零边界）
area = cglib.fmul(cglib.fmul(r, r), FOUR_PI_Q16)     # 4πR²
denom = cglib.fmul(area, cos_l)
if denom == 0:
    # 定点除零边界：cosθ_l 很小（掠射）时 `area·cosθ_l` 会被截断到 0。
    # 物理上这个方向的 pdf 趋于无穷（立体角测度在掠射处退化），此处返回 0 表示
    # 「该方向不可能由光源采样生成」，调用方据此把另一条路径的权重置为 1。
    return 0
return cglib.fdiv(cglib.fmul(t, t), denom)

# snippet: sim/cg_trace_07_2_cosine_light_sampling.py（节选：球面面积采样）
while True:
    xs = [2 * rng_q16(state)[1] - ONE for _ in range(3)]   # [−1,1]³
    if fmul(xs[0],xs[0]) + fmul(xs[1],xs[1]) + fmul(xs[2],xs[2]) < ONE:
        break                                              # 落在单位球内
d = cgtrace.v_norm(xs)                                     # 径向投影到球面
p = cgtrace.v_add(center, (fmul(d[0], radius), fmul(d[1], radius), fmul(d[2], radius)))

# snippet: 本机实跑（工作区 lantern/）
cd lantern
/opt/homebrew/bin/python3 sim/cg_trace_07_2_parity.py

#!/usr/bin/env python3
# file: lantern/sim/cg_trace_07_2_parity.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_trace_07_2_parity.py
"""7.2 的紧凑驱动：调用 cg_trace_07_2_cosine_light_sampling 的四个函数，打印正文数字。

两块输出：小/大光源下两条采样路径的方差对照（总辐射功率相同、半径差 3.33 倍），
以及 P 层逐字节对照用的整数缓冲与整幅直接光照图的 sha256。
"""

import hashlib
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
sys.path.insert(0, HERE)
import cg_trace_07_2_cosine_light_sampling as s  # noqa: E402

ONE = 65536


def main():
    print("== 7.2 余弦加权与光源采样 ==")
    for label in ("small", "medium", "large"):
        r = s.variance_study(os.path.join(ROOT, f"config/cg_trace_07_{label}.json"), label)
        print(f"[{r['label']:>5}] 光源半径 {r['radiusQ16'] / ONE:.4f}｜面积 {r['areaQ16'] / ONE:.6f}")
        for name in ("cosine", "light"):
            print(f"    {name:>6}：相对标准差 {r[name]['relStd']:.6f}｜相对偏差 {r[name]['bias']:+.6f}")
        print(f"    光源/余弦 方差比 = {r['varianceRatio']:.6f}")
    sb, _, _ = s.parity_buffer(os.path.join(ROOT, "config/cg_trace_07_small.json"))
    lb, _, _ = s.parity_buffer(os.path.join(ROOT, "config/cg_trace_07_large.json"))
    img = s.render_direct_image(os.path.join(ROOT, "config/cg_trace_07_small.json"), 32, 24, 8, "light")
    print(f"P 层对照缓冲 sha256（小 / 大）：{hashlib.sha256(sb).hexdigest()[:16]}… / "
          f"{hashlib.sha256(lb).hexdigest()[:16]}…")
    print(f"小光源直接光照图 32x24 8spp sha256 : {s.cgtrace.digest(img)}")
    return 0


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

== 7.2 余弦加权与光源采样 ==
[small] 光源半径 0.1500｜面积 0.282623
    cosine：相对标准差 1.116682｜相对偏差 +0.022172
     light：相对标准差 0.191869｜相对偏差 -0.000864
    光源/余弦 方差比 = 0.065012
[medium] 光源半径 0.2800｜面积 0.985001
    cosine：相对标准差 0.586727｜相对偏差 +0.016720
     light：相对标准差 0.228210｜相对偏差 -0.000071
    光源/余弦 方差比 = 0.426234
[large] 光源半径 0.5000｜面积 3.141586
    cosine：相对标准差 0.307881｜相对偏差 +0.014411
     light：相对标准差 0.341026｜相对偏差 +0.005673
    光源/余弦 方差比 = 6.731654
P 层对照缓冲 sha256（小 / 大）：8ca392900f4d3fdb… / 8523e5147731d158…
小光源直接光照图 32x24 8spp sha256 : dc549d33886d475622bd94e24d4ae8856aae5efb8c72ef49837ff716ca71d95f

// file: lantern/core/test/cg_trace_07_2_parity.test.ts
// tier: P
// verify: node --test 'core/test/cg_trace_07_2_parity.test.ts'
// 7.2 的最小 P 复现：BigInt 内核重画小光源的 32x24 直接光照图，像素缓冲的
// sha256 必须与 Python 侧逐字节相同；再把两条采样路径的方差交叉点钉住。

import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { test } from "node:test";
import { fileURLToPath } from "node:url";

import {
  parityBuffer, renderDirectImage, type SceneConfig,
} from "../src/lantern/cg_trace_07_2_cosine_light_sampling.ts";

const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
const cfg = JSON.parse(
  readFileSync(join(root, "config", "cg_trace_07_small.json"), "utf8"),
) as SceneConfig;
const par = JSON.parse(
  readFileSync(join(root, "out", "cg_trace_07_2_parity.json"), "utf8"),
) as {
  width: number; height: number; spp: number; lightSha256: string;
  smallBufferSha256: string; smallValues: number[]; smallBufferLen: number;
};
const va = JSON.parse(
  readFileSync(join(root, "out", "cg_trace_07_2_variance.json"), "utf8"),
) as {
  small: { cosine: { relStd: number }; light: { relStd: number }; varianceRatio: number };
  medium: { cosine: { relStd: number }; light: { relStd: number }; varianceRatio: number };
  large: { varianceRatio: number };
};

test("【核心】小光源场景的整数缓冲 sha256 与 Python 侧相同", () => {
  const { buf, vals } = parityBuffer(cfg);
  assert.equal(buf.length, par.smallBufferLen);
  assert.deepEqual(vals.map(Number), par.smallValues);
  assert.equal(createHash("sha256").update(buf).digest("hex"), par.smallBufferSha256);
});

test("【核心】光源采样的直接光照图 32x24 8spp 像素缓冲 sha256 相同", () => {
  const img = renderDirectImage(cfg, par.width, par.height, par.spp, "light");
  assert.equal(img.length, par.width * par.height * 3);
  assert.equal(createHash("sha256").update(img).digest("hex"), par.lightSha256);
});

test("【核心】方差比随光源尺寸单调上升，交叉点落在中档", () => {
  assert.ok(va.small.varianceRatio < 0.1, `小光源方差比 ${va.small.varianceRatio} 应 < 0.1`);
  assert.ok(va.medium.varianceRatio > 0.3 && va.medium.varianceRatio < 0.6,
    `中光源方差比 ${va.medium.varianceRatio} 应落在 0.3–0.6`);
  assert.ok(va.large.varianceRatio > 1, `大光源方差比 ${va.large.varianceRatio} 应 > 1`);
  assert.ok(va.small.varianceRatio < va.medium.varianceRatio
    && va.medium.varianceRatio < va.large.varianceRatio, "三档方差比必须单调上升");
});

test("【负例】小光源下光源采样方差远小于余弦采样", () => {
  assert.ok(va.small.light.relStd < 0.25 * va.small.cosine.relStd,
    `光源 ${va.small.light.relStd} vs 余弦 ${va.small.cosine.relStd}`);
});

✔ 【核心】小光源场景的整数缓冲 sha256 与 Python 侧相同 (6.696959ms)
✔ 【核心】光源采样的直接光照图 32x24 8spp 像素缓冲 sha256 相同 (27.735459ms)
✔ 【核心】方差比随光源尺寸单调上升，交叉点落在中档 (0.170375ms)
✔ 【负例】小光源下光源采样方差远小于余弦采样 (0.07725ms)
ℹ tests 4 / pass 4 / fail 0