@faicad/faijs 0.29.5 → 0.31.1

package/dist/mesh/threemf-loader.js

@@ -46,44 +46,53 @@ function hexToRgb(hex) {
         return null;
     return [parseInt(m[1], 16) / 255, parseInt(m[2], 16) / 255, parseInt(m[3], 16) / 255];
 }
-/** Bake a column-major ST_Matrix3D (translation = last three tokens) into positions. */
+/**
+ * Bake a 3MF ST_Matrix3D into positions.
+ *
+ * 3MF 约定（Core spec §4.3.1）：12 元组 **行主序** 3×4，平移在**末列**——token
+ * 序为 `m00 m01 m02 tx | m10 m11 m12 ty | m20 m21 m22 tz`，平移 = token[3]/[7]/[11]。
+ * 与写出器 `export-model.ts#transformToMatrix12`（同一行主序约定）必须同源，否则
+ * 写出 → 读回的 transform 会被旋转/平移错位（步骤 5 修复：此前本函数误用列主序）。
+ */
 function bakeTransform(positions, m) {
-    const [a, b, c, d, e, f, g, h, iz, p, q, r] = m;
+    const [a, b, c, d, e, f, g, h, i, j, k, l] = m;
     const out = new Float32Array(positions.length);
     for (let v = 0; v < positions.length; v += 3) {
         const x = positions[v];
         const y = positions[v + 1];
         const z = positions[v + 2];
-        out[v] = a * x + d * y + g * z + p;
-        out[v + 1] = b * x + e * y + h * z + q;
-        out[v + 2] = c * x + f * y + iz * z + r;
+        out[v] = a * x + b * y + c * z + d;
+        out[v + 1] = e * x + f * y + g * z + h;
+        out[v + 2] = i * x + j * y + k * z + l;
     }
     return out;
 }
 /**
- * Compose two ST_Matrix3D column-major transforms (12 tokens each, same
- * layout as `bakeTransform`: `[a b c, d e f, g h i, p q r]`, translation last).
+ * Compose two 3MF ST_Matrix3D transforms (12 tokens each, **row-major** 3×4,
+ * translation in the last column — same layout as `bakeTransform`).
  *
  * Semantics: the child transform is applied first, then the parent —
  * `M = parent · child` (the child lives in the parent's space, exactly like
- * three.js `clone.applyMatrix4(parent).applyMatrix4(child)`).
+ * three.js `clone.applyMatrix4(parent).applyMatrix4(child)`). For the 3×3 part
+ * `M_rot = parent_rot · child_rot`; for the translation
+ * `M_t = parent_rot · child_t + parent_t`.
  */
 function composeTransform(parent, child) {
-    const [a1, b1, c1, d1, e1, f1, g1, h1, i1, p1, q1, r1] = parent;
-    const [a2, b2, c2, d2, e2, f2, g2, h2, i2, p2, q2, r2] = child;
+    const [a1, b1, c1, d1, e1, f1, g1, h1, i1, j1, k1, l1] = parent;
+    const [a2, b2, c2, d2, e2, f2, g2, h2, i2, j2, k2, l2] = child;
     return [
-        a1 * a2 + d1 * b2 + g1 * c2,
-        b1 * a2 + e1 * b2 + h1 * c2,
-        c1 * a2 + f1 * b2 + i1 * c2,
-        a1 * d2 + d1 * e2 + g1 * f2,
-        b1 * d2 + e1 * e2 + h1 * f2,
-        c1 * d2 + f1 * e2 + i1 * f2,
-        a1 * g2 + d1 * h2 + g1 * i2,
-        b1 * g2 + e1 * h2 + h1 * i2,
-        c1 * g2 + f1 * h2 + i1 * i2,
-        a1 * p2 + d1 * q2 + g1 * r2 + p1,
-        b1 * p2 + e1 * q2 + h1 * r2 + q1,
-        c1 * p2 + f1 * q2 + i1 * r2 + r1,
+        a1 * a2 + b1 * e2 + c1 * i2,
+        a1 * b2 + b1 * f2 + c1 * j2,
+        a1 * c2 + b1 * g2 + c1 * k2,
+        a1 * d2 + b1 * h2 + c1 * l2 + d1,
+        e1 * a2 + f1 * e2 + g1 * i2,
+        e1 * b2 + f1 * f2 + g1 * j2,
+        e1 * c2 + f1 * g2 + g1 * k2,
+        e1 * d2 + f1 * h2 + g1 * l2 + h1,
+        i1 * a2 + j1 * e2 + k1 * i2,
+        i1 * b2 + j1 * f2 + k1 * j2,
+        i1 * c2 + j1 * g2 + k1 * k2,
+        i1 * d2 + j1 * h2 + k1 * l2 + l1,
     ];
 }
 /**
@@ -481,15 +490,26 @@ function parseModelMetadata(rootDoc) {
  *
  * `unit` is read from the ROOT model document (the file the build items
  * belong to); all documents share the same declared unit in practice.
+ * `forcedUnit`（opts.unit，用户显式指定）时**覆盖/忽略文件内部声明**——unit
+ * 参数对所有格式一视同仁：直接指定模型的源单位（unit-system §5.2），
+ * 未提供才回落到文件声明。
  */
-function parseModelXml(docTexts) {
+function parseModelXml(docTexts, forcedUnit) {
     // Last document = root model (caller appends it last).
     const rootDoc = docTexts[docTexts.length - 1];
-    const unitMatch = /<model\b[^>]*\bunit="([^"]+)"/.exec(rootDoc);
-    const unit = unitMatch ? unitMatch[1] : 'millimeter';
-    const unitName = threemfUnitToFaijs(unit);
-    if (unitName === null) {
-        throw new Error(`[mesh/threemf] unsupported <model unit>: ${JSON.stringify(unit)}`);
+    let unitName;
+    if (forcedUnit) {
+        // 强制设置模型单位：跳过文件声明（含非法声明）——用户显式指定优先。
+        unitName = forcedUnit;
+    }
+    else {
+        const unitMatch = /<model\b[^>]*\bunit="([^"]+)"/.exec(rootDoc);
+        const unit = unitMatch ? unitMatch[1] : 'millimeter';
+        const mapped = threemfUnitToFaijs(unit);
+        if (mapped === null) {
+            throw new Error(`[mesh/threemf] unsupported <model unit>: ${JSON.stringify(unit)}`);
+        }
+        unitName = mapped;
     }
     const scale = UNIT_SCALE[unitName];
     // 整体级元数据（`<model>` 直接子级 `<metadata>`；well-known 名映射到
@@ -513,13 +533,14 @@ function parseModelXml(docTexts) {
      * host's clone-and-apply semantics without shared geometry. `path` guards
      * reference cycles (a self-referencing component chain terminates).
      */
-    function materialize(src, mat, path) {
+    function materialize(src, mat, path, parentObjectId, componentIndex) {
         if (src.positions && src.indices) {
-            return [materializeMesh(src, mat)];
+            return [materializeMesh(src, mat, parentObjectId, componentIndex)];
         }
         if (src.components && src.components.length > 0) {
             const out = [];
-            for (const comp of src.components) {
+            for (let i = 0; i < src.components.length; i++) {
+                const comp = src.components[i];
                 if (path.has(comp.objectId))
                     continue;
                 const ref = byObjectId.get(comp.objectId);
@@ -530,7 +551,11 @@ function parseModelXml(docTexts) {
                     : mat;
                 const nextPath = new Set(path);
                 nextPath.add(comp.objectId);
-                out.push(...materialize(ref, next, nextPath));
+                // P4：把 build-item 的父对象 id 与组件序号透传到每个叶子实例——
+                // 嵌套组件逐层展开时沿用同一父（父 identity 属于 build item）。
+                const leafParentId = parentObjectId ?? src.id;
+                const leafCompIndex = componentIndex ?? i + 1;
+                out.push(...materialize(ref, next, nextPath, leafParentId, leafCompIndex));
             }
             return out;
         }
@@ -558,7 +583,7 @@ function parseModelXml(docTexts) {
             meta.metadata = src.metadata;
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
-    function materializeMesh(src, mat) {
+    function materializeMesh(src, mat, parentObjectId, componentIndex) {
         const positions = src.positions;
         const indices = src.indices;
         let pid;
@@ -613,6 +638,7 @@ function parseModelXml(docTexts) {
                 positions: mat ? bakeTransform(outPos, mat) : outPos,
                 indices: outIdx,
                 vertexColors: outCol,
+                ...(parentObjectId !== undefined ? { parentObjectId, componentIndex: componentIndex ?? 1 } : {}),
                 ...(srcMeta(src) ? { meta: srcMeta(src) } : {}),
             };
         }
@@ -703,6 +729,7 @@ function parseModelXml(docTexts) {
                 indices,
                 baseColor: baseColor ?? undefined,
                 ...(!singleFull && groups.length > 0 ? { materialGroups: groups } : {}),
+                ...(parentObjectId !== undefined ? { parentObjectId, componentIndex: componentIndex ?? 1 } : {}),
                 ...(srcMeta(src) ? { meta: srcMeta(src) } : {}),
             };
         }
@@ -711,6 +738,7 @@ function parseModelXml(docTexts) {
             name: src.name,
             positions: mat ? bakeTransform(positions, mat) : positions,
             indices,
+            ...(parentObjectId !== undefined ? { parentObjectId, componentIndex: componentIndex ?? 1 } : {}),
             ...(srcMeta(src) ? { meta: srcMeta(src) } : {}),
         };
     }
@@ -738,7 +766,8 @@ function parseModelXml(docTexts) {
         // malformed transforms are IGNORED (identity) — never bake NaN into
         // geometry (mirrors the host's fast-3mf tolerance contract).
         const tokens = parseTransformAttr(/\btransform="([^"]*)"/.exec(attrs)?.[1] ?? null);
-        out.push(...materialize(src, tokens ?? undefined, new Set([objId])));
+        // parentObjectId=objId；componentIndex 留给 materialize 按组件序推导（undefined）。
+        out.push(...materialize(src, tokens ?? undefined, new Set([objId]), objId, undefined));
     }
     if (itemCount === 0) {
         // No build items: emit every `<resources>` object directly (¶ the empty
@@ -747,10 +776,60 @@ function parseModelXml(docTexts) {
             out.push(...materialize(src, undefined, new Set([src.id])));
         }
     }
+    // 装配层级 + 局部几何（方案 §2.1 / 第 5 步「导入归一」）。
+    // `hierarchy`：build 顶层 item + 其 `<components>` 递归，节点带**相对父**位姿
+    // （行主序 3×4，平移末列——与写出器 `transformToMatrix12` 同源）。`localGeomById`：
+    // 未烘焙的局部几何（mesh 对象），供 assembly 重建（与 `out` 的已烘焙实例不同轴）。
+    const localGeomById = new Map();
+    for (const src of byObjectId.values()) {
+        if (src.positions && src.indices) {
+            localGeomById.set(src.id, materializeMesh(src, undefined));
+        }
+        else if (src.components && src.components.length > 0) {
+            localGeomById.set(src.id, { id: src.id, name: src.name, positions: new Float32Array(), indices: new Uint32Array() });
+        }
+    }
+    const nodeOf = (objId, tf, visited) => {
+        const src = byObjectId.get(objId);
+        const node = { objectId: objId };
+        if (tf)
+            node.transform = tf;
+        if (src?.components && src.components.length > 0) {
+            // 路径守卫：组件回指祖先（含自指）即时剪枝，避免无限递归（测试「component
+            // reference cycles terminate」）。被剪的重复引用不再展开为子节点。
+            const next = new Set(visited);
+            next.add(objId);
+            node.children = src.components
+                .filter((c) => !next.has(c.objectId))
+                .map((c) => nodeOf(c.objectId, c.transform ?? null, next));
+        }
+        return node;
+    };
+    const roots = [];
+    let hi;
+    const hItemRe = /<item\b[^>]*>/g;
+    while ((hi = hItemRe.exec(buildSec)) !== null) {
+        const objId = Number(/(?:^|\s)objectid="([^"]+)"/.exec(hi[0])?.[1]);
+        if (!byObjectId.has(objId))
+            continue;
+        const tf = parseTransformAttr(/\btransform="([^"]*)"/.exec(hi[0])?.[1] ?? null);
+        roots.push(nodeOf(objId, tf, new Set()));
+    }
+    if (roots.length === 0) {
+        for (const src of byObjectId.values())
+            roots.push(nodeOf(src.id, null, new Set()));
+    }
+    const hierarchy = roots;
     if (out.length === 0) {
         throw new Error('[mesh/threemf] no buildable geometry found in 3dmodel.model');
     }
-    return { unitName, objects: out, ...(fileMeta ? { fileMeta } : {}) };
+    return {
+        unitName,
+        objects: out,
+        hierarchy,
+        localGeomById,
+        ...(fileMeta ? { fileMeta } : {}),
+    };
 }
 /**
  * Parse 3MF bytes into a structured archive.
@@ -761,11 +840,17 @@ function parseModelXml(docTexts) {
  * (sub-models first, root last — root wins collisions).
  *
  * @param buffer - the raw .3mf (ZIP) bytes.
- * @returns an `ThreemfArchive` with mm-base per-instance objects, the declared
- *   source unit, and every non-model archive entry.
- * @throws when the buffer is not a 3MF/ZIP archive or the unit is invalid.
+ * @param opts - optional settings; `unit`（用户显式指定）**强制设置模型源单位**：
+ *   覆盖/忽略文件内部 `<model unit>` 声明（unit 对所有格式一视同仁，unit-system
+ *   §5.2）；未提供时读文件声明。无声明 → millimeter。
+ * @returns an `ThreemfArchive` with mm-base per-instance objects, the source
+ *   unit (forced value when provided, else the file declaration), and every
+ *   non-model archive entry.
+ * @throws when the buffer is not a 3MF/ZIP archive or the unit is invalid
+ *   (no forced unit → an unsupported declaration throws; forced unit skips
+ *   declaration parsing entirely).
  */
-export async function parseThreemf(buffer) {
+export async function parseThreemf(buffer, opts) {
     let entries;
     try {
         entries = readZipEntries(new Uint8Array(buffer));
@@ -787,7 +872,7 @@ export async function parseThreemf(buffer) {
     }
     docKeys.push(rootKey);
     const docTexts = docKeys.map((k) => new TextDecoder().decode(entries.get(k)));
-    const parsed = parseModelXml(docTexts);
+    const parsed = parseModelXml(docTexts, opts?.unit);
     // `extraEntries` = everything that is NOT a model document — Bambu's
     // `Metadata/model_settings.config`, `Metadata/project_settings.config`,
     // `Metadata/thumbnail.png`, etc.
@@ -797,6 +882,19 @@ export async function parseThreemf(buffer) {
             continue;
         extraEntries.set(k, v);
     }
-    return { unit: parsed.unitName, objects: parsed.objects, extraEntries, ...(parsed.fileMeta ? { fileMeta: parsed.fileMeta } : {}) };
+    return {
+        unit: parsed.unitName,
+        objects: parsed.objects,
+        // 装配层级 + 局部几何（方案 §2.1 / 第 5 步「导入归一」）：3MF `<components>`
+        // 重建 CompoundShape 时需要的相对父位姿树与未烘焙局部几何（与 `objects` 的
+        // 已烘焙实例不同轴）。必须透传，否则 importFile 拿不到 assembly。
+        ...(parsed.hierarchy ? { hierarchy: parsed.hierarchy } : {}),
+        ...(parsed.localGeomById ? { localGeomById: parsed.localGeomById } : {}),
+        extraEntries,
+        // P4：根 model XML（Bambu 层解析 build items / 父对象 components 需要；
+        // 根 model 不在 extraEntries——extraEntries 只收非 model 条目）。
+        ...(rootKey ? { modelXml: new TextDecoder().decode(entries.get(rootKey)) } : {}),
+        ...(parsed.fileMeta ? { fileMeta: parsed.fileMeta } : {}),
+    };
 }
 //# sourceMappingURL=threemf-loader.js.map