8.2 蒙皮数据量与显存

#!/usr/bin/env python3
# file: sim/ta08_skinning.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/ta08_skinning.py
"""8.2 蒙皮数据量与显存（S 层，卷二 8.2）。

蒙皮数据分两块：

* **顶点蒙皮属性**：每顶点 4 个骨骼索引 + 4 个权重，字节 = 顶点数 × 每顶点字节；
* **骨骼调色板**：骨骼矩阵数据，字节 = 骨骼数 × vec4PerBone × 16。

索引位宽决定一个骨架能不能用该格式：4 位索引最多 16 根骨、8 位最多 256 根、16 位最多 65536 根。
本脚本读 config/ta08_skinning.json，对每个角色 × 每种格式算出两块字节与合法性，并对一组权重做
8 位 unorm 量化示例。全整数，落 out/ta08_skinning.json。
"""
import hashlib
import json
import os
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
CFG = os.path.join(ROOT, "config/ta08_skinning.json")
OUT = os.path.join(ROOT, "out")


def max_bones(index_bits: int) -> int:
    """索引位宽能寻址的最大骨骼数：2^bits。"""
    return 1 << index_bits


def quantize_unorm8(weights):
    """把一组权重缩放到 8 位整数（0–255）。返回 (整数列表, 和)。"""
    q = [round(w * 255) for w in weights]
    return q, sum(q)


def main() -> int:
    cfg = json.load(open(CFG, encoding="utf-8"))
    os.makedirs(OUT, exist_ok=True)
    pal = cfg["palette"]
    palette_bytes_per_bone = pal["vec4PerBone"] * pal["bytesPerVec4"]
    formats = [{**f, "maxBones": max_bones(f["indexBits"])} for f in cfg["formats"]]

    rows = []
    for c in cfg["characters"]:
        per_fmt = []
        for f in formats:
            legal = c["bones"] <= f["maxBones"]
            attr = c["verts"] * f["bytesPerVertex"]
            palette = c["bones"] * palette_bytes_per_bone
            per_fmt.append({"id": f["id"], "legal": legal, "attrBytes": attr,
                            "paletteBytes": palette, "totalBytes": attr + palette})
        rows.append({"id": c["id"], "bones": c["bones"], "verts": c["verts"], "formats": per_fmt})

    totals = []
    for fi, f in enumerate(formats):
        legal_rows = [r for r in rows if r["formats"][fi]["legal"]]
        attr = sum(r["verts"] * f["bytesPerVertex"] for r in legal_rows)
        palette = sum(r["bones"] * palette_bytes_per_bone for r in legal_rows)
        total = attr + palette
        totals.append({"id": f["id"], "legalCharacters": len(legal_rows),
                       "attrBytes": attr, "paletteBytes": palette, "totalBytes": total,
                       "palettePermille": palette * 1000 // total if total else 0})

    sample = cfg["sampleWeights"]
    q, qsum = quantize_unorm8(sample)
    fix = list(q)
    fix[q.index(max(q))] -= (qsum - 255)
    quant = {"weights": sample, "scaled": q, "naiveSum": qsum,
             "normalized": fix, "normalizedSum": sum(fix), "stepPermille": 1000 // 255}

    lines = sorted(f"{r['id']}:{f['id']}:{f['totalBytes']}"
                   for r in rows for f in r["formats"] if f["legal"])
    digest = hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()[:16]

    report = {"project": cfg["project"], "paletteBytesPerBone": palette_bytes_per_bone,
              "vramBudgetBytes": cfg["vramBudgetBytes"], "formats": formats,
              "characters": rows, "rosterTotals": totals,
              "weightQuantization": quant, "digest": digest}
    with open(os.path.join(OUT, "ta08_skinning.json"), "w", encoding="utf-8") as fh:
        json.dump(report, fh, ensure_ascii=False, indent=2, sort_keys=True)
        fh.write("\n")

    print(f"paletteBytesPerBone={palette_bytes_per_bone} vramBudget={cfg['vramBudgetBytes']}")
    for f in formats:
        print(f"  fmt {f['id']:<10} idx{f['indexBits']:<3} w{f['weightBits']:<3} "
              f"bytesPerVertex={f['bytesPerVertex']:<3} maxBones={f['maxBones']}")
    for t in totals:
        print(f"  total {t['id']:<10} legal={t['legalCharacters']}/6 attr={t['attrBytes']:<7} "
              f"palette={t['paletteBytes']:<6} sum={t['totalBytes']:<7} palette={t['palettePermille']}permille")
    print(f"weight8 sample={sample} scaled={q} sum={qsum} normalizedSum={sum(fix)} "
          f"step={quant['stepPermille']}permille")
    print(f"digest={digest}")
    print("wrote out/ta08_skinning.json")
    return 0


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

{
  "project": "stardust-inn",
  "specRef": "config/visual_spec.json",
  "note": "卷二 8.2 的蒙皮数据规格：蒙皮数据分两块——顶点上的蒙皮属性（每顶点 4 索引 + 4 权重）与骨骼调色板（骨骼矩阵）。索引位宽决定一个骨架能不能用该格式（4 位 ≤ 16 骨、8 位 ≤ 256 骨、16 位 ≤ 65536 骨）。权重精度用 8 位 unorm 做量化示例。蒙皮矩阵如何参与顶点变换属 graphics 专题，本节只算字节。",
  "palette": {
    "vec4PerBone": 3,
    "bytesPerVec4": 16
  },
  "vramBudgetBytes": 262144,
  "formats": [
    { "id": "packed4", "indexBits": 4, "weightBits": 4, "bytesPerVertex": 4 },
    { "id": "idx8_w8", "indexBits": 8, "weightBits": 8, "bytesPerVertex": 8 },
    { "id": "idx8_w16", "indexBits": 8, "weightBits": 16, "bytesPerVertex": 12 },
    { "id": "idx16_wf32", "indexBits": 16, "weightBits": 32, "bytesPerVertex": 24 }
  ],
  "characters": [
    { "id": "innkeeper", "bones": 28, "verts": 1800 },
    { "id": "pet_cat", "bones": 16, "verts": 620 },
    { "id": "guest_female", "bones": 52, "verts": 3400 },
    { "id": "merchant", "bones": 58, "verts": 3900 },
    { "id": "chef", "bones": 72, "verts": 5200 },
    { "id": "boss_dragon", "bones": 96, "verts": 8600 }
  ],
  "sampleWeights": [0.5, 0.25, 0.15, 0.1]
}

paletteBytesPerBone=48 vramBudget=262144
  fmt packed4    idx4   w4   bytesPerVertex=4   maxBones=16
  fmt idx8_w8    idx8   w8   bytesPerVertex=8   maxBones=256
  fmt idx8_w16   idx8   w16  bytesPerVertex=12  maxBones=256
  fmt idx16_wf32 idx16  w32  bytesPerVertex=24  maxBones=65536
  total packed4    legal=1/6 attr=2480    palette=768    sum=3248    palette=236permille
  total idx8_w8    legal=6/6 attr=188160  palette=15456  sum=203616  palette=75permille
  total idx8_w16   legal=6/6 attr=282240  palette=15456  sum=297696  palette=51permille
  total idx16_wf32 legal=6/6 attr=564480  palette=15456  sum=579936  palette=26permille
weight8 sample=[0.5, 0.25, 0.15, 0.1] scaled=[128, 64, 38, 26] sum=256 normalizedSum=255 step=3permille
digest=8348cde946c94323
wrote out/ta08_skinning.json

sample=[0.5, 0.25, 0.15, 0.1] → scaled=[128, 64, 38, 26] → sum=256（不是 255）