Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

9.2 KB
Raw Blame
import { expect, test, vi } from 'vitest';
import fixture from '../samples/miko-qipao/rig.json';
import { ARM_DEFAULTS, parseRig, validateRig, type Arms } from 'mesh-avatar';
import { createArms } from '../packages/runtime/src/engine/arms.js';
import { createRig, PARAMS } from '../packages/runtime/src/engine/rig.js';
import { Motion } from '../packages/runtime/src/engine/motion.js';

const arms: Arms = {
  left: { shoulder: [250, 650], elbow: [200, 800], wrist: [150, 950], split: [[265, 680], [235, 800], [200, 1030]] },
  right: { shoulder: [1004, 650], elbow: [1054, 800], wrist: [1104, 950], split: [[989, 680], [1019, 800], [1054, 1030]] },
};
const defaults = Object.fromEntries(PARAMS.map(p => [p.id, p.def]));
const phys = { gain: 0, bunL: [0, 0], bunR: [0, 0], strands: [] };
function rigWithArms() { const rig = parseRig(fixture); rig.arms = structuredClone(arms); return rig; }

test('optional arms accept defaults and boundary settings; reject malformed geometry and tuning', () => {
  expect(ARM_DEFAULTS).toEqual({ swing: 4, bend: 6, inward: 0.4 });
  expect(validateRig(rigWithArms())).toEqual([]);
  for (const [swing, bend, inward] of [[0, 0, 0], [10, 12, 1]]) {
    const rig = rigWithArms(); Object.assign(rig.arms!, { swing, bend, inward });
    expect(validateRig(rig)).toEqual([]);
  }
  for (const change of [
    (a: Arms) => { a.left.elbow[1] = a.left.shoulder[1]; },
    (a: Arms) => { a.right.wrist[1] = a.right.elbow[1]; },
    (a: Arms) => { a.left.split[1][1] = a.left.split[0][1]; },
    (a: Arms) => { a.right.split = [[900, 680]]; },
    (a: Arms) => { a.left.split[1][0] = 190; },
    (a: Arms) => { a.right.split[1][0] = 1060; },
    (a: Arms) => { a.left.wrist[0] = -1; },
    (a: Arms) => { a.right.shoulder[0] = fixture.image.width; },
    (a: Arms) => { a.left.split[0][1] = -1; },
    (a: Arms) => { a.swing = -1; },
    (a: Arms) => { a.swing = 10.01; },
    (a: Arms) => { a.bend = 12.01; },
    (a: Arms) => { a.bend = -0.01; },
    (a: Arms) => { a.inward = 1.01; },
    (a: Arms) => { a.inward = -0.01; },
    (a: Arms) => { a.left.elbow[0] = NaN; },
  ]) {
    const rig = rigWithArms(); change(rig.arms!);
    expect(validateRig(rig).join()).toContain('rig.arms');
  }
});

test('legacy avatars ignore all new parameters and zero arms preserve every original point exactly', () => {
  const old = createRig(parseRig(fixture)), newer = createRig(rigWithArms());
  let maximum = 0;
  for (const pose of [{}, { bodyAngleZ: 8, bodyAngleX: -7, breath: 0.8, angleZ: 15 }, { angleX: -30, angleY: 15 }]) {
    const P = { ...defaults, ...pose };
    for (let y = 0; y <= fixture.image.height; y += 13) for (let x = 0; x <= fixture.image.width; x += 13) {
      const expected = old.deformBase(x, y, old.baseWeights(x, y, 0), P, phys, [0, 0]);
      expect(old.deformBase(x, y, old.baseWeights(x, y, 0), { ...P, armSwingL: 1, armSwingR: -1, elbowBendL: 1, elbowBendR: 1 }, phys, [0, 0])).toEqual(expected);
      const actual = newer.deformBase(x, y, newer.baseWeights(x, y, 0), P, phys, [0, 0]);
      maximum = Math.max(maximum, Math.hypot(actual[0] - expected[0], actual[1] - expected[1]));
    }
  }
  console.log(`Arms neutral regression: max delta ${maximum} px`);
  expect(maximum).toBe(0);
});

test('image sides swing outwards, inward swing is reduced, flex never hyperextends and controls clamp', () => {
  const model = createArms(arms, fixture.body)!;
  for (const [index, side] of (['L', 'R'] as const).entries()) {
    const rest = index ? arms.right : arms.left;
    const w = model.weights(...rest.wrist);
    const point = (value: number, bend = 0) => {
      const p = [...rest.wrist]; model.apply(p, ...rest.wrist, w, { [`armSwing${side}`]: value, [`elbowBend${side}`]: bend }); return p;
    };
    const outward = point(1), inward = point(-1);
    expect(index ? outward[0] > rest.wrist[0] : outward[0] < rest.wrist[0]).toBe(true);
    expect(index ? inward[0] < rest.wrist[0] : inward[0] > rest.wrist[0]).toBe(true);
    expect(Math.hypot(outward[0] - rest.wrist[0], outward[1] - rest.wrist[1]))
      .toBeGreaterThan(Math.hypot(inward[0] - rest.wrist[0], inward[1] - rest.wrist[1]) * 2);
    expect(point(10, 10)).toEqual(point(1, 1));
    expect(point(-10, -10)).toEqual(point(-1, 0));
    const f = model.frame({ [`armSwing${side}`]: 1, [`elbowBend${side}`]: 1 })[index];
    expect(Math.abs(f.swing)).toBeCloseTo(4 * Math.PI / 180, 12);
    expect(Math.abs(f.bend)).toBeCloseTo(6 * Math.PI / 180, 12);
    const bent = point(0, 1);
    expect(index ? bent[0] < rest.wrist[0] : bent[0] > rest.wrist[0]).toBe(true);
    // Forearm rotation retains its length, and the opposite side is untouched.
    expect(Math.hypot(bent[0] - rest.elbow[0], bent[1] - rest.elbow[1])).toBeCloseTo(Math.hypot(rest.wrist[0] - rest.elbow[0], rest.wrist[1] - rest.elbow[1]), 10);
    const other = index ? arms.left.wrist : arms.right.wrist, p = [...other];
    model.apply(p, ...other, model.weights(...other), { [`armSwing${side}`]: 1, [`elbowBend${side}`]: 1 });
    expect(p).toEqual(other);
  }
});

test('body-side vertices, shoulder seam and points below the arm stay fixed, elbow band is continuous', () => {
  const model = createArms(arms, fixture.body)!;
  const P = { armSwingL: 1, armSwingR: 1, elbowBendL: 1, elbowBendR: 1 };
  for (const rest of [[500, 850], arms.left.shoulder, arms.right.shoulder, [150, 1200]]) {
    const p = [...rest]; model.apply(p, rest[0], rest[1], model.weights(rest[0], rest[1]), P); expect(p).toEqual(rest);
  }
  const points = [799.999, 800, 800.001].map(y => {
    const p = [200, y]; model.apply(p, 200, y, model.weights(200, y), P); return p;
  });
  expect(Math.hypot(points[0][0] - points[2][0], points[0][1] - points[2][1])).toBeLessThan(0.003);
  const bad = structuredClone(arms); bad.left.elbow = [...bad.left.shoulder]; bad.left.wrist = [...bad.left.shoulder]; bad.left.split[1] = [...bad.left.split[0]];
  const degenerate = createArms(bad, fixture.body)!;
  const p = [200, 800]; degenerate.apply(p, 200, 800, degenerate.weights(200, 800), { ...P, armSwingL: NaN, elbowBendL: Infinity });
  expect(p.every(Number.isFinite)).toBe(true);
});

test('arms ride the deformed shoulder, including planted legs, with exact identity when disabled', () => {
  const rig = rigWithArms();
  rig.legs = { pelvis: [627, 900], band: [700, 940], shift: 12, tilt: 0.04, bend: 4,
    left: { hip: [570, 930], knee: [560, 1080], ankle: [550, 1210] },
    right: { hip: [680, 930], knee: [690, 1080], ankle: [700, 1210] }, split: [[627, 950], [627, 1250]] };
  const engine = createRig(rig), plainRig = structuredClone(rig); delete plainRig.arms;
  const plain = createRig(plainRig);
  for (let f = 0; f < 60; f++) {
    const P = { ...defaults, bodyAngleZ: 8, breath: 0.7, weightShift: f / 60 };
    engine.stepBody(P, 1 / 60); plain.stepBody(P, 1 / 60);
    const [x, y] = arms.left.shoulder;
    expect(engine.deformBase(x, y, engine.baseWeights(x, y, 0), { ...P, armSwingL: 1, elbowBendL: 1 }, phys, [0, 0]))
      .toEqual(plain.deformBase(x, y, plain.baseWeights(x, y, 0), P, phys, [0, 0]));
    for (const [px, py] of [arms.left.wrist, arms.right.wrist])
      expect(engine.deformBase(px, py, engine.baseWeights(px, py, 0), P, phys, [0, 0]))
        .toEqual(plain.deformBase(px, py, plain.baseWeights(px, py, 0), P, phys, [0, 0]));
  }
});

test('idle arms follow the torso with lag, consume no RNG, preserve legacy tracks, and respect manual rest', () => {
  const run = (withArms: boolean) => {
    const random = vi.spyOn(Math, 'random').mockReturnValue(0.5);
    try {
      const m = new Motion([512, 180], false, withArms ? rigWithArms() : null);
      m.autoIdle = false; m.autoMotion = false;
      const samples = Array.from({ length: 600 }, () => m.update(1 / 60));
      return { samples, calls: random.mock.calls.length, m };
    } finally { random.mockRestore(); }
  };
  const old = run(false), newer = run(true);
  expect(newer.calls).toBe(old.calls);
  for (let i = 0; i < 600; i++) for (const key of Object.keys(old.samples[i]))
    if (!/^(armSwing|elbowBend)/.test(key)) expect(newer.samples[i][key]).toBe(old.samples[i][key]);
  expect(old.samples.every(p => p.armSwingL === 0 && p.elbowBendR === 0)).toBe(true);
  expect(newer.samples.some(p => Math.abs(p.armSwingL) > 0.02)).toBe(true);
  expect(newer.samples.every(p => Math.abs(p.armSwingL) <= 1 && p.elbowBendR >= 0 && p.elbowBendR <= 1)).toBe(true);
  newer.m.mode = 'manual';
  const rest = newer.m.update(1 / 60);
  for (const id of ['armSwingL', 'armSwingR', 'elbowBendL', 'elbowBendR']) expect(rest[id]).toBe(0);
  // Start within a planted hold: gravity follow approaches the fixed torso tilt
  // gradually instead of snapping on its first frame.
  const rig = rigWithArms(); rig.body.maxRoll = 0;
  rig.legs = { pelvis: [627, 900], band: [700, 940], shift: 12, tilt: 0.04, bend: 4,
    left: { hip: [570, 930], knee: [560, 1080], ankle: [550, 1210] },
    right: { hip: [680, 930], knee: [690, 1080], ankle: [700, 1210] }, split: [[627, 950], [627, 1250]] };
  const m = new Motion([512, 180], true, rig);
  m.autoIdle = false; m.autoMotion = false; m.t = 1;
  m.update(1 / 60); const initial = Math.abs(m.armFollow);
  for (let i = 0; i < 60; i++) m.update(1 / 60);
  const target = -rig.legs.tilt * 0.3 * 0.7 * 0.65;
  expect(initial).toBeLessThan(Math.abs(target) * 0.1);
  expect(m.armFollow).toBeCloseTo(target, 4);
  expect(Number.isFinite(m.update(1).armSwingL)).toBe(true);
});