Skip to content
Python
12.0 KB
Raw Blame
#!/usr/bin/env python3
"""Gate `--cont-head` before it costs cluster time.

    python tools/verify_cont_head.py --data_root data

Six checks, all on real ground truth and the real rig:

1. **Reachability.** Every GT 204-vector must be expressible in the head's
   output space. Invert a real annotation into the 447 numbers, push it back
   through `ContMHRHead`, and compare parameters *and* forward kinematics. If
   this fails the head cannot represent its own targets and no amount of
   training fixes it.
2. **Neutral initialisation.** A freshly built head, before any training, must
   decode to the rig's zero pose -- not to whatever all-zero continuous inputs
   happen to mean, which is a 6D vector with no rotation and an `atan2` at a
   0/0 gradient.
3. **Invariants.** Root translation exactly zero, bone scales inside the
   teacher's 24-dimensional scale subspace, size channels inside the rig limits
   -- for arbitrary head outputs, including deliberately extreme ones.
4. **Finite gradients** through the whole conversion, at the neutral pose, at
   random poses, and at the two places the geometry is singular: identity and a
   half turn.
5. **Root-loss magnitude.** The chordal rotation loss replaces a SmoothL1 on the
   Euler triple. The gradient comparison is printed rather than assumed.
6. **Scale stability** under a large random head output: the failure mode that
   killed four runs at epochs 24-32 was a bone scale running away, and the PCA
   parameterisation changes how that can happen.

Exit status is 0 only if every check passes.
"""

from __future__ import annotations

import argparse
import glob
import sys
from pathlib import Path

import numpy as np
import torch

sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "training"))
import mhr_cont as MC                                          # noqa: E402
import train as T                             # noqa: E402

OK, BAD = "  ok  ", "*FAIL*"
_fails = 0


def check(cond: bool, label: str, detail: str = "") -> None:
    global _fails
    if not cond:
        _fails += 1
    print(f"[{OK if cond else BAD}] {label}{('  ' + detail) if detail else ''}")


def atanh_to_range(x, lo, hi):
    """Pre-tanh value that `ContMHRHead._to_range` maps back onto `x`."""
    span = hi - lo
    t = torch.where(span > 0, (2.0 * (x - lo) / span.clamp_min(1e-12) - 1.0).clamp(-1 + 1e-6, 1 - 1e-6),
                    torch.zeros_like(x))
    return torch.atanh(t)


def head_vector_from_gt(head, gt204, gt_shape):
    """The 447 numbers whose decode is `gt204` -- the inverse of ContMHRHead."""
    B = gt204.shape[0]
    root6 = MC.rotmat_to_rot6d(MC.euler_xyz_to_rotmat(gt204[:, 3:6]))

    body133 = torch.cat([gt204[:, 6:136], torch.zeros(B, 3, device=gt204.device)], 1)
    if head.bound_scales:                       # the head tanh's 130:136
        body133 = body133.clone()
        body133[:, 124:130] = atanh_to_range(body133[:, 124:130], head.flex_lo, head.flex_hi)
    body_cont = MC.body_params_to_cont(body133)

    coeff = (gt204[:, 136:204] - head.scale_mean) @ head.scale_pinv
    if head.bound_scales:
        coeff = atanh_to_range(coeff, head.coeff_lo, head.coeff_hi)

    hands = []
    for idx in (head.hand_idx_left, head.hand_idx_right):
        hands.append(MC.hand_params_to_cont(gt204[:, idx]) - head.hand_mean)
    return torch.cat([root6, body_cont, gt_shape, coeff] + hands, dim=1)


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--data_root", default="data")
    ap.add_argument("--n", type=int, default=512)
    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
    args = ap.parse_args()
    dev = args.device

    cfg = T.DistillConfig()
    T.cfg = cfg
    T.apply_rebalanced_losses(cfg)
    cfg.cont_head = True
    cfg.root_rot_loss = True
    cfg.bound_scales = True
    cfg.w_verts = 0.35

    head = T.ContMHRHead(cfg, cfg.d_model).to(dev).eval()
    # Extras the inverse needs; they live in the asset, not in the head.
    a = np.load(cfg.cont_head_path)
    head.scale_pinv = torch.from_numpy(a["scale_pinv"]).float().to(dev)
    head.hand_idx_left = torch.from_numpy(a["hand_joint_idxs_left"]).long().to(dev)
    head.hand_idx_right = torch.from_numpy(a["hand_joint_idxs_right"]).long().to(dev)

    files = sorted(glob.glob(f"{args.data_root}/*/annotations/*.npz"))[:args.n]
    if not files:
        files = sorted(glob.glob(f"{args.data_root}/annotations/*.npz"))[:args.n]
    gt204 = torch.from_numpy(np.stack([np.load(f)["mhr_model_params"] for f in files])).float().to(dev)
    gt_shape = torch.from_numpy(np.stack([np.load(f)["shape_params"] for f in files])).float().to(dev)
    print(f"{len(gt204):,} real GT annotations from {args.data_root}, device {dev}\n")

    mhr = T.MHRForwardPass(cfg.mhr_model_path, dev,
                           kp_regressor=np.load(cfg.kp_regressor_path))

    # --- 1. reachability ----------------------------------------------------
    vec = head_vector_from_gt(head, gt204, gt_shape)
    check(vec.shape[1] == MC.N_HEAD_OUT, "head output width",
          f"{vec.shape[1]} dims (6 root + 260 body + 45 shape + 28 scale + 108 hands)")
    with torch.no_grad():
        rec, rec_shape, _ = head.decode(vec)

    dp = (rec[:, 6:136] - gt204[:, 6:136]).abs().max()
    ds = (rec[:, 136:204] - gt204[:, 136:204]).abs().max()
    check(dp < 2e-3, "GT body angles round-trip", f"max {dp:.2e} rad")
    check(ds < 2e-3, "GT bone scales round-trip", f"max {ds:.2e}")

    # The ROOT is compared as a rotation, not as three numbers. `atan2` returns
    # the representative in (-pi, pi], and real annotations go outside it: 5 of
    # 256 COCO roots have an axis beyond pi, so the round trip legitimately
    # comes back 2pi away on that axis while encoding the identical rotation.
    # Comparing the raw triples flags those as a 6.28 rad error -- which is
    # precisely the defect `--cont-head` exists to remove, since the SmoothL1
    # this replaces charges 0.96 for such a pair, more than it charges for a
    # genuine 179 deg error.
    Rg = MC.euler_xyz_to_rotmat(gt204[:, 3:6])
    Rr = MC.euler_xyz_to_rotmat(rec[:, 3:6])
    cos = ((torch.einsum("bii->b", Rg.transpose(1, 2) @ Rr) - 1) / 2).clamp(-1, 1)
    geo = torch.rad2deg(torch.acos(cos)).max()
    raw = (rec[:, 3:6] - gt204[:, 3:6]).abs().max(1).values
    n_wrap = int((raw > 1e-2).sum())
    check(geo < 0.1, "GT root round-trip, as a rotation", f"max {geo:.2e} deg")
    print(f"         ({n_wrap} of {len(gt204)} roots come back on the other side of "
          f"+-pi -- same rotation, different Euler representative; the root loss "
          f"is on the matrix, so this costs nothing)")
    check((rec_shape - gt_shape).abs().max() < 1e-6, "identity coefficients pass through")

    with torch.no_grad():
        j_gt = mhr.get_joints(gt204, gt_shape)[..., :3]
        j_rc = mhr.get_joints(rec, gt_shape)[..., :3]
    fk = (j_gt - j_rc).norm(dim=-1).max() * 10.0     # 1 rig unit = 10 cm -> mm
    check(fk < 1.0, "forward kinematics after round-trip", f"max joint error {fk:.4f} mm")

    # --- 2. neutral initialisation -----------------------------------------
    # The 54 finger channels are NOT expected to be zero: zero hand
    # coefficients decode to `hand_pose_mean`, which is the teacher's mean hand
    # pose (up to 0.594 rad) and is the intended resting hand.
    hand_ch = torch.cat([head.hand_idx_left, head.hand_idx_right])
    body_ch = torch.tensor([i for i in range(6, 130) if i not in set(hand_ch.tolist())],
                           device=dev)
    with torch.no_grad():
        p0, _, R0 = head.decode(MC.neutral_head_output().to(dev))
    check(p0[:, body_ch].abs().max() < 1e-6, "neutral encoding decodes the zero pose",
          f"max |body angle|, fingers excluded, {p0[:, body_ch].abs().max():.2e} rad")
    with torch.no_grad():
        want = MC.cont_to_hand_params(head.hand_mean[None])
    check((p0[:, head.hand_idx_right] - want).abs().max() < 1e-6,
          "finger channels start at the teacher's mean hand pose",
          f"max |angle| {want.abs().max():.3f} rad")
    check((R0 - torch.eye(3, device=dev)).abs().max() < 1e-6,
          "neutral root rotation is identity")
    check((p0[:, 136:204] - head.scale_mean).abs().max() < 1e-5,
          "neutral bone scales are exactly scale_mean",
          f"max {(p0[:, 136:204] - head.scale_mean).abs().max():.2e}")
    with torch.no_grad():
        q, _, Rq = head(torch.randn(8, cfg.d_model, device=dev))
    check((q[:, body_ch]).abs().max() < 1e-2 and (Rq - torch.eye(3, device=dev)).abs().max() < 1e-2,
          "untrained head starts at that neutral pose",
          f"max |body angle| {q[:, body_ch].abs().max():.2e} rad, "
          f"root off identity by {torch.rad2deg(torch.acos((((Rq * torch.eye(3, device=dev)).sum((-1,-2)) - 1) / 2).clamp(-1,1))).max():.3f} deg")

    # --- 3. invariants under arbitrary output ------------------------------
    torch.manual_seed(0)
    for scale, tag in ((1.0, "N(0,1)"), (25.0, "N(0,25) -- the runaway regime")):
        with torch.no_grad():
            p, _, _ = head.decode(torch.randn(256, MC.N_HEAD_OUT, device=dev) * scale)
        check(p[:, :3].abs().max() == 0, f"root translation exactly zero [{tag}]")
        resid = ((p[:, 136:204] - head.scale_mean) @ head.scale_pinv @ head.scale_comps
                 + head.scale_mean - p[:, 136:204]).abs().max()
        check(resid < 1e-3, f"bone scales stay in the scale subspace [{tag}]",
              f"residual {resid:.2e}")
        lo, hi = head.flex_lo.min(), head.flex_hi.max()
        inb = (p[:, 130:136] >= head.flex_lo - 1e-4).all() and (p[:, 130:136] <= head.flex_hi + 1e-4).all()
        check(bool(inb), f"size channels 130:136 inside rig limits [{tag}]")
        with torch.no_grad():
            j = mhr.get_joints(p, torch.zeros(len(p), 45, device=dev))[..., :3]
        span = (j.max(1).values - j.min(1).values).norm(dim=-1).max() * 10 / 1000
        check(span < 5.0, f"skeleton stays human-sized [{tag}]", f"max extent {span:.2f} m")

    # --- 4. finite gradients ------------------------------------------------
    for tag, v in (("neutral", MC.neutral_head_output().to(dev).repeat(8, 1)),
                   ("random", torch.randn(8, MC.N_HEAD_OUT, device=dev))):
        v = v.clone().requires_grad_(True)
        p, s, R = head.decode(v)
        (p.sum() + s.sum() + R.sum()).backward()
        check(torch.isfinite(v.grad).all(), f"gradients finite through the decode [{tag}]",
              f"max |grad| {v.grad.abs().max():.3e}")

    crit = T.DistillationLoss(cfg, mhr)
    for tag, ang in (("identity", torch.zeros(8, 3)),
                     ("half turn (pi)", torch.tensor([[np.pi, 0., 0.]] * 8)),
                     ("gimbal (pi/2 middle axis)", torch.tensor([[0.3, np.pi / 2, 0.7]] * 8))):
        six = MC.rotmat_to_rot6d(MC.euler_xyz_to_rotmat(ang.to(dev))).requires_grad_(True)
        Rp = MC.rot6d_to_rotmat(six)
        tgt = torch.zeros(8, 204, device=dev)
        e = crit.root_chordal({"root_rotmat": Rp}, None, tgt)
        e.sum().backward()
        check(torch.isfinite(six.grad).all(), f"root loss gradient finite at {tag}",
              f"loss {e.mean():.4f}, max |grad| {six.grad.abs().max():.3e}")

    # --- 5. root-loss magnitude vs the SmoothL1 it replaces -----------------
    print("\nroot-loss magnitude:")
    err_deg = [1.0, 5.0, 30.0, 90.0, 179.0]
    print(f"  {'error':>10} | {'chordal /6':>10} | {'SmoothL1(beta=1) on the Euler triple':>38}")
    for d in err_deg:
        r = torch.deg2rad(torch.tensor(d))
        A = MC.euler_xyz_to_rotmat(torch.zeros(1, 3))
        B = MC.euler_xyz_to_rotmat(torch.tensor([[r, 0., 0.]]))
        ch = ((A - B).pow(2).sum() * 0.25 / 6.0).item()
        sl = torch.nn.functional.smooth_l1_loss(
            torch.tensor([[0., 0., 0., r, 0., 0.]]), torch.zeros(1, 6),
            reduction="none", beta=1.0).mean().item()
        print(f"  {d:8.0f} deg | {ch:10.5f} | {sl:38.5f}")

    print()
    if _fails:
        print(f"{_fails} check(s) FAILED")
    else:
        print("all checks passed")
    return 1 if _fails else 0


if __name__ == "__main__":
    raise SystemExit(main())