cozyclay 3.1.6 → 3.2.1

package/src/motion3/qa/ballistic.js

@@ -0,0 +1,67 @@
+// The ballistic arc a FLOAT run should follow (qa/style.js floatChecks reads the run, this file
+// says how to fix it). Off the ground the hips ride a gravity parabola: anchored at the frame
+// just before takeoff (A = a - 1) and the frame just after landing (B = b + 1), with gravity
+// fixed (g = 9.81 / fps^2 m per frame^2), the launch speed v0 is the one closed form that makes
+// the parabola pass through both anchors:
+//   y(f) = yA + v0 (f - A) - g/2 (f - A)^2,   v0 = (yB - yA) / T + g T / 2,   T = B - A.
+// The fix is that parabola minus the hips height, per frame, vertical only. No anchor (the run
+// touches either end of the take) or a correction past MAX_FIX (the run is too long for the
+// height it has: the arc would throw the body half a metre or more) means no fix; past MAX_FIX
+// arcPrescription gives the apex the run needs, or the run the hips' own apex fits.
+// Pure: numbers in, numbers out.
+
+/** A correction past this (m) is not a fix: the run needs fewer frames, not a higher arc. */
+export const MAX_FIX = 0.5;
+
+/**
+ * ballisticArc(y, a, b, g) -> { from, to, v0, delta, worst } | null
+ * @param {ArrayLike<number>} y  hips height per frame (index = frame of the same take)
+ * @param {number} a  first airborne frame (index into y)
+ * @param {number} b  last airborne frame (index into y)
+ * @param {number} g  gravity in m per frame^2 (9.81 / fps^2)
+ * @returns delta[i] = fitted - actual height at frame a + i; worst = the frame (index into y)
+ *   of the largest |delta|; from/to = the anchor frames; v0 = the launch speed (m per frame)
+ */
+export function ballisticArc(y, a, b, g, maxFix = MAX_FIX) {
+	if (!Number.isInteger(a) || !Number.isInteger(b) || b < a || !(g > 0)) return null;
+	const A = a - 1, B = b + 1;
+	if (A < 0 || B > y.length - 1) return null;
+	const yA = y[A], yB = y[B], T = B - A;
+	if (!Number.isFinite(yA) || !Number.isFinite(yB)) return null;
+	const v0 = (yB - yA) / T + g * T / 2, delta = [];
+	let worst = a;
+	for (let f = a; f <= b; f++) {
+		if (!Number.isFinite(y[f])) return null;
+		const t = f - A, d = yA + v0 * t - g / 2 * t * t - y[f];
+		delta.push(d);
+		if (Math.abs(d) > Math.abs(delta[worst - a])) worst = f;
+	}
+	if (Math.abs(delta[worst - a]) > maxFix) return null;
+	return { from: A, to: B, v0, delta, worst };
+}
+
+/**
+ * The frames (indexes into y) at 1/4, 1/2 and 3/4 of the way between the anchors, each once,
+ * inside the run [a, b] of arc.
+ */
+export function arcFrames(arc) {
+	const { from: A, to: B } = arc, a = A + 1, b = B - 1, out = [];
+	for (const q of [0.25, 0.5, 0.75]) {
+		const f = Math.min(b, Math.max(a, Math.round(A + (B - A) * q)));
+		if (!out.includes(f)) out.push(f);
+	}
+	return out;
+}
+
+/**
+ * arcPrescription(y, a, b, g) -> { off, frames, apex, height, fits } | null: for an arc past MAX_FIX, the numbers that
+ * fix the run instead. A flight of N frames (anchor to anchor) peaks g N^2 / 8 above takeoff (apex, g per frame^2:
+ * 9.81 (N / fps)^2 / 8); the hips' own apex h above takeoff fits N = sqrt(8 h / g) frames (fits, rounded; 0 when the
+ * hips never rise). off = the arc minus the hips at the worst frame. Null when there is no anchor or the arc fits.
+ */
+export function arcPrescription(y, a, b, g) {
+	const arc = ballisticArc(y, a, b, g, Infinity);
+	if (!arc || Math.abs(arc.delta[arc.worst - a]) <= MAX_FIX) return null;
+	const frames = arc.to - arc.from, height = Math.max(...Array.from(arc.delta, (_, i) => y[a + i])) - y[arc.from];
+	return { off: arc.delta[arc.worst - a], frames, apex: g * frames * frames / 8, height, fits: height > 0 ? Math.round(Math.sqrt(8 * height / g)) : 0 };
+}

package/src/motion3/qa/com.js

@@ -0,0 +1,140 @@
+// Balance measurements on one frame's pose: the mass-weighted centre of mass of the body and the
+// support polygon of the feet on the ground. QA's BALANCE check and observations.balance
+// (style.js) and the BALANCE hint (hints-contact.js) all read them from here, so the issue, the
+// observation and the fix agree on the same point and the same polygon.
+//   centre of mass   the segment-mass-weighted average of the segment midpoints (SEGMENT_FRACTIONS),
+//                    from the frame's joint positions; a skeleton missing a segment bone falls back
+//                    to the average of the hips, the spine and the head.
+//   support polygon  the 2D convex hull (x, z) of the sole points (heel, ball, tip) of the feet on
+//                    the ground (ground.js): one foot's points when only one is down. While the hips
+//                    travel every foot counts (a step is about to land).
+//   margin           how far the centre of mass's ground projection sits inside the polygon (m, the
+//                    distance to its nearest edge), < 0 outside it (minus the distance to it).
+import { groundSole } from "./ground.js";
+
+/**
+ * Segment mass fractions of total body mass (Dempster, WADC TR 55-159, 1955, as tabulated by
+ * Winter, "Biomechanics and Motor Control of Human Movement"). The trunk (0.497) is split into
+ * pelvis (0.142) and thorax+abdomen (0.355); the hand rides on the forearm and the foot on the
+ * shank. Each entry's fraction sits at the midpoint of its two joints (bone names without a rig
+ * prefix). The fractions sum to 1. src/motion/center-of-mass.js reads the same table.
+ */
+export const SEGMENT_FRACTIONS = [
+	{ id: "pelvis", start: "Hips", end: "Spine1", mass: 0.142 },
+	{ id: "torso", start: "Spine1", end: "Neck", mass: 0.355 },
+	{ id: "head", start: "Neck", end: "Head", mass: 0.081 },
+	{ id: "leftUpperArm", start: "LeftArm", end: "LeftForeArm", mass: 0.028 },
+	{ id: "leftForeArmHand", start: "LeftForeArm", end: "LeftHand", mass: 0.022 },
+	{ id: "rightUpperArm", start: "RightArm", end: "RightForeArm", mass: 0.028 },
+	{ id: "rightForeArmHand", start: "RightForeArm", end: "RightHand", mass: 0.022 },
+	{ id: "leftThigh", start: "LeftUpLeg", end: "LeftLeg", mass: 0.100 },
+	{ id: "leftShankFoot", start: "LeftLeg", end: "LeftFoot", mass: 0.061 },
+	{ id: "rightThigh", start: "RightUpLeg", end: "RightLeg", mass: 0.100 },
+	{ id: "rightShankFoot", start: "RightLeg", end: "RightFoot", mass: 0.061 },
+];
+
+/** The joints whose plain average stands in for the centre of mass on a skeleton missing a segment bone. */
+const TRUNK = ["Hips", "Spine1", "Spine2", "Head"];
+
+/** Mass-weighted centre of mass [x, y, z] of pose s (world joint positions s.P), or null when sk lacks a segment bone. */
+export function centerOfMass(sk, s) {
+	const I = sk.index, c = [0, 0, 0];
+	let total = 0;
+	for (const { start, end, mass } of SEGMENT_FRACTIONS) {
+		const a = s.P[I[start]], b = s.P[I[end]];
+		if (I[start] === undefined || I[end] === undefined || !a || !b) return null;
+		for (let k = 0; k < 3; k++) c[k] += mass * (a[k] + b[k]) / 2;
+		total += mass;
+	}
+	return c.map(v => v / total);
+}
+
+/** centerOfMass, or the average of the hips, the spine and the head where the skeleton cannot give it. */
+export function bodyCentre(sk, s) {
+	const com = centerOfMass(sk, s);
+	if (com) return com;
+	const js = TRUNK.filter(j => sk.index[j] !== undefined);
+	return [0, 1, 2].map(k => js.reduce((acc, j) => acc + s.P[sk.index[j]][k], 0) / js.length);
+}
+
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+
+/** Convex hull of 2D points [x, z], counter-clockwise in (x, z), collinear points dropped (monotone chain). */
+export function convexHull(points) {
+	const p = [...points].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+	if (p.length < 3) return p;
+	const half = list => {
+		const h = [];
+		for (const q of list) {
+			while (h.length >= 2 && cross(h[h.length - 2], h[h.length - 1], q) <= 1e-12) h.pop();
+			h.push(q);
+		}
+		h.pop();
+		return h;
+	};
+	return [...half(p), ...half([...p].reverse())];
+}
+
+/** Nearest point to c on segment a-b (2D). */
+function onSegment(c, a, b) {
+	const d = [b[0] - a[0], b[1] - a[1]], l2 = d[0] * d[0] + d[1] * d[1];
+	const t = l2 > 0 ? Math.max(0, Math.min(1, ((c[0] - a[0]) * d[0] + (c[1] - a[1]) * d[1]) / l2)) : 0;
+	return [a[0] + t * d[0], a[1] + t * d[1]];
+}
+
+/**
+ * Where 2D point c ([x, z]) sits against the convex polygon of points: { margin, near }. near is
+ * the nearest point of the polygon's boundary; margin is the distance to it, > 0 inside the
+ * polygon, < 0 outside (a polygon of one or two points has no inside).
+ */
+export function supportMargin(c, points) {
+	const H = convexHull(points);
+	let near = H[0], best = Infinity;
+	for (let i = 0; i < (H.length > 1 ? H.length : 1); i++) {
+		const q = H.length > 1 ? onSegment(c, H[i], H[(i + 1) % H.length]) : H[0];
+		const d = Math.hypot(q[0] - c[0], q[1] - c[1]);
+		if (d < best) { best = d; near = q; }
+	}
+	const inside = H.length >= 3 && H.every((a, i) => cross(a, H[(i + 1) % H.length], c) >= 0);
+	return { margin: inside ? best : -best, near };
+}
+
+/**
+ * Balance at frame index i of out (out.frames[i]): "air" with no foot on the ground, else
+ * { margin, com, near, feet }: the centre of mass (bodyCentre), its margin against the support
+ * polygon (supportMargin of its ground projection) and the polygon's nearest point near ([x, z]).
+ * feet: the sole points [x, z] that made the polygon; ground: the ground height (groundSole) each
+ * of them was measured from, in the same order. Declared supports are style.js's.
+ */
+export function balanceAt(out, i) {
+	const F = out.frames, P = F[i].s.P, I = out.ctx.sk.index;
+	const moving = i > 0 && i < F.length - 1 && Math.hypot(F[i + 1].s.P[I.Hips][0] - F[i - 1].s.P[I.Hips][0], F[i + 1].s.P[I.Hips][2] - F[i - 1].s.P[I.Hips][2]) / 2 > 0.006;
+	const feet = [], ground = [];
+	for (const S of ["Left", "Right"]) {
+		const sp = groundSole(out, i, S);
+		if (!moving && Math.min(sp.heel[1], sp.ball[1]) >= 0.02) continue;
+		for (const key of ["heel", "ball", "tip"]) { feet.push([sp[key][0], sp[key][2]]); ground.push(sp.ground[key]); }
+	}
+	if (!feet.length) return "air";
+	const com = bodyCentre(out.ctx.sk, F[i].s), { margin, near } = supportMargin([com[0], com[2]], feet);
+	return { margin, com, near, feet, ground, facing: facing(P, I) };
+}
+
+/** The body's horizontal forward [x, z] from the hip axis (left hip minus right hip, turned a quarter about up). */
+function facing(P, I) {
+	const sx = P[I.LeftUpLeg][0] - P[I.RightUpLeg][0], sz = P[I.LeftUpLeg][2] - P[I.RightUpLeg][2], l = Math.hypot(sx, sz) || 1;
+	return [-sz / l, sx / l];
+}
+
+/**
+ * Words for where the centre of mass is off the support polygon: "0.12 m ahead of the feet
+ * (toward +Z)". b = balanceAt (outside: margin < 0). Ahead, behind, left and right are the
+ * body's (its hips); the axis in brackets is the world's.
+ */
+export function offsetWords(b) {
+	const o = [b.com[0] - b.near[0], b.com[2] - b.near[1]], [fx, fz] = b.facing;
+	const ahead = o[0] * fx + o[1] * fz, left = o[0] * fz - o[1] * fx;
+	const side = Math.abs(ahead) >= Math.abs(left) ? (ahead >= 0 ? "ahead of" : "behind") : (left >= 0 ? "left of" : "right of");
+	const axis = Math.abs(o[0]) >= Math.abs(o[1]) ? `${o[0] >= 0 ? "+" : "-"}X` : `${o[1] >= 0 ? "+" : "-"}Z`;
+	return `${(-b.margin).toFixed(2)} m ${side} the feet (toward ${axis})`;
+}

package/src/motion3/qa/ground.js

@@ -52,9 +52,16 @@ export function groundY(out, i, p) {
 	return g;
 }
 
-/** solePoints of frame index i with y the height above the ground under each point (x, z are world). */
+/**
+ * solePoints of frame index i with y the height above the ground under each point (x, z are world);
+ * ground: { heel, ball, tip }, the ground heights those were measured from.
+ */
 export function groundSole(out, i, side) {
-	const sp = solePoints(out.ctx.sk, out.frames[i].s, side);
-	for (const key of ["heel", "ball", "tip"]) sp[key] = [sp[key][0], sp[key][1] - groundY(out, i, sp[key]), sp[key][2]];
+	const sp = solePoints(out.ctx.sk, out.frames[i].s, side), ground = {};
+	for (const key of ["heel", "ball", "tip"]) {
+		ground[key] = groundY(out, i, sp[key]);
+		sp[key] = [sp[key][0], sp[key][1] - ground[key], sp[key][2]];
+	}
+	sp.ground = ground;
 	return sp;
 }

package/src/motion3/qa/hints-contact.js

@@ -2,7 +2,8 @@
 // other limb. Each answers a world move (direction x amount) for whatever drives that part.
 import { add, sub, scale, norm, dot, len, clamp, apply, ry, T } from "../compiler/math.js";
 import { bonePoint } from "../compiler/skeleton.js";
-import { CAPSULES, segPoints, sdBox, boxNormal, headDepth, segDist, solePoints, ankleY } from "./geometry.js";
+import { CAPSULES, segPoints, sdBox, boxNormal, headDepth, segDist, ankleY } from "./geometry.js";
+import { balanceAt, offsetWords } from "./com.js";
 import { vec, m3 } from "./fmt.js";
 import { kneeFoldHint, kneeWhy } from "./hints-knee.js";
 import { objectFrame } from "../compiler/anchors.js";
@@ -95,10 +96,22 @@ function probes(X, f, nm) {
 	return Object.entries(diag.props?.[nm.slice(5)] ?? {}).filter(([k, p]) => Array.isArray(p) && k !== "origin").map(([, p]) => p);
 }
 
+/** The most a hand's reachGrip world anchor rises over a scene box's top it went into (#819: past ~3.5 cm the fingers miss the thing). */
+const GRIP_LIFT = 0.035;
+/** A hand whose reachGrip world anchor sits too low over a scene box's top: that anchor rises by what the hit lacks. */
+function gripLift(X, g, part, id, need) {
+	const f = g.worstFrame, k = sideOf(part), box = X.out.objectsAt(X.rel(f))[id], d = X.hand(k, f);
+	const grip = d.anchor && X.keys(d.ch).some(key => / reachGrip$/.test(key.src));
+	if (!/^hand_[lr]$/.test(part) || !box || X.spec.objects?.[id] || !grip || X.spec.anchors?.[d.anchor]?.kind !== "world" || !(need > 0 && need <= GRIP_LIFT)) return null;
+	return deepest(X, f, part, box).n[1] > 0.5 ? moveHint(X, part, f, [0, need, 0], ` (over ${id}'s top)`) : null;
+}
+
 export const contactHints = {
 	COLLIDE(X, g) {
 		const [, part, id] = /^(\S+) x (.+)$/.exec(g.subject) ?? [];
 		if (/^foot_[lr]$/.test(part ?? "")) return footHint(X, g, part, id);
+		const lift = gripLift(X, g, part, id, g.worst - g.limit + MARGIN);
+		if (lift) return lift;
 		const r = boxHint(X, g, part, id, g.worst - g.limit + MARGIN);
 		if (r && /^(hand|farm)_/.test(part) && !X.spec.fix?.penetration && g.worst - g.limit <= 0.05) {
 			r.hint += "; or fix.penetration: 0.02 pushes shallow hand hits out";
@@ -184,12 +197,13 @@ export const contactHints = {
 			fix: { channel: ch, f: g.worstFrame, value: clean } };
 	},
 	BALANCE(X, g) {
-		const f = g.worstFrame, { s } = X.fr(f), P = s.P, I = X.I;
+		const f = g.worstFrame;
 		if (g.subject === "no foot on the ground") return { cause: X.cause("root", f), hint: `at f${f} lower foot_l or foot_r onto the ground, the floor or the top of an object under it (the ankle stands ${ankleY(X.sk)} m above it), or declare checks.supports for the seat the hips rest on` };
-		const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, P[I[j]]), [0, 0, 0]), 0.25);
-		const feet = ["Left", "Right"].flatMap(S => Object.values(solePoints(X.sk, s, S)));
-		const xs = feet.map(p => p[0]), zs = feet.map(p => p[2]), mg = 0.08 - 0.01;
-		const to = [clamp(com[0], Math.min(...xs) - mg, Math.max(...xs) + mg), com[1], clamp(com[2], Math.min(...zs) - mg, Math.max(...zs) + mg)];
-		return { cause: X.cause("root", f), hint: `root: move ${vec(sub(to, com))} m at f${f} (centre of mass over the feet), or step a foot under it`, fix: { channel: "root", f, delta: sub(to, com) } };
+		// the mass-weighted centre of mass toward the support polygon's nearest point, to within limit - 1 cm of it (com.js)
+		const b = balanceAt(X.out, Math.max(0, Math.min(X.out.frames.length - 1, f - (X.out.f0 ?? 0))));
+		if (b === "air" || b.margin >= 0) return null;
+		const d = -b.margin, keep = Math.min(d, Math.max(0, (g.limit ?? 0.08) - 0.01)), t = (d - keep) / d;
+		const delta = [(b.near[0] - b.com[0]) * t, 0, (b.near[1] - b.com[2]) * t];
+		return { cause: X.cause("root", f), hint: `root: move ${vec(delta)} m at f${f} (centre of mass ${offsetWords(b)}, toward the nearest edge of the support polygon), or step a foot under it`, fix: { channel: "root", f, delta } };
 	},
 };

package/src/motion3/qa/hints-motion.js

@@ -13,6 +13,7 @@ import { vec, m3 } from "./fmt.js";
 import { moveHint } from "./hints-contact.js";
 import { kneeFoldHint, kneeWhy } from "./hints-knee.js";
 import { bodyMove } from "./hints-goal.js";
+import { ballisticArc, arcFrames, arcPrescription } from "./ballistic.js";
 
 const LIMB = { Leg: ["UpLeg", "Leg", "Foot", "knee"], ForeArm: ["Arm", "ForeArm", "Hand", "elbow"] };
 const sideOf = s => (s.startsWith("Left") ? "l" : "r");
@@ -63,6 +64,33 @@ function probe(X, f, tries, measure) {
 	return { best, base, c0 };
 }
 
+/** The ballistic arc of a FLOAT group's run (its subject names f<a>-f<b>): the worst frame, the correction at any frame, the keys that follow it; { presc } past MAX_FIX; null without anchors. */
+function floatArc(X, g) {
+	const f0 = X.out.f0 ?? 0, [, a = g.first, b = g.last] = / f(\d+)-f(\d+)/.exec(g.subject)?.map(Number) ?? [];
+	const y = X.out.frames.map(fr => fr.s.P[X.I.Hips][1]), G = 9.81 / (X.out.fps ?? 24) ** 2, arc = ballisticArc(y, a - f0, b - f0, G);
+	if (!arc) { const p = arcPrescription(y, a - f0, b - f0, G); return p && { presc: { ...p, from: a - 1, to: b + 1 } }; }
+	const dyAt = f => Math.round((arc.delta[f - f0 - arc.from - 1] ?? 0) * 1e4) / 1e4, at = q => ({ f: q + f0, dy: dyAt(q + f0) });
+	return { ...at(arc.worst), from: arc.from + f0, to: arc.to + f0, dyAt, keys: arcFrames(arc).map(at) };
+}
+
+/** Root keys moved up or down by the arc: the agent's root key within 2 frames moves by the arc at its own frame, else a key is added; the anchors get their own height unless a root key sits within 2 frames. */
+function arcOps(X, userSpec, arc) {
+	const ops = Array.isArray(userSpec.keys) ? [] : [{ op: "add", path: "/keys", value: [] }], used = new Set(), r4 = v => Math.round(v * 1e4) / 1e4;
+	for (const { f, dy } of arc.keys) {
+		const i = (userSpec.keys ?? []).findIndex(k => Array.isArray(k?.set?.root) && k.set.root.length === 3 && Math.abs(k.f - f) <= 2 && k.f > arc.from && k.f < arc.to);
+		if (i >= 0 && used.has(i)) continue;
+		const r = i >= 0 ? userSpec.keys[i].set.root : X.fr(f).c.root, d = i >= 0 ? arc.dyAt(userSpec.keys[i].f) : dy;
+		if (!Array.isArray(r)) continue;
+		if (i >= 0) used.add(i);
+		const value = [r4(r[0]), r4(r[1] + d), r4(r[2])];
+		ops.push(i >= 0 ? { op: "replace", path: `/keys/${i}/set/root`, value } : { op: "add", path: "/keys/-", value: { f, set: { root: value } } });
+	}
+	// the anchors keep their height: without a root key near takeoff and landing the channel would ease into the arc early and hold its last key after
+	const near = f => (userSpec.keys ?? []).some(k => Array.isArray(k?.set?.root) && Math.abs(k.f - f) <= 2);
+	for (const f of [arc.from, arc.to]) if (!near(f) && Array.isArray(X.fr(f).c.root)) ops.push({ op: "add", path: "/keys/-", value: { f, set: { root: X.fr(f).c.root.map(r4) } } });
+	return ops;
+}
+
 const hipOrShoulder = (X, k, f, limb) => X.fr(f).s.P[X.I[`${k === "l" ? "Left" : "Right"}${LIMB[limb][0]}`]];
 
 export const motionHints = {
@@ -149,7 +177,16 @@ export const motionHints = {
 	SPEED: (X, g) => speedHint(X, g, 1),
 	POP: (X, g) => speedHint(X, g, 0.5),
 	ACC: (X, g) => speedHint(X, g, 0.5),
-	FLOAT: (X, g) => ({ cause: X.cause("root", g.worstFrame), hint: `over f${g.first}-f${g.last} lower the root or key foot_l/foot_r back onto the ground, the floor or the top of an object under the foot (the ankle stands ${ankleY(X.sk)} m above it); a jump needs the hips to rise and fall; a seat or ledge the hips rest on goes in checks.supports (a foot on an object's top needs none)` }),
+	FLOAT(X, g) {
+		const base = `over f${g.first}-f${g.last} lower the root or key foot_l/foot_r back onto the ground, the floor or the top of an object under the foot (the ankle stands ${ankleY(X.sk)} m above it); a jump needs the hips to rise and fall; a seat or ledge the hips rest on goes in checks.supports (a foot on an object's top needs none)`;
+		const arc = floatArc(X, g);
+		if (!arc) return { cause: X.cause("root", g.worstFrame), hint: base };
+		const p = arc.presc, m2 = v => (Math.round(v * 100) / 100).toFixed(2), other = p && p.fits >= 2 && p.fits !== p.frames;
+		if (p) return { cause: X.cause("root", g.worstFrame), hint: `hips held ${m2(Math.abs(p.off))} m ${p.off > 0 ? "below" : "above"} a ballistic arc over ${p.frames} frames (f${p.from}-f${p.to}): either ${p.apex > p.height ? "raise" : "lower"} the apex to ${m2(p.apex)} m above takeoff${other ? `, or ${p.fits < p.frames ? "shorten" : "lengthen"} the air run to ${p.fits} frames for this apex (${m2(p.height)} m)` : ""}; or ${base}` };
+		const { f, dy } = arc;
+		return { cause: X.cause("root", f), hint: `hips should be ${Math.round(Math.abs(dy) * 100)} cm ${dy < 0 ? "lower" : "higher"} at f${f} (ballistic arc from f${arc.from} to f${arc.to}): root ${vec([0, dy, 0])} m there${arc.keys.length > 1 ? ` (keys at ${arc.keys.map(k => `f${k.f} ${vec([0, k.dy, 0])}`).join(", ")} follow the arc)` : ""}; or ${base}`,
+			fix: { channel: "root", f, delta: [0, dy, 0], ops: userSpec => arcOps(X, userSpec, arc) } };
+	},
 	LENGTH: () => ({ cause: "compiler", hint: "a bone changed length: report the spec, this is a compiler fault" }),
 	CONTACT(X, g) {
 		const ck = (X.spec.checks?.contacts ?? []).find(c => g.subject.startsWith(`${c.name}:`)), f = g.worstFrame, i = X.rel(f);

package/src/motion3/qa/key-checks.js

@@ -8,9 +8,10 @@
 // wrist turn past its limit after the elbow swung and the forearm turned (lane K8: the whole arm
 // follows the object, compiler/arm-orient.js).
 // Measured, not judged (C16, output.observations.held): every key as drawn, so the agent sees how
-// far each one is from what the hand can hold without a probe.
+// far each one is from what the hand can hold without a probe. Both read the pose before a spring swings it
+// (object-pose.js basePoseAt): the swing rides on the keys, it is not the hand falling short.
 import { keyedEntries, curveIn, keyedPose } from "../object-keys.js";
-import { rootPoseAt, partsOf } from "../object-pose.js";
+import { basePoseAt, partsOf } from "../object-pose.js";
 import { relative } from "../carried.js";
 import { groupsOf } from "../scene.js";
 import { WRIST_LIMITS } from "../compiler/arm-orient.js";
@@ -36,7 +37,7 @@ export function keyIssues(out, L, push) {
 		const curve = curveIn(out, id), corners = cornersOf(scene, id);
 		if (!corners.length) continue;
 		for (let f = Math.max(f0, Math.ceil(curve.t[0])); f <= Math.min(f0 + out.frames.length - 1, Math.floor(curve.t[curve.t.length - 1])); f++) {
-			const want = keyedPose(curve, f), got = rootPoseAt(out, id, f);
+			const want = keyedPose(curve, f), got = basePoseAt(out, id, f);
 			const off = Math.max(...corners.map(c => dist(add(want.pos, apply(want.R, c)), add(got.pos, apply(got.R, c)))));
 			if (off > L.reach) push("REACH", `${id}: ${(off * 100).toFixed(1)} cm off its keys`, f - f0, off, L.reach);
 		}
@@ -75,7 +76,7 @@ export function heldReadings(out) {
 		// the keys as the compile holds them: a mouth key the compile leaned says so (object-keys.js faceLeaned)
 		const curve = curveIn(out, id), keys = [...(out.ctx.hold?.entry?.(id) ?? o).keys].sort((a, b) => a.f - b.f);
 		return [id, keys.map((k, i) => {
-			const got = rootPoseAt(out, id, Math.round(curve.t[i])), y = [got.R[0][1], got.R[1][1], got.R[2][1]];
+			const got = basePoseAt(out, id, Math.round(curve.t[i])), y = [got.R[0][1], got.R[1][1], got.R[2][1]];
 			const want = k.aim ? norm(k.aim) : apply(matFromQuat(curve.q[i]), [0, 1, 0]), deg = r1(angle(want, y));
 			return { f: k.f, deg, cm: r1(dist(k.pos, got.pos) * 100), ...(deg >= 1 ? { got: y.map(r2) } : {}), ...(k.aim ? { rot: curve.rots[i] } : {}), ...(k.leaned ? { lean: k.lean } : {}) };
 		})];

package/src/motion3/qa/patch.js

@@ -7,9 +7,12 @@
 //   { path: "/anchors/cupHandle/p", delta: [dx, dy, dz] }     move a spec value by delta
 //   { channel: "root", f, delta, hold: true }                  move the body that stands at f
 //   { ops: userSpec => [{ op, path, value }] }                 the operations for the agent's spec (a second hand: load.js)
+//     + candidates: [ops, ...]                                 other ways to the same end, which compile repair alone can
+//                                                              price: g.candidates (non-enumerable, never in the output)
 // Each becomes g.patch = [{ op, path, value }] against opts.userSpec (the spec as the agent sent
 // it, use[] not expanded): a user key that sets the channel within f +-2 -> replace
-// /keys/<i>/set/<ch>; a standIdle stance moved sideways -> /use/<i>/args/at; otherwise add
+// /keys/<i>/set/<ch> (a delta: with the agent's keys next to it that hold the same value, so a held
+// pose moves whole instead of sliding from one end to the other); a standIdle stance moved sideways -> /use/<i>/args/at; otherwise add
 // /keys/- with the frame's value moved. A path fix replaces the value, or adds it when only the
 // last step is missing (or the top-level /fix object). A hold fix moves what placed the body
 // at f by the delta's x and z: a standIdle args.at, a walkTo's length (firstStep with 2 steps,
@@ -50,6 +53,27 @@ function userKey(userSpec, ch, f) {
 	return best;
 }
 
+/** a and b the same channel value (a number or a vector) within 1e-6. */
+const same = (a, b) => (isNum(a) && isNum(b) ? Math.abs(a - b) <= 1e-6
+	: Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, j) => isNum(x) && isNum(b[j]) && Math.abs(x - b[j]) <= 1e-6));
+
+/**
+ * User key i and the agent's keys next to it in frame order (no other source's key of ch between) that set
+ * ch to the same value: the hold a delta moves. The order is X.keys(ch) when the context has it, else the
+ * agent's own keys by frame.
+ */
+function heldSpan(X, userSpec, ch, i) {
+	const keys = userSpec.keys, held = j => j >= 0 && same(keys[j]?.set?.[ch], keys[i].set[ch]);
+	const order = X?.keys ? X.keys(ch).map(k => Number(/^keys\[(\d+)\]$/.exec(k.src)?.[1] ?? -1))
+		: keys.map((k, j) => j).filter(j => keys[j]?.set && Object.hasOwn(keys[j].set, ch) && isNum(keys[j].f)).sort((a, b) => keys[a].f - keys[b].f);
+	const at = order.indexOf(i);
+	if (at < 0) return [i];
+	let a = at, b = at;
+	while (a > 0 && held(order[a - 1])) a -= 1;
+	while (b < order.length - 1 && held(order[b + 1])) b += 1;
+	return order.slice(a, b + 1);
+}
+
 /** A standIdle stance moved by the root's sideways delta: /use/<i>/args/at. */
 function standPatch(X, userSpec, fix, near) {
 	const m = /^use\[(\d+)\] standIdle$/.exec(near?.src ?? ""), d = fix.delta;
@@ -105,8 +129,11 @@ function channelPatch(X, userSpec, fix) {
 	const to = v => (fix.value !== undefined ? fix.value : moved(v, fix.delta));
 	const i = userKey(userSpec, ch, f);
 	if (i >= 0) {
-		const value = to(userSpec.keys[i].set[ch]);
-		return value === undefined ? null : [{ op: "replace", path: pointer(["keys", i, "set", ch]), value: round4(value) }];
+		const ops = (fix.delta !== undefined ? heldSpan(X, userSpec, ch, i) : [i]).map(j => {
+			const value = to(userSpec.keys[j].set[ch]);
+			return value === undefined ? null : { op: "replace", path: pointer(["keys", j, "set", ch]), value: round4(value) };
+		});
+		return ops.includes(null) ? null : ops;
 	}
 	if (!X?.fr) return null;
 	const { prev, next } = X.bracket(ch, f);
@@ -152,8 +179,9 @@ export function attachPatches(groups, { X, userSpec } = {}) {
 	for (const g of groups) {
 		if (!g.fix) continue;
 		try {
-			const patch = patchOf(g.fix, X, userSpec);
+			const patch = patchOf(g.fix, X, userSpec), more = patch && (g.fix.candidates ?? []).map(ops => patchOf({ ops }, X, userSpec)).filter(Boolean);
 			if (patch) g.patch = patch;
+			if (more?.length > 1) Object.defineProperty(g, "candidates", { value: more, enumerable: false, configurable: true });
 		} catch {
 			// a fix the context cannot place (no frame, no key table) gets no patch
 		}

package/src/motion3/qa/people-checks.js

@@ -7,7 +7,7 @@ import { allowance, QA_LIMITS } from "./checks.js";
 import { dist } from "../compiler/math.js";
 
 /** Two bodies whose hips are this far apart (m) cannot touch: a body is under 1 m from its hips to any skin. */
-const APART = 2.2;
+export const APART = 2.2;
 
 /** The person's capsule endpoints at timeline frame f: [part, A, B, r] with the joints read from P. */
 export function personCapsules(p, f) {

package/src/motion3/qa/spring-pivot.js

@@ -0,0 +1,23 @@
+// Measured, not judged (output.observations.spring): a carried spring object swings about its base
+// (compiler/spring.js), so a base far from the hand puts the pivot out there and every arm swing and
+// wrist turn shakes it harder (a bag carried by its far end: the drive about 1.9x). One line per carry
+// whose base sits PIVOT_FAR m or more from its prop origin (the hand socket), measured mid-carry.
+import { isCarried, propOrigin } from "../carried.js";
+import { basePoseAt, frameAt, spanOf } from "../object-pose.js";
+import { dist } from "../compiler/math.js";
+
+/** How far from the hand a spring object's base may sit before the observation, m. */
+const PIVOT_FAR = 0.15;
+
+/** observations.spring: ["SPRING_PIVOT <id>: base is 0.30 m from the hand; ..."], or null when every spring carry pivots at the hand. */
+export function springPivots(out) {
+	const { sk, spec } = out.ctx, lines = [];
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		if (!o?.spring || !isCarried(o) || !spec.props?.[o.prop]) continue;
+		const [grab, release] = spanOf(out, o), f = Math.round((grab + release) / 2), base = basePoseAt(out, id, f);
+		if (!base) continue;
+		const d = dist(base.pos, propOrigin(sk, spec, frameAt(out, f).s, o));
+		if (d >= PIVOT_FAR) lines.push(`SPRING_PIVOT ${id}: base is ${d.toFixed(2)} m from the hand; the swing pivots there, so put the base at the hand with at/along`);
+	}
+	return lines.length ? lines : null;
+}

package/src/motion3/qa/style.js

@@ -8,9 +8,10 @@
 // QA error, and so is a FLOAT: the body off the ground without falling (floatChecks). A pop is a
 // spike, not a large value: a hard but continuous acceleration (a swing's launch) is style.
 // See docs/motion-api-v3.1.md C13.
-import { add, sub, scale, len, dot, angle } from "../compiler/math.js";
+import { sub, len, dot, angle } from "../compiler/math.js";
 import { CAPSULES, segPoints, sdBox } from "./geometry.js";
 import { groundSole, groundY } from "./ground.js";
+import { balanceAt } from "./com.js";
 
 const SPEED_JOINTS = ["Hips", "Head", "LeftHand", "RightHand", "LeftFoot", "RightFoot", "LeftLeg", "RightLeg", "LeftForeArm", "RightForeArm"];
 const CORE = new Set(["Hips", "Head"]);
@@ -81,28 +82,12 @@ function supported(out, f, supports) {
 }
 
 /**
- * Per frame: null where a declared support carries the body, "air" with no foot on the ground,
- * else the balance margin in metres: how far the centre of mass (hips, spine, head) sits inside
- * the box of the feet on the ground, the floor or an object's top (ground.js; < 0: outside it).
- * While the hips travel every foot counts.
+ * Per frame: null where a declared support carries the body, else balanceAt (com.js): "air" with
+ * no foot on the ground, or { margin, ... } with margin in metres: how far the mass-weighted
+ * centre of mass sits inside the support polygon of the feet on the ground, the floor or an
+ * object's top (ground.js; < 0: outside it).
  */
-function balanceMargins(out, supports = []) {
-	const sk = out.ctx.sk, I = sk.index, F = out.frames;
-	return F.map(({ s }, f) => {
-		if (supported(out, f, supports)) return null;
-		const { P } = s;
-		const moving = f > 0 && f < F.length - 1 && Math.hypot(F[f + 1].s.P[I.Hips][0] - F[f - 1].s.P[I.Hips][0], F[f + 1].s.P[I.Hips][2] - F[f - 1].s.P[I.Hips][2]) / 2 > 0.006;
-		const feet = [];
-		for (const S of ["Left", "Right"]) {
-			const sp = groundSole(out, f, S);
-			if (moving || Math.min(sp.heel[1], sp.ball[1]) < 0.02) feet.push(sp.heel, sp.ball, sp.tip);
-		}
-		if (!feet.length) return "air";
-		const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, P[I[j]]), [0, 0, 0]), 0.25);
-		const xs = feet.map(p => p[0]), zs = feet.map(p => p[2]);
-		return Math.min(com[0] - Math.min(...xs), Math.max(...xs) - com[0], com[2] - Math.min(...zs), Math.max(...zs) - com[2]);
-	});
-}
+export const balanceFrames = (out, supports = []) => out.frames.map((_, f) => (supported(out, f, supports) ? null : balanceAt(out, f)));
 
 /** True when a hand rests on the ground at frame f: its wrist or knuckles within HAND_DOWN of the ground under them. */
 const HAND_DOWN = 0.06;
@@ -112,7 +97,7 @@ function handDown(out, f) {
 }
 
 /** Runs [a, b] (indexes of out.frames) with both soles 2 cm or more above the ground (ground.js), no hand on it and no declared support. */
-function airRuns(out, supports = []) {
+export function airRuns(out, supports = []) {
 	const n = out.frames.length, runs = [];
 	const air = out.frames.map((_, f) => !supported(out, f, supports)
 		&& ["Left", "Right"].every(S => { const sp = groundSole(out, f, S); return Math.min(sp.heel[1], sp.ball[1]) >= 0.02; }) && !handDown(out, f));
@@ -169,12 +154,10 @@ export function styleChecks(sk, out, checks, L) {
 			if (deg > L.knee) push("KNEE", `${bend[0] === "knee_l" ? "Left" : "Right"} knee bent ${deg.toFixed(0)}deg`, f, deg, L.knee);
 		}
 	});
-	if (on("balance")) balanceMargins(out, checks.supports).forEach((m, f) => {
-		if (m === "air") push("BALANCE", "no foot on the ground", f, 0, 0);
-		else if (m !== null && -m > L.balance) {
-			const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, out.frames[f].s.P[sk.index[j]]), [0, 0, 0]), 0.25);
-			push("BALANCE", `centre of mass ${com[0].toFixed(2)},${com[2].toFixed(2)} outside the feet`, f, -m, L.balance);
-		}
+	if (on("balance")) balanceFrames(out, checks.supports).forEach((b, f) => {
+		if (b === "air") push("BALANCE", "no foot on the ground", f, 0, 0);
+		// one subject whatever the direction: a lean that swings from ahead to left stays one group; the hint says how far and which way
+		else if (b && -b.margin > L.balance) push("BALANCE", "centre of mass outside the feet", f, -b.margin, L.balance);
 	});
 	return issues;
 }
@@ -192,7 +175,7 @@ export function observeMotion(sk, out, checks = {}) {
 		return [Math.round(arr[at] * k * 100) / 100, at + f0];
 	};
 	const peaks = Object.fromEntries(kinematics(sk, out).map(({ j, v, a }) => [j, { speed: peak(v, fps), accel: peak(a, fps * fps) }]).filter(([, p]) => p.speed[0] >= STILL));
-	const margins = balanceMargins(out, checks.supports), span = test => {
+	const margins = balanceFrames(out, checks.supports).map(b => (b && b !== "air" ? b.margin : b)), span = test => {
 		const fs = margins.map((m, f) => (test(m) ? f + f0 : -1)).filter(f => f >= 0);
 		return fs.length ? [fs[0], fs[fs.length - 1]] : null;
 	}, air = airRuns(out, checks.supports).slice(0, 4).map(([a, b]) => [a + f0, b + f0]);

package/src/motion3/qa/verdict.js

@@ -2,7 +2,8 @@
 // (hint-check.js) offers a patch by. Better means all of
 //   less       the summed severity (severity.js) drops
 //   goals      no more goals fail, and every goal that held still holds
-//   problems   no more issue groups than before
+//   problems   no more issue groups than before, unless a HARD group is gone and every new group is SMALL: a second
+//              hand that ends a LOAD may leave a forearm grazing the box, which the next repair round can finish
 //   trade      what got worse (a new group, or a group whose severity rose) costs at most half of what got better
 // Logs: a hint patch applied as sent made the take worse 49% of the time, and repair moved the root and broke the arms;
 // a lower sum alone let a change through that traded one failure for several new ones.
@@ -13,6 +14,9 @@ const sevOf = qa => groupsOf(qa).reduce((sum, g) => sum + (g.severity ?? 0), 0);
 const heldOf = qa => (qa?.goals ?? []).filter(g => g.ok).map(g => g.name);
 const failedOf = qa => (qa?.goals ?? []).filter(g => !g.ok).length;
 const TRADE = 0.5;
+// failures the take cannot keep (a hand that cannot hold its load), and the severity (severity.js) a new group may have
+// for a change that ends one to pass with more groups: 5 is a few frames just past a limit, never a held failure
+const HARD = new Set(["LOAD"]), SMALL = 5;
 const r2 = x => Math.round(x * 100) / 100;
 
 /** The group severities by key (severity.js groupKey). */
@@ -35,9 +39,10 @@ export function compareQa(next, base) {
 	worse.sort((x, y) => y.severity[1] - y.severity[0] - (x.severity[1] - x.severity[0]));
 	const sev = [r2(sevOf(base)), r2(sevOf(next))], problems = [groupsOf(base).length, groupsOf(next).length];
 	const lost = heldOf(base).filter(n => !heldOf(next).includes(n));
+	const ends = groupsOf(base).some(g => HARD.has(g.kind) && !b.has(groupKey(g))) && [...b].every(([k, v]) => a.has(k) || v <= SMALL);
 	const why = !(sevOf(next) < sevOf(base) - 1e-9) ? `summed severity ${sev[0]} -> ${sev[1]}`
 		: failedOf(next) > failedOf(base) || lost.length ? `goal ${lost.length ? `"${lost[0]}" no longer holds` : "failures rose"}`
-			: problems[1] > problems[0] ? `problems ${problems[0]} -> ${problems[1]}`
+			: problems[1] > problems[0] && !ends ? `problems ${problems[0]} -> ${problems[1]}`
 				: rise > TRADE * drop + 1e-9 ? `${worse[0]?.key} got worse (${worse[0]?.severity.join(" -> ")})` : "";
 	return { better: !why, why, sev, problems, worse: worse.slice(0, 3) };
 }