附录 A 场景规格字段表、定点约定与数据集索引

#!/usr/bin/env python3
# file: lantern/sim/cg_raster_appendix_fields.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_raster_appendix_fields.py
"""附录 A 的字段表与定点约定自检：把 scene_spec.json 摊平成表，并逐条断言定点约定。

本脚本是附录 A 唯一的可跑块，它证明两件事：
  ① 场景规格里**没有一个浮点数**（config/ 禁浮点），且字段可以被摊平成一张表；
  ② 定点约定的四条铁律在 Python 侧成立，且与 TypeScript 侧 fixed.ts 逐字同义。

产物：out/cg_raster_appendix_fields.csv（字段表）
      out/cg_raster_appendix_fixed.json（定点约定自检结果）
"""

import json
import os
import sys

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 flatten(obj, prefix=""):
    """把嵌套的规格摊平成 (路径, 类型, 值) 三元组列表，顺序即字典插入序。"""
    rows = []
    if isinstance(obj, dict):
        for k, v in obj.items():
            rows.extend(flatten(v, f"{prefix}.{k}" if prefix else k))
    elif isinstance(obj, list):
        for i, v in enumerate(obj):
            rows.extend(flatten(v, f"{prefix}[{i}]"))
    else:
        rows.append((prefix, type(obj).__name__, obj))
    return rows


def check_fixed_point():
    """四条铁律的自检。任一断言失败即退出非 0。"""
    out = {}
    # ① 常量的定义
    out["ONE"] = cglib.ONE
    out["SUB"] = cglib.SUB
    out["SUB1"] = cglib.SUB1
    assert cglib.ONE == 65536, "ONE 必须是 65536"
    assert cglib.SUB == 6 and cglib.SUB1 == 64, "子像素必须是 6 位 / 1 像素 = 64 单位"

    # ② 乘法：降精度用算术右移（负数向下取整），1.0 * 1.0 == 1.0
    assert cglib.fmul(cglib.ONE, cglib.ONE) == cglib.ONE
    assert cglib.fmul(-cglib.ONE, cglib.ONE) == -cglib.ONE
    # 0.5 * 0.5 == 0.25（Q16.16 里 0.25 = 16384）
    assert cglib.fmul(cglib.ONE // 2, cglib.ONE // 2) == cglib.ONE // 4
    out["fmul_ok"] = True

    # ③ 除法：向零截断。Python 的 // 是 floor，负数上会给出不同的答案 ——
    #    这正是必须用 fdiv 而不是裸 // 的原因。
    #    注意例子必须**不整除**：-3.0/2.0 恰好整除，两种除法给出相同结果，看不出差别。
    a, b = -cglib.ONE, 3 * cglib.ONE  # -1.0 / 3.0
    out["fdiv_neg1_over_3"] = cglib.fdiv(a, b)
    out["floor_neg1_over_3"] = (a << 16) // b
    assert cglib.fdiv(a, b) == -21845, "fdiv(-1.0, 3.0) 应为 -0.33333… 向零截断 = -21845"
    assert (a << 16) // b == -21846, "裸 // 给出 -21846（floor），与 fdiv 差 1 —— 这就是必须禁 // 的理由"

    # ④ 平方根：fsqrt 的入参与返回值都是 Q16.16，内部走 isqrt(x << 16)
    assert cglib.fsqrt(cglib.ONE) == cglib.ONE, "sqrt(1.0) 必须精确等于 1.0"
    assert cglib.fsqrt(4 * cglib.ONE) == 2 * cglib.ONE, "sqrt(4.0) 必须精确等于 2.0"
    # 非完全平方：floor(sqrt(2) * 65536) = floor(92681.9) = 92681
    out["fsqrt_2"] = cglib.fsqrt(2 * cglib.ONE)
    assert cglib.fsqrt(2 * cglib.ONE) == 92681, "sqrt(2.0) 向下取整应为 92681"
    out["fsqrt_ok"] = True

    # ⑤ 屏幕映射：NDC 的 [-1,1] 映到 [0, width*SUB1]，1 像素恰好 64 个单位
    sx0, _ = cglib.to_screen(-cglib.ONE, 0, 320, 240)
    sx1, _ = cglib.to_screen(0, 0, 320, 240)
    out["sx_ndc_minus1"] = sx0
    out["sx_ndc_zero"] = sx1
    assert sx0 == 0, "NDC x = -1 必须映到屏幕 x = 0"
    assert sx1 == 320 * 64 // 2, "NDC x = 0 必须映到画布中点 320*64/2"
    out["one_pixel_units"] = cglib.SUB1
    return out


def main():
    spec = cglib.load_spec()
    rows = flatten(spec)

    # config/ 禁浮点：任何一个 float 都是规格错误
    floats = [r for r in rows if r[1] == "float"]
    assert not floats, f"config/ 禁浮点，发现 {len(floats)} 个：{floats[:5]}"

    out = os.path.join(ROOT, "out")
    os.makedirs(out, exist_ok=True)
    with open(os.path.join(out, "cg_raster_appendix_fields.csv"), "w", encoding="utf-8") as fh:
        fh.write("path,type,value\n")
        for path, typ, val in rows:
            fh.write(f"{path},{typ},{val}\n")

    fixed = check_fixed_point()
    with open(os.path.join(out, "cg_raster_appendix_fixed.json"), "w", encoding="utf-8") as fh:
        json.dump(fixed, fh, ensure_ascii=False, indent=2)

    kinds = {}
    for _, typ, _v in rows:
        kinds[typ] = kinds.get(typ, 0) + 1
    print(f"字段数        : {len(rows)}")
    print(f"类型分布      : {kinds}")
    print(f"浮点数        : {len(floats)}（config/ 禁浮点）")
    print(f"定点约定自检  : 5 项全过")
    print(f"fdiv(-1.0,3.0): {fixed['fdiv_neg1_over_3']}  裸 // 给出 {fixed['floor_neg1_over_3']}")
    print(f"1 像素        : {fixed['one_pixel_units']} 个子像素单位")
    print(f"csv           : out/cg_raster_appendix_fields.csv")
    return 0


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

字段数        : 71
类型分布      : {'str': 1, 'int': 70}
浮点数        : 0（config/ 禁浮点）
定点约定自检  : 5 项全过
fdiv(-1.0,3.0): -21845  裸 // 给出 -21846
1 像素        : 64 个子像素单位
csv           : out/cg_raster_appendix_fields.csv