60cce66993
Tests / test (push) Has been cancelled
导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
359 lines
17 KiB
Python
359 lines
17 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""VRM 文件静态检查:结构、SpringBone、官方 JSON Schema、导入器会踩的坑。
|
||
|
||
python tools/qa/check_vrm.py 文件或目录 [...] [--no-schema] [-v]
|
||
|
||
逐个文件检查(目录会递归找 .vrm),有问题的打印出来,最后汇总;有错误时退出码为 1。
|
||
|
||
* humanoid:骨位名合法、必需骨位齐全、每根骨的 VRM 父骨位确实是它的祖先、
|
||
用占位骨(vrm_*)补的骨位(道具 / 非人形模型会有,记为提示)。
|
||
* 网格:JOINTS_0 不越界;同一网格里 morph target 不重名(Unity 遇到重名的
|
||
BlendShape 会抛异常,UniVRM 导入直接中断)。
|
||
* 表情:materialColorBinds 的材质号、morphTargetBinds 的 node / index 在范围内。
|
||
* SpringBone(VRM 1.0):相邻关节是祖先关系、关节不落在 humanoid 骨上、参数有限、
|
||
碰撞组号合法、同一节点不重复当关节。
|
||
* SpringBone(VRM 0.x):硬度键名是 stiffiness、参数有限、碰撞组号合法、组根子树不含
|
||
humanoid 骨、同一节点不落在两个组的子树里(0.x 组根下面整棵子树都会摆动)。
|
||
* Schema:用 vrm-c/vrm-specification 的官方 JSON Schema 校验 VRMC_vrm、
|
||
VRMC_springBone、VRMC_materials_mtoon,以及 VRM 0.x 的 VRM 扩展。需要 jsonschema 包;第一次运行时从 GitHub
|
||
下载固定版本的 schema,缓存在 tools/qa/.schema-cache/。UniVRM 对不合规的数据很少
|
||
容错(例如 targetValue 少一个分量就 IndexOutOfRange),所以这一项很有用。
|
||
"""
|
||
import argparse
|
||
import json
|
||
import math
|
||
import os
|
||
import sys
|
||
import urllib.request
|
||
from collections import Counter
|
||
|
||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||
ROOT = os.path.dirname(os.path.dirname(HERE))
|
||
sys.path[:0] = [os.path.join(ROOT, "formats"), os.path.join(ROOT, "convert")]
|
||
import vrmio # noqa: E402
|
||
from vrmconv.humanoid import _vrm_anchor # noqa: E402
|
||
|
||
# ---------------------------------------------------------------- humanoid --
|
||
_B10 = set("hips spine chest upperChest neck head leftEye rightEye jaw leftUpperLeg leftLowerLeg "
|
||
"leftFoot leftToes rightUpperLeg rightLowerLeg rightFoot rightToes leftShoulder "
|
||
"leftUpperArm leftLowerArm leftHand rightShoulder rightUpperArm rightLowerArm "
|
||
"rightHand".split())
|
||
_B0 = set(_B10)
|
||
for _s in ("left", "right"):
|
||
_B10 |= {_s + "ThumbMetacarpal", _s + "ThumbProximal", _s + "ThumbDistal"}
|
||
_B0 |= {_s + "ThumbProximal", _s + "ThumbIntermediate", _s + "ThumbDistal"}
|
||
for _f in ("Index", "Middle", "Ring", "Little"):
|
||
for _j in ("Proximal", "Intermediate", "Distal"):
|
||
_B10.add(_s + _f + _j)
|
||
_B0.add(_s + _f + _j)
|
||
_REQ = ("hips spine head leftUpperArm leftLowerArm leftHand rightUpperArm rightLowerArm "
|
||
"rightHand leftUpperLeg leftLowerLeg leftFoot rightUpperLeg rightLowerLeg "
|
||
"rightFoot").split()
|
||
|
||
# ------------------------------------------------------------------ schema --
|
||
SPEC_COMMIT = "94e82dd346fa6cf0337c4421728640e5252dd38e" # vrm-c/vrm-specification
|
||
SPEC_URL = "https://raw.githubusercontent.com/vrm-c/vrm-specification/%s/specification/%s/schema/%s"
|
||
SPEC_FILES = {
|
||
"VRMC_vrm-1.0": [
|
||
"VRMC_vrm.schema.json", "VRMC_vrm.meta.schema.json", "VRMC_vrm.humanoid.schema.json",
|
||
"VRMC_vrm.humanoid.humanBones.schema.json",
|
||
"VRMC_vrm.humanoid.humanBones.humanBone.schema.json",
|
||
"VRMC_vrm.firstPerson.schema.json", "VRMC_vrm.firstPerson.meshAnnotation.schema.json",
|
||
"VRMC_vrm.lookAt.schema.json", "VRMC_vrm.lookAt.rangeMap.schema.json",
|
||
"VRMC_vrm.expressions.schema.json", "VRMC_vrm.expressions.expression.schema.json",
|
||
"VRMC_vrm.expressions.expression.materialColorBind.schema.json",
|
||
"VRMC_vrm.expressions.expression.morphTargetBind.schema.json",
|
||
"VRMC_vrm.expressions.expression.textureTransformBind.schema.json"],
|
||
"VRMC_springBone-1.0": [
|
||
"VRMC_springBone.schema.json", "VRMC_springBone.collider.schema.json",
|
||
"VRMC_springBone.colliderGroup.schema.json", "VRMC_springBone.joint.schema.json",
|
||
"VRMC_springBone.shape.schema.json", "VRMC_springBone.spring.schema.json"],
|
||
"VRMC_materials_mtoon-1.0": [
|
||
"VRMC_materials_mtoon.schema.json", "mtoon.shadingShiftTexture.schema.json"],
|
||
"0.0": [
|
||
"vrm.schema.json", "vrm.meta.schema.json", "vrm.humanoid.schema.json", "vrm.humanoid.bone.schema.json",
|
||
"vrm.firstperson.schema.json", "vrm.firstperson.degreemap.schema.json",
|
||
"vrm.firstperson.meshannotation.schema.json", "vrm.blendshape.schema.json",
|
||
"vrm.blendshape.group.schema.json", "vrm.blendshape.bind.schema.json",
|
||
"vrm.blendshape.materialbind.schema.json", "vrm.secondaryanimation.schema.json",
|
||
"vrm.secondaryanimation.spring.schema.json", "vrm.secondaryanimation.collidergroup.schema.json",
|
||
"vrm.material.schema.json"],
|
||
}
|
||
# glTF 本体的几个 schema 只被引用、不需要逐项校验,用最小定义代替
|
||
_GLTF_STUBS = {
|
||
"glTFProperty.schema.json": {"type": "object"},
|
||
"glTFid.schema.json": {"type": "integer", "minimum": 0},
|
||
"textureInfo.schema.json": {"type": "object", "required": ["index"],
|
||
"properties": {"index": {"type": "integer", "minimum": 0},
|
||
"texCoord": {"type": "integer", "minimum": 0}}},
|
||
}
|
||
_BASE = "https://vrm-spec.invalid/"
|
||
|
||
|
||
def load_validators():
|
||
"""→ {扩展名: validator};缺 jsonschema 或下载失败时返回 (None, 原因)。"""
|
||
try:
|
||
import jsonschema
|
||
from referencing import Registry, Resource
|
||
from referencing.jsonschema import DRAFT4
|
||
except ImportError:
|
||
return None, "未安装 jsonschema(pip install jsonschema),跳过 Schema 校验"
|
||
cache = os.path.join(HERE, ".schema-cache", SPEC_COMMIT[:12])
|
||
docs = dict(_GLTF_STUBS)
|
||
for d, files in SPEC_FILES.items():
|
||
for fn in files:
|
||
path = os.path.join(cache, fn)
|
||
if not os.path.isfile(path):
|
||
os.makedirs(cache, exist_ok=True)
|
||
try:
|
||
with urllib.request.urlopen(SPEC_URL % (SPEC_COMMIT, d, fn), timeout=30) as r:
|
||
data = r.read()
|
||
except OSError as e:
|
||
return None, "下载 schema 失败(%s),跳过 Schema 校验" % e
|
||
with open(path, "wb") as f:
|
||
f.write(data)
|
||
with open(path, encoding="utf-8") as f:
|
||
docs[fn] = json.load(f)
|
||
resources = []
|
||
for fn, doc in docs.items():
|
||
# draft-04 用 id(不是 $id)定基准 URI,相对的 $ref 才解析得到
|
||
doc = dict({k: v for k, v in doc.items() if k not in ("$schema", "$id")}, id=_BASE + fn)
|
||
resources.append((_BASE + fn, Resource.from_contents(doc, default_specification=DRAFT4)))
|
||
registry = Registry().with_resources(resources)
|
||
out = {}
|
||
for ext, fn in (("VRMC_vrm", "VRMC_vrm"), ("VRMC_springBone", "VRMC_springBone"),
|
||
("VRMC_materials_mtoon", "VRMC_materials_mtoon"), ("VRM", "vrm")):
|
||
schema = registry.contents(_BASE + fn + ".schema.json")
|
||
out[ext] = jsonschema.Draft4Validator(schema, registry=registry)
|
||
return out, None
|
||
|
||
|
||
def schema_errors(g, validators):
|
||
errs = []
|
||
|
||
def run(ext, obj, where):
|
||
for e in validators[ext].iter_errors(obj):
|
||
path = "/".join(str(p) for p in e.absolute_path)
|
||
errs.append("schema %s/%s: %s" % (where, path, e.message[:120]))
|
||
|
||
ext = g.get("extensions", {})
|
||
if "VRMC_vrm" in ext:
|
||
run("VRMC_vrm", ext["VRMC_vrm"], "VRMC_vrm")
|
||
if "VRMC_springBone" in ext:
|
||
run("VRMC_springBone", ext["VRMC_springBone"], "VRMC_springBone")
|
||
if "VRM" in ext:
|
||
run("VRM", ext["VRM"], "VRM")
|
||
for i, m in enumerate(g.get("materials", [])):
|
||
mt = m.get("extensions", {}).get("VRMC_materials_mtoon")
|
||
if mt is not None:
|
||
run("VRMC_materials_mtoon", mt, "materials/%d/mtoon" % i)
|
||
return errs
|
||
|
||
|
||
# ------------------------------------------------------------------ checks --
|
||
def check(path, validators=None):
|
||
"""→ (错误列表, 提示列表, 摘要 dict)"""
|
||
errs, notes = [], []
|
||
g, b = vrmio.read_glb(path)
|
||
ext = g.get("extensions", {})
|
||
nodes = g["nodes"]
|
||
par = {c: i for i, n in enumerate(nodes) for c in n.get("children", [])}
|
||
is1 = "VRMC_vrm" in ext
|
||
if not is1 and "VRM" not in ext:
|
||
return ["不是 VRM(没有 VRMC_vrm / VRM 扩展)"], [], {}
|
||
|
||
# humanoid
|
||
if is1:
|
||
hb = {k: v["node"] for k, v in ext["VRMC_vrm"]["humanoid"]["humanBones"].items()}
|
||
valid, req = _B10, _REQ
|
||
else:
|
||
hb = {x["bone"]: x["node"] for x in ext["VRM"]["humanoid"]["humanBones"]}
|
||
valid, req = _B0, _REQ + ["chest", "neck"]
|
||
for k in sorted(set(hb) - valid):
|
||
errs.append("humanoid:非法骨位 %s" % k)
|
||
for k in req:
|
||
if k not in hb:
|
||
errs.append("humanoid:缺少必需骨位 %s" % k)
|
||
for h, n in hb.items():
|
||
a = _vrm_anchor(h, hb)
|
||
if a is None:
|
||
continue
|
||
p = par.get(n)
|
||
while p is not None and p != hb[a]:
|
||
p = par.get(p)
|
||
if p is None:
|
||
errs.append("humanoid:%s 不在 %s 之下" % (h, a))
|
||
placeholders = sorted(h for h, n in hb.items() if nodes[n].get("name", "").startswith("vrm_"))
|
||
if placeholders:
|
||
notes.append("humanoid:%d 根占位骨(%s)" % (len(placeholders), ", ".join(placeholders[:6])
|
||
+ (" …" if len(placeholders) > 6 else "")))
|
||
|
||
# mesh
|
||
njoints = len(g["skins"][0]["joints"]) if g.get("skins") else 0
|
||
for mi, m in enumerate(g.get("meshes", [])):
|
||
for pr in m["primitives"]:
|
||
if "JOINTS_0" in pr["attributes"]:
|
||
if max(vrmio.read_accessor(g, b, pr["attributes"]["JOINTS_0"])) >= njoints:
|
||
errs.append("mesh %d:JOINTS_0 超出 skin.joints" % mi)
|
||
break
|
||
names = (m.get("extras") or {}).get("targetNames") or []
|
||
for k, v in Counter(names).items():
|
||
if v > 1:
|
||
errs.append("mesh %d:morph target 重名「%s」×%d(Unity 导入会中断)" % (mi, k, v))
|
||
|
||
# expressions
|
||
nm = len(g.get("materials", []))
|
||
if is1:
|
||
groups = ext["VRMC_vrm"].get("expressions", {})
|
||
for grp in ("preset", "custom"):
|
||
for name, e in (groups.get(grp) or {}).items():
|
||
for bnd in e.get("materialColorBinds", []):
|
||
if not 0 <= bnd["material"] < nm:
|
||
errs.append("表情 %s:材质号 %d 越界" % (name, bnd["material"]))
|
||
for bnd in e.get("morphTargetBinds", []):
|
||
node = nodes[bnd["node"]] if 0 <= bnd["node"] < len(nodes) else {}
|
||
if "mesh" not in node:
|
||
errs.append("表情 %s:node %d 没有网格" % (name, bnd["node"]))
|
||
continue
|
||
nt = len(g["meshes"][node["mesh"]]["primitives"][0].get("targets", []))
|
||
if not 0 <= bnd["index"] < nt:
|
||
errs.append("表情 %s:morph 索引 %d 越界(共 %d)" % (name, bnd["index"], nt))
|
||
|
||
# SpringBone
|
||
summary = {"spec": "1.0" if is1 else "0.x", "humanBones": len(hb),
|
||
"placeholders": len(placeholders)}
|
||
sb = ext.get("VRMC_springBone")
|
||
if sb:
|
||
hum = set(hb.values())
|
||
seen = Counter()
|
||
ncg = len(sb.get("colliderGroups", []))
|
||
for sp in sb["springs"]:
|
||
js = sp["joints"]
|
||
for a, c in zip(js, js[1:]):
|
||
q = par.get(c["node"])
|
||
while q is not None and q != a["node"]:
|
||
q = par.get(q)
|
||
if q is None:
|
||
errs.append("SpringBone %s:%s 不是 %s 的后代" % (
|
||
sp.get("name"), nodes[c["node"]]["name"], nodes[a["node"]]["name"]))
|
||
for j in js:
|
||
seen[j["node"]] += 1
|
||
if j["node"] in hum:
|
||
errs.append("SpringBone %s:关节落在 humanoid 骨 %s 上"
|
||
% (sp.get("name"), nodes[j["node"]]["name"]))
|
||
for k in ("hitRadius", "stiffness", "gravityPower", "dragForce"):
|
||
if k in j and not math.isfinite(j[k]):
|
||
errs.append("SpringBone %s:%s 不是有限值" % (sp.get("name"), k))
|
||
for cg in sp.get("colliderGroups", []):
|
||
if not 0 <= cg < ncg:
|
||
errs.append("SpringBone %s:碰撞组号 %d 越界" % (sp.get("name"), cg))
|
||
for n, c in seen.items():
|
||
if c > 1:
|
||
errs.append("SpringBone:节点 %s 在 %d 条链里当关节" % (nodes[n]["name"], c))
|
||
summary.update(springs=len(sb["springs"]),
|
||
joints=sum(len(sp["joints"]) for sp in sb["springs"]),
|
||
colliders=len(sb.get("colliders", [])))
|
||
sa = None if is1 else ext["VRM"].get("secondaryAnimation")
|
||
if sa and sa.get("boneGroups"):
|
||
errs += _check_secondary(sa, nodes, par, set(hb.values()))
|
||
summary.update(springs=len(sa["boneGroups"]),
|
||
colliders=sum(len(c.get("colliders", [])) for c in sa.get("colliderGroups", [])))
|
||
|
||
if validators:
|
||
errs += schema_errors(g, validators)
|
||
return errs, notes, summary
|
||
|
||
|
||
def _check_secondary(sa, nodes, par, hum):
|
||
"""VRM 0.x 的 secondaryAnimation:组根子树整棵都会摆动,同一节点在两个组里会被模拟两次。"""
|
||
errs = []
|
||
kids = {i: n.get("children", []) for i, n in enumerate(nodes)}
|
||
ncg = len(sa.get("colliderGroups", []))
|
||
owner = {}
|
||
for gi, grp in enumerate(sa["boneGroups"]):
|
||
name = grp.get("comment") or "#%d" % gi
|
||
if "stiffness" in grp and "stiffiness" not in grp:
|
||
errs.append("secondaryAnimation %s:硬度要写成 stiffiness(规范里的拼写),stiffness 不会被读取" % name)
|
||
for k in ("stiffiness", "gravityPower", "dragForce", "hitRadius"):
|
||
if k in grp and not math.isfinite(grp[k]):
|
||
errs.append("secondaryAnimation %s:%s 不是有限值" % (name, k))
|
||
for cg in grp.get("colliderGroups", []):
|
||
if not 0 <= cg < ncg:
|
||
errs.append("secondaryAnimation %s:碰撞组号 %d 越界" % (name, cg))
|
||
for r in grp.get("bones", []):
|
||
if not 0 <= r < len(nodes):
|
||
errs.append("secondaryAnimation %s:根节点 %d 越界" % (name, r))
|
||
continue
|
||
stack = [r]
|
||
while stack:
|
||
n = stack.pop()
|
||
if n in hum:
|
||
errs.append("secondaryAnimation %s:humanoid 骨 %s 在摆动子树里" % (name, nodes[n]["name"]))
|
||
if n in owner:
|
||
errs.append("secondaryAnimation:节点 %s 同时在组 %s 和 %s 的子树里(会被模拟两次)"
|
||
% (nodes[n]["name"], owner[n], name))
|
||
continue
|
||
owner[n] = name
|
||
stack.extend(kids[n])
|
||
for ci, cg in enumerate(sa.get("colliderGroups", [])):
|
||
if not 0 <= cg.get("node", -1) < len(nodes):
|
||
errs.append("secondaryAnimation:碰撞组 %d 的节点越界" % ci)
|
||
return errs
|
||
|
||
|
||
def iter_files(paths):
|
||
for p in paths:
|
||
if os.path.isdir(p):
|
||
for d, _, fs in os.walk(p):
|
||
for f in sorted(fs):
|
||
if f.lower().endswith(".vrm"):
|
||
yield os.path.join(d, f)
|
||
else:
|
||
yield p
|
||
|
||
|
||
def main(argv=None):
|
||
ap = argparse.ArgumentParser(description="VRM 文件静态检查")
|
||
ap.add_argument("paths", nargs="+", help=".vrm 文件或目录")
|
||
ap.add_argument("--no-schema", action="store_true", help="不做官方 JSON Schema 校验")
|
||
ap.add_argument("-v", "--verbose", action="store_true", help="通过的文件也打印摘要和提示")
|
||
a = ap.parse_args(argv)
|
||
try:
|
||
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
|
||
except Exception:
|
||
pass
|
||
validators = None
|
||
if not a.no_schema:
|
||
validators, why = load_validators()
|
||
if why:
|
||
print("提示:" + why)
|
||
n = bad = 0
|
||
for path in iter_files(a.paths):
|
||
n += 1
|
||
try:
|
||
errs, notes, summ = check(path, validators)
|
||
except Exception as e: # noqa: BLE001 坏文件也要继续往下查
|
||
errs, notes, summ = ["读取失败:%s: %s" % (type(e).__name__, e)], [], {}
|
||
if errs:
|
||
bad += 1
|
||
print("✗ %s" % path)
|
||
shown = Counter()
|
||
for e in errs: # 同类错误只列前几条
|
||
key = e.split(":")[0] if ":" in e else e[:40]
|
||
shown[key] += 1
|
||
if shown[key] <= 5:
|
||
print(" " + e)
|
||
for k, c in shown.items():
|
||
if c > 5:
|
||
print(" …… %s 还有 %d 条" % (k, c - 5))
|
||
elif a.verbose:
|
||
print("✓ %s %s" % (path, " ".join("%s=%s" % kv for kv in summ.items())))
|
||
for t in notes:
|
||
print(" 提示:" + t)
|
||
print("检查 %d 个文件,%d 个有错误" % (n, bad))
|
||
return 1 if bad else 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main())
|