cozyclay 3.0.1 → 3.0.3

package/src/motion3/skills/reach-human.js

@@ -0,0 +1,139 @@
+// How a person's reach to grasp unfolds in time (reachGrip's keys), from the prehension literature:
+//   transport  the wrist's speed is a single bell whose peak comes early, at about a third of the movement, and the
+//              longer deceleration (about two thirds) is the slow approach onto the object (time to peak velocity 33 %
+//              of movement time: Paulignan et al., Exp Brain Res 1991, doi:10.1007/BF00231858). A minimum-jerk bell
+//              (Flash & Hogan 1985) on time warped by t^WARP puts the peak at 0.5^(1/WARP) of the reach.
+//   grasp      the hand stays open wider than the object through the transport and closes onto it in the slow
+//              approach: the maximum grip aperture comes at about two thirds to three quarters of the movement (Jeannerod,
+//              J Mot Behav 1984; Hu et al., Exp Brain Res 2005), and it scales with the object's size (Marteniuk et al.,
+//              Hum Mov Sci 1990), a couple of centimetres wider than the object (MARGIN). These rigs' relaxed hands are
+//              already open (thumb tip to index tip: Y Bot 11.5 cm, X Bot 9.7 cm) and there is no wider preset: a thing
+//              that fits that opening with the margin (a can, a cup) is reached with the hand held open to CLOSE of the
+//              reach, then closed on it; a wider one closes along the reach as before, or the open fingers would sweep
+//              into it on the way (a 10 cm box: 6 cm deep). So does a thing that sits more than OVER m in from the near
+//              edge of what it stands on: the open fingertips hang below the hand and dragged across the table top on the
+//              way (a cup 12 cm in, bench S8). CLOSE is 0.4, earlier than a person's: the hand comes straight in, and the
+//              open fingertips (about 8 cm past the finger middles) went into a cup wrapped from the side when they
+//              stayed open later (1.5 cm at 0.7); a hand that plans an arc around the thing is the next step.
+//   gaze       the eyes go to the grasp point before the hand gets there and stay on it until the hand has it
+//              (Johansson et al., J Neurosci 2001;21:6917). The rigs have no eyes: the head turns HEAD_SHARE of the
+//              way, done by GAZE of the reach, held through the hold, back by the end of the release.
+import { add, apply, len, sub } from "../compiler/math.js";
+import { restState } from "../compiler/skeleton.js";
+import { fingers } from "../compiler/limbs.js";
+import { sdBox } from "../qa/geometry.js";
+
+const WARP = 0.65, ARM_WARP = 0.75, HEAD_SHARE = 0.75, MARGIN = 0.025, KNEE = 0.1, OVER = 0.08, BELOW = 0.12;
+export const CLOSE = 0.4, GAZE = 0.3;
+const TRANSPORT = [0.15, 0.3, 0.45, 0.6, 0.7, 0.8, 0.9];
+const minJerk = t => t * t * t * (10 - 15 * t + 6 * t * t);
+/** The share of the way the hand has come at fraction t of the reach. */
+// two phases: the fast transport covers NEAR of the way by SLOW of the time, the low-velocity approach the rest while the
+// fingers close (about half the movement time is that slow approach after peak deceleration, Paulignan et al. 1991)
+const NEAR = 0.9, SLOW = 0.7;
+const transport = (t, warp) => {
+	const u = Math.min(1, Math.max(0, t));
+	return u < SLOW ? NEAR * minJerk(Math.pow(u / SLOW, warp)) : NEAR + (1 - NEAR) * minJerk((u - SLOW) / (1 - SLOW));
+};
+/**
+ * Inner keys of the transport for a reach of n frames: [frame from f0, the target's share, the arm's IK share]. The arm's
+ * IK weight follows a milder bell (ARM_WARP): the hand is the blend of the two, and the target's bell alone on an arm
+ * blending in at its plain ease peaked at mid-reach, while both at WARP pushed a cup reach past the QA's one-frame pop.
+ */
+export const transportKeys = n => [...new Map(TRANSPORT.map(t => Math.round(t * n)).filter(f => f > 0 && f < n).map(f => [f, [transport(f / n, WARP), transport(f / n, ARM_WARP)]])).entries()].map(([f, [t, a]]) => [f, t, a]);
+
+const DEG = 180 / Math.PI, clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/**
+ * True when the reach to anchor a takes the early-peaked transport: a thing at rest (a world point or a scene object's;
+ * a reach to a body, a bone or a prop chases a moving point) above the knees (KNEE m over the rest knee). A person
+ * reaching lower bends or crouches, which these keys do not plan: the arm alone, sped up early, swept the thigh and
+ * shin on the way to a vending tray (QA 5 -> 7), so a low reach keeps the plain ease.
+ */
+export function earlyTransport(ctx, a) {
+	const p = restPoint(ctx, a), I = ctx.sk.index;
+	return !!p && p[1] >= ctx.sk.restWorldPos[I.LeftLeg][1] + KNEE;
+}
+
+/** The world point an anchor rests at before the grab (world, or a scene object's point), or null for one that moves with a body. */
+function restPoint(ctx, a) {
+	if (a?.kind === "world" && Array.isArray(a.p)) return a.p.map(Number); // a copy, as in bodyOf
+	const o = a?.kind === "object" ? ctx.scene?.objects?.[a.object] : null;
+	if (!o || [a.object, ...(o.ancestors ?? [])].some(id => movesBy(ctx, id))) return null;
+	return add(o.pos, apply(o.R, a.local ?? [0, o.half?.[1] ?? 0, 0]));
+}
+
+/**
+ * True when spec.objects moves record `id` before the reach is done (ctx.until): a follow or a hinge, or keys or a fall
+ * from before that frame (a carry whose keys start at a grab after the hand arrives rests until then).
+ */
+function movesBy(ctx, id) {
+	const o = ctx.objects?.[id];
+	if (!o || typeof o !== "object") return false;
+	if (o.follow !== undefined || o.hinge !== undefined) return true;
+	const from = Math.min(...(o.keys ?? []).map(k => k.f).filter(Number.isFinite), o.fall?.at ?? Infinity);
+	return from < (ctx.until ?? Infinity);
+}
+
+const opened = new WeakMap();
+/** The rig's relaxed hand opening, thumb tip to index tip (m). */
+function openHand(sk) {
+	if (!opened.has(sk)) {
+		const s = restState(sk), I = sk.index;
+		fingers(sk, s, "Right", {});
+		opened.set(sk, len(sub(s.P[I.RightHandThumb4], s.P[I.RightHandIndex4])));
+	}
+	return opened.get(sk);
+}
+
+/** The scene body anchor a reaches for (its object, or the body its world point lies in), or null. */
+function bodyOf(ctx, a) {
+	const objects = ctx.scene?.objects ?? {};
+	if (a?.kind === "object") return objects[a.object]?.half ? objects[a.object] : null;
+	if (a?.kind !== "world" || !Array.isArray(a.p)) return null;
+	// a copy: the spec's own (frozen) array passed into the shared vector math deoptimised it for the whole compile (2x)
+	const p = a.p.map(Number);
+	return Object.values(objects).filter(o => o.half && sdBox(p, o) <= 0.01).sort((x, y) => sdBox(p, x) - sdBox(p, y))[0] ?? null;
+}
+
+/** True when, OVER m short of point p toward the character (root r), the hand is still above a surface within BELOW m under p. */
+function overSupport(ctx, p, r, skip) {
+	const dx = r[0] - p[0], dz = r[2] - p[2], d = Math.hypot(dx, dz);
+	if (d < 1e-6) return false;
+	const q = [p[0] + (dx / d) * OVER, p[1], p[2] + (dz / d) * OVER];
+	return Object.entries(ctx.scene?.objects ?? {}).some(([id, o]) => {
+		if (!o.half || skip.has(id) || skip.has(o.parent)) return false;
+		const top = sub(q, [0, BELOW, 0]);
+		return sdBox(q, o) > 0 && sdBox(top, o) <= 0;
+	});
+}
+
+/**
+ * True when the hand stays open on the way to the thing anchor a reaches for, from the pose at f0 (state): it fits the
+ * rig's open hand with MARGIN, and the hand's last OVER m to it are not over the surface it rests on.
+ */
+export function holdsOpen(ctx, a, state) {
+	const o = bodyOf(ctx, a), p = restPoint(ctx, a) ?? (o && add(o.pos, apply(o.R, [0, o.half[1], 0])));
+	if (!o || !p || 2 * Math.min(...o.half) + MARGIN > openHand(ctx.sk)) return false;
+	const skip = new Set(Object.entries(ctx.scene.objects).filter(([, x]) => x === o).map(([id]) => id));
+	return !(Array.isArray(state.root) && overSupport(ctx, p, state.root, skip));
+}
+
+/**
+ * The head's yaw and pitch (deg, the head's own channels) that turn the gaze HEAD_SHARE of the way onto anchor a from the
+ * pose at f0 (state), or null when the anchor moves with a body or the pose has no root.
+ */
+export function gazeAt(ctx, a, state) {
+	const p = restPoint(ctx, a), r = state.root;
+	if (!p || !Array.isArray(r)) return null;
+	const P = ctx.sk.restWorldPos, I = ctx.sk.index, eye = [r[0], r[1] + P[I.Head][1] - P[I.Hips][1], r[2]];
+	const d = [p[0] - eye[0], p[1] - eye[1], p[2] - eye[2]], flat = Math.hypot(d[0], d[2]);
+	if (flat < 0.05) return null;
+	let yaw = Math.atan2(d[0], d[2]) * DEG - (state.yaw ?? 0) - (state.spine_yaw ?? 0);
+	while (yaw > 180) yaw -= 360;
+	while (yaw < -180) yaw += 360;
+	const down = Math.atan2(-d[1], flat) * DEG - (state.pitch ?? 0) - (state.spine_pitch ?? 0);
+	return { head_yaw: clamp(HEAD_SHARE * yaw, -60, 60), head_pitch: clamp(HEAD_SHARE * down, -30, 50) };
+}
+
+/** True when keys before this skill already move the head within [a, b]: a keyed look wins. */
+export const headKeyed = (keys, a, b) => keys.some(k => k.f >= a && k.f <= b && (k.set?.head_yaw !== undefined || k.set?.head_pitch !== undefined));

package/src/motion3/skills/stance.js

@@ -0,0 +1,92 @@
+// Where a standing body stands (standIdle): clear of the scene's bodies, and within reach of what it reaches for.
+// Session 7f15b4ae: every cup and ball attempt stood with a foot in the table (COLLIDE foot_r x cube over the whole
+// take) and the arm at full reach, while QA's hint already said how far to move the body; the agent kept guessing
+// `at` by hand. Two rules:
+//   clear   a stance whose legs, feet or hips are inside a body (a table, a box on the floor) slides out of it, the
+//           least distance that clears it by MARGIN: straight back first, then sideways, then the diagonals
+//   reach   standIdle with no `at` (and no root keyed) before a reachGrip in the same spec keeps its heading and steps
+//           up to the anchor: the reaching shoulder in line with it, as near as COMFORT of the arm's length allows,
+//           then back out of whatever is in the way (it stands at a table's edge)
+// The body is the rest pose's legs, feet and hips as capsules (qa/geometry.js radii); a body whose top is under
+// SUPPORT m (a floor, a mat, a low step) is stood on, not stood clear of.
+import { add, sub, len, apply, ry } from "../compiler/math.js";
+import { sdBox } from "../qa/geometry.js";
+import { partsOf } from "../object-pose.js";
+
+const MARGIN = 0.01, SUPPORT = 0.12, COMFORT = 0.8, SLIDE = 0.6, STEP = 0.01, NEAREST = 0.15, HANG = 0.62;
+// [from, to, radius] of the standing body, as in qa/geometry.js CAPSULES (the foot: ankle to the toe tip)
+const PARTS = ["Left", "Right"].flatMap(S => [[`${S}UpLeg`, `${S}Leg`, 0.07], [`${S}Leg`, `${S}Foot`, 0.05], [`${S}Foot`, `${S}ToeBase`, 0.045], [`${S}ToeBase`, `${S}Toe_End`, 0.04]])
+	.concat([["LeftUpLeg", "RightUpLeg", 0.095], ["Hips", "Spine2", 0.12]]);
+const DIRS = [[0, -1], [1, 0], [-1, 0], [Math.SQRT1_2, -Math.SQRT1_2], [-Math.SQRT1_2, -Math.SQRT1_2]];
+
+/** The standing body's sample points [p, r] at ground point c = [x, z] facing heading h (deg): legs, feet, hips and the arms hanging at the sides (standIdle's FK arms down). */
+function bodyPoints(sk, c, h) {
+	const I = sk.index, P = sk.restWorldPos, hip = P[I.Hips], R = ry(h), at = p => add([c[0], 0, c[1]], apply(R, [p[0] - hip[0], p[1], p[2] - hip[2]]));
+	const seg = (A, B, r) => [0, 0.25, 0.5, 0.75, 1].map(t => [add(A, sub(B, A).map(v => v * t)), r]);
+	const arms = ["Left", "Right"].flatMap(S => { const sh = P[I[`${S}Arm`]], side = Math.sign(sh[0] - hip[0]) * 0.04; return seg(at(sh), at([sh[0] + side, sh[1] - HANG, sh[2]]), 0.045); });
+	return PARTS.filter(([a, b]) => I[a] !== undefined && I[b] !== undefined).flatMap(([a, b, r]) => seg(at(P[I[a]]), at(P[I[b]]), r)).concat(arms);
+}
+
+/** The bodies a stance must stay clear of: every scene body whose top is above SUPPORT m. */
+const obstacles = scene => Object.values(scene?.objects ?? {}).filter(o => o.half && o.pos && o.R && o.pos[1] + 2 * o.half[1] * o.R[1][1] > SUPPORT);
+
+/** How far the body at c, h is clear of the obstacles (m; negative: inside one by that much, past MARGIN). */
+function clearance(sk, boxes, c, h) {
+	let worst = Infinity;
+	for (const [p, r] of bodyPoints(sk, c, h)) for (const b of boxes) worst = Math.min(worst, sdBox(p, b) - r - MARGIN);
+	return worst;
+}
+
+/** A stance at c ([x, z]) facing h moved the least distance out of the scene's bodies: { at, moved } or null when it is clear. */
+export function clearStance(sk, scene, c, h) {
+	const boxes = obstacles(scene);
+	if (!boxes.length || clearance(sk, boxes, c, h) >= 0) return null;
+	const R = ry(h);
+	for (let d = STEP; d <= SLIDE + 1e-9; d += STEP) {
+		for (const [x, z] of DIRS) {
+			const v = apply(R, [x * d, 0, z * d]), at = [c[0] + v[0], c[1] + v[2]];
+			if (clearance(sk, boxes, at, h) >= 0) return { at: at.map(n => +n.toFixed(4)), moved: +d.toFixed(2) };
+		}
+	}
+	return null;
+}
+
+/**
+ * The world point an anchor definition names on the still scene, as anchors.js resolves it: world p; an object's (or a
+ * group's) `local` point, its base pivot without one; with `grasp` and no `local`, the centre of its parts (where a
+ * thin part's socket sits). Null for any other kind.
+ */
+function anchorPoint(scene, a) {
+	if (a?.kind === "world" && Array.isArray(a.p)) return a.p;
+	if (a?.kind !== "object" || !scene) return null;
+	const o = scene.objects?.[a.object] ?? scene.groups?.[a.object];
+	if (!o) return null;
+	if (!a.grasp || a.local) return add(o.pos, apply(o.R, a.local ?? [0, 0, 0]));
+	const parts = partsOf(scene, a.object).map(id => scene.objects[id]).filter(p => p?.half);
+	const centres = parts.map(p => add(p.pos, apply(p.R, [0, p.half[1], 0])));
+	return centres.reduce((m, p) => add(m, p.map(v => v / centres.length)), [0, 0, 0]);
+}
+
+/**
+ * The stance for a standIdle with no `at`: the first reachGrip after it in `use` (index i) and its anchor. The body
+ * keeps its facing (args.heading, else the keyed yaw, else 0: the agent turns it by heading) and steps up to the
+ * anchor: the reaching shoulder lined up with it, COMFORT of the arm's length from it (at least NEAREST m ahead), then
+ * straight back out of any body in the way (a table: the body stands at its edge). { at, heading, anchor, moved } or
+ * null when no reachGrip follows or its anchor has no still point.
+ */
+export function reachStance(ctx) {
+	const { sk, scene, use = [], index = -1 } = ctx, next = use.slice(index + 1).find(u => u?.skill === "reachGrip");
+	const a = next && (next.args?.define ?? ctx.anchors?.[next.args?.anchor]), T = anchorPoint(scene, a);
+	if (!T) return null;
+	const I = sk.index, P = sk.restWorldPos, S = next.args.side === "l" ? "Left" : "Right", hip = P[I.Hips], sh = P[I[`${S}Arm`]];
+	const arm = len(sub(P[I[`${S}ForeArm`]], sh)) + len(sub(P[I[`${S}Hand`]], P[I[`${S}ForeArm`]])) + len(sub(P[I[`${S}HandMiddle2`]], P[I[`${S}Hand`]]));
+	const dy = sh[1] - T[1], ahead = Math.max(NEAREST, Math.sqrt(Math.max(0, (COMFORT * arm) ** 2 - dy * dy)));
+	const h = ctx.args.heading ?? ctx.state?.yaw ?? 0, R = ry(h), boxes = obstacles(scene);
+	const off = apply(R, [sh[0] - hip[0], 0, sh[2] - hip[2] + ahead]), c0 = [T[0] - off[0], T[2] - off[2]];
+	let moved = 0, c = c0;
+	for (; moved <= SLIDE + 1e-9 && clearance(sk, boxes, c, h) < 0; moved += STEP) {
+		const back = apply(R, [0, 0, -(moved + STEP)]);
+		c = [c0[0] + back[0], c0[1] + back[2]];
+	}
+	return { at: c.map(n => +n.toFixed(4)), heading: h, anchor: next.args.anchor, moved: +moved.toFixed(2) };
+}

package/src/motion3/sockets.js

@@ -0,0 +1,121 @@
+// Grasp sockets (lane socket): where and how a hand takes hold of an object, so the agent names the part and the
+// grasp and the compiler turns the hand. The grasp is the object's (sessions 02263581, 38322b5d: the agent computed
+// the wrist by hand and held a barbell 90 deg off, the bar through the palm; a rifle's second hand was measured off
+// the first). A socket is, in its record's own axes (metres from the base pivot, as an object anchor's `local`):
+//   at     the point the fingers close on
+//   axis   the line that runs across the palm, the knuckle line along it (a bar, a handle, a grip); none: any
+//   from   the side the hand comes from: the palm faces against it; none: the roll the arm holds most easily
+//          (compiler/socket-grip.js), or on a body with no axis the face nearest the point
+//   thumb  the end of the axis the thumb takes; none: the end-state-comfort end (socketPalm)
+// A record stores named sockets in `grasp` (src/object-grasp.js); every thin body (two half sizes under THIN m: a
+// bar, a can, a handle) is one too, named by its id, through its centre along its long axis. An object anchor with
+// `grasp` (power, pinch, hook, palm) takes the hand by a socket of its object: `socket` names it, else the one
+// nearest the anchor's `local` point or, without one, nearest the shoulder of the hand, picked once per compile.
+// A disc (a cylinder whose height is under THIN m and whose two sides are wider: a steering wheel) is a rim socket
+// instead: `rim` its radius, `normal` its axis; the hand takes the rim where it is nearest the anchor's `local` point
+// or the hand's shoulder, the knuckle line along the rim (session 2ad2760a: the wheel was held by points in the
+// driver's frame, 15 cm off the rim, and they did not follow the truck). anchorSocket fixes that point once per hand.
+import { add, sub, scale, norm, cross, dot, len, apply, ry, T } from "./compiler/math.js";
+import { partsOf } from "./object-pose.js";
+
+const THIN = 0.045, AXES = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const flat = (v, n) => sub(v, scale(n, dot(v, n)));
+
+/** The long axis index of a thin body's half sizes, else -1. */
+function thinAxis(half) {
+	if (!half) return -1;
+	const long = [0, 1, 2].reduce((a, i) => (half[i] > half[a] ? i : a), 0);
+	return [0, 1, 2].filter(i => i !== long).every(i => half[i] < THIN) ? long : -1;
+}
+
+/** A cylinder flat along its axis (its height under THIN m) and round across it, both sides over THIN m. */
+const isDisc = (renderer, half) => renderer === "cylinder" && !!half && half[1] < THIN && Math.min(half[0], half[2]) >= THIN && Math.abs(half[0] - half[2]) < 0.1 * half[0];
+
+/** The record's stored sockets: a body's in scene.objects, a group's (an Empty) in scene.others. */
+const stored = (scene, id) => scene?.objects?.[id]?.grasp ?? scene?.others?.[id]?.grasp ?? null;
+
+/**
+ * Every socket of body or group `id`: [{ name, owner, at, axis?, from?, thumb? }], each in its owner's axes. The record's
+ * own sockets by name; a part's as "<part>.<name>"; a thin part's derived one by the part id.
+ */
+export function socketsOf(scene, id) {
+	const out = [], own = (owner, prefix) => Object.entries(stored(scene, owner) ?? {}).forEach(([name, s]) => out.push({ ...s, name: prefix + name, owner }));
+	own(id, "");
+	for (const part of partsOf(scene, id)) {
+		if (part !== id) own(part, `${part}.`);
+		const { half, renderer } = scene.objects[part], long = thinAxis(half);
+		// a thin body's radius: the thinner of the two half sizes across the axis (how far the palm sits off the axis)
+		if (long >= 0) out.push({ name: part, owner: part, at: [0, half[1], 0], axis: AXES[long], radius: Math.min(...half.filter((_, i) => i !== long)) });
+		else if (isDisc(renderer, half)) out.push({ name: part, owner: part, at: [0, half[1], 0], rim: half[0], normal: AXES[1] });
+	}
+	return out;
+}
+
+/** The socket of `id` named `name`, or undefined. */
+export const socketNamed = (scene, id, name) => socketsOf(scene, id).find(s => s.name === name);
+
+/** A socket in world space on its owner's pose { pos, R }: { p, axis?, from?, thumb? }. */
+export function socketWorld(socket, pose) {
+	const dir = v => (v ? norm(apply(pose.R, v)) : undefined);
+	return { p: add(pose.pos, apply(pose.R, socket.at ?? [0, 0, 0])), axis: dir(socket.axis), from: dir(socket.from), thumb: dir(socket.thumb), radius: socket.radius,
+		...(socket.rim ? { rim: socket.rim, normal: dir(socket.normal) } : {}) };
+}
+
+/** The point of world rim socket w nearest world point q, and the rim's direction there: { p, axis }. */
+export function rimPoint(w, q) {
+	const v = flat(sub(q, w.p), w.normal), r = len(v) > 1e-6 ? norm(v) : norm(flat(Math.abs(w.normal[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], w.normal));
+	return { p: add(w.p, scale(r, w.rim)), axis: norm(cross(w.normal, r)) };
+}
+
+/** The outward normal of the face of the box (of boxes [{ pos, R, half }], base pivots) nearest world point p, or undefined. */
+export function faceFrom(boxes, p) {
+	let best;
+	for (const b of boxes) {
+		const q = apply(T(b.R), sub(p, add(b.pos, apply(b.R, [0, b.half[1], 0])))), out = [0, 1, 2].map(i => Math.abs(q[i]) - b.half[i]);
+		const i = [0, 1, 2].reduce((m, j) => (out[j] > out[m] ? j : m), 0), gap = Math.max(...out);
+		if (!best || gap < best.gap) best = { gap, n: scale([b.R[0][i], b.R[1][i], b.R[2][i]], q[i] < 0 ? -1 : 1) };
+	}
+	return best?.n;
+}
+
+/** How far world point q is from a world socket: from its rim, else its axis line through p, else from p. */
+export function socketDistance(w, q) {
+	const v = sub(q, w.p);
+	if (w.rim) return Math.hypot(dot(v, w.normal), len(flat(v, w.normal)) - w.rim);
+	return len(w.axis ? flat(v, w.axis) : v);
+}
+
+/**
+ * The palm frame (columns d, l, n of compiler/limbs.js palmAxes: d to the middle finger, l to the thumb side, n = d x
+ * l; the palm is -n on the right hand, +n on the left) a grasp of `type` takes on world socket w, the forearm along fwd,
+ * the body turned yawDeg. Along an axis (not a flat palm): with `from` the palm faces against it and the knuckle line
+ * runs along the axis; without, the fingers stay on the forearm's line across the axis (a power grip turns the forearm,
+ * not the wrist) and the palm closes on it. The thumb takes `thumb`'s end, else the end-state-comfort end (people take
+ * the grip that ends comfortable, Rosenbaum): up when the forearm is level, toward the midline when it points down or
+ * up. Without an axis the palm faces against `from` (anchorSocket gives a box face's), the fingers on the forearm's line.
+ */
+export function socketPalm(side, w, type, fwd, yawDeg = 0) {
+	const right = side === "Right", sign = v => (right ? v : scale(v, -1));
+	// a side along the axis leaves no knuckle line across it: the palm then just faces against the side (below)
+	if (w.axis && type !== "palm" && !(w.from && len(flat(w.axis, w.from)) < 1e-3)) {
+		if (w.from) {
+			const n = sign(w.from), l0 = norm(flat(w.axis, n)), pick = l => (w.thumb ? dot(l, w.thumb) : dot(cross(l, n), fwd));
+			const l = pick(l0) >= pick(scale(l0, -1)) ? l0 : scale(l0, -1);
+			return cols(cross(l, n), l, n);
+		}
+		const d = across(fwd, w.axis), medial = apply(ry(yawDeg), [right ? 1 : -1, 0, 0]), vy = Math.abs(d[1]);
+		const want = w.thumb ?? flat(add(scale([0, 1, 0], 1 - vy), scale(medial, vy)), d), l0 = norm(flat(w.axis, d));
+		const l = dot(l0, want) >= 0 ? l0 : scale(l0, -1);
+		return cols(d, l, cross(d, l));
+	}
+	const n = sign(w.from ?? scale(fwd, -1)), d = across(fwd, n);
+	return cols(d, cross(n, d), n);
+}
+
+/** fwd made perpendicular to v (unit); any perpendicular when fwd runs along v. */
+function across(fwd, v) {
+	const d = flat(fwd, v);
+	return norm(len(d) > 1e-3 ? d : flat(Math.abs(v[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0], v));
+}
+
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];

package/src/motion3/take-edit.js

@@ -148,7 +148,7 @@ export function renderTakeEdit(take) {
 		if (track.pos) { next.pos = new Float32Array(D * 3); at.forEach(({ i0, i1, t }, f) => lerp(next.pos, f * 3, track.pos, i0 * 3, track.pos, i1 * 3, t, 3)); }
 		if (track.quat) { next.quat = new Float32Array(D * 4); at.forEach(({ i0, i1, t }, f) => nlerp(next.quat, f * 4, track.quat, i0 * 4, track.quat, i1 * 4, t)); }
 		if (track.lvl) { next.lvl = new Float32Array(D); at.forEach(({ i0, i1, t }, f) => lerp(next.lvl, f, track.lvl, i0, track.lvl, i1, t, 1)); }
-		for (const key of ["vis", "hold"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
+		for (const key of ["vis", "hold", "world"]) if (track[key]) { next[key] = new Uint8Array(D); at.forEach(({ near }, f) => { next[key][f] = track[key][near]; }); }
 		return [id, next];
 	}));
 	return { ...take, frameCount: D, frames: D, rot, hips, objects, edit, editRendered: true };

package/src/motion3/take.js

@@ -6,12 +6,13 @@
 // world space: one track per spec.objects key (a group: its root only). A switch entry (C15)
 // bakes only vis and lvl, no pos/quat: its record keeps its own place (object-travel.js). A follow
 // entry (C16) bakes pos/quat with hold on every frame: its track is world space throughout. A free entry
-// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold.
+// (C17) bakes pos/quat (and vis/lvl when it names them), world space, no hold. A carry that rides a moving body after
+// its release (object-pose.js riderOf) marks those frames `world`: world space too, though no hand holds it.
 import { toLocal } from "./compiler/skeleton.js";
 import { sub, apply, ry, quatFromMat, mul } from "./compiler/math.js";
 import { isCarried, isFollow, isSwitch } from "./carried.js";
 import { isFree } from "./free-motion.js";
-import { rootPoseAt, spanOf } from "./object-pose.js";
+import { rootPoseAt, spanOf, riderOf } from "./object-pose.js";
 
 const TAKE_SCHEMA = "cozyclay.take.v3";
 
@@ -36,7 +37,7 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 		const pos = moves ? new Float32Array(F * 3) : null, quat = moves ? new Float32Array(F * 4) : null;
 		const named = rides || !moves || isFree(spec), vis = named && spec.visible ? new Uint8Array(F) : null, hold = rides ? new Uint8Array(F) : null;
 		const lvl = named && spec.level ? new Float32Array(F) : null;
-		const [grab, release] = carried ? spanOf(out, spec) : [0, 0];
+		const [grab, release] = carried ? spanOf(out, spec) : [0, 0], world = carried && riderOf(out, id) ? new Uint8Array(F) : null;
 		for (let f = 0; f < F; f++) {
 			if (vis) vis[f] = (out.baked?.[spec.visible]?.[f + f0] ?? 0) > 0.5 ? 1 : 0;
 			if (lvl) lvl[f] = Math.max(0, Math.min(4, out.baked?.[spec.level]?.[f + f0] ?? 1));
@@ -45,8 +46,9 @@ export function bakeTake(sk, out, placement = { position: [0, 0, 0], yaw: 0 }, m
 			if (!o) continue;
 			pos.set(o.pos, f * 3); quat.set(quatFromMat(o.R), f * 4);
 			if (hold) hold[f] = follows || (f + f0 >= grab && f + f0 <= release) ? 1 : 0;
+			if (world) world[f] = f + f0 > release ? 1 : 0;
 		}
-		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(lvl ? { lvl } : {}) };
+		objects[id] = { ...(moves ? { pos, quat } : {}), ...(vis ? { vis } : {}), ...(hold ? { hold } : {}), ...(world ? { world } : {}), ...(lvl ? { lvl } : {}) };
 	}
 	return { schema: TAKE_SCHEMA, fps: out.fps, frameCount: F, rig: sk.model, bones: sk.names.slice(), rot, hips, objects, placement, ...meta };
 }

package/src/motion3/views.js

@@ -1,6 +1,7 @@
 // C11 own views: the cameras of a verify_result contact_sheet with `views`. They are the
 // agent's own cameras around the subject, never the user's shot camera. A view stays at one
-// place for every frame of the sheet and frames what matters over those frames (the focus
+// place for every frame of the sheet (or rides with the focus when it travels farther than its
+// size) and frames what matters over those frames (the focus
 // refs, else the whole character, plus any trail), so a small action fills the tile and
 // motion reads as change inside one still frame. Pure over a compile result (compileSpec .out).
 //   front          in front of the character, 10 degrees up
@@ -78,7 +79,8 @@ function fit(name, points, back, upHint, aspect) {
  * Deterministic: the same compile, frames and arguments give the same cameras.
  */
 export function viewCameras(out, { views, frames, focus = [], trails = [], aspect = 1 }) {
-	let points = frames.flatMap(f => focus.flatMap(ref => refPoints(out, f, ref)));
+	const ride = rideOf(out, frames, focus);
+	let points = frames.flatMap(f => focus.flatMap(ref => refPoints(out, f, ref)).map(p => (ride ? sub(p, ride[f]) : p)));
 	const body = frames.flatMap(f => jointsAt(out, f));
 	if (!points.length) points = body;
 	points = [...points, ...trails.flatMap(t => t.points.map(q => q.p))];
@@ -86,12 +88,33 @@ export function viewCameras(out, { views, frames, focus = [], trails = [], aspec
 	const { left, forward } = facingOf(out, frames), hips = mean(frames.map(f => jointsAt(out, f)[out.ctx.sk.index.Hips]).filter(Boolean));
 	const side = focus.length && dot(sub(mean(points), hips), left) > 0.02 ? left : scale(left, -1);
 	return views.map(name => {
-		if (name === "top") return fit(name, points, UP, forward, aspect);
-		const e = rad(ELEVATION[name]), level = name === "front" ? forward : name === "side" ? side : norm(add(forward, side));
-		return fit(name, points, add(scale(level, Math.cos(e)), scale(UP, Math.sin(e))), UP, aspect);
+		const cam = name === "top" ? fit(name, points, UP, forward, aspect)
+			: (e => fit(name, points, add(scale(name === "front" ? forward : name === "side" ? side : norm(add(forward, side)), Math.cos(e)), scale(UP, Math.sin(e))), UP, aspect))(rad(ELEVATION[name]));
+		return ride ? { ...cam, ride } : cam;
 	});
 }
 
+/**
+ * The focus's travel over the frames: { [frame]: its centre there less its mean centre } when it moves farther than its
+ * own size (a wheel in a driving truck, session 2ad2760a: one camera for the whole drive framed the road and showed the
+ * hands too small to read), else null. A riding view keeps its place relative to the focus (cameraAt).
+ */
+function rideOf(out, frames, focus) {
+	if (!focus.length) return null;
+	const at = frames.map(f => ({ f, points: focus.flatMap(ref => refPoints(out, f, ref)) })).filter(x => x.points.length);
+	if (at.length < 2) return null;
+	const centres = at.map(x => mean(x.points)), mid = mean(centres);
+	const size = Math.max(MIN_HALF, ...at.map((x, i) => Math.max(...x.points.map(p => Math.hypot(...sub(p, centres[i]))))));
+	if (Math.max(...centres.map(c => Math.hypot(...sub(c, mid)))) <= size) return null;
+	return Object.fromEntries(at.map((x, i) => [x.f, sub(centres[i], mid)]));
+}
+
+/** View camera `cam` at `frame`: a riding view moved by the focus's travel there (rideOf), else cam itself. */
+export function cameraAt(cam, frame) {
+	const d = cam.ride?.[frame];
+	return d ? { ...cam, eye: add(cam.eye, d), target: add(cam.target, d) } : cam;
+}
+
 // A picture hides distance along its own line of sight, so a sheet holds two views at least APART
 // degrees apart. Front and three-quarter (45 degrees apart) look along nearly one line: the
 // guitarist's right hand 20 cm in front of the guitar (session df388a9b) showed in neither.

package/src/object-catalog.jsx

@@ -7,6 +7,7 @@ const GROUP_LABELS_KO = {
 	"Set pieces": "세트 소품",
 	Lights: "조명",
 	Effects: "효과",
+	Text: "텍스트",
 };
 
 const OBJECT_LABELS_KO = {
@@ -24,6 +25,7 @@ const OBJECT_LABELS_KO = {
 	"Spot light": "스포트 조명",
 	Light: "조명",
 	Effect: "효과",
+	Text: "텍스트",
 };
 
 function displayObjectGroupName(name) {
@@ -73,7 +75,7 @@ export function CatalogueEntries({ onPick }) {
 					<span className={`add-object-swatch ${entry.kind}`} style={{ background: entry.color }} aria-hidden="true" />
 					<span>{displayObjectLabel(entry.label)}</span>
 					{/* An empty has no size to quote: say what it is instead of "0 × 0 m". */}
-					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
+					<small>{entry.light ? ko("practical light", "실제 조명") : entry.kind === EMPTY_KIND ? ko("node only", "노드 전용") : entry.kind === "effect" ? ko("smoke, fire, rain…", "연기, 불, 비…") : entry.kind === "text" ? ko("words, signs, logos", "글자, 간판, 로고") : `${entry.footprint.width} × ${entry.footprint.depth} m`}</small>
 				</button>
 			))}
 		</div>

package/src/object-grasp.js

@@ -0,0 +1,38 @@
+/**
+ * Grasp sockets on a record (`grasp`): where and how a hand takes hold of it, in the record's own axes, so they move
+ * with it and save with it. { <name>: { at: [x, y, z] m from the base pivot, axis?: the line across the palm (a bar,
+ * a handle), from?: the side the hand comes from (the palm faces against it), thumb?: the axis end the thumb takes } }.
+ * A motion spec's object anchor with `grasp` takes a hand by one (src/motion3/sockets.js), and a thin body is a socket
+ * of its own without one. At most MAX sockets, names of letters, digits, _ and -.
+ */
+const MAX = 8, NAME = /^[A-Za-z0-9_-]{1,32}$/, REACH = 10;
+
+const vec = (v, limit) => (Array.isArray(v) && v.length === 3 && v.every(Number.isFinite) && v.every(x => Math.abs(x) <= limit) ? v.map(x => Math.round(x * 1e4) / 1e4) : null);
+const dir = v => { const u = vec(v, 1e3), n = u && Math.hypot(...u); return n > 1e-6 ? u.map(x => Math.round((x / n) * 1e4) / 1e4) : null; };
+
+/** The repaired sockets of a record, or null for none (invalid entries are dropped). */
+function normalizeObjectGrasp(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const out = {};
+	for (const [name, s] of Object.entries(value)) {
+		if (Object.keys(out).length >= MAX || !NAME.test(name) || !s || typeof s !== "object") continue;
+		const at = vec(s.at, REACH);
+		if (!at) continue;
+		out[name] = { at };
+		for (const k of ["axis", "from", "thumb"]) { const d = dir(s[k]); if (d) out[name][k] = d; }
+	}
+	return Object.keys(out).length ? out : null;
+}
+
+/** The grasp field of a stored record (normalizeSceneObject): kept when it has a socket. */
+export function objectGraspFields(record) {
+	const grasp = normalizeObjectGrasp(record?.grasp);
+	return grasp ? { grasp } : {};
+}
+
+/** The grasp part of an object.update patch: the sockets replace the record's own; `grasp: null` removes them. Only a change is returned. */
+export function objectGraspPatch(object, patch) {
+	if (patch?.grasp === undefined) return {};
+	const next = patch.grasp === null ? null : normalizeObjectGrasp(patch.grasp);
+	return JSON.stringify(next) === JSON.stringify(object.grasp ?? null) ? {} : { grasp: next };
+}

package/src/object-look.js

@@ -194,3 +194,5 @@ export function withShadowCapWarnings(result, objects) {
 	const warnings = shadowCapWarnings(objects, result?.affectedIds ?? []);
 	return warnings.length ? { ...result, warnings: [...(result.warnings ?? []), ...warnings] } : result;
 }
+// A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
+export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";

package/src/object-travel.js

@@ -115,12 +115,15 @@ export function trackLevel(id, frame, take) {
 }
 
 /**
- * True while a compiled take holds the record in a hand (a grabbed cup): its track is in world
- * space then, so the carry from its own parents (the table it stood on) is cut, like `attach`.
+ * True while a compiled take holds the record in a hand (a grabbed cup), or the record rides a
+ * moving body after its release (`world`, take.js): its track is in world space then, so the
+ * carry from its own parents (the table it stood on) is cut, like `attach`.
  */
 function held(id, frame, take) {
 	const track = take?.objectTracks?.get?.(id);
-	return !!track?.hold && track.hold[trackFrame(track, frame)] === 1;
+	if (!track) return false;
+	const at = trackFrame(track, frame);
+	return track.hold?.[at] === 1 || track.world?.[at] === 1;
 }
 
 /** The record's own route sample (or compiled track) as a matrix, or null when it does not travel. */

package/src/panels/ObjectLookPanel.jsx

@@ -5,11 +5,13 @@ import Foldout from "./Foldout.jsx";
 import { Field, Slider } from "../ui.jsx";
 import { ko } from "../locale.js";
 import { LIGHT_KIND, practicalShadows } from "../object-look.js";
+import { TEXT_KIND } from "../text/text-record.js";
 
 /**
- * Light and glow for the selected record: a practical light's type, colour,
- * brightness, reach, cone, shadow and flicker, and any record's glow. A drag is
- * one open transaction (one undo); a switch is one atomic edit.
+ * Words, light and glow for the selected record: a text's words and letter
+ * size, a practical light's type, colour, brightness, reach, cone, shadow and
+ * flicker, and any record's glow. A drag or a typing run is one open
+ * transaction (one undo); a switch is one atomic edit.
  */
 export default function ObjectLookPanel() {
 	const { selectedSceneObject: object, sceneObjects, beginSceneTransaction, endSceneTransaction } = useStudioShell();
@@ -35,6 +37,7 @@ export default function ObjectLookPanel() {
 	if (!object) return null;
 	const light = object.renderer === LIGHT_KIND ? object.light : null;
 	const glow = object.glow ?? null;
+	const text = object.renderer === TEXT_KIND ? object.text : null;
 	const capped = light?.shadow && practicalShadows(sceneObjects).capped.includes(object.id);
 	const ends = { onPointerUp: commit, onPointerCancel: commit, onKeyUp: commit, onBlur: commit };
 	const lightSlider = (field, label, min, max, step, unit = "") => (
@@ -42,6 +45,24 @@ export default function ObjectLookPanel() {
 	);
 	return (
 		<>
+			{text && (
+				<Foldout title={ko("Text", "텍스트")}>
+					<Field label={ko("Words", "글자")}>
+						<textarea rows={2} value={text.value} onChange={(event) => drag("text.value", { text: { value: event.target.value } })} onBlur={commit} />
+					</Field>
+					<div {...ends}>
+						<Slider label={ko("Letter height", "글자 높이")} min={0.02} max={3} step={0.01} unit=" m" softMax value={text.size} onChange={(value) => drag("text.size", { text: { size: value } })} />
+						<Slider label={ko("Depth (0 = flat)", "두께 (0 = 평면)")} min={0} max={0.5} step={0.005} unit=" m" softMax value={text.depth} onChange={(value) => drag("text.depth", { text: { depth: value } })} />
+						<Field label={ko("Align", "정렬")}>
+							<select value={text.align} onChange={(event) => set({ text: { align: event.target.value } })}>
+								<option value="left">{ko("Left", "왼쪽")}</option>
+								<option value="center">{ko("Centre", "가운데")}</option>
+								<option value="right">{ko("Right", "오른쪽")}</option>
+							</select>
+						</Field>
+					</div>
+				</Foldout>
+			)}
 			{light && (
 				<Foldout title={ko("Light", "조명")}>
 					<div {...ends}>