animation/tools/handshape_verify.py

"""Verify the emitted hand-morph GLB numerically:
1. CROSS-HAND INDEPENDENCE: each hand_<pose>_<side> shape must move ONLY that side's verts.
2. CURL DIRECTION: per shape, left-hand fingertip-region deltas must point toward the palm
   (dot with palm normal < 0) — catches a flipped normal making fingers bend backward.
"""
import json, struct, sys
from pathlib import Path
import numpy as np

def read_glb(path):
    d = Path(path).read_bytes()
    ln = struct.unpack_from("<I", d, 8)[0]
    off = 12; g = b = None
    while off < ln:
        clen, ct = struct.unpack_from("<II", d, off); off += 8
        if ct == 0x4E4F534A: g = json.loads(d[off:off+clen])
        elif ct == 0x004E4942: b = d[off:off+clen]
        off += clen
    return g, b

def acc(g, b, i):
    a = g["accessors"][i]; bv = g["bufferViews"][a["bufferView"]]
    dt = np.dtype({5126: "<f4", 5123: "<u2", 5121: "u1", 5125: "<u4", 5122: "<i2"}[a["componentType"]])
    nc = {"VEC3": 3, "SCALAR": 1, "VEC4": 4}[a["type"]]
    size = dt.itemsize * nc
    stride = bv.get("byteStride") or size
    off2 = bv.get("byteOffset", 0) + a.get("byteOffset", 0)
    raw = np.frombuffer(b, np.uint8, a["count"] * stride, off2).reshape(a["count"], stride)
    return raw[:, :size].copy().view(dt).reshape(a["count"], nc).astype(np.float64)

argv = sys.argv
argv = argv[argv.index("--") + 1:] if "--" in argv else argv[1:]
g, b = read_glb(argv[0])
prim = g["meshes"][0]["primitives"][0]
P = acc(g, b, prim["attributes"]["POSITION"])
names = [g["nodes"][j].get("name", "") for j in g["skins"][0]["joints"]]
idx = {n: i for i, n in enumerate(names)}

# bone heads in world (mesh) space: node global translations
def node_local(nd):
    t = np.array(nd.get("translation", [0, 0, 0])); s = np.array(nd.get("scale", [1, 1, 1]))
    x, y, z, w = nd.get("rotation", [0, 0, 0, 1])
    n = np.sqrt(x*x+y*y+z*z+w*w); x, y, z, w = x/n, y/n, z/n, w/n
    R = np.array([[1-2*(y*y+z*z), 2*(x*y-z*w), 2*(x*z+y*w)],
                  [2*(x*y+z*w), 1-2*(x*x+z*z), 2*(y*z-x*w)],
                  [2*(x*z-y*w), 2*(y*z+x*w), 1-2*(x*x+y*y)]])
    M = np.eye(4); M[:3, :3] = R * s[None, :]; M[:3, 3] = t
    return M

node_to_joint = {j: i for i, j in enumerate(g["skins"][0]["joints"])}
parent = {}
for i, j in enumerate(g["skins"][0]["joints"]):
    for c in g["nodes"][j].get("children", []):
        if c in node_to_joint: parent[node_to_joint[c]] = i
G = {}
def glob(i):
    if i in G: return G[i]
    j = g["skins"][0]["joints"][i]
    M = node_local(g["nodes"][j])
    G[i] = M if parent.get(i, -1) < 0 else glob(parent[i]) @ M
    return G[i]

def head(n): return glob(idx[n])[:3, 3]

# palm plane per side: normal via middle/pinky/index MCP + hand
for side in ("l", "r"):
    h = head(f"hand_{side}")
    mid, ix, pk = head(f"middle_01_{side}"), head(f"index_01_{side}"), head(f"pinky_01_{side}")
    n = np.cross(mid - h, pk - ix); n /= np.linalg.norm(n)
    print(f"side {side}: palm normal (world) = {np.round(n, 3)}")

# nearest-bone segmentation for vert labeling (euclidean, fingers only — verification only)
finger_bones = [f"{d}_{p}{s}" for s in ("l", "r") for d in ("thumb","index","middle","ring","pinky")
                for p in ("01","02","03") if f"{d}_{p}{s}" in idx]
heads = {bn: head(bn) for bn in finger_bones}
dmin = np.full(len(P), 1e9); label = np.full(len(P), -1, dtype=int)
for bi, bn in enumerate(finger_bones):
    d = np.linalg.norm(P - heads[bn], axis=1)
    closer = d < dmin
    dmin[closer] = d[closer]; label[closer] = bi
# keep verts within 8cm of their nearest finger bone (fingertip region <= 3.5cm for direction)
targets = prim["targets"]
tnames = g["meshes"][0]["extras"]["targetNames"]
for ti, tname in enumerate(tnames):
    delta = acc(g, b, targets[ti]["POSITION"])
    mag = np.linalg.norm(delta, axis=1)
    side = tname[-1]
    # 1) cross-hand: verts whose nearest bone is the OTHER side must not move
    other = np.array([finger_bones[l][-1] != side if l >= 0 else False for l in label])
    other &= dmin < 0.08
    cross = float(mag[other].max()) if other.any() else 0.0
    # 2) curl direction: fingertip verts of THIS side (non-thumb, nearest <= 3.5cm of _03 bone)
    tip = np.zeros(len(P), dtype=bool)
    for d in ("index", "middle", "ring", "pinky"):
        bn = f"{d}_03_{side}"
        if bn in heads:
            tip |= (np.linalg.norm(P - heads[bn], axis=1) < 0.035)
    if tip.any():
        h = head(f"hand_{side}")
        mid, ix, pk = head(f"middle_01_{side}"), head(f"index_01_{side}"), head(f"pinky_01_{side}")
        n = np.cross(mid - h, pk - ix); n /= np.linalg.norm(n)
        dots = delta[tip] @ n
        toward = float((dots < 0).mean())
    else:
        toward = -1
    own = ~other & (dmin < 0.08)
    ownmax = float(mag[own].max()) * 100 if own.any() else -1.0
    print(f"{tname}: max|delta| other-hand={cross*100:.2f}cm  tip-toward-palm={toward*100:.0f}%  "
          f"max|delta| own={ownmax:.1f}cm")