4.1 硬阴影与阴影光线

# snippet: sim/cg_trace_04_light.py（节选：起点这一行）
# verify: /opt/homebrew/bin/python3 sim/cg_trace_04_1_hard_shadow.py
        # 阴影光线的起点 = 命中点 + 沿法线的偏移（`off` 是偏移向量，不是起点）
        so = off if off_is_origin else cglib.v_add(p, off)

#!/usr/bin/env python3
# file: lantern/sim/cg_trace_04_1_hard_shadow.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_trace_04_1_hard_shadow.py
"""4.1《硬阴影与阴影光线》：阴影光线的起点、遮挡计数与一个真实的起点错误。

本节只做一件事：把「这个点在不在阴影里」还原成一条从命中点出发、朝光源方向的光线，
并用整数把它的条数与遮挡数数清楚。场景是 `config/scene_spec.json`（487 顶点 /
896 三角形 / 320x240），直接光照 = 环境光 + 方向光 + 点光源。

三个量：

  1. **正确实现**：阴影光线起点 = `v_add(p, off)`（`off` 是沿法线的偏移**向量**，
     模长 `EPSILON`）。实测 77211 条阴影光线，遮挡 1357 条，像素缓冲 sha256 与卷三
     基线逐字节相同。
  2. **错误实现**：把 `off` 当**起点**（`so = off`）。光线从世界原点附近发出并立刻
     自交，遮挡数从 1357 跳到 77210（999.987‰），画面只剩环境光。
  3. **阴影掩码**：单独渲一张「方向光是否被遮挡」的二值图，数出真正落在阴影里的像素
     ——它远小于遮挡光线数，因为一条主光线最多发两条阴影光线。

产出：
  out/cg_trace_04_1_shadow.json     计数与 sha256（供正文引用与 P 层对拍）
  out/cg_trace_04_1_shadowmask.png  方向光阴影掩码（255 阴影 / 0 受光 / 64 背光）
"""

import json
import os
import sys
import time

import numpy as np

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
sys.path.insert(0, HERE)
import cglib  # noqa: E402
import cgtrace  # noqa: E402
import cg_trace_04_light as light  # noqa: E402

OUT = os.path.join(ROOT, "out")
MAX_DEPTH = 1
KEYS = ["dir_rays", "dir_hits", "pt_rays", "pt_hits"]


def make_shader(ctx, off_is_origin=False):
    """直接光照 + 硬阴影，复用第 4 章共用的求值器。

    `off_is_origin=True` 复现那个真实踩过的坑：把 `off` 当成阴影光线起点，而不是
    「命中点 + 偏移」。两条分支只差一行，计数差一个量级。
    """
    spec = ctx["spec"]
    tris, _ = cgtrace.build_scene_tris(spec)
    nodes, order = cgtrace.build_bvh(tris)
    ctx["tris"] = tris
    ctx["bvh"] = (nodes, order)
    return light.build_direct(spec, nodes, order, tris, ctx["tmax"],
                              ctx["stats"], ctx["bvh_stats"], off_is_origin)


def make_mask_shader(ctx):
    """方向光阴影掩码：255 = 被遮挡（真阴影）、0 = 受光、64 = 背光（法线背对光源）。"""
    spec = ctx["spec"]
    tris, _ = cgtrace.build_scene_tris(spec)
    nodes, order = cgtrace.build_bvh(tris)
    ctx["tris"] = tris
    ctx["bvh"] = (nodes, order)
    ldir = tuple(spec["directionalLight"]["dirQ16"])
    tmax, stats, bvh_stats = ctx["tmax"], ctx["stats"], ctx["bvh_stats"]

    def shade(p, off, n, albedo, depth):
        so = cglib.v_add(p, off)
        if cglib.v_dot(n, ldir) <= 0:
            stats["back"] += 1
            return (64, 64, 64)
        if cgtrace.bvh_intersect(nodes, order, tris, so, ldir, tmax, bvh_stats) is None:
            stats["lit"] += 1
            return (0, 0, 0)
        stats["shadow"] += 1
        return (255, 255, 255)

    return shade


def render(factory, stats_keys):
    spec = cglib.load_spec()
    ctx = {"stats": {k: 0 for k in stats_keys}}
    t0 = time.time()
    color, stats = cgtrace.render_trace(spec, spec["width"], spec["height"],
                                        MAX_DEPTH, factory, ctx)
    ms = int((time.time() - t0) * 1000)
    return spec, color, stats, ctx["stats"], ms, len(ctx["tris"])


def hit_pixels(color, spec):
    """命中像素数：与背景色不同的像素。"""
    bg = tuple(spec["backgroundQ8"])
    mask = ~((color[:, :, 0] == bg[0]) & (color[:, :, 1] == bg[1])
             & (color[:, :, 2] == bg[2]))
    return int(mask.sum())


def main():
    os.makedirs(OUT, exist_ok=True)
    spec, ok_color, ok_stats, ok_s, ok_ms, n_tris = render(
        lambda c: make_shader(c, False), KEYS)
    _, bad_color, _, bad_s, bad_ms, _ = render(lambda c: make_shader(c, True), KEYS)
    _, mask_color, _, mask_s, mask_ms, _ = render(make_mask_shader, ["lit", "shadow", "back"])

    ok_sha = cgtrace.digest(ok_color)
    bad_sha = cgtrace.digest(bad_color)
    hit_px = hit_pixels(ok_color, spec)
    shadow_rays = ok_s["dir_rays"] + ok_s["pt_rays"]
    shadow_hits = ok_s["dir_hits"] + ok_s["pt_hits"]
    bad_rays = bad_s["dir_rays"] + bad_s["pt_rays"]
    bad_hits = bad_s["dir_hits"] + bad_s["pt_hits"]

    cglib.save_png(os.path.join(OUT, "cg_trace_04_1_shadowmask.png"), mask_color)
    with open(os.path.join(OUT, "cg_trace_04_1_shadow_ok.rgb"), "wb") as f:
        f.write(np.ascontiguousarray(ok_color, dtype=np.uint8).tobytes())

    report = {
        "canvas": [spec["width"], spec["height"]],
        "triangles": n_tris,
        "primary_rays": ok_stats["rays"],
        "hit_pixels": hit_px,
        "shadow_rays": shadow_rays,
        "shadow_hits": shadow_hits,
        "shadow_hit_permille": round(1000.0 * shadow_hits / shadow_rays, 4),
        "dir_rays": ok_s["dir_rays"], "dir_hits": ok_s["dir_hits"],
        "pt_rays": ok_s["pt_rays"], "pt_hits": ok_s["pt_hits"],
        "shadow_rays_per_hit_px": round(shadow_rays / hit_px, 4),
        "mask_lit": mask_s["lit"], "mask_shadow": mask_s["shadow"], "mask_back": mask_s["back"],
        "ok_sha256": ok_sha,
        "buggy_shadow_rays": bad_rays,
        "buggy_shadow_hits": bad_hits,
        "buggy_permille": round(1000.0 * bad_hits / bad_rays, 4),
        "buggy_sha256": bad_sha,
        "mae_ok_vs_buggy": round(cgtrace.mae(ok_color, bad_color), 4),
        "psnr_ok_vs_buggy": round(cgtrace.psnr(ok_color, bad_color), 4),
        "ms_ok": ok_ms, "ms_buggy": bad_ms, "ms_mask": mask_ms,
    }
    with open(os.path.join(OUT, "cg_trace_04_1_shadow.json"), "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2)
        f.write("\n")

    print("== 4.1 硬阴影与阴影光线 ==")
    print(f"主光线            : {ok_stats['rays']}")
    print(f"命中像素          : {hit_px}")
    print(f"阴影光线          : {shadow_rays}（方向光 {ok_s['dir_rays']} + 点光 {ok_s['pt_rays']}）")
    print(f"遮挡              : {shadow_hits}（方向光 {ok_s['dir_hits']} + 点光 {ok_s['pt_hits']}，"
          f"{report['shadow_hit_permille']}‰）")
    print(f"阴影掩码          : 受光 {mask_s['lit']} / 阴影 {mask_s['shadow']} / 背光 {mask_s['back']}")
    print(f"正确 sha256       : {ok_sha}")
    print(f"错误(off 当起点)  : 光线 {bad_rays} 遮挡 {bad_hits}（{report['buggy_permille']}‰）")
    print(f"两者 MAE / PSNR   : {report['mae_ok_vs_buggy']} / {report['psnr_ok_vs_buggy']} dB")
    print(f"耗时              : ok {ok_ms} ms / buggy {bad_ms} ms / mask {mask_ms} ms")
    return 0


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

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

== 4.1 硬阴影与阴影光线 ==
主光线            : 76800
命中像素          : 43731
阴影光线          : 77211（方向光 43250 + 点光 33961）
遮挡              : 1357（方向光 839 + 点光 518，17.5752‰）
阴影掩码          : 受光 42411 / 阴影 839 / 背光 481
正确 sha256       : 213b413069ca66c9f0cc091bce5328eac0f540d075afa3bab37788aea335ba71
错误(off 当起点)  : 光线 77211 遮挡 77210（999.987‰）
两者 MAE / PSNR   : 40.0972 / 16.0685 dB
耗时              : ok 6827 ms / buggy 6294 ms / mask 5016 ms

# snippet: core/test/cg_trace_04_1_hard_shadow.test.ts（节选：正例与负例）
# verify: node --test 'core/test/cg_trace_04_1_hard_shadow.test.ts'
    assert.equal(counts.dirRays + counts.ptRays, golden.shadow_rays);
    assert.equal(counts.dirHits + counts.ptHits, golden.shadow_hits);
  // 负例：把 off 当起点，光线条数不变但几乎全部自交
  assert.equal(counts.dirRays + counts.ptRays, golden.buggy_shadow_rays);
  assert.equal(sha(rgb), golden.buggy_sha256, "错的起点必须让逐字节判据分叉");