Skip to content

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

FBX: real skinning, scene graph, and per-polygon-vertex UVs / normals

Claudefb286bf09c14
diff --git a/packages/framefields/src/extended-models-render.test.ts b/packages/framefields/src/extended-models-render.test.ts
index 1c84c5e0..8a37b78a 100644
--- a/packages/framefields/src/extended-models-render.test.ts
+++ b/packages/framefields/src/extended-models-render.test.ts
@@ -798,3 +798,119 @@ Connections: {
await fs.rm(tmpDir, { recursive: true, force: true });
});
});
+
+describe("FBX skinning", () => {
+ it("moves a skinned mesh with its animated bone", async () => {
+ const tmpDir = await fs.mkdtemp(
+ path.join(os.tmpdir(), "framefields-fbx-skin-"),
+ );
+ const file = path.join(tmpDir, "skinned.fbx");
+ // A quad fully weighted to "Bone", whose x translation goes 0 -> 100 over 1 s.
+ await fs.writeFile(
+ file,
+ `; FBX 7.4.0 project file
+Objects: {
+ Geometry: 1001, "Geometry::Quad", "Mesh" {
+ Vertices: *12 {
+ a: -50,-50,0, 50,-50,0, 50,50,0, -50,50,0
+ }
+ PolygonVertexIndex: *4 {
+ a: 0,1,2,-4
+ }
+ }
+ Model: 3001, "Model::Body", "Mesh" {
+ }
+ Model: 3002, "Model::Bone", "LimbNode" {
+ }
+ Deformer: 5001, "Deformer::Skin", "Skin" {
+ }
+ Deformer: 6001, "SubDeformer::Bone", "Cluster" {
+ Indexes: *4 {
+ a: 0,1,2,3
+ }
+ Weights: *4 {
+ a: 1,1,1,1
+ }
+ }
+ AnimationStack: 7001, "AnimStack::Slide", "" {
+ }
+ AnimationLayer: 7002, "AnimLayer::Base", "" {
+ }
+ AnimationCurveNode: 7003, "AnimCurveNode::T", "" {
+ }
+ AnimationCurve: 7004, "AnimCurve::", "" {
+ KeyTime: *2 {
+ a: 0,46186158000
+ }
+ KeyValueFloat: *2 {
+ a: 0,100
+ }
+ }
+}
+
+Connections: {
+ C: "OO", 1001, 3001
+ C: "OO", 3001, 0
+ C: "OO", 3002, 0
+ C: "OO", 5001, 1001
+ C: "OO", 6001, 5001
+ C: "OO", 3002, 6001
+ C: "OO", 7002, 7001
+ C: "OO", 7003, 7002
+ C: "OP", 7003, 3002, "Lcl Translation"
+ C: "OP", 7004, 7003, "d|X"
+}
+`,
+ );
+
+ const comp = new Composition({
+ width: 400,
+ height: 300,
+ fps: 30,
+ durationMs: 1000,
+ backgroundColor: "#000000",
+ });
+ comp.add(
+ Layer.camera({
+ id: "cam3d",
+ x: 200,
+ y: 150,
+ z: -600,
+ targetX: 200,
+ targetY: 150,
+ targetZ: 0,
+ }),
+ );
+ comp.add(
+ Layer.fbx(file, {
+ id: "fbx-skinned",
+ x: 200,
+ y: 150,
+ z: 0,
+ color: "#ff0000",
+ material: "unlit",
+ loop: false,
+ }),
+ );
+
+ /** Mean x of the red pixels. */
+ const redCenterX = async (frame: number) => {
+ const img = await decodePngPixels(await comp.renderFrame({ frame }));
+ let sum = 0;
+ let count = 0;
+ for (let y = 0; y < img.height; y += 2)
+ for (let x = 0; x < img.width; x += 2)
+ if (getPixel(img, x, y).r > 128) {
+ sum += x;
+ count++;
+ }
+ expect(count).toBeGreaterThan(50);
+ return sum / count;
+ };
+ const start = await redCenterX(0);
+ const half = await redCenterX(15);
+ // 50 model units at this distance is ~25 px.
+ expect(Math.abs(half - start)).toBeGreaterThan(15);
+ await fs.rm(tmpDir, { recursive: true, force: true });
+ });
+});
diff --git a/packages/webgpu-renderers/src/loaders/fbx-loader.ts b/packages/webgpu-renderers/src/loaders/fbx-loader.ts
index 36391218..c86ab72a 100644
--- a/packages/webgpu-renderers/src/loaders/fbx-loader.ts
+++ b/packages/webgpu-renderers/src/loaders/fbx-loader.ts
@@ -1,7 +1,12 @@
import fs from "node:fs";
import path from "node:path";
import { inflateSync } from "node:zlib";
-import { type Vec3, Vector3Math } from "../math3d/index.js";
+import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
+import {
+ accumulateVertexNormals,
+ resolveModelTransform,
+} from "./mesh-utils.js";
+import { MAX_JOINTS, poseNodes, type Quat } from "./pose.js";
import {
isSupportedTexture,
readTextureFile,
@@ -14,7 +19,9 @@ import type {
Material3D,
Mesh3DData,
Model3DData,
+ ModelNode3D,
NodeAnimationTrack3D,
+ Skin3D,
} from "./types.js";
interface FBXNode {
@@ -495,6 +502,41 @@ export class FbxLoader {
return [];
}
+ // Scene graph: every Model is a node (glTF semantics), parented by its
+ // OO connection to another Model. Pre-/post-rotations fold into the
+ // rotation; pivots and offsets are not supported.
+ const modelIds = [...objects.values()]
+ .filter((o) => o.node.name === "Model")
+ .map((o) => o.id);
+ const nodeIndexById = new Map(modelIds.map((id, i) => [id, i]));
+ const nodes: ModelNode3D[] = modelIds.map((id) => {
+ const model = objects.get(id)!;
+ const parentConn = connections.find(
+ (c) => c.childId === id && !c.propName && nodeIndexById.has(c.parentId),
+ );
+ return {
+ name: model.name,
+ parent: parentConn ? nodeIndexById.get(parentConn.parentId)! : -1,
+ translation: readVec3(model.node, "Lcl Translation", 0),
+ rotation: modelRotation(
+ model.node,
+ fbxEulerToQuat(
+ readVec3(model.node, "Lcl Rotation", 0),
+ rotationOrder(model.node),
+ ),
+ ),
+ scale: readVec3(model.node, "Lcl Scaling", 1),
+ };
+ });
+ const modelOfGeometry = (geometryId: number | string) =>
+ connections.find(
+ (c) =>
+ c.childId === geometryId &&
+ !c.propName &&
+ nodeIndexById.has(c.parentId),
+ )?.parentId;
+
+ const skins: Skin3D[] = [];
for (const [id, entry] of objects) {
if (
entry.node.name === "Geometry" &&
@@ -510,215 +552,171 @@ export class FbxLoader {
const indicesNode = geomNode.children.find(
(c) => c.name === "PolygonVertexIndex",
);
- const normalLayer = geomNode.children.find(
- (c) => c.name === "LayerElementNormal",
- );
- const uvLayer = geomNode.children.find(
- (c) => c.name === "LayerElementUV",
- );
-
if (!verticesNode || !indicesNode) continue;
const rawVerts = extractArrayProp(verticesNode);
const rawPolyIndices = extractArrayProp(indicesNode);
-
- const normalsNode = normalLayer?.children.find(
- (c) => c.name === "Normals",
+ const layer = (
+ name: string,
+ data: string,
+ index: string,
+ size: number,
+ ) => {
+ const node = geomNode.children.find((c) => c.name === name);
+ if (!node) return undefined;
+ return layerElement(
+ node,
+ extractArrayProp(node.children.find((c) => c.name === data)),
+ extractArrayProp(node.children.find((c) => c.name === index)),
+ size,
+ );
+ };
+ const normalAt = layer(
+ "LayerElementNormal",
+ "Normals",
+ "NormalsIndex",
+ 3,
);
- const rawNormals = extractArrayProp(normalsNode);
-
- const uvsNode = uvLayer?.children.find((c) => c.name === "UV");
- const uvIndexNode = uvLayer?.children.find((c) => c.name === "UVIndex");
- const rawUvs = extractArrayProp(uvsNode);
- const rawUvIndices = extractArrayProp(uvIndexNode);
-
- // Triangulate polygons (indices with negative termination)
- const triangles: Array<[number, number, number]> = [];
- const triVertexIndexSequence: number[] = [];
-
- let polygon: number[] = [];
+ const uvAt = layer("LayerElementUV", "UV", "UVIndex", 2);
+
+ // Triangulate polygons (the last index of each is stored as -(i + 1)).
+ // Each corner keeps its control point and its polygon-vertex index,
+ // which ByPolygonVertex layers (normals, UVs) are indexed by.
+ const corners: Array<{ cp: number; pv: number; poly: number }> = [];
+ let polygon: Array<{ cp: number; pv: number }> = [];
+ let polyIndex = 0;
for (let i = 0; i < rawPolyIndices.length; i++) {
const idx = rawPolyIndices[i]!;
- if (idx < 0) {
- // End of polygon: real index is -(idx + 1)
- polygon.push(-(idx + 1));
- triVertexIndexSequence.push(i);
-
- if (polygon.length >= 3) {
- for (let k = 1; k < polygon.length - 1; k++) {
- triangles.push([polygon[0]!, polygon[k]!, polygon[k + 1]!]);
- }
- }
- polygon = [];
- } else {
- polygon.push(idx);
- triVertexIndexSequence.push(i);
+ polygon.push({ cp: idx < 0 ? -(idx + 1) : idx, pv: i });
+ if (idx >= 0) continue;
+ for (let k = 1; k < polygon.length - 1; k++) {
+ for (const c of [polygon[0]!, polygon[k]!, polygon[k + 1]!])
+ corners.push({ ...c, poly: polyIndex });
}
+ polygon = [];
+ polyIndex++;
}
- const outPositions: number[] = [];
- const outNormals: number[] = [];
- const outUvs: number[] = [];
- const outIndices: number[] = [];
-
- for (let t = 0; t < triangles.length; t++) {
- const tri = triangles[t]!;
- for (let v = 0; v < 3; v++) {
- const vertIdx = tri[v]!;
- const outIdx = outPositions.length / 3;
-
- const px = rawVerts[vertIdx * 3] ?? 0;
- const py = rawVerts[vertIdx * 3 + 1] ?? 0;
- const pz = rawVerts[vertIdx * 3 + 2] ?? 0;
- outPositions.push(px, py, pz);
-
- // Normals
- if (rawNormals.length > 0) {
- const nx = rawNormals[vertIdx * 3] ?? 0;
- const ny = rawNormals[vertIdx * 3 + 1] ?? 0;
- const nz = rawNormals[vertIdx * 3 + 2] ?? 0;
- outNormals.push(nx, ny, nz);
- } else {
- outNormals.push(0, 0, 1);
- }
-
- // UVs
- if (rawUvs.length > 0) {
- let uvIdx = vertIdx;
- if (rawUvIndices.length > 0) {
- uvIdx = rawUvIndices[vertIdx] ?? vertIdx;
- }
- const u = rawUvs[uvIdx * 2] ?? 0;
- const v = rawUvs[uvIdx * 2 + 1] ?? 0;
- outUvs.push(u, 1.0 - v);
- } else {
- outUvs.push(0, 0);
- }
-
- outIndices.push(outIdx);
- }
- }
-
- // Generate normals if missing
- if (rawNormals.length === 0 || options.smoothNormals) {
- const computedNormals = new Float32Array(outPositions.length);
- for (let i = 0; i < outIndices.length; i += 3) {
- const i0 = outIndices[i]!;
- const i1 = outIndices[i + 1]!;
- const i2 = outIndices[i + 2]!;
-
- const p0: Vec3 = [
- outPositions[i0 * 3]!,
- outPositions[i0 * 3 + 1]!,
- outPositions[i0 * 3 + 2]!,
- ];
- const p1: Vec3 = [
- outPositions[i1 * 3]!,
- outPositions[i1 * 3 + 1]!,
- outPositions[i1 * 3 + 2]!,
- ];
- const p2: Vec3 = [
- outPositions[i2 * 3]!,
- outPositions[i2 * 3 + 1]!,
- outPositions[i2 * 3 + 2]!,
- ];
-
- const edge1 = Vector3Math.subtract(p1, p0);
- const edge2 = Vector3Math.subtract(p2, p0);
- const faceNormal = Vector3Math.cross(edge1, edge2);
-
- computedNormals[i0 * 3] += faceNormal[0];
- computedNormals[i0 * 3 + 1] += faceNormal[1];
- computedNormals[i0 * 3 + 2] += faceNormal[2];
-
- computedNormals[i1 * 3] += faceNormal[0];
- computedNormals[i1 * 3 + 1] += faceNormal[1];
- computedNormals[i1 * 3 + 2] += faceNormal[2];
-
- computedNormals[i2 * 3] += faceNormal[0];
- computedNormals[i2 * 3 + 1] += faceNormal[1];
- computedNormals[i2 * 3 + 2] += faceNormal[2];
- }
+ const numVerts = corners.length;
+ const outPositions = new Float32Array(numVerts * 3);
+ const outNormals = new Float32Array(numVerts * 3);
+ const outUvs = new Float32Array(numVerts * 2);
+ const outIndices = new Array<number>(numVerts);
+ corners.forEach(({ cp, pv, poly }, v) => {
+ outPositions[v * 3] = rawVerts[cp * 3] ?? 0;
+ outPositions[v * 3 + 1] = rawVerts[cp * 3 + 1] ?? 0;
+ outPositions[v * 3 + 2] = rawVerts[cp * 3 + 2] ?? 0;
+ const n = normalAt?.(cp, pv, poly);
+ outNormals.set(n ?? [0, 0, 1], v * 3);
+ const uv = uvAt?.(cp, pv, poly);
+ outUvs[v * 2] = uv?.[0] ?? 0;
+ outUvs[v * 2 + 1] = 1.0 - (uv?.[1] ?? 0);
+ outIndices[v] = v;
+ });
- for (let v = 0; v < outPositions.length / 3; v++) {
- const nx = computedNormals[v * 3]!;
- const ny = computedNormals[v * 3 + 1]!;
- const nz = computedNormals[v * 3 + 2]!;
- const len = Math.hypot(nx, ny, nz) || 1.0;
- outNormals[v * 3] = nx / len;
- outNormals[v * 3 + 1] = ny / len;
- outNormals[v * 3 + 2] = nz / len;
- }
+ if (!normalAt || options.smoothNormals) {
+ outNormals.fill(0);
+ accumulateVertexNormals(outPositions, outIndices, outNormals);
}
- // Find associated deformers/skins
+ // Skin: each cluster deforms the control points in its Indexes by its
+ // Weights, driven by the bone Model linked to it.
const skinConn = connections.find(
(c) =>
c.parentId === id &&
- objects.get(c.childId)?.type === "Deformer" &&
+ objects.get(c.childId)?.node.name === "Deformer" &&
objects.get(c.childId)?.node.props[2] === "Skin",
);
let jointIndices: Float32Array | undefined;
let jointWeights: Float32Array | undefined;
-
+ let skinIndex: number | undefined;
if (skinConn) {
- const numVerts = outPositions.length / 3;
- jointIndices = new Float32Array(numVerts * 4);
- jointWeights = new Float32Array(numVerts * 4);
-
- const clusterConns = connections.filter(
- (c) =>
- c.parentId === skinConn.childId &&
- objects.get(c.childId)?.type === "Deformer" &&
- objects.get(c.childId)?.node.props[2] === "Cluster",
- );
-
- clusterConns.forEach((cc, boneIdx) => {
- const clusterNode = objects.get(cc.childId)?.node;
- const indexesNode = clusterNode?.children.find(
- (c) => c.name === "Indexes",
+ const joints: number[] = [];
+ const inverseBinds: number[] = [];
+ // Per control point: up to 4 (joint, weight) influences.
+ const influences = new Map<number, Array<[number, number]>>();
+ for (const cc of connections) {
+ const cluster = objects.get(cc.childId);
+ if (
+ cc.parentId !== skinConn.childId ||
+ cluster?.node.name !== "Deformer" ||
+ cluster.node.props[2] !== "Cluster"
+ )
+ continue;
+ const boneId = connections.find(
+ (b) => b.parentId === cluster.id && nodeIndexById.has(b.childId),
+ )?.childId;
+ if (boneId === undefined) continue;
+ const joint = joints.length;
+ joints.push(nodeIndexById.get(boneId)!);
+ // Vertices sit in the mesh's bind space (Transform); the bone's
+ // bind-pose world matrix is TransformLink.
+ const transform = matrixChild(cluster.node, "Transform");
+ const link = matrixChild(cluster.node, "TransformLink");
+ inverseBinds.push(
+ ...Matrix4Math.multiply(
+ Matrix4Math.invert(link) ?? Matrix4Math.identity(),
+ transform,
+ ),
);
- const weightsNode = clusterNode?.children.find(
- (c) => c.name === "Weights",
+ const cpIndexes = extractArrayProp(
+ cluster.node.children.find((c) => c.name === "Indexes"),
);
-
- if (indexesNode && weightsNode) {
- const cIndexes = extractArrayProp(indexesNode);
- const cWeights = extractArrayProp(weightsNode);
-
- for (let k = 0; k < cIndexes.length; k++) {
- const weight = cWeights[k] ?? 0;
-
- // Apply weight to all duplicated vertices referencing originalVert
- for (let v = 0; v < numVerts; v++) {
- // Slot into lowest available slot in 4-component vector
- for (let slot = 0; slot < 4; slot++) {
- if (jointWeights![v * 4 + slot] === 0) {
- jointIndices![v * 4 + slot] = boneIdx;
- jointWeights![v * 4 + slot] = weight;
- break;
- }
- }
- }
- }
+ const cpWeights = extractArrayProp(
+ cluster.node.children.find((c) => c.name === "Weights"),
+ );
+ for (let k = 0; k < cpIndexes.length; k++) {
+ const weight = Number(cpWeights[k] ?? 0);
+ if (!(weight > 0)) continue;
+ const cp = Number(cpIndexes[k]);
+ const list = influences.get(cp) ?? [];
+ list.push([joint, weight]);
+ influences.set(cp, list);
}
- });
+ }
+ if (joints.length > MAX_JOINTS)
+ throw new Error(
+ `FBX skin has ${joints.length} bones; the mesh shader holds ${MAX_JOINTS}`,
+ );
+ if (joints.length > 0) {
+ skinIndex = skins.length;
+ skins.push({
+ joints,
+ inverseBindMatrices: new Float32Array(inverseBinds),
+ });
+ jointIndices = new Float32Array(numVerts * 4);
+ jointWeights = new Float32Array(numVerts * 4);
+ corners.forEach(({ cp }, v) => {
+ // The 4 strongest influences, renormalized to sum to 1.
+ const top = (influences.get(cp) ?? [])
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 4);
+ const total = top.reduce((sum, [, w]) => sum + w, 0);
+ top.forEach(([joint, weight], slot) => {
+ jointIndices![v * 4 + slot] = joint;
+ jointWeights![v * 4 + slot] = total > 0 ? weight / total : 0;
+ });
+ });
+ }
}
- const isLarge = outPositions.length / 3 > 65535;
+ const modelId = modelOfGeometry(id);
+ const isLarge = numVerts > 65535;
meshes.push({
id: `fbx_mesh_${id}`,
name: entry.name,
- positions: new Float32Array(outPositions),
- normals: new Float32Array(outNormals),
- uvs: new Float32Array(outUvs),
+ positions: outPositions,
+ normals: outNormals,
+ uvs: outUvs,
indices: isLarge
? new Uint32Array(outIndices)
: new Uint16Array(outIndices),
jointIndices,
jointWeights,
materialName: materialNameForGeometry(id) ?? entry.name,
+ node: modelId !== undefined ? nodeIndexById.get(modelId) : undefined,
+ skin: skinIndex,
});
}
}
@@ -799,6 +797,7 @@ export class FbxLoader {
string,
{
nodeName: string;
+ modelId: number | string | undefined;
model: FBXNode | undefined;
kind: TransformKind;
defaults: Vec3;
@@ -830,6 +829,7 @@ export class FbxLoader {
const model = targetModel?.node;
group = {
nodeName: targetModel?.name ?? curveNodeObj.name,
+ modelId: targetModel?.id,
model,
kind,
defaults: staticTransform(model, curveNodeObj.node, kind),
@@ -865,7 +865,19 @@ export class FbxLoader {
for (const group of groups.values()) {
const track = buildTransformTrack(group);
- if (track) tracks.push(track);
+ if (!track) continue;
+ if (group.modelId !== undefined)
+ track.node = nodeIndexById.get(group.modelId);
+ // Rotation keys are Lcl Rotation; the node also carries pre/post rotation.
+ if (track.rotations && group.model) {
+ for (let k = 0; k < track.rotations.length; k += 4) {
+ const q = Array.from(
+ track.rotations.subarray(k, k + 4),
+ ) as Quat;
+ track.rotations.set(modelRotation(group.model, q), k);
+ }
+ }
+ tracks.push(track);
}
}
@@ -886,58 +898,161 @@ export class FbxLoader {
}
}
- // Calculate bounds across all meshes
- let minX = Infinity;
- let minY = Infinity;
- let minZ = Infinity;
- let maxX = -Infinity;
- let maxY = -Infinity;
- let maxZ = -Infinity;
-
+ // Bounds of the meshes where the rest pose places them; centering and
+ // size become a root transform, since skinned vertices move with bones.
+ const model: Model3DData = {
+ meshes,
+ materials,
+ animations,
+ nodes,
+ skins,
+ bounds: {
+ min: [0, 0, 0],
+ max: [0, 0, 0],
+ center: [0, 0, 0],
+ size: [0, 0, 0],
+ boundingSphereRadius: 0,
+ },
+ };
+ const rest = poseNodes(model, undefined, 0);
+ const lo: Vec3 = [Infinity, Infinity, Infinity];
+ const hi: Vec3 = [-Infinity, -Infinity, -Infinity];
for (const mesh of meshes) {
+ const place = mesh.node !== undefined ? rest[mesh.node] : undefined;
for (let i = 0; i < mesh.positions.length; i += 3) {
- const x = mesh.positions[i]!;
- const y = mesh.positions[i + 1]!;
- const z = mesh.positions[i + 2]!;
- if (x < minX) minX = x;
- if (y < minY) minY = y;
- if (z < minZ) minZ = z;
- if (x > maxX) maxX = x;
- if (y > maxY) maxY = y;
- if (z > maxZ) maxZ = z;
+ const p: Vec3 = [
+ mesh.positions[i]!,
+ mesh.positions[i + 1]!,
+ mesh.positions[i + 2]!,
+ ];
+ const q = place ? Matrix4Math.projectPoint(place, p) : p;
+ for (let a = 0; a < 3; a++) {
+ if (q[a]! < lo[a]!) lo[a] = q[a]!;
+ if (q[a]! > hi[a]!) hi[a] = q[a]!;
+ }
}
}
-
- if (!Number.isFinite(minX)) {
- minX = -1;
- minY = -1;
- minZ = -1;
- maxX = 1;
- maxY = 1;
- maxZ = 1;
+ if (!Number.isFinite(lo[0])) {
+ lo.fill(-1);
+ hi.fill(1);
}
-
- const sizeX = maxX - minX;
- const sizeY = maxY - minY;
- const sizeZ = maxZ - minZ;
- const centerX = (minX + maxX) * 0.5;
- const centerY = (minY + maxY) * 0.5;
- const centerZ = (minZ + maxZ) * 0.5;
- const sphereRadius = Math.hypot(sizeX, sizeY, sizeZ) * 0.5;
-
- return {
- meshes,
- materials,
- animations,
- bounds: {
- min: [minX, minY, minZ],
- max: [maxX, maxY, maxZ],
- center: [centerX, centerY, centerZ],
- size: [sizeX, sizeY, sizeZ],
- boundingSphereRadius: sphereRadius,
+ const { offset, scale } = resolveModelTransform(
+ {
+ min: lo,
+ max: hi,
+ center: [
+ (lo[0] + hi[0]) * 0.5,
+ (lo[1] + hi[1]) * 0.5,
+ (lo[2] + hi[2]) * 0.5,
+ ],
+ size: [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]],
},
+ options,
+ );
+ model.rootTransform = Matrix4Math.multiply(
+ Matrix4Math.scale(scale[0], scale[1], scale[2]),
+ Matrix4Math.translate(-offset[0], -offset[1], -offset[2]),
+ );
+ const min: Vec3 = [0, 1, 2].map(
+ (a) => (lo[a]! - offset[a]!) * scale[a]!,
+ ) as Vec3;
+ const max: Vec3 = [0, 1, 2].map(
+ (a) => (hi[a]! - offset[a]!) * scale[a]!,
+ ) as Vec3;
+ model.bounds = {
+ min,
+ max,
+ center: [
+ (min[0] + max[0]) * 0.5,
+ (min[1] + max[1]) * 0.5,
+ (min[2] + max[2]) * 0.5,
+ ],
+ size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
+ boundingSphereRadius:
+ Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) * 0.5,
};
+ return model;
+ }
+}
+
+/** A Properties70 vector (Lcl Translation / Rotation / Scaling), `fallback` where absent. */
+function readVec3(node: FBXNode, name: string, fallback: number): Vec3 {
+ const v = readProperty70(node, name);
+ return [0, 1, 2].map((a) => {
+ const x = v?.[a];
+ return x !== undefined && Number.isFinite(x) ? x : fallback;
+ }) as Vec3;
+}
+
+function multiplyQuat(a: Quat, b: Quat): Quat {
+ return [
+ a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+ a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+ a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+ a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+ ];
+}
+
+/**
+ * A Model's full local rotation for an Lcl Rotation `q`:
+ * PreRotation · q · PostRotation⁻¹ (FBX always applies pre/post in XYZ order).
+ */
+function modelRotation(model: FBXNode, q: Quat): Quat {
+ const pre = readProperty70(model, "PreRotation");
+ const post = readProperty70(model, "PostRotation");
+ let out = q;
+ if (pre)
+ out = multiplyQuat(fbxEulerToQuat(readVec3(model, "PreRotation", 0)), out);
+ if (post) {
+ const p = fbxEulerToQuat(readVec3(model, "PostRotation", 0));
+ out = multiplyQuat(out, [-p[0], -p[1], -p[2], p[3]]);
}
+ return out;
+}
+
+/** A 4×4 matrix child (`Transform: *16 { a: … }`), identity when absent. */
+function matrixChild(node: FBXNode, name: string): Mat4 {
+ const child = node.children.find((c) => c.name === name);
+ const raw =
+ child?.children.find((c) => c.name === "a")?.props ?? child?.props;
+ const values =
+ raw?.[0] instanceof Float64Array || raw?.[0] instanceof Float32Array
+ ? Array.from(raw[0] as ArrayLike<number>)
+ : (raw ?? []).map(Number);
+ return values.length === 16 ? (values as Mat4) : Matrix4Math.identity();
+}
+
+/**
+ * A geometry layer (normals, UVs) as a lookup by corner: its mapping says
+ * whether values are per control point, per polygon vertex, per polygon or
+ * one for all; IndexToDirect layers go through their index array.
+ */
+function layerElement(
+ layer: FBXNode,
+ data: ArrayLike<number>,
+ index: ArrayLike<number>,
+ size: number,
+): ((cp: number, pv: number, poly: number) => number[]) | undefined {
+ if (data.length === 0) return undefined;
+ const text = (name: string) =>
+ String(layer.children.find((c) => c.name === name)?.props[0] ?? "");
+ const mapping = text("MappingInformationType");
+ const indexed =
+ /^Index/.test(text("ReferenceInformationType")) && index.length > 0;
+ return (cp, pv, poly) => {
+ let i =
+ mapping === "ByPolygonVertex"
+ ? pv
+ : mapping === "ByPolygon"
+ ? poly
+ : mapping === "AllSame"
+ ? 0
+ : cp; // ByControlPoint / ByVertice
+ if (indexed) i = Number(index[i] ?? i);
+ return Array.from({ length: size }, (_, c) =>
+ Number(data[i * size + c] ?? 0),
+ );
+ };
}
/** Which local transform an AnimationCurveNode drives. */
diff --git a/packages/webgpu-renderers/src/loaders/fbx-scene.test.ts b/packages/webgpu-renderers/src/loaders/fbx-scene.test.ts
new file mode 100644
index 00000000..a28d2cc1
--- /dev/null
+++ b/packages/webgpu-renderers/src/loaders/fbx-scene.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+import { FbxLoader } from "./fbx-loader.js";
+
+/**
+ * A quad (control points 0..3) on model "Body" (translated +5 x), skinned
+ * to bones "Root" and "Tip" (Tip: child of Root, 10 up, pre-rotated 90° z).
+ * UVs and normals are ByPolygonVertex; UVs through an index array. The
+ * polygon starts at control point 1, so polygon-vertex and control-point
+ * indices differ.
+ */
+const fbx = `
+; FBX 7.4.0 project file
+Objects: {
+ Geometry: 1001, "Geometry::Quad", "Mesh" {
+ Vertices: *12 {
+ a: -10,-10,0, 10,-10,0, 10,10,0, -10,10,0
+ }
+ PolygonVertexIndex: *4 {
+ a: 1,2,3,-1
+ }
+ LayerElementNormal: 0 {
+ MappingInformationType: "ByPolygonVertex"
+ ReferenceInformationType: "Direct"
+ Normals: *12 {
+ a: 1,0,0, 0,1,0, 0,0,1, 0,0,-1
+ }
+ }
+ LayerElementUV: 0 {
+ MappingInformationType: "ByPolygonVertex"
+ ReferenceInformationType: "IndexToDirect"
+ UV: *8 {
+ a: 0,0, 1,0, 1,1, 0,1
+ }
+ UVIndex: *4 {
+ a: 2,3,0,1
+ }
+ }
+ }
+ Model: 3001, "Model::Body", "Mesh" {
+ Properties70: {
+ P: "Lcl Translation", "Lcl Translation", "", "A",5,0,0
+ }
+ }
+ Model: 3002, "Model::Root", "LimbNode" {
+ }
+ Model: 3003, "Model::Tip", "LimbNode" {
+ Properties70: {
+ P: "PreRotation", "Vector3D", "Vector", "",0,0,90
+ P: "Lcl Translation", "Lcl Translation", "", "A",0,10,0
+ }
+ }
+ Deformer: 5001, "Deformer::Skin", "Skin" {
+ }
+ Deformer: 6001, "SubDeformer::Root", "Cluster" {
+ Indexes: *2 {
+ a: 0,1
+ }
+ Weights: *2 {
+ a: 1,1
+ }
+ }
+ Deformer: 6002, "SubDeformer::Tip", "Cluster" {
+ Indexes: *3 {
+ a: 1,2,3
+ }
+ Weights: *3 {
+ a: 0.5,2,1
+ }
+ Transform: *16 {
+ a: 1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1
+ }
+ TransformLink: *16 {
+ a: 1,0,0,0, 0,1,0,0, 0,0,1,0, 0,10,0,1
+ }
+ }
+ AnimationStack: 7001, "AnimStack::Wave", "" {
+ }
+ AnimationLayer: 7002, "AnimLayer::Base", "" {
+ }
+ AnimationCurveNode: 7003, "AnimCurveNode::R", "" {
+ }
+ AnimationCurve: 7004, "AnimCurve::", "" {
+ KeyTime: *2 {
+ a: 0,46186158000
+ }
+ KeyValueFloat: *2 {
+ a: 0,0
+ }
+ }
+}
+
+Connections: {
+ C: "OO", 1001, 3001
+ C: "OO", 3001, 0
+ C: "OO", 3002, 0
+ C: "OO", 3003, 3002
+ C: "OO", 5001, 1001
+ C: "OO", 6001, 5001
+ C: "OO", 6002, 5001
+ C: "OO", 3002, 6001
+ C: "OO", 3003, 6002
+ C: "OO", 7002, 7001
+ C: "OO", 7003, 7002
+ C: "OP", 7003, 3003, "Lcl Rotation"
+ C: "OP", 7004, 7003, "d|Z"
+}
+`;
+
+const SIN45 = Math.SQRT1_2;
+
+describe("FBX scene graph and skinning", () => {
+ const model = FbxLoader.parse(fbx);
+ const nodeIndex = (name: string) =>
+ model.nodes!.findIndex((n) => n.name === name);
+ const mesh = model.meshes[0]!;
+
+ it("reads ByPolygonVertex normals and IndexToDirect UVs per corner", () => {
+ // Corners: (cp1 pv0) (cp2 pv1) (cp3 pv2) | (cp1 pv0) (cp3 pv2) (cp0 pv3).
+ expect(Array.from(mesh.normals.slice(0, 9))).toEqual([
+ 1, 0, 0, 0, 1, 0, 0, 0, 1,
+ ]);
+ expect(Array.from(mesh.normals.slice(15, 18))).toEqual([0, 0, -1]);
+ // pv0 -> UV 2 = (1, 1), pv1 -> UV 3 = (0, 1); v is flipped.
+ expect(Array.from(mesh.uvs.slice(0, 4))).toEqual([1, 0, 0, 0]);
+ });
+
+ it("builds the Model hierarchy and places the mesh on its model", () => {
+ expect(model.nodes!.map((n) => n.name)).toEqual(["Body", "Root", "Tip"]);
+ expect(model.nodes![nodeIndex("Tip")]!.parent).toBe(nodeIndex("Root"));
+ expect(model.nodes![nodeIndex("Body")]!.translation).toEqual([5, 0, 0]);
+ expect(mesh.node).toBe(nodeIndex("Body"));
+ const q = model.nodes![nodeIndex("Tip")]!.rotation;
+ expect(q[2]).toBeCloseTo(SIN45, 6);
+ expect(q[3]).toBeCloseTo(SIN45, 6);
+ // Bounds include the model's translation.
+ expect(model.bounds.min[0]).toBeCloseTo(-5, 6);
+ expect(model.bounds.max[0]).toBeCloseTo(15, 6);
+ });
+
+ it("weights each control point by its clusters only, normalized, strongest first", () => {
+ expect(mesh.skin).toBe(0);
+ const skin = model.skins![0]!;
+ expect(skin.joints).toEqual([nodeIndex("Root"), nodeIndex("Tip")]);
+ const at = (corner: number) => ({
+ joints: Array.from(mesh.jointIndices!.slice(corner * 4, corner * 4 + 4)),
+ weights: Array.from(mesh.jointWeights!.slice(corner * 4, corner * 4 + 4)),
+ });
+ expect(at(5)).toEqual({ joints: [0, 0, 0, 0], weights: [1, 0, 0, 0] }); // cp0
+ const cp1 = at(0);
+ expect(cp1.joints.slice(0, 2)).toEqual([0, 1]);
+ expect(cp1.weights[0]).toBeCloseTo(2 / 3, 6);
+ expect(cp1.weights[1]).toBeCloseTo(1 / 3, 6);
+ expect(at(1)).toEqual({ joints: [1, 0, 0, 0], weights: [1, 0, 0, 0] }); // cp2
+ expect(at(2)).toEqual({ joints: [1, 0, 0, 0], weights: [1, 0, 0, 0] }); // cp3
+ });
+
+ it("takes inverse bind matrices from TransformLink and Transform", () => {
+ const ibm = model.skins![0]!.inverseBindMatrices;
+ expect(Array.from(ibm.slice(16 + 12, 16 + 15))).toEqual([0, -10, 0]);
+ });
+
+ it("targets animation tracks at their node, with the pre-rotation folded in", () => {
+ const track = model.animations[0]!.tracks[0]!;
+ expect(track.node).toBe(nodeIndex("Tip"));
+ expect(track.rotations![2]).toBeCloseTo(SIN45, 6);
+ expect(track.rotations![3]).toBeCloseTo(SIN45, 6);
+ });
+
+ it("centers and sizes through the root transform", () => {
+ const centered = FbxLoader.parse(fbx, { center: true, normalizeSize: 2 });
+ expect(centered.bounds.center[0]).toBeCloseTo(0, 6);
+ expect(Math.max(...centered.bounds.size)).toBeCloseTo(2, 6);
+ expect(centered.rootTransform?.[0]).toBeCloseTo(0.1, 6);
+ });
+});