1.1 从场景到像素

#!/usr/bin/env python3
# file: lantern/sim/cg_raster_01_1_scene_stats.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_raster_01_1_scene_stats.py
"""1.1 从场景到像素：最小可跑脚本。

一份 config/scene_spec.json，四步走完，全程整数：
  1 顶点变换    Q16.16，Python int；mat_look_at x mat_perspective = MVP
  2 三角形组装  世界顶点 -> 屏幕 Q6 子像素（project + to_screen）
  3 光栅化      整数边函数定覆盖 + 深度缓冲（cglib.rasterize，numpy int64）
  4 逐像素着色  顶点色的重心插值，与深度共用同一套整数除法

产物：out/cg_raster_01_1_scene.png、out/cg_raster_01_1_stats.json
"""

import hashlib
import json
import os
import sys
import time

import numpy as np

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

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))


def shade(normal, albedo, light, ambient):
    """顶点光照：Lambert + 环境项，全整数（k 为 Q16.16）。"""
    ndl = cglib.v_dot(normal, light["dirQ16"])
    ndl = ndl if ndl > 0 else 0
    k = ambient + cglib.fmul(ndl, light["intensityQ16"])
    k = k if k < cglib.ONE else cglib.ONE
    return tuple((albedo[i] * k) >> 16 for i in range(3))


def geometry(spec):
    """程序化几何：起伏地形 + 三个材质球。返回 (verts, tris, vcolors)。"""
    amb, dl = spec["ambientQ16"], spec["directionalLight"]
    terr = spec["terrain"]
    verts, tris, vcolors = [], [], []

    tv, tt = cglib.build_terrain(
        terr["gridN"], terr["extentQ16"], terr["heightScaleQ16"], terr["noiseSeed"]
    )
    lo, hi, hs = terr["albedoQ8"], terr["albedoHighQ8"], terr["heightScaleQ16"]
    verts += tv
    for _, y, _ in tv:
        # 高度归一化到 [0, ONE]：y 非负、hs > 0，故 // 与截断一致
        t = min((y << 16) // hs if hs else 0, cglib.ONE)
        alb = tuple(lo[i] + (((hi[i] - lo[i]) * t) >> 16) for i in range(3))
        vcolors.append(shade((0, cglib.ONE, 0), alb, dl, amb))  # 地形法线取竖直向上
    tris += [(a, b, c) for a, b, c in tt]

    for sp in spec["spheres"]:
        sv, st = cglib.build_sphere(sp["centerQ16"], sp["radiusQ16"], sp["subdiv"])
        base = len(verts)
        verts += sv
        for v in sv:
            n = cglib.v_norm(cglib.v_sub(v, sp["centerQ16"]))
            vcolors.append(shade(n, sp["albedoQ8"], dl, amb))
        tris += [(a + base, b + base, c + base) for a, b, c in st]
    return verts, tris, vcolors


def main():
    t0 = time.perf_counter()
    spec = cglib.load_spec()
    w, h = spec["width"], spec["height"]

    # 步骤 1：顶点变换。视图矩阵 x 投影矩阵 = MVP，全 Q16.16 整数矩阵链。
    cam = spec["camera"]
    aspect = cglib.fdiv(cglib.f_from_int(w), cglib.f_from_int(h))
    view = cglib.mat_look_at(tuple(cam["eyeQ16"]), tuple(cam["targetQ16"]), tuple(cam["upQ16"]))
    proj = cglib.mat_perspective(cam["tanHalfFovYQ16"], aspect, cam["nearQ16"], cam["farQ16"])
    mvp = cglib.mat_mul(proj, view)

    verts, tris, vcolors = geometry(spec)

    # 步骤 2：三角形组装。每个顶点投影到屏幕 Q6；相机后方的顶点记 None。
    scr = []
    for v in verts:
        p = cglib.project(mvp, v)
        scr.append(None if p is None else (*cglib.to_screen(p[0], p[1], w, h), p[2]))

    rtris, dropped = [], 0
    for a, b, c in tris:
        sa, sb, sc = scr[a], scr[b], scr[c]
        if sa is None or sb is None or sc is None:
            dropped += 1
            continue
        rtris.append((*sa, *vcolors[a], *sb, *vcolors[b], *sc, *vcolors[c]))

    # 步骤 3 + 4：光栅化。整数边函数判覆盖，整数除法插深度与颜色。
    color, depth, covered, culled = cglib.rasterize(rtris, w, h, spec["backgroundQ8"])

    out = os.path.join(ROOT, "out")
    png = cglib.save_png(os.path.join(out, "cg_raster_01_1_scene.png"), color)
    px = np.clip(color, 0, 255).astype(np.uint8)
    digest = hashlib.sha256(px.tobytes()).hexdigest()

    stats = {
        "spec": spec["name"],
        "width": w,
        "height": h,
        "vertices": len(verts),
        "triangles_total": len(tris),
        "triangles_projected": len(rtris),
        "triangles_dropped": dropped,
        "triangles_culled": culled,
        "triangles_rasterized": len(rtris) - culled,
        "pixels_covered": int(covered.sum()),
        "coverage_permille": int(covered.sum()) * 1000 // (w * h),
        "sha256": digest,
        "png_bytes": png,
        "ms": round((time.perf_counter() - t0) * 1000, 1),
    }
    with open(os.path.join(out, "cg_raster_01_1_stats.json"), "w", encoding="utf-8") as fh:
        json.dump(stats, fh, ensure_ascii=False, indent=2)

    print(f"spec           : {stats['spec']}")
    print(f"canvas         : {w}x{h}  (subpixel Q6, depth Q16.16)")
    print(f"vertices       : {stats['vertices']}")
    print(f"triangles      : {stats['triangles_total']} total")
    print(f"  projected    : {stats['triangles_projected']} ({stats['triangles_dropped']} dropped)")
    print(f"  culled       : {stats['triangles_culled']} (backface, area <= 0)")
    print(f"  rasterized   : {stats['triangles_rasterized']}")
    print(f"pixels covered : {stats['pixels_covered']} ({stats['coverage_permille']} permille)")
    print(f"sha256(rgb)    : {digest}")
    print(f"png            : out/cg_raster_01_1_scene.png ({png} bytes)")
    print(f"elapsed        : {stats['ms']} ms")
    return 0


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

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

spec           : lantern-hollow
canvas         : 320x240  (subpixel Q6, depth Q16.16)
vertices       : 487
triangles      : 896 total
  projected    : 896 (0 dropped)
  culled       : 290 (backface, area <= 0)
  rasterized   : 606
pixels covered : 43731 (569 permille)
sha256(rgb)    : bac659770178037ad3f6a6ad184945a96ff37a7fe4d754ef1ebc5b0aaa538ced
png            : out/cg_raster_01_1_scene.png (14055 bytes)
elapsed        : 71.6 ms