Code-first video & image, rendered natively on WebGPU.
Fix FBX animation import: merge X/Y/Z curves into vec3/quaternion tracks
okanasl1836905ca6dc
diff --git a/packages/webgpu-renderers/src/loaders/fbx-animation.test.ts b/packages/webgpu-renderers/src/loaders/fbx-animation.test.tsnew file mode 100644index 00000000..92609ff0--- /dev/null+++ b/packages/webgpu-renderers/src/loaders/fbx-animation.test.ts@@ -0,0 +1,160 @@+import { describe, expect, it } from "vitest";+import { FbxLoader, fbxEulerToQuat } from "./fbx-loader.js";+import type { NodeAnimationTrack3D } from "./types.js";++const K = FbxLoader.FBX_KTIME; // ticks per second++/** An AnimationCurve object with keys at the given seconds. */+function curve(id: number, seconds: number[], values: number[]): string {+ return `+ AnimationCurve: ${id}, "AnimCurve::", "" {+ Default: 0+ KeyVer: 4009+ KeyTime: *${seconds.length} {+ a: ${seconds.map((s) => s * K).join(",")}+ }+ KeyValueFloat: *${values.length} {+ a: ${values.join(",")}+ }+ }`;+}++function curveNode(id: number, name: string): string {+ return `+ AnimationCurveNode: ${id}, "AnimCurveNode::${name}", "" {+ Properties70: {+ P: "d|X", "Number", "", "A",0+ P: "d|Y", "Number", "", "A",0+ P: "d|Z", "Number", "", "A",0+ }+ }`;+}++/**+ * One model "Cube" (RotationOrder XYZ, rest translation z = 5) animated over+ * 0..2 s. The translation curve node has a junk name ("rs") so only its+ * "Lcl Translation" connection property identifies it.+ */+function animatedCubeFbx(rotationOrder = 0): string {+ return `; FBX 7.4.0 project file+FBXHeaderExtension: {+ FBXVersion: 7400+}+Objects: {+ Model: 1001, "Model::Cube", "Mesh" {+ Properties70: {+ P: "RotationOrder", "enum", "", "",${rotationOrder}+ P: "Lcl Translation", "Lcl Translation", "", "A",0,0,5+ P: "Lcl Rotation", "Lcl Rotation", "", "A",0,0,0+ P: "Lcl Scaling", "Lcl Scaling", "", "A",1,1,1+ }+ }+ AnimationStack: 5001, "AnimStack::Take 001", "" {+ }+ AnimationLayer: 5002, "AnimLayer::BaseLayer", "" {+ }${curveNode(2001, "rs")}${curveNode(2002, "R")}${curveNode(2003, "S")}${curve(3001, [0, 1, 2], [0, 10, 20])}${curve(3002, [0, 2], [0, 4])}${curve(3003, [0, 1, 2], [0, 90, 180])}${curve(3004, [0, 1, 2], [1, 2, 3])}${curve(3005, [0, 2], [1, 5])}${curve(3006, [0, 2], [1, 1])}+}+Connections: {+ C: "OO", 5002, 5001+ C: "OO", 2001, 5002+ C: "OO", 2002, 5002+ C: "OO", 2003, 5002+ C: "OP", 2001, 1001, "Lcl Translation"+ C: "OP", 2002, 1001, "Lcl Rotation"+ C: "OP", 2003, 1001, "Lcl Scaling"+ C: "OP", 3002, 2001, "d|Y"+ C: "OP", 3001, 2001, "d|X"+ C: "OP", 3003, 2002, "d|Z"+ C: "OP", 3004, 2003, "d|X"+ C: "OP", 3005, 2003, "d|Y"+ C: "OP", 3006, 2003, "d|Z"+}+`;+}++function trackWith(+ tracks: NodeAnimationTrack3D[],+ field: "translations" | "rotations" | "scales",+): NodeAnimationTrack3D {+ const matches = tracks.filter((t) => t[field]);+ expect(matches).toHaveLength(1);+ return matches[0]!;+}++function expectClose(actual: ArrayLike<number>, expected: number[]): void {+ expect(actual).toHaveLength(expected.length);+ expected.forEach((v, i) => expect(actual[i]).toBeCloseTo(v, 5));+}++/** Rotates v by the [x, y, z, w] quaternion q. */+function rotate(q: number[], v: number[]): number[] {+ const [x, y, z, w] = q as [number, number, number, number];+ const [vx, vy, vz] = v as [number, number, number];+ const tx = 2 * (y * vz - z * vy);+ const ty = 2 * (z * vx - x * vz);+ const tz = 2 * (x * vy - y * vx);+ return [+ vx + w * tx + (y * tz - z * ty),+ vy + w * ty + (z * tx - x * tz),+ vz + w * tz + (x * ty - y * tx),+ ];+}++describe("FBX animation import", () => {+ const model = FbxLoader.parse(animatedCubeFbx());+ const clip = model.animations[0]!;++ it("merges X/Y/Z curves into one track per transform", () => {+ expect(clip.name).toBe("Take 001");+ expect(clip.duration).toBeCloseTo(2, 5);+ expect(clip.tracks).toHaveLength(3);+ for (const track of clip.tracks) {+ expect(track.nodeName).toBe("Cube");+ expectClose(track.times, [0, 1, 2]);+ }+ });++ it("translates with vec3 keys, interpolating sparse channels and keeping the static value", () => {+ const t = trackWith(clip.tracks, "translations");+ expect(t.rotations).toBeUndefined();+ expect(t.scales).toBeUndefined();+ // Mid key (1 s): X keyed, Y interpolated between 0 and 4, Z from Lcl Translation.+ expectClose(t.translations!.subarray(3, 6), [10, 2, 5]);+ expectClose(t.translations!.subarray(6, 9), [20, 4, 5]);+ });++ it("rotates with quaternion keys converted from Euler degrees", () => {+ const r = trackWith(clip.tracks, "rotations");+ expect(r.rotations).toHaveLength(12);+ const s = Math.SQRT1_2;+ expectClose(r.rotations!.subarray(0, 4), [0, 0, 0, 1]);+ // Mid key: 90° about Z.+ expectClose(r.rotations!.subarray(4, 8), [0, 0, s, s]);+ expectClose(rotate(Array.from(r.rotations!.subarray(4, 8)), [1, 0, 0]), [0, 1, 0]);+ // 180° about Z, kept in the same hemisphere as the previous key.+ expectClose(r.rotations!.subarray(8, 12), [0, 0, 1, 0]);+ });++ it("scales with vec3 keys", () => {+ const sc = trackWith(clip.tracks, "scales");+ expectClose(sc.scales!.subarray(3, 6), [2, 3, 1]);+ expectClose(sc.scales!.subarray(6, 9), [3, 5, 1]);+ });+});++describe("fbxEulerToQuat", () => {+ it("applies axes in FBX RotationOrder", () => {+ // XYZ: X first, then Y. (1,0,0) is fixed by X 90°, then Y 90° sends it to (0,0,-1).+ expectClose(rotate(fbxEulerToQuat([90, 90, 0], "XYZ"), [1, 0, 0]), [0, 0, -1]);+ // YXZ: Y first sends (1,0,0) to (0,0,-1), then X 90° sends that to (0,1,0).+ expectClose(rotate(fbxEulerToQuat([90, 90, 0], "YXZ"), [1, 0, 0]), [0, 1, 0]);+ });++ it("uses the model's RotationOrder enum when importing", () => {+ const fbx = animatedCubeFbx(5) // ZYX+ .replace('"Lcl Rotation", "", "A",0,0,0', '"Lcl Rotation", "", "A",90,0,0');+ const r = trackWith(FbxLoader.parse(fbx).animations[0]!.tracks, "rotations");+ expectClose(r.rotations!.subarray(4, 8), fbxEulerToQuat([90, 0, 90], "ZYX"));+ expect(fbxEulerToQuat([90, 0, 90], "ZYX")).not.toEqual(fbxEulerToQuat([90, 0, 90], "XYZ"));+ });+});diff --git a/packages/webgpu-renderers/src/loaders/fbx-loader.ts b/packages/webgpu-renderers/src/loaders/fbx-loader.tsindex 03650d13..e4537a02 100644--- a/packages/webgpu-renderers/src/loaders/fbx-loader.ts+++ b/packages/webgpu-renderers/src/loaders/fbx-loader.ts@@ -1,15 +1,13 @@import fs from "node:fs";import { inflateSync } from "node:zlib";-import { type Mat4, Matrix4Math, type Vec3, Vector3Math } from "../math3d/index.js";+import { type Vec3, Vector3Math } from "../math3d/index.js";import type {AnimationClip3D,- Bone3D,LoadModelOptions,Material3D,Mesh3DData,Model3DData,NodeAnimationTrack3D,- Skeleton3D,} from "./types.js";interface FBXNode {@@ -67,21 +65,18 @@ export class FbxLoader {let endOffset: number;let numProperties: number;- let propertyListLen: number;let nameLen: number;if (is64Bit) {if (offset + 25 > u8.byteLength) return null;endOffset = Number(view.getBigUint64(offset, true));numProperties = Number(view.getBigUint64(offset + 8, true));- propertyListLen = Number(view.getBigUint64(offset + 16, true));nameLen = view.getUint8(offset + 24);offset += 25;} else {if (offset + 13 > u8.byteLength) return null;endOffset = view.getUint32(offset, true);numProperties = view.getUint32(offset + 4, true);- propertyListLen = view.getUint32(offset + 8, true);nameLen = view.getUint8(offset + 12);offset += 13;}@@ -396,9 +391,6 @@ export class FbxLoader {const uvLayer = geomNode.children.find((c) => c.name === "LayerElementUV",);- const materialLayer = geomNode.children.find(- (c) => c.name === "LayerElementMaterial",- );if (!verticesNode || !indicesNode) continue;@@ -574,7 +566,6 @@ export class FbxLoader {const cWeights = extractArrayProp(weightsNode);for (let k = 0; k < cIndexes.length; k++) {- const originalVert = cIndexes[k]!;const weight = cWeights[k] ?? 0;// Apply weight to all duplicated vertices referencing originalVert@@ -611,7 +602,7 @@ export class FbxLoader {}// 2. Parse Materials- for (const [id, entry] of objects) {+ for (const [, entry] of objects) {if (entry.node.name === "Material") {const matNode = entry.node;const props70 = matNode.children.find((c) => c.name === "Properties70");@@ -670,11 +661,23 @@ export class FbxLoader {objects.get(c.childId)?.node.name === "AnimationCurveNode",);+ // One entry per (model, transform); its X/Y/Z curves merge into one track.+ const groups = new Map<+ string,+ {+ nodeName: string;+ model: FBXNode | undefined;+ kind: TransformKind;+ defaults: Vec3;+ channels: Array<FbxCurve | undefined>;+ }+ >();+for (const cnc of curveNodeConns) {const curveNodeObj = objects.get(cnc.childId);if (!curveNodeObj) continue;- // Find connected Model/Bone+ // Find connected Model/Bone; the OP connection names the property.const modelConn = connections.find((c) =>c.childId === curveNodeObj.id &&@@ -682,50 +685,54 @@ export class FbxLoader {);const targetModel = modelConn? objects.get(modelConn.parentId)- : null;- const nodeName = targetModel?.name ?? curveNodeObj.name;- const propType = (modelConn?.property ?? curveNodeObj.name).toLowerCase();+ : undefined;+ const kind =+ transformKindFromProperty(modelConn?.propName) ??+ transformKindFromProperty(curveNodeObj.name);+ if (!kind) continue;++ const key = `${targetModel?.id ?? curveNodeObj.id}|${kind}`;+ let group = groups.get(key);+ if (!group) {+ const model = targetModel?.node;+ group = {+ nodeName: targetModel?.name ?? curveNodeObj.name,+ model,+ kind,+ defaults: staticTransform(model, curveNodeObj.node, kind),+ channels: [undefined, undefined, undefined],+ };+ groups.set(key, group);+ }- // Find connected AnimationCurves (X, Y, Z channels)- const animCurves = connections.filter(+ // Find connected AnimationCurves; "d|X" / "d|Y" / "d|Z" pick the channel.+ const curveConns = connections.filter((c) =>c.parentId === curveNodeObj.id &&objects.get(c.childId)?.node.name === "AnimationCurve",);-- for (const ac of animCurves) {- const curveObj = objects.get(ac.childId)?.node;- const keyTimeNode = curveObj?.children.find(- (c) => c.name === "KeyTime",+ curveConns.forEach((cc, order) => {+ const axis = axisFromProperty(cc.propName) ?? order;+ if (axis > 2) return;+ const curveObj = objects.get(cc.childId)?.node;+ const times = extractArrayProp(+ curveObj?.children.find((c) => c.name === "KeyTime"),);- const keyValueNode = curveObj?.children.find(- (c) => c.name === "KeyValueFloat",+ const values = extractArrayProp(+ curveObj?.children.find((c) => c.name === "KeyValueFloat"),);+ const n = Math.min(times.length, values.length);+ if (n === 0) return;+ group.channels[axis] = {+ times: Array.from(times.slice(0, n), (t) => Number(t)),+ values: Array.from(values.slice(0, n), (v) => Number(v)),+ };+ });+ }- if (keyTimeNode && keyValueNode) {- const rawTimes = extractArrayProp(keyTimeNode);- const rawValues = extractArrayProp(keyValueNode);-- const times = new Float32Array(rawTimes.length);- const values = new Float32Array(rawValues.length);-- for (let k = 0; k < rawTimes.length; k++) {- times[k] = (rawTimes[k] ?? 0) / FbxLoader.FBX_KTIME;- values[k] = rawValues[k] ?? 0;- }-- const isRotation = propType.includes("rot") || propType.includes("r");- const isScaling = propType.includes("sc") || propType.includes("s");-- tracks.push({- nodeName,- times,- translations: !isRotation && !isScaling ? values : undefined,- rotations: isRotation ? values : undefined,- scalings: isScaling ? values : undefined,- });- }- }+ for (const group of groups.values()) {+ const track = buildTransformTrack(group);+ if (track) tracks.push(track);}}@@ -800,6 +807,180 @@ export class FbxLoader {}}+/** Which local transform an AnimationCurveNode drives. */+type TransformKind = "T" | "R" | "S";++/** One AnimationCurve channel; times stay in FBX KTime ticks. */+interface FbxCurve {+ times: number[];+ values: number[];+}++/**+ * Classifies a curve node from its OP connection property ("Lcl Translation",+ * "Lcl Rotation", "Lcl Scaling") or, failing that, its short name ("T", "R", "S").+ */+function transformKindFromProperty(name: string | undefined): TransformKind | undefined {+ switch (name) {+ case "Lcl Translation":+ case "T":+ return "T";+ case "Lcl Rotation":+ case "R":+ return "R";+ case "Lcl Scaling":+ case "S":+ return "S";+ default:+ return undefined;+ }+}++/** Channel index of a curve from its curve-node connection property ("d|X" → 0). */+function axisFromProperty(name: string | undefined): number | undefined {+ switch (name) {+ case "d|X":+ return 0;+ case "d|Y":+ return 1;+ case "d|Z":+ return 2;+ default:+ return undefined;+ }+}++/** Numeric values of a Properties70 `P` entry (they start at props[4]). */+function readProperty70(node: FBXNode | undefined, name: string): number[] | undefined {+ const props70 = node?.children.find((c) => c.name === "Properties70");+ const p = props70?.children.find((c) => c.name === "P" && c.props[0] === name);+ if (!p) return undefined;+ return p.props.slice(4).map((v) => Number(v));+}++/** A model's rest value for one transform, used where a channel has no curve. */+function staticTransform(+ model: FBXNode | undefined,+ curveNode: FBXNode,+ kind: TransformKind,+): Vec3 {+ const fallback = kind === "S" ? 1 : 0;+ const modelProp = readProperty70(+ model,+ kind === "T" ? "Lcl Translation" : kind === "R" ? "Lcl Rotation" : "Lcl Scaling",+ );+ const out: Vec3 = [fallback, fallback, fallback];+ for (let axis = 0; axis < 3; axis++) {+ const fromModel = modelProp?.[axis];+ const fromCurveNode = readProperty70(curveNode, `d|${"XYZ"[axis]}`)?.[0];+ const value = fromModel ?? fromCurveNode;+ if (value !== undefined && Number.isFinite(value)) out[axis] = value;+ }+ return out;+}++/** FBX EOrder enum (Model "RotationOrder"): axes in the order they are applied. */+const FBX_ROTATION_ORDERS = ["XYZ", "XZY", "YZX", "YXZ", "ZXY", "ZYX"] as const;++function rotationOrder(model: FBXNode | undefined): string {+ const order = readProperty70(model, "RotationOrder")?.[0] ?? 0;+ // 6 (eSphericXYZ) and anything unknown fall back to XYZ.+ return FBX_ROTATION_ORDERS[order] ?? "XYZ";+}++/**+ * Euler degrees → [x, y, z, w] quaternion. FBX applies the axes in `order`+ * (XYZ: X first, so R = Rz·Ry·Rx).+ */+export function fbxEulerToQuat(+ degrees: Vec3,+ order = "XYZ",+): [number, number, number, number] {+ let q: [number, number, number, number] = [0, 0, 0, 1];+ for (const axisName of order) {+ const axis = "XYZ".indexOf(axisName);+ const half = ((degrees[axis] ?? 0) * Math.PI) / 360;+ const s = Math.sin(half);+ const a: [number, number, number, number] = [0, 0, 0, Math.cos(half)];+ a[axis] = s;+ // q = a · q: each later axis is applied after the ones before it.+ q = [+ a[3] * q[0] + a[0] * q[3] + a[1] * q[2] - a[2] * q[1],+ a[3] * q[1] - a[0] * q[2] + a[1] * q[3] + a[2] * q[0],+ a[3] * q[2] + a[0] * q[1] - a[1] * q[0] + a[2] * q[3],+ a[3] * q[3] - a[0] * q[0] - a[1] * q[1] - a[2] * q[2],+ ];+ }+ return q;+}++/** Linear sample of a curve at `t` (KTime ticks), clamped to its ends. */+function sampleCurve(curve: FbxCurve, t: number): number {+ const { times, values } = curve;+ const last = times.length - 1;+ if (t <= times[0]!) return values[0]!;+ if (t >= times[last]!) return values[last]!;+ let k = 0;+ while (k < last - 1 && times[k + 1]! <= t) k++;+ const t0 = times[k]!;+ const t1 = times[k + 1]!;+ const u = t1 > t0 ? (t - t0) / (t1 - t0) : 0;+ return values[k]! + (values[k + 1]! - values[k]!) * u;+}++/**+ * Merges a transform's X/Y/Z curves onto one sorted key set: channels without+ * a key at some time are interpolated, channels without a curve keep the+ * static value. Rotations become quaternions in the model's RotationOrder.+ */+function buildTransformTrack(group: {+ nodeName: string;+ model: FBXNode | undefined;+ kind: TransformKind;+ defaults: Vec3;+ channels: Array<FbxCurve | undefined>;+}): NodeAnimationTrack3D | undefined {+ const keySet = new Set<number>();+ for (const channel of group.channels) {+ for (const t of channel?.times ?? []) keySet.add(t);+ }+ if (keySet.size === 0) return undefined;+ const keys = [...keySet].sort((a, b) => a - b);++ const times = new Float32Array(keys.length);+ const isRotation = group.kind === "R";+ const values = new Float32Array(keys.length * (isRotation ? 4 : 3));+ const order = isRotation ? rotationOrder(group.model) : "XYZ";+ let prev: [number, number, number, number] | undefined;++ keys.forEach((key, k) => {+ times[k] = key / FbxLoader.FBX_KTIME;+ const v: Vec3 = [0, 1, 2].map((axis) => {+ const channel = group.channels[axis];+ return channel ? sampleCurve(channel, key) : group.defaults[axis]!;+ }) as Vec3;+ if (!isRotation) {+ values.set(v, k * 3);+ return;+ }+ const q = fbxEulerToQuat(v, order);+ // Keep neighbours in the same hemisphere so slerp takes the short way.+ if (prev && prev[0] * q[0] + prev[1] * q[1] + prev[2] * q[2] + prev[3] * q[3] < 0) {+ for (let i = 0; i < 4; i++) q[i] = -q[i]!;+ }+ prev = q;+ values.set(q, k * 4);+ });++ return {+ nodeName: group.nodeName,+ times,+ translations: group.kind === "T" ? values : undefined,+ rotations: isRotation ? values : undefined,+ scales: group.kind === "S" ? values : undefined,+ };+}+export function parseFBX(bufferOrText: ArrayBuffer | Uint8Array | string,options: LoadModelOptions = {},