cozyclay 3.1.5 → 3.2.0

package/src/motion3/physics-trail.js

@@ -0,0 +1,45 @@
+// The physics overlay's motion trail of spring objects (spec.objects[id].spring, compiler/spring.js): the path of
+// each one's tip over the last TRAIL_FRAMES frames, read from the take's own track (what playback draws). The tip
+// is the corner of the record's boxes (its parts, for a group) farthest from its anchor, the pose's origin the
+// spring swings it about (compiler/spring.js swungPose). An object without a spring has no trail.
+// Pure and cached per view (physics-view.js).
+import { add, apply, sub, len, T } from "./compiler/math.js";
+import { trackPose } from "./physics-frames.js";
+import { groupsOf } from "./scene.js";
+import { corners } from "./free-motion.js";
+import { partsOf } from "./object-pose.js";
+
+/** How many frames back a trail reaches (the playhead's frame included). */
+export const TRAIL_FRAMES = 24;
+const tips = new WeakMap();
+
+/** [{ id, local }]: each spring object the take tracks, with its tip in its own frame. */
+function springTips(view) {
+	if (tips.has(view)) return tips.get(view);
+	const { scene, spec } = view.out.ctx, groups = groupsOf(scene), list = [];
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		const rest = scene.objects[id] ?? groups[id];
+		if (!o?.spring || !rest || !view.take.objects?.[id]?.pos) continue;
+		let local = null;
+		for (const c of partsOf(scene, id).flatMap(part => corners(scene.objects[part]))) {
+			const q = apply(T(rest.R), sub(c, rest.pos));
+			if (!local || len(q) > len(local) + 1e-9) local = q;
+		}
+		if (local) list.push({ id, local });
+	}
+	tips.set(view, list);
+	return list;
+}
+
+/** [{ id, points: [[x, y, z], ...] }]: each spring object's tip from `length` - 1 frames before `frame` up to it, oldest first. */
+export function tipTrails(view, frame, length = TRAIL_FRAMES) {
+	const last = Math.max(0, Math.min(view.out.frames.length - 1, Math.round(frame) || 0));
+	return springTips(view).map(({ id, local }) => {
+		const points = [];
+		for (let f = Math.max(0, last - length + 1); f <= last; f++) {
+			const pose = trackPose(view.take.objects[id], f);
+			if (pose) points.push(add(pose.pos, apply(pose.R, local)));
+		}
+		return { id, points };
+	});
+}

package/src/motion3/physics-view.js

@@ -0,0 +1,79 @@
+// What the physics overlay draws (src/physics-overlay.js), frame by frame, measured by QA's own functions on the
+// installed take (physics-frames.js takeOut), so the overlay's colours are QA's verdicts:
+//   comAt      the mass-weighted centre of mass (qa/com.js) and its state: "outside" when it sits farther outside
+//              the support polygon than the balance limit (checks.limits.balance, else QA_LIMITS.balance: what
+//              BALANCE reports), "inside" otherwise, "air" with no foot on the ground, "supported" where a declared
+//              support carries the body (qa/style.js balanceFrames)
+//   supportAt  the convex hull of the sole points on the ground (qa/com.js balanceAt feet), each corner on
+//              the ground QA measured that sole point from (balanceAt ground)
+//   airArcs    per air run of 4 frames or more (qa/style.js airRuns, the runs floatChecks judges): the hips path
+//              from the frame before takeoff to the frame after landing, and the gravity parabola through the same
+//              two anchors (qa/ballistic.js); float marks the runs QA calls FLOAT
+// Positions are world metres where the take was compiled (take.placement). Pure and cached per take.
+import { takeOut } from "./physics-frames.js";
+import { balanceFrames, airRuns, floatChecks } from "./qa/style.js";
+import { balanceAt, bodyCentre, convexHull } from "./qa/com.js";
+import { groundY } from "./qa/ground.js";
+import { ballisticArc } from "./qa/ballistic.js";
+import { QA_LIMITS } from "./qa/checks.js";
+
+/** floatChecks judges runs of this many frames or more. */
+const MIN_RUN = 4;
+const views = new WeakMap();
+
+/** The overlay's view of take v3 `take` over the authored records `objects`, or null when it has none. */
+export function physicsView(take, objects = []) {
+	const out = takeOut(take, objects);
+	if (!out) return null;
+	if (!views.has(out)) {
+		const checks = out.ctx.spec.checks ?? {};
+		views.set(out, { take, out, checks, limit: checks.limits?.balance ?? QA_LIMITS.balance, balance: null, arcs: null });
+	}
+	return views.get(out);
+}
+
+/** The take frame shown at timeline frame `frame` (clamped to the take). */
+const viewFrame = (view, frame) => Math.max(0, Math.min(view.out.frames.length - 1, Math.round(frame) || 0));
+
+const balanceOf = view => (view.balance ??= balanceFrames(view.out, view.checks.supports));
+
+/** { frame, p: [x, y, z], ground: the ground height under p, state, margin (m, null off the ground) } at `frame`. */
+export function comAt(view, frame) {
+	const f = viewFrame(view, frame), b = balanceOf(view)[f], measured = b && b !== "air";
+	const p = measured ? b.com : bodyCentre(view.out.ctx.sk, view.out.frames[f].s);
+	const state = b === null ? "supported" : b === "air" ? "air" : -b.margin > view.limit ? "outside" : "inside";
+	return { frame: f, p, ground: groundY(view.out, f, p), state, margin: measured ? b.margin : null };
+}
+
+/**
+ * The support polygon at `frame`: its corners [x, y, z] counter-clockwise in (x, z), y the ground QA measured that
+ * sole point from (balanceAt ground); [] with no foot down. convexHull keeps the feet's own points, so each corner
+ * finds its ground by identity.
+ */
+export function supportAt(view, frame) {
+	const f = viewFrame(view, frame), b = balanceOf(view)[f] ?? balanceAt(view.out, f);
+	if (b === "air") return [];
+	return convexHull(b.feet).map(p => [p[0], b.ground[b.feet.indexOf(p)], p[1]]);
+}
+
+/**
+ * [{ a, b, from, to, float, path, fit, worst }]: per air run [a, b], the hips path from anchor `from` (a - 1) to `to`
+ * (b + 1) and the parabola `fit` over the same frames (the hips' x and z, the arc's height); worst = the largest
+ * fit - actual height (m). A run that touches either end of the take has no anchor and no arc.
+ */
+export function airArcs(view) {
+	if (view.arcs) return view.arcs;
+	const { out, checks } = view, I = out.ctx.sk.index, hips = out.frames.map(fr => fr.s.P[I.Hips]), y = hips.map(p => p[1]);
+	const floats = new Set(floatChecks(out, checks).map(issue => issue.frame)), g = 9.81 / out.fps ** 2;
+	view.arcs = [];
+	for (const [a, b] of airRuns(out, checks.supports)) {
+		const arc = b - a + 1 >= MIN_RUN ? ballisticArc(y, a, b, g, Infinity) : null;
+		if (!arc) continue;
+		const path = hips.slice(arc.from, arc.to + 1).map(p => [...p]);
+		const fit = path.map((p, i) => (i === 0 || i === path.length - 1 ? [...p] : [p[0], p[1] + arc.delta[i - 1], p[2]]));
+		let float = true;
+		for (let f = a; f <= b; f++) float &&= floats.has(f);
+		view.arcs.push({ a, b, from: arc.from, to: arc.to, float, path, fit, worst: arc.delta[arc.worst - a] });
+	}
+	return view.arcs;
+}

package/src/motion3/pipeline.js

@@ -7,7 +7,8 @@
 // heldReadings; each hand and foot against the nearest object, qa/near.js observeNear; each holding
 // wrist's bend, qa/wrist-obs.js observeWrist; how mechanical it reads against the agent's own
 // keys, qa/motion-life.js observeLife; a skill
-// paced to fit a short span: observations.paced; a skill whose release or
+// paced to fit a short span: observations.paced; a carried spring whose base is far from the hand:
+// qa/spring-pivot.js observations.spring; a skill whose release or
 // settle the last frame cut: observations.cut; what the spec asked against what it got, per skill,
 // contact and goal: qa/asked.js observeAsked), and the timeline and the
 // requested probes read the result.
@@ -33,6 +34,7 @@ import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
 import { observeLoad, LOAD_UNITS } from "./load.js";
 import { observeLife, LIFE_UNITS } from "./qa/motion-life.js";
 import { observeGait, GAIT_UNITS } from "./qa/gait-observe.js";
+import { springPivots } from "./qa/spring-pivot.js";
 import { planWalks, applyWalkPlans } from "./walk-plan.js";
 import { relaxSpec } from "./lenient.js";
 import { observeAsked } from "./qa/asked.js";
@@ -140,6 +142,8 @@ function compilePrepared(prepared, { sk, scene }, opts, notes, refusals) {
 	const placed = used.filter(u => u.placed).map(u => `${u.skill} f${u.f0}: ${u.placed.why}: at [${u.placed.at.join(", ")}], heading ${u.placed.heading}`);
 	if (placed.length) observations.placed = placed;
 	if (plans.length) observations.planned = plans.map(p => p.note);
+	const pivots = springPivots(out);
+	if (pivots) observations.spring = pivots;
 	const got = observeAsked(out, { used, use: resolved?.use, checks: measured.checks, goals: measured.goals, results: qa.goals });
 	if (got) observations.asked = got;
 	const timeline = timelineOf(out, { used, spec: expanded }), probes = asked && runProbes(out, asked, { spec: expanded, sk, scene, notes });

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";
@@ -184,12 +185,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

@@ -9,7 +9,8 @@
 //   { ops: userSpec => [{ op, path, value }] }                 the operations for the agent's spec (a second hand: load.js)
 // 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 +51,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 +127,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);

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;
+}