Skip to content

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.ts
new file mode 100644
index 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.ts
index 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 = {},