cozyclay 2.1.0 → 3.0.0

package/src/ardy/pose-pin.js

@@ -1,97 +0,0 @@
-/**
- * Which frames a generation request pins, and why.
- *
- * The bridge has two modes and they are mutually exclusive. `posePin: true`
- * sends full-body poses and runs the box's pose mode; `segments` (a prompt
- * schedule) uses autoregressive history and demands `posePin: false`. Getting
- * that wrong is a rejected request, so the decision is made here, once, as
- * data — not spread across the call site where it cannot be tested.
- *
- * Pinning is deliberately NOT automatic for a loaded take. Pose mode builds on
- * a fixed implicit reference base, so pinning a whole clip makes a new prompt
- * dress up the same canned root path ("I changed the prompt but got the same
- * walk"). The cases below are the ones where a pin is what the operator asked
- * for:
- *
- *   - `startFromPose` — the character's blocking pose is pinned at a chosen
- *     frame and the motion is generated around it. The frame is the operator's
- *     choice: the first frame to leave from, the last to arrive at, or any
- *     frame in between to pass through.
- *   - authored IK edits — corrections addressed to specific frames.
- *   - block edits — IK keys inside a scheduled block, addressed to that take.
- */
-
-/** Reasons a request ends up unpinned, so the caller can explain itself. */
-export const PIN_BLOCKED = Object.freeze({
-	SCHEDULE: "prompt-schedule",
-	NOTHING_TO_PIN: "nothing-to-pin",
-});
-
-/**
- * @param {object} input
- * @param {boolean} input.startFromPose  operator asked to continue from the pose
- * @param {boolean} input.hasPromptSchedule  more than one prompt block
- * @param {boolean} input.hasBlockEdits  IK keys land inside scheduled blocks
- * @param {boolean} input.waypointMode  a root path is being authored
- * @param {number[]} input.ikFrames  timeline frames carrying authored IK keys
- * @param {number} input.clipFrames  the clip's length in timeline frames
- * @param {{startFrame:number,endFrame:number}[]} input.segments
- * @param {{startFrame:number,endFrame:number}[]} input.editedSegments
- * @returns {{pin: boolean, frames: number[], blockedBy: string|null}}
- */
-export function planPosePin({
-	startFromPose = false,
-	poseFrame = 0,
-	hasPromptSchedule = false,
-	hasBlockEdits = false,
-	waypointMode = false,
-	ikFrames = [],
-	clipFrames = 0,
-	segments = [],
-	editedSegments = [],
-}) {
-	// The pin must land inside the clip the box is about to generate: an
-	// out-of-range destination is refused at the far end of the pipeline, so it
-	// is clamped here where the clip length is known.
-	const pinFrame = Math.max(0, Math.min(Math.max(0, clipFrames - 1), Math.round(poseFrame) || 0));
-	// A schedule cannot be pinned at all: the bridge refuses the combination,
-	// so an opted-in pose start has to be reported as blocked rather than
-	// silently dropped.
-	if (hasPromptSchedule && !hasBlockEdits) {
-		return {
-			pin: false,
-			frames: [],
-			blockedBy: startFromPose ? PIN_BLOCKED.SCHEDULE : PIN_BLOCKED.NOTHING_TO_PIN,
-		};
-	}
-
-	const wantsPin = hasBlockEdits || ikFrames.length > 0 || startFromPose;
-	if (!wantsPin) return { pin: false, frames: [], blockedBy: PIN_BLOCKED.NOTHING_TO_PIN };
-
-	// A root path is generated from frame 0 outward, so one pin at the start is
-	// the whole constraint — pinning later frames would fight the path.
-	if (waypointMode) return { pin: true, frames: [0], blockedBy: null };
-
-	if (hasBlockEdits) {
-		const frames = ikFrames.filter((frame) =>
-			editedSegments.some((segment) => frame >= segment.startFrame && frame < segment.endFrame)
-		);
-		return { pin: frames.length > 0, frames, blockedBy: frames.length > 0 ? null : PIN_BLOCKED.NOTHING_TO_PIN };
-	}
-
-	// A pose placement is exactly one constraint, at the chosen frame. Anything
-	// more would pin motion the operator never authored.
-	if (ikFrames.length === 0) return { pin: true, frames: [pinFrame], blockedBy: null };
-
-	const frames = [...new Set([
-		...(startFromPose ? [pinFrame] : []),
-		...segments.flatMap((segment) => [
-			segment.startFrame,
-			Math.min(segment.endFrame - 1, segment.startFrame + 1),
-			Math.max(segment.startFrame, segment.endFrame - 2),
-			segment.endFrame - 1,
-		]),
-		...ikFrames.filter((frame) => frame >= 0 && frame < clipFrames),
-	])].sort((a, b) => a - b);
-	return { pin: frames.length > 0, frames, blockedBy: null };
-}

package/src/ardy/prompt-clips.js

@@ -1,30 +0,0 @@
-/** Move one prompt clip on the fixed prompt-block grid without changing its
- * duration. Segment generation needs at most one prompt per frame range, so a
- * snapped position that lands inside a neighbor clamps to abut that neighbor
- * instead of overlapping; gaps remain valid and inherit the main prompt.
- *
- * Clock-agnostic: `blockFrames` is the caller's grid, and App.jsx always
- * passes ARDY_PROMPT_HORIZON_FRAMES (2 s on the 24 fps timeline clock = 48).
- * The 40 default is only the bare-call fallback and means nothing on the
- * wire — nothing here ever reaches the bridge unconverted. */
-export function movePromptClipFrames(clips, id, rawStartFrame, blockFrames = 40) {
-	const target = clips.find((clip) => clip.id === id);
-	if (!target) return clips;
-	const duration = target.endFrame - target.startFrame;
-	let startFrame = Math.max(0, Math.round(rawStartFrame / blockFrames) * blockFrames);
-	// Generated takes lay clips off the block grid (phase seconds are free-form),
-	// so every grid position near an off-grid neighbor can overlap it — the clip
-	// would refuse to move at all. Slide to touch the neighbor's nearest edge.
-	const others = clips.filter((clip) => clip.id !== id);
-	for (const clip of others) {
-		if (startFrame < clip.endFrame && startFrame + duration > clip.startFrame) {
-			const mid = (clip.startFrame + clip.endFrame) / 2;
-			startFrame = rawStartFrame + duration / 2 <= mid ? clip.startFrame - duration : clip.endFrame;
-		}
-	}
-	const endFrame = startFrame + duration;
-	if (startFrame < 0 || startFrame === target.startFrame) return clips;
-	const overlaps = others.some((clip) => startFrame < clip.endFrame && endFrame > clip.startFrame);
-	if (overlaps) return clips;
-	return clips.map((clip) => clip.id === id ? { ...clip, startFrame, endFrame } : clip);
-}

package/src/ardy/retime.js

@@ -1,211 +0,0 @@
-// retime.js — duration-preserving resample of a decoded motion between frame
-// clocks. ARDY Core generates on its trained 20 fps clock, filmed takes arrive
-// at 30 or 60; the app timeline runs the production 24 fps one. A 20 fps take
-// counted against a 24 fps reference reads 1.2× fast, so inbound takes are
-// resampled here: rotations slerp between neighbouring source frames, the root
-// lerps, frame 0 stays identical, and the clip's length in seconds does not
-// move — only how densely it is sampled.
-//
-// World joint positions are NOT interpolated. A slerped rotation walks the arc
-// between two frames while a lerped position cuts the chord, so the two used to
-// disagree at every blended frame — and since most 24 fps frames land between
-// source frames, that disagreement was phase-locked to the resample (a 6 Hz
-// pulse from 30 fps, alternating frames from 60). Playback drives bone.position
-// straight from posedJoints, so on screen the shin visibly shortened by up to
-// 2.6 cm and sprang back: the trembling feet. Positions are regenerated by
-// forward kinematics from the retimed rotations instead, which makes constant
-// bone length a property of the output rather than a hope.
-
-import { CSKEL27_JOINTS } from "./cskel27.js";
-import { deriveBoneOffsets, forwardKinematics, matToQuat, quatToMat } from "./convert.js";
-import { canonicalCskel27Reference } from "./to-cskel27.js";
-
-/** w-first quaternion slerp with hemisphere correction; falls back to a
- *  normalised lerp when the arc is too small for a stable sine. Shared with
- *  the bridge's BVH conversion (torso stabilization, root-spin repair). */
-export function slerpQuat(a, b, t) {
-	let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
-	const sign = dot < 0 ? -1 : 1;
-	dot *= sign;
-	let wa;
-	let wb;
-	if (dot > 0.9995) {
-		wa = 1 - t;
-		wb = t;
-	} else {
-		const theta = Math.acos(Math.min(1, dot));
-		const sinTheta = Math.sin(theta);
-		wa = Math.sin((1 - t) * theta) / sinTheta;
-		wb = Math.sin(t * theta) / sinTheta;
-	}
-	const out = [
-		a[0] * wa + b[0] * sign * wb,
-		a[1] * wa + b[1] * sign * wb,
-		a[2] * wa + b[2] * sign * wb,
-		a[3] * wa + b[3] * sign * wb,
-	];
-	const norm = Math.hypot(...out);
-	return out.map((component) => component / norm);
-}
-
-function readMat(flat, offset) {
-	return [
-		[flat[offset], flat[offset + 1], flat[offset + 2]],
-		[flat[offset + 3], flat[offset + 4], flat[offset + 5]],
-		[flat[offset + 6], flat[offset + 7], flat[offset + 8]],
-	];
-}
-
-function writeMat(flat, offset, m) {
-	flat[offset] = m[0][0]; flat[offset + 1] = m[0][1]; flat[offset + 2] = m[0][2];
-	flat[offset + 3] = m[1][0]; flat[offset + 4] = m[1][1]; flat[offset + 5] = m[1][2];
-	flat[offset + 6] = m[2][0]; flat[offset + 7] = m[2][1]; flat[offset + 8] = m[2][2];
-}
-
-const JOINTS = CSKEL27_JOINTS.length;
-
-// Bone lengths are a property of the skeleton, not of the frame, so the offsets
-// are derived once for the module rather than per take or per frame. Same
-// pairing the BVH bridge uses (tools/ardy/bvh-cskel27.mjs): the canonical
-// cskel27 reference, not a clip's frame zero, so a take whose first frame is
-// noisy cannot smear its noise across the whole clip's proportions.
-const BONE_OFFSETS = (() => {
-	const skeleton = canonicalCskel27Reference();
-	return deriveBoneOffsets(skeleton.posed_joints, skeleton.local_rot_mats);
-})();
-
-// Above this (in npz metres) a take's own posedJoints are not the forward
-// kinematics of its own rotations, so regenerating them would move the take
-// rather than repair it. Measured across every take in tools/ardy/out — filmed
-// extractions and ARDY-generated clips alike — the residual is at most 1e-6 m,
-// pure float32 serialization noise, so 1e-4 m sits 100x above the honest floor
-// and far below any disagreement worth calling one.
-const FK_CONSISTENCY_TOLERANCE = 1e-4;
-
-// The 27 local rotations of one frame, as the nested matrices convert.js takes.
-function readLocals(flat, frame) {
-	const locals = new Array(JOINTS);
-	for (let j = 0; j < JOINTS; j += 1) locals[j] = readMat(flat, (frame * JOINTS + j) * 9);
-	return locals;
-}
-
-/**
- * Does this take's posedJoints already agree with FK of its own rotations?
- * Sampled rather than exhaustive: an inconsistent take is inconsistent by
- * construction (wrong proportions, hand-authored positions, a legacy writer),
- * not on one unlucky frame, and the check must not cost a second FK sweep.
- */
-function posedJointsFollowRotations(motion) {
-	const step = Math.max(1, Math.floor(motion.frames / 16));
-	for (let f = 0; f < motion.frames; f += step) {
-		const positions = forwardKinematics(
-			readLocals(motion.rotMats, f),
-			BONE_OFFSETS,
-			[motion.rootPos[f * 3], motion.rootPos[f * 3 + 1], motion.rootPos[f * 3 + 2]]
-		);
-		for (let j = 0; j < JOINTS; j += 1) {
-			const p = (f * JOINTS + j) * 3;
-			const dx = positions[j][0] - motion.posedJoints[p];
-			const dy = positions[j][1] - motion.posedJoints[p + 1];
-			const dz = positions[j][2] - motion.posedJoints[p + 2];
-			if (Math.hypot(dx, dy, dz) > FK_CONSISTENCY_TOLERANCE) return false;
-		}
-	}
-	return true;
-}
-
-/**
- * Resample `{ frames, fps, rotMats, rootPos, posedJoints, ... }` onto
- * `targetFps`. Every other field rides through untouched (`personScale`
- * included — changing the sampling clock does not change how big the filmed
- * performer was), except a present `anchorFrame`, which is rescaled onto the
- * new clock. Same-rate input is
- * returned as-is — retiming is never a copy for its own sake.
- *
- * `posedJoints` comes out of forward kinematics on the retimed rotations, so
- * every bone keeps its length exactly. The one exception is a take whose own
- * posedJoints do not already follow its own rotations: there the positions are
- * the authority and FK would move the take rather than repair it, so those
- * lerp between source frames as before. Nothing in tools/ardy/out is such a
- * take; the branch exists so a legacy or hand-built one is not rewritten.
- */
-export function retimeMotion(motion, targetFps) {
-	if (!motion || !Number.isFinite(motion.fps) || motion.fps <= 0) {
-		throw new Error("retimeMotion: motion.fps must be a positive finite number");
-	}
-	if (!Number.isFinite(targetFps) || targetFps <= 0) {
-		throw new Error("retimeMotion: targetFps must be a positive finite number");
-	}
-	if (motion.fps === targetFps) return motion;
-	const srcFrames = motion.frames;
-	if (!Number.isInteger(srcFrames) || srcFrames < 1) {
-		throw new Error("retimeMotion: motion.frames must be a positive integer");
-	}
-	const ratio = targetFps / motion.fps;
-	const frames = Math.max(1, Math.round(srcFrames * ratio));
-	const rotMats = new Float32Array(frames * JOINTS * 9);
-	const rootPos = new Float32Array(frames * 3);
-	const posedJoints = new Float32Array(frames * JOINTS * 3);
-	const regenerate = posedJointsFollowRotations(motion);
-
-	for (let f = 0; f < frames; f += 1) {
-		const s = f / ratio;
-		const i0 = Math.min(Math.floor(s), srcFrames - 1);
-		const i1 = Math.min(i0 + 1, srcFrames - 1);
-		const t = Math.min(Math.max(s - i0, 0), 1);
-		const exact = t === 0 || i0 === i1;
-
-		for (let j = 0; j < JOINTS; j += 1) {
-			const src0 = (i0 * JOINTS + j) * 9;
-			const dst = (f * JOINTS + j) * 9;
-			if (exact) {
-				for (let k = 0; k < 9; k += 1) rotMats[dst + k] = motion.rotMats[src0 + k];
-			} else {
-				const src1 = (i1 * JOINTS + j) * 9;
-				const q = slerpQuat(
-					matToQuat(readMat(motion.rotMats, src0)),
-					matToQuat(readMat(motion.rotMats, src1)),
-					t
-				);
-				writeMat(rotMats, dst, quatToMat(q));
-			}
-		}
-		for (let axis = 0; axis < 3; axis += 1) {
-			rootPos[f * 3 + axis] =
-				motion.rootPos[i0 * 3 + axis] * (1 - t) + motion.rootPos[i1 * 3 + axis] * t;
-		}
-
-		if (regenerate) {
-			// The root is the only position left in the interpolation; every joint
-			// below it is placed rigidly off the retimed rotations, which is what
-			// keeps bone lengths out of the blend entirely.
-			const positions = forwardKinematics(readLocals(rotMats, f), BONE_OFFSETS, [
-				rootPos[f * 3],
-				rootPos[f * 3 + 1],
-				rootPos[f * 3 + 2],
-			]);
-			for (let j = 0; j < JOINTS; j += 1) {
-				const pd = (f * JOINTS + j) * 3;
-				posedJoints[pd] = positions[j][0];
-				posedJoints[pd + 1] = positions[j][1];
-				posedJoints[pd + 2] = positions[j][2];
-			}
-		} else {
-			for (let j = 0; j < JOINTS; j += 1) {
-				const p0 = (i0 * JOINTS + j) * 3;
-				const p1 = (i1 * JOINTS + j) * 3;
-				const pd = (f * JOINTS + j) * 3;
-				for (let axis = 0; axis < 3; axis += 1) {
-					posedJoints[pd + axis] =
-						motion.posedJoints[p0 + axis] * (1 - t) + motion.posedJoints[p1 + axis] * t;
-				}
-			}
-		}
-	}
-
-	const retimed = { ...motion, frames, fps: targetFps, rotMats, rootPos, posedJoints };
-	if (Number.isFinite(motion.anchorFrame)) {
-		retimed.anchorFrame = Math.min(frames - 1, Math.round(motion.anchorFrame * ratio));
-	}
-	return retimed;
-}