Files
VRMify-Enhanced/tools/qa/check_vrm.py
T
Black-Cyan 60cce66993
Tests / test (push) Has been cancelled
初始化 VRMify 增强版(VRMify Enhanced)
导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
2026-11-15 23:21:59 +08:00

359 lines
17 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# -*- 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())