Skip to content

Code-first video & image, rendered natively on WebGPU.

7.1 KB
Raw Blame
/**
 * Poses a model's scene graph (glTF semantics): samples an animation clip's
 * translation / rotation / scale tracks at a time, composes the node
 * hierarchy into model-space matrices, and turns a skin's joints into the
 * joint matrices the mesh shader blends (joint world × inverse bind).
 */
import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
import type {
	AnimationClip3D,
	Mesh3DData,
	Model3DData,
	ModelNode3D,
	NodeAnimationTrack3D,
} from "./types.js";

export type Quat = [number, number, number, number];

/** Column-major translate · rotate(quaternion) · scale. */
export function trsMatrix(t: Vec3, q: Quat, s: Vec3): Mat4 {
	const [x, y, z, w] = q;
	const xx = x * x;
	const yy = y * y;
	const zz = z * z;
	const xy = x * y;
	const xz = x * z;
	const yz = y * z;
	const wx = w * x;
	const wy = w * y;
	const wz = w * z;
	return [
		(1 - 2 * (yy + zz)) * s[0],
		2 * (xy + wz) * s[0],
		2 * (xz - wy) * s[0],
		0,
		2 * (xy - wz) * s[1],
		(1 - 2 * (xx + zz)) * s[1],
		2 * (yz + wx) * s[1],
		0,
		2 * (xz + wy) * s[2],
		2 * (yz - wx) * s[2],
		(1 - 2 * (xx + yy)) * s[2],
		0,
		t[0],
		t[1],
		t[2],
		1,
	];
}

function normalizeQuat(q: Quat): Quat {
	const len = Math.hypot(q[0], q[1], q[2], q[3]) || 1;
	return [q[0] / len, q[1] / len, q[2] / len, q[3] / len];
}

export function slerp(a: Quat, b: Quat, t: number): Quat {
	let cos = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
	const sign = cos < 0 ? -1 : 1;
	cos *= sign;
	if (cos > 0.9995) {
		return normalizeQuat([
			a[0] + (sign * b[0] - a[0]) * t,
			a[1] + (sign * b[1] - a[1]) * t,
			a[2] + (sign * b[2] - a[2]) * t,
			a[3] + (sign * b[3] - a[3]) * t,
		]);
	}
	const theta = Math.acos(cos);
	const sin = Math.sin(theta);
	const wa = Math.sin((1 - t) * theta) / sin;
	const wb = (sign * Math.sin(t * theta)) / sin;
	return [
		a[0] * wa + b[0] * wb,
		a[1] * wa + b[1] * wb,
		a[2] * wa + b[2] * wb,
		a[3] * wa + b[3] * wb,
	];
}

/** Index of the last keyframe at or before `time` (binary search). */
function keyBefore(times: Float32Array, time: number): number {
	let lo = 0;
	let hi = times.length - 1;
	while (lo < hi) {
		const mid = (lo + hi + 1) >> 1;
		if ((times[mid] ?? 0) <= time) lo = mid;
		else hi = mid - 1;
	}
	return lo;
}

/** Element `k` (of `size` components) of a track's values; cubic tracks store [in, value, out] triples. */
function valueAt(
	values: Float32Array,
	k: number,
	size: number,
	cubic: boolean,
	part = 1,
): number[] {
	const at = cubic ? (k * 3 + part) * size : k * size;
	return Array.from(values.subarray(at, at + size));
}

function sampleChannel(
	track: NodeAnimationTrack3D,
	values: Float32Array,
	size: number,
	time: number,
	quaternion = false,
): number[] {
	const { times } = track;
	const cubic = track.interpolation === "cubic";
	const last = times.length - 1;
	if (time <= (times[0] ?? 0)) return valueAt(values, 0, size, cubic);
	if (time >= (times[last] ?? 0)) return valueAt(values, last, size, cubic);
	const k = keyBefore(times, time);
	if (track.interpolation === "step") return valueAt(values, k, size, cubic);
	const t0 = times[k] ?? 0;
	const dt = (times[k + 1] ?? t0) - t0;
	const u = dt > 0 ? (time - t0) / dt : 0;
	const a = valueAt(values, k, size, cubic);
	const b = valueAt(values, k + 1, size, cubic);
	if (cubic) {
		// Hermite with the glTF tangents (scaled by the keyframe gap).
		const outA = valueAt(values, k, size, true, 2);
		const inB = valueAt(values, k + 1, size, true, 0);
		const u2 = u * u;
		const u3 = u2 * u;
		const out = a.map(
			(p0, i) =>
				(2 * u3 - 3 * u2 + 1) * p0 +
				(u3 - 2 * u2 + u) * dt * (outA[i] ?? 0) +
				(-2 * u3 + 3 * u2) * (b[i] ?? 0) +
				(u3 - u2) * dt * (inB[i] ?? 0),
		);
		return quaternion ? normalizeQuat(out as Quat) : out;
	}
	if (quaternion) return slerp(a as Quat, b as Quat, u);
	return a.map((v, i) => v + ((b[i] ?? v) - v) * u);
}

/** Samples per-instance glTF morph weights without quaternion interpolation. */
export function sampleMorphWeights(
	mesh: Mesh3DData,
	clip: AnimationClip3D | undefined,
	time: number,
): number[] {
	const count = mesh.morphTargets?.length ?? 0;
	if (!count) return [];
	const track = clip?.tracks.find(
		(t) => t.node === mesh.node && t.weights && t.times.length > 0,
	);
	return track?.weights
		? sampleChannel(track, track.weights, count, time)
		: (mesh.morphWeights ?? Array(count).fill(0));
}

/** Every node's local translation, rotation (unit quaternion) and scale. */
export interface LocalPose {
	t: Vec3[];
	r: Quat[];
	s: Vec3[];
}

/** The rest pose with the clip's tracks applied at `time` (seconds). */
export function sampleLocalPose(
	nodes: ModelNode3D[],
	clip: AnimationClip3D | undefined,
	time: number,
): LocalPose {
	const t = nodes.map((n) => [...n.translation] as Vec3);
	const r = nodes.map((n) => [...n.rotation] as Quat);
	const s = nodes.map((n) => [...n.scale] as Vec3);
	const byName = new Map(nodes.map((n, i) => [n.name, i]));
	for (const track of clip?.tracks ?? []) {
		const i = track.node ?? byName.get(track.nodeName);
		if (i === undefined || !track.times.length) continue;
		if (track.translations)
			t[i] = sampleChannel(track, track.translations, 3, time) as Vec3;
		if (track.rotations)
			r[i] = sampleChannel(track, track.rotations, 4, time, true) as Quat;
		if (track.scales)
			s[i] = sampleChannel(track, track.scales, 3, time) as Vec3;
	}
	return { t, r, s };
}

/** Each node's local matrix (a fixed glTF `matrix` wins over TRS). */
export function localPoseMatrices(
	nodes: ModelNode3D[],
	pose: LocalPose,
): Mat4[] {
	return nodes.map(
		(n, i) => n.matrix ?? trsMatrix(pose.t[i]!, pose.r[i]!, pose.s[i]!),
	);
}

/** Model-space matrices from local ones. Parents may follow their children in the list. */
export function composeWorld(nodes: ModelNode3D[], local: Mat4[]): Mat4[] {
	const world: (Mat4 | undefined)[] = new Array(nodes.length);
	const resolve = (i: number): Mat4 => {
		const done = world[i];
		if (done) return done;
		const parent = nodes[i]!.parent;
		const m =
			parent < 0 ? local[i]! : Matrix4Math.multiply(resolve(parent), local[i]!);
		world[i] = m;
		return m;
	};
	return nodes.map((_, i) => resolve(i));
}

/**
 * Model-space matrix of every node, posed by `clip` at `time` seconds (the
 * rest pose without a clip). Parents may follow their children in the list.
 */
export function poseNodes(
	model: Model3DData,
	clip: AnimationClip3D | undefined,
	time: number,
): Mat4[] {
	const nodes = model.nodes ?? [];
	return composeWorld(
		nodes,
		localPoseMatrices(nodes, sampleLocalPose(nodes, clip, time)),
	);
}

/** The joint matrices of one skin for a posed scene graph. */
export function jointMatrices(
	model: Model3DData,
	skinIndex: number,
	world: Mat4[],
): Float32Array {
	const skin = model.skins?.[skinIndex];
	if (!skin) throw new Error(`model has no skin ${skinIndex}`);
	const out = new Float32Array(Math.max(1, skin.joints.length) * 16);
	for (let j = 0; j < Math.max(1, skin.joints.length); j++) {
		const node = skin.joints[j];
		if (node === undefined) {
			out.set(Matrix4Math.identity(), j * 16);
			continue;
		}
		const ibm = Array.from(
			skin.inverseBindMatrices.subarray(j * 16, j * 16 + 16),
		) as Mat4;
		out.set(Matrix4Math.multiply(world[node]!, ibm), j * 16);
	}
	return out;
}