@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/models/src/fbx/interpreter/global-settings.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// FBX GlobalSettings — UpAxis, UnitScaleFactor, rotation order
+// ============================================================================
+// Extracts coordinate system and unit information from the GlobalSettings
+// node. The parser does NOT convert vertices — that's the normalization
+// layer's job, which respects sidecar overrides.
+//
+import { childNode } from "../types.js";
+/**
+ * Parse GlobalSettings from the FBX node tree.
+ *
+ * FBX UpAxis values:
+ *   0 = Y-up (Maya default, X-right, Z-forward)
+ *   1 = Y-up (3ds Max, X-forward, Z-right) — still Y-up
+ *   2 = Z-up (Blender / Maya Z-up, X-right, Y-forward)
+ *
+ * FBX UnitScaleFactor (units per centimeter):
+ *   1.0   → centimeters (Maya default)
+ *   0.1   → millimeters
+ *   2.54  → inches
+ *   100   → meters
+ */
+export function parseGlobalSettings(nodes, diag) {
+    const globalSettings = nodes.find((n) => n.name === "GlobalSettings");
+    if (!globalSettings) {
+        return { upAxis: "y", unitScaleFactor: undefined, units: "centimeters", rotationOrder: 0 };
+    }
+    const props70 = childNode(globalSettings, "Properties70");
+    if (!props70) {
+        return { upAxis: "y", unitScaleFactor: undefined, units: "centimeters", rotationOrder: 0 };
+    }
+    let upAxis = "y";
+    let unitScaleFactor;
+    let rotationOrder = 0;
+    for (let _i = 0, _it = props70.children, _n = _it.length; _i < _n; _i++) {
+        const p = _it[_i];
+        if (p.name !== "P" || p.properties.length < 5)
+            continue;
+        const propName = String(p.properties[0].value);
+        if (propName === "UpAxis") {
+            const val = p.properties[4].value;
+            upAxis = val === 2 ? "z" : "y";
+            diag.debug("global-settings", `UpAxis = ${val}`);
+        }
+        else if (propName === "UnitScaleFactor") {
+            unitScaleFactor = p.properties[4].value;
+            diag.debug("global-settings", `UnitScaleFactor = ${unitScaleFactor}`);
+        }
+        else if (propName === "RotationOrder") {
+            // RotationOrder is a 4th property (index 3) in some FBX versions,
+            // but usually it's at index 4 like other properties.
+            if (p.properties.length >= 5) {
+                rotationOrder = p.properties[4].value;
+            }
+        }
+    }
+    const units = classifyFBXUnits(unitScaleFactor);
+    return { upAxis, unitScaleFactor, units, rotationOrder };
+}
+/**
+ * Classify a raw FBX UnitScaleFactor (units per cm) into our UnitSystem enum.
+ * Falls back to "units" if the value doesn't match a known unit.
+ */
+function classifyFBXUnits(unitScaleFactor) {
+    if (unitScaleFactor === undefined)
+        return "centimeters"; // FBX default is cm
+    // Common values: 0.1=mm, 1=cm, 2.54=in, 100=m
+    if (Math.abs(unitScaleFactor - 100) < 0.01)
+        return "meters";
+    if (Math.abs(unitScaleFactor - 1) < 0.01)
+        return "centimeters";
+    if (Math.abs(unitScaleFactor - 2.54) < 0.01)
+        return "inches";
+    if (Math.abs(unitScaleFactor - 0.1) < 0.01)
+        return "millimeters";
+    return "units";
+}

package/dist/libraries/models/src/fbx/interpreter/materials.js

@@ -0,0 +1,231 @@
+// ============================================================================
+// FBX Materials + Textures — MaterialData[] extraction
+// ============================================================================
+// Extracts material colors and textures from Material/Video/Texture nodes
+// via the connection graph. Maps FBX Phong/Lambert properties to our
+// MaterialData (baseColor, metallic, roughness, emissive, textures).
+//
+import { childNode, findNodesInTree } from "../types.js";
+import { getObjectId } from "./connections.js";
+/**
+ * Parse all materials from the FBX node tree.
+ *
+ * @returns MaterialData[] and a map of material node index → texture info.
+ */
+export function parseMaterials(nodes, graph, diag) {
+    const materialNodes = findNodesInTree(nodes, "Material");
+    if (materialNodes.length === 0) {
+        return { materials: undefined, materialTextures: new Map() };
+    }
+    const videoNodes = findNodesInTree(nodes, "Video");
+    const textureNodes = findNodesInTree(nodes, "Texture");
+    // Build video info map: videoId → { data?, filename? }
+    const videoInfo = new Map();
+    for (let i = 0; i < videoNodes.length; i++) {
+        const node = videoNodes[i];
+        const id = getObjectId(node, `video_${i}`);
+        const info = extractVideoInfo(node);
+        if (info.data || info.filename) {
+            videoInfo.set(id, info);
+        }
+    }
+    // Build texture → video mapping via connections
+    const textureToVideo = new Map();
+    for (let i = 0; i < textureNodes.length; i++) {
+        const texId = getObjectId(textureNodes[i], `tex_${i}`);
+        // Connection can be either direction: Texture→Video or Video→Texture
+        for (let _i = 0, _it = graph.connections, _n = _it.length; _i < _n; _i++) {
+            const conn = _it[_i];
+            if (conn.childId === texId && videoInfo.has(conn.parentId)) {
+                textureToVideo.set(texId, conn.parentId);
+                break;
+            }
+            if (conn.parentId === texId && videoInfo.has(conn.childId)) {
+                textureToVideo.set(texId, conn.childId);
+                break;
+            }
+        }
+    }
+    // Build material index → texture info via OP connections
+    const materialTextures = new Map();
+    const materials = [];
+    for (let i = 0; i < materialNodes.length; i++) {
+        const matNode = materialNodes[i];
+        const matId = getObjectId(matNode, `mat_${i}`);
+        const matName = extractMaterialName(matNode, `material_${i}`);
+        // Extract material color from Properties70
+        const props = extractMaterialProperties(matNode);
+        // Find connected textures
+        const texInfo = {};
+        for (let _i = 0, _it = graph.connections, _n = _it.length; _i < _n; _i++) {
+            const conn = _it[_i];
+            if (conn.parentId !== matId)
+                continue;
+            const videoId = textureToVideo.get(conn.childId);
+            if (!videoId)
+                continue;
+            const info = videoInfo.get(videoId);
+            if (!info)
+                continue;
+            const propLower = (conn.property ?? "").toLowerCase();
+            if (propLower.includes("diffuse") || conn.property === "") {
+                if (info.data)
+                    texInfo.textureData = info.data;
+                if (info.filename) {
+                    texInfo.textureUri = info.filename.replace(/[\\/]/g, "/").split("/").pop() ?? info.filename;
+                }
+            }
+            else if (propLower.includes("normal") || propLower.includes("bump")) {
+                if (info.filename) {
+                    texInfo.normalTextureUri = info.filename.replace(/[\\/]/g, "/").split("/").pop() ?? info.filename;
+                }
+            }
+            else if (propLower.includes("emissive")) {
+                if (info.filename) {
+                    texInfo.emissiveTextureUri = info.filename.replace(/[\\/]/g, "/").split("/").pop() ?? info.filename;
+                }
+            }
+        }
+        if (texInfo.textureData || texInfo.textureUri || texInfo.normalTextureUri || texInfo.emissiveTextureUri) {
+            materialTextures.set(i, texInfo);
+        }
+        materials.push({
+            name: matName,
+            baseColor: [props.diffuse[0], props.diffuse[1], props.diffuse[2], props.opacity ?? 1],
+            metallic: 0,
+            roughness: 1,
+            textureData: texInfo.textureData
+                ? texInfo.textureData.slice().buffer
+                : null,
+            textureUri: texInfo.textureUri,
+            normalTextureUri: texInfo.normalTextureUri,
+            emissiveColor: props.emissive,
+        });
+    }
+    diag.debug("materials", `Parsed ${materials.length} materials, ${materialTextures.size} with textures`);
+    return { materials, materialTextures };
+}
+/** Extract embedded content and filename from a Video node. */
+function extractVideoInfo(node) {
+    let data;
+    let filename;
+    node.children.forEach((child) => {
+        const childNameLower = child.name.toLowerCase();
+        if (childNameLower === "content" && child.properties.length > 0) {
+            const prop = child.properties[0];
+            if (prop.type === "R" && prop.value instanceof Uint8Array && prop.value.length > 0) {
+                data = prop.value;
+            }
+        }
+        else if (childNameLower === "filename" && child.properties.length > 0) {
+            filename = String(child.properties[0].value);
+        }
+        else if (childNameLower === "relativefilename" && child.properties.length > 0 && !filename) {
+            filename = String(child.properties[0].value);
+        }
+    });
+    // Also check the Video node's own properties for a filename
+    if (!filename && node.properties.length >= 2) {
+        for (let _i = 0, _it = node.properties, _n = _it.length; _i < _n; _i++) {
+            const prop = _it[_i];
+            if (prop.type === "S") {
+                const val = String(prop.value);
+                if (val.match(/\.(png|jpg|jpeg|tga|bmp|webp)$/i)) {
+                    filename = val;
+                    break;
+                }
+            }
+        }
+    }
+    return { data, filename };
+}
+/** Extract the material name from a Material node. */
+function extractMaterialName(node, fallback) {
+    if (node.properties.length >= 2 && node.properties[1].type === "S") {
+        return String(node.properties[1].value);
+    }
+    return fallback;
+}
+/** Convert a single linear-space channel to sRGB for display. */
+function linearToSrgb(c) {
+    return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+/** Convert a linear-space [r, g, b] color to sRGB. */
+function linearColorToSrgb(rgb) {
+    return [linearToSrgb(rgb[0]), linearToSrgb(rgb[1]), linearToSrgb(rgb[2])];
+}
+/** Extract diffuse color, emissive color, and opacity from a Material node's Properties70.
+ *
+ * Blender 4.x exports DiffuseColor in linear space (see Blender bug #128498).
+ * The renderer's shader does simple sRGB-space multiplication (texture ×
+ * vertexColor × lighting × baseColor) and outputs to a non-sRGB swapchain.
+ * Textures are sRGB (rgba8unorm). To keep solid colors consistent with
+ * textured colors, we convert DiffuseColor/EmissiveColor from linear to sRGB
+ * here, so the shader can treat all inputs uniformly as sRGB.
+ *
+ * Transparency handling: FBX/3ds Max uses two conventions — `TransparencyFactor`
+ * (0 = opaque, 1 = transparent) and `Opacity` (0 = transparent, 1 = opaque).
+ * Both are normalized to the `Opacity` convention (alpha) on output.
+ */
+export function extractMaterialProperties(node) {
+    const props70 = childNode(node, "Properties70");
+    if (!props70)
+        return { diffuse: [1, 1, 1] };
+    let diffuse = [1, 1, 1];
+    let emissive;
+    let emissiveFactor;
+    let opacity;
+    for (let _i = 0, _it = props70.children, _n = _it.length; _i < _n; _i++) {
+        const p = _it[_i];
+        if (p.name !== "P" || p.properties.length < 5)
+            continue;
+        const propName = String(p.properties[0].value);
+        const propLower = propName.toLowerCase();
+        if (propLower === "diffuse" || propLower === "diffusecolor" || propLower === "color") {
+            diffuse = linearColorToSrgb([
+                p.properties[4].value,
+                p.properties[5].value,
+                p.properties[6].value,
+            ]);
+        }
+        else if (propLower === "emissive" || propLower === "emissivecolor") {
+            emissive = linearColorToSrgb([
+                p.properties[4].value,
+                p.properties[5].value,
+                p.properties[6].value,
+            ]);
+        }
+        else if (propLower === "emissivefactor") {
+            // Effective emission is color × factor — exporters (Blender 4.x) write
+            // EmissiveColor=(1,1,1) with EmissiveFactor=0 when emission is unused,
+            // which would otherwise render the material fully white.
+            emissiveFactor = p.properties[4].value;
+        }
+        else if (propLower === "transparencyfactor") {
+            // TransparencyFactor uses the 3ds Max convention: 0 = opaque, 1 = fully
+            // transparent. Convert to opacity (alpha) so the rest of the pipeline
+            // can treat `opacity` uniformly as 0 = transparent, 1 = opaque.
+            opacity = 1 - p.properties[4].value;
+        }
+        else if (propLower === "opacity") {
+            // Opacity is already in alpha convention: 0 = transparent, 1 = opaque.
+            opacity = p.properties[4].value;
+        }
+    }
+    if (emissive && emissiveFactor !== undefined) {
+        emissive = [emissive[0] * emissiveFactor, emissive[1] * emissiveFactor, emissive[2] * emissiveFactor];
+        if (emissive[0] <= 0 && emissive[1] <= 0 && emissive[2] <= 0)
+            emissive = undefined;
+    }
+    return { diffuse, emissive, opacity };
+}
+/**
+ * Get the diffuse color for a material index.
+ * Used by the geometry interpreter for vertex colors when no texture is present.
+ */
+export function getMaterialColor(materialIndex, materials) {
+    if (!materials || materialIndex >= materials.length)
+        return [1, 1, 1];
+    const mat = materials[materialIndex];
+    return [mat.baseColor[0], mat.baseColor[1], mat.baseColor[2]];
+}

package/dist/libraries/models/src/fbx/interpreter/nodes.js

@@ -0,0 +1,168 @@
+// ============================================================================
+// FBX Node Hierarchy — Model objects → ModelNode[]
+// ============================================================================
+// Builds the node hierarchy from Model objects and OO connections.
+// Applies semantic normalizations:
+//   - Strip "Model" suffix from node names (FBX naming quirk)
+//   - Normalize Mixamo namespace variant: mixamorig7: → mixamorig:
+//
+// The parser emits clean node names so downstream code (skeleton-animator,
+// animation retargeting) doesn't need to strip FBX naming quirks.
+//
+import { childNode, findNodesInTree } from "../types.js";
+import { getObjectId, getObjectName } from "./connections.js";
+/**
+ * Normalize a node name:
+ * - Strip trailing "Model" suffix (FBX Model nodes often have names like
+ *   "CubeModel" — the actual object name is "Cube")
+ * - Normalize Mixamo namespace variant: mixamorig7: → mixamorig:
+ */
+export function normalizeNodeName(name) {
+    let result = name;
+    // Strip "Model" suffix
+    if (result.endsWith("Model")) {
+        result = result.slice(0, -5);
+    }
+    // Normalize Mixamo namespace variant
+    if (result.startsWith("mixamorig7:")) {
+        result = "mixamorig:" + result.substring(11);
+    }
+    return result;
+}
+/**
+ * Build the ModelNode[] hierarchy from Model objects and connections.
+ *
+ * Each Model object becomes a ModelNode with translation, rotation, and scale
+ * extracted from Properties70. PreRotation and LclRotation are combined into
+ * a single rotation quaternion.
+ *
+ * @param nodes The full FBX node tree.
+ * @param graph The connection graph.
+ * @param diag Diagnostics collector.
+ * @returns The node hierarchy, or undefined if no Model objects.
+ */
+export function parseNodeHierarchy(nodes, graph, diag) {
+    const modelNodes = findNodesInTree(nodes, "Model");
+    if (modelNodes.length === 0)
+        return undefined;
+    const result = [];
+    const idToIndex = new Map();
+    // First pass: create ModelNode entries for each Model object
+    for (let i = 0; i < modelNodes.length; i++) {
+        const node = modelNodes[i];
+        const id = getObjectId(node, `model_${i}`);
+        const rawName = getObjectName(node, `node_${i}`);
+        const nodeName = normalizeNodeName(rawName);
+        const props = extractNodeProperties(node);
+        idToIndex.set(id, i);
+        result.push({
+            name: nodeName,
+            translation: props.translation,
+            rotation: props.rotation,
+            scale: props.scale,
+            nodeIndex: i,
+        });
+    }
+    // Second pass: build children indices using the connection graph
+    let matched = 0;
+    let unmatched = 0;
+    for (let i = 0; i < modelNodes.length; i++) {
+        const id = getObjectId(modelNodes[i], `model_${i}`);
+        const parentId = graph.getHierarchyParent(id);
+        if (parentId && idToIndex.has(parentId)) {
+            const parentIdx = idToIndex.get(parentId);
+            if (!result[parentIdx].children)
+                result[parentIdx].children = [];
+            result[parentIdx].children.push(i);
+            matched++;
+        }
+        else {
+            unmatched++;
+            if (unmatched <= 3) {
+                diag.debug("nodes", `Node ${i} id=${id} name=${result[i].name}: no hierarchy parent found`);
+            }
+        }
+    }
+    diag.debug("nodes", `Hierarchy: ${matched} matched, ${unmatched} unmatched, ${idToIndex.size} model IDs`);
+    return result;
+}
+/** Extract Lcl Translation, Lcl Rotation, PreRotation, and Lcl Scaling from a Model node. */
+function extractNodeProperties(node) {
+    const props70 = childNode(node, "Properties70");
+    if (!props70)
+        return {};
+    let translation;
+    let lclRotation;
+    let preRotation;
+    let scale;
+    for (let _i = 0, _it = props70.children, _n = _it.length; _i < _n; _i++) {
+        const p = _it[_i];
+        if (p.name !== "P" || p.properties.length < 5)
+            continue;
+        const propName = String(p.properties[0].value);
+        if (propName === "Lcl Translation") {
+            translation = [
+                p.properties[4].value,
+                p.properties[5].value,
+                p.properties[6].value,
+            ];
+        }
+        else if (propName === "Lcl Rotation") {
+            lclRotation = eulerToQuaternion(p.properties[4].value, p.properties[5].value, p.properties[6].value);
+        }
+        else if (propName === "PreRotation") {
+            preRotation = eulerToQuaternion(p.properties[4].value, p.properties[5].value, p.properties[6].value);
+        }
+        else if (propName === "Lcl Scaling") {
+            scale = [
+                p.properties[4].value,
+                p.properties[5].value,
+                p.properties[6].value,
+            ];
+        }
+    }
+    // Combine PreRotation * LclRotation
+    let rotation;
+    if (preRotation && lclRotation) {
+        rotation = qmul(preRotation, lclRotation);
+    }
+    else if (preRotation) {
+        rotation = preRotation;
+    }
+    else if (lclRotation) {
+        rotation = lclRotation;
+    }
+    return { translation, rotation, scale };
+}
+/**
+ * Convert Euler angles (degrees) to a quaternion.
+ * FBX default rotation order is 0 = XYZ (extrinsic).
+ * Extrinsic XYZ means: rotate around fixed X, then fixed Y, then fixed Z.
+ * This is equivalent to intrinsic ZYX, and the quaternion is q = qz * qy * qx.
+ */
+function eulerToQuaternion(exDeg, eyDeg, ezDeg) {
+    const ex = (exDeg * Math.PI) / 180;
+    const ey = (eyDeg * Math.PI) / 180;
+    const ez = (ezDeg * Math.PI) / 180;
+    const cx = Math.cos(ex / 2), sx = Math.sin(ex / 2);
+    const cy = Math.cos(ey / 2), sy = Math.sin(ey / 2);
+    const cz = Math.cos(ez / 2), sz = Math.sin(ez / 2);
+    // q = qz * qy * qx (extrinsic XYZ = FBX default rotation order 0)
+    return [
+        sx * cy * cz - cx * sy * sz,
+        cx * sy * cz + sx * cy * sz,
+        cx * cy * sz - sx * sy * cz,
+        cx * cy * cz + sx * sy * sz,
+    ];
+}
+/** Quaternion multiplication: a * b. */
+function qmul(a, b) {
+    const [ax, ay, az, aw] = a;
+    const [bx, by, bz, bw] = b;
+    return [
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    ];
+}