@faicad/faijs 0.30.9 → 0.31.1

package/dist/mesh/io.js

@@ -6,17 +6,25 @@
  * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。
  *
  * 单位换算边界（unit-system §5.2）：
- * - STL 无单位元数据 → 由 `opts.unit` 显式声明优先；未声明时 faijs 按历史
- *   host 行为做启发式猜测（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
- *   迁移回归的单位断言依赖此行为）。猜测收敛在 faijs 内（红线 R0：宿主不
- *   自实现单位换算），G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - 本模块只处理 **mesh 格式（STL/3MF）**，坐标可直接折算 → `opts.unit` 提供即
+ *   **强制设置模型的源单位**（直接指定，覆盖/忽略模型内部记录的单位——STL 无
+ *   内部单位、3MF `<model unit>` 声明被覆盖），按 `unitScale(unit)` 折算坐标。
+ *   它**只可能来自调用方的显式知识**（脚本作者手写 `cad.load({ file, unit })`、
+ *   或宿主让用户选定单位后传入）；调用方不知道单位时**必须省略**——省略时：
+ *   STL 走 faijs 启发式（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
+ *   迁移回归的单位断言依赖此行为）、3MF 走文件 `<model unit>`（无声明 →
+ *   millimeter）。猜测/折算收敛在 faijs 内（红线 R0：宿主不自实现单位换算），
+ *   G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - **STEP/.brep 不经过本模块**（走 BREP 链，load op 内 OCCT 读取）：OCCT 按
+ *   文件内部单位声明折算（SI_UNIT），**不支持强制设置单位**——load op 对
+ *   BREP 路径 + 用户显式 unit 直接**明确报错**（不缩放、不 workaround）。
  * - 3MF `<model unit>` 由解析器读取并换算（micron/mm/cm/inch/foot/meter）。
  *
  * 返回契约（unit-system §10.6）：`importFile` 返回 `{ shape, unit }` — `unit`
- * 是文件源单位（必然有值；faijs 是单一真源）：3MF/STEP 取文件声明（STEP 无声明
- * → 'mm'，与 OCCT 一致），STL 取 opts.unit 或 guessStlUnit 启发式猜测。坐标恒
- * 为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不参与几何
- * 缩放（读入折算已由内核/解析器完成，二次缩放 = 双重换算）。
+ * 是文件源单位（必然有值；faijs 是单一真源）：3MF 取 opts.unit（强制）或文件
+ * 声明（无声明 → millimeter），STL 取 opts.unit 或 guessStlUnit 启发式猜测。
+ * 坐标恒为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不
+ * 参与几何缩放（读入折算已由解析器完成，二次缩放 = 双重换算）。
  */
 import { geoToManifoldMesh } from '../boolean/geo-convert.js';
 import { parseStl } from './stl-loader.js';
@@ -97,17 +105,25 @@ export function detectStepUnit(stepText) {
  * @param buffer - the raw file bytes to parse (already decompressed; stpz
  *   unzipping is the caller's job — faijs never unzips implicitly).
  * @param format - format identifier such as 'stl', '3mf'/'threemf' or 'step'
- *   (defaults to 'stl').
- * @param opts - optional settings; `unit` (a UnitName string) declares the
- *   source unit for formats without unit metadata (e.g. STL). Defaults to
- *   the guessStlUnit heuristic when omitted.
+ *   (defaults to 'stl'). **仅 mesh 格式（STL/3MF）走本模块**；STEP/BREP 走
+ *   BREP 链（load op 内 OCCT 读取，不支持强制设置单位）。
+ * @param opts - optional settings; `unit` (a UnitName string) **force-sets the
+ *   model's source unit** (STL/3MF): it is NOT a default, it directly specifies
+ *   the unit and overrides/ignores any unit recorded inside the model (3MF
+ *   `<model unit>`; STL has none), geometry scaled by `unitScale(unit)`. Only
+ *   provide it when the caller actually knows the unit (author-written
+ *   `cad.load({ file, unit })`, or a host unit picker). When the caller does
+ *   NOT know the unit, it MUST omit `unit` — STL then guesses via
+ *   `guessStlUnit` (the only allowed guessing path), 3MF uses the file
+ *   declaration (none → millimeter). A wrong explicit unit scales geometry
+ *   wrongly and is never re-guessed.
  * @returns the shape with base-unit coordinates plus the file's source unit
  *   (`unit`, metadata only; always present — faijs is the single source of truth).
  */
 export async function importFile(buffer, format, opts) {
     const fmt = (format ?? 'stl').toLowerCase();
     if (fmt === '3mf' || fmt === 'threemf') {
-        const archive = await parseThreemf(buffer);
+        const archive = await parseThreemf(buffer, opts);
         // P0（方案 §5.4）：不再折叠——返回全部 `<build><item>` 对象（declaration order，
         // 坐标已在 parseThreemf 里折算为 faijs 基准单位）。`shape` 保留为 parts[0]
         // （单零件兼容，过渡期）。
@@ -153,6 +169,11 @@ export async function importFile(buffer, format, opts) {
         const bambuViews = buildBambuViews(bambu);
         if (bambuViews)
             importModel.bambuViews = bambuViews;
+        // 装配层级重建（方案 §2.1 / 第 5 步）：含 `<components>` 时还原 CompoundShape，
+        // 叶节点携带相对父 transform；单零件平铺导入不挂载。
+        const assembly = archive.hierarchy && archive.localGeomById
+            ? buildAssemblyFromArchive(archive.hierarchy, archive.localGeomById)
+            : undefined;
         return {
             shape: parts[0],
             parts,
@@ -161,6 +182,7 @@ export async function importFile(buffer, format, opts) {
             importModel,
             // 整体级元数据（`<model><metadata>`）随导入结果上抛（方案 §5.1）。
             ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),
+            ...(assembly ? { assembly } : {}),
         };
     }
     if (fmt === 'stl') {
@@ -226,6 +248,48 @@ function threemfObjectToShape(obj) {
         ...(obj.meta ? { meta: obj.meta } : {}),
     };
 }
+/**
+ * 由 3MF 装配层级重建 `CompoundShape`（方案 §2.1 / 第 5 步「导入归一」）。
+ *
+ * 见 `ThreemfArchive.hierarchy` / `localGeomById`：节点带**相对父**位姿（行主序 3×4，
+ * 平移在末列，与写出器 `transformToMatrix12` 同源）；几何来自 `localGeomById` 的**未烘焙**
+ * 局部网格。叶节点的最终 `Shape.transform` 即该相对位姿（写回 `Shape.transform`，供
+ * 后续导出按 3MF `<component transform>` 原样还原——D1 往返）。容器节点落为
+ * `CompoundShape`（不含 `transform` / `meta`，与 `shape.ts` 的 `CompoundShape` 形态一致）。
+ *
+ * 注：`shape.ts` 的 `CompoundShape.children` 当前声明为 `Shape[]`（非递归），故嵌套装配
+ * 在类型层面暂不表达；运行时子节点可为子 `CompoundShape`（由 `isCompoundLike` 结构判定消费）。
+ * 把 `CompoundShape` 改为递归类型是独立的后续重构（会波及 faijs-extra / cad-runtime），本步
+ * 以最小改动桥接——见下方 `children` 处的收窄断言。
+ *
+ * 仅在存在真实装配（多 item 或任一 item 带 components）时返回非空；单零件平铺导入返回
+ * `undefined`（由调用方决定是否挂载到 `result.assembly`，避免改变单零件结果形状）。
+ */
+function buildAssemblyFromArchive(hierarchy, localGeomById) {
+    const hasHierarchy = hierarchy.length > 1 || hierarchy.some((n) => (n.children?.length ?? 0) > 0);
+    if (!hasHierarchy)
+        return undefined;
+    const buildNode = (node) => {
+        const obj = localGeomById.get(node.objectId);
+        if (node.children && node.children.length > 0) {
+            // 收窄断言：共享 CompoundShape 非递归声明，运行时子节点可含子 CompoundShape。
+            return { kind: 'compound', children: node.children.map(buildNode) };
+        }
+        // 叶节点：局部几何 + 相对父位姿。
+        if (!obj || !obj.positions || !obj.indices) {
+            return { kind: 'compound', children: [] };
+        }
+        const leaf = threemfObjectToShape(obj);
+        if (node.transform) {
+            ;
+            leaf.transform = { matrix: Array.from(node.transform) };
+        }
+        return leaf;
+    };
+    return hierarchy.length === 1
+        ? buildNode(hierarchy[0])
+        : { kind: 'compound', children: hierarchy.map(buildNode) };
+}
 /** Bambu 显示视图数据 → ImportModel.bambuViews（无任何 Bambu 结构时省略）。 */
 function buildBambuViews(bambu) {
     const plates = [...bambu.plates.keys()].sort((a, b) => a - b);

package/dist/mesh/io.js.map

@@ -1 +1 @@
-{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/mesh/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,YAAY,EAAsB,MAAM,kBAAkB,CAAA;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAiB,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAwCzC,gFAAgF;AAChF,MAAM,iBAAiB,GAA6B;IAClD,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,GAAG,EAAE,GAAG;CACT,CAAA;AAED,+EAA+E;AAC/E,MAAM,uBAAuB,GAA6B;IACxD,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,MAAM;CACf,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAA;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAA;IAErD,uEAAuE;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAClE,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;QAC7D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;IAC3B,CAAC;IAED,4EAA4E;IAC5E,uDAAuD;IACvD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAA;IACtE,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QACzC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QACzC,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;IAC3B,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAmB,EACnB,MAAe,EACf,IAA0B;IAE1B,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IAE3C,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAA;QAC1C,+DAA+D;QAC/D,0DAA0D;QAC1D,eAAe;QACf,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;QACtD,CAAC;QACD,sDAAsD;QACtD,0DAA0D;QAC1D,wCAAwC;QACxC,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;QACvD,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;QAClE,MAAM,WAAW,GAAgB;YAC/B,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBACpC,MAAM,IAAI,GAAiC;oBACzC,KAAK,EAAE,CAAC;oBACR,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,YAAY,CAAC,EAAE;iBAClC,CAAA;gBACD,IAAI,GAAG,CAAC,SAAS;oBAAE,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;gBACtF,IAAI,GAAG,CAAC,IAAI;oBAAE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAA;gBAClC,uDAAuD;gBACvD,uDAAuD;gBACvD,mEAAmE;gBACnE,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,KAAK,SAAS;oBACzC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;oBACzE,CAAC,CAAC,SAAS,CAAA;gBACb,IAAI,EAAE,EAAE,CAAC;oBACP,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;oBAC3B,IAAI,EAAE,CAAC,OAAO,GAAG,CAAC;wBAAE,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAA;oBAC7C,yCAAyC;oBACzC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;oBAC3B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAA;gBACzB,CAAC;gBACD,OAAO,IAAI,CAAA;YACb,CAAC,CAAC;YACF,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAA;QACD,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;QACzC,IAAI,UAAU;YAAE,WAAW,CAAC,UAAU,GAAG,UAAU,CAAA;QACnD,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;YACf,KAAK;YACL,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,cAAc;YACd,WAAW;YACX,+CAA+C;YAC/C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAA;IACH,CAAC;IAED,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;QAC5B,wCAAwC;QACxC,wDAAwD;QACxD,0CAA0C;QAC1C,8CAA8C;QAC9C,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,IAAI,UAAU,GAAa,IAAI,CAAA;QAC/B,MAAM,QAAQ,GAAG,IAAI,EAAE,IAAI,CAAA;QAC3B,IAAI,QAAQ,EAAE,CAAC;YACb,UAAU,GAAG,QAAQ,CAAA;YACrB,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;QAC7B,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,kBAAkB,EAAE,CAAA;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAA;YAC1B,IAAI,EAAE,EAAE,CAAC;gBACP,UAAU,GAAG,YAAY,CAAC;oBACxB,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;oBACnC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;iBACpC,CAAC,CAAA;gBACF,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,UAAU,CAA0B,CAAA;YAClE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAqB,CAAA;YACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;gBAAE,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAA;QACtD,CAAC;QACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;QACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;IACpD,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAA;AACzD,CAAC;AAED,gEAAgE;AAChE,SAAS,oBAAoB,CAAC,GAAkB;IAC9C,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,SAAyB;QACxC,OAAO,EAAE,GAAG,CAAC,OAAsB;QACnC,4DAA4D;QAC5D,4DAA4D;QAC5D,yDAAyD;QACzD,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3G,+DAA+D;QAC/D,2DAA2D;QAC3D,mCAAmC;QACnC,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;YACrD,CAAC,CAAC;gBACE,cAAc,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7C,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAmB;iBAC7E,CAAC,CAAC;aACJ;YACH,CAAC,CAAC,EAAE,CAAC;QACP,iEAAiE;QACjE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAA;AACH,CAAC;AAED,8DAA8D;AAC9D,SAAS,eAAe,CACtB,KAAiD;IAEjD,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,IAAI,CAAC,KAAK,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAA;IACjG,MAAM,KAAK,GAA2C,EAAE,MAAM,EAAE,CAAA;IAChE,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC;QAC7B,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,WAAW,CAC3C,CAAC,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CACjG,CAAA;IACH,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC3B,KAAK,CAAC,gBAAgB,GAAG,MAAM,CAAC,WAAW,CACzC,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CACrG,CAAA;IACH,CAAC;IACD,qDAAqD;IACrD,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9C,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI;SAC/B,CAAC,CAAC,CAAA;IACL,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAA;IAChF,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAA;IAC7E,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpC,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC,CAAA;IACL,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * mesh IO API — headless 文件加载\n *\n * STL 由 core 自持的 `mesh/stl-loader.ts` 解析（零 three addons）；3MF 由\n * `mesh/threemf-loader.ts` 解析（ZIP 解压 + XML，单位换算到 mm 基准）。\n * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。\n *\n * 单位换算边界（unit-system §5.2）：\n * - STL 无单位元数据 → 由 `opts.unit` 显式声明优先；未声明时 faijs 按历史\n *   host 行为做启发式猜测（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor\n *   迁移回归的单位断言依赖此行为）。猜测收敛在 faijs 内（红线 R0：宿主不\n *   自实现单位换算），G0 = 折算后坐标，渲染 = 拓扑 = G0。\n * - 3MF `<model unit>` 由解析器读取并换算（micron/mm/cm/inch/foot/meter）。\n *\n * 返回契约（unit-system §10.6）：`importFile` 返回 `{ shape, unit }` — `unit`\n * 是文件源单位（必然有值；faijs 是单一真源）：3MF/STEP 取文件声明（STEP 无声明\n * → 'mm'，与 OCCT 一致），STL 取 opts.unit 或 guessStlUnit 启发式猜测。坐标恒\n * 为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不参与几何\n * 缩放（读入折算已由内核/解析器完成，二次缩放 = 双重换算）。\n */\n\nimport * as THREE from 'three'\nimport { geoToManifoldMesh } from '../boolean/geo-convert'\nimport { parseStl } from './stl-loader'\nimport { parseThreemf, type ThreemfObject } from './threemf-loader'\nimport { parseBambu3mfFromEntries } from './threemf-bambu'\nimport { unitScale, type UnitName } from '../units'\nimport { guessStlUnit } from './stl-unit'\nimport type { Shape } from './types'\nimport type { PbrAppearance } from '../api/appearance'\nimport type { FileMeta } from '../api/meta'\nimport type { ImportModel } from './import-model'\n\n/** Result of a unit-aware file import. */\nexport interface ImportFileResult {\n  shape: Shape\n  /**\n   * All parts the file declared, in declaration order (3MF `<build><item>` 序 /\n   * STL 单零件)。`shape` is `parts[0]`（单零件兼容，过渡期）。\n   * P0（2026-10-06-step-3mf-multipart-import-plan.md §5.4）：多对象 3MF 不再折叠。\n   */\n  parts: Shape[]\n  /**\n   * The file's source unit (always present; faijs is the single source of truth).\n   * 3MF/STEP: the file's declared unit (STEP 无声明 → 'mm', 与 OCCT 一致).\n   * STL: opts.unit if declared, else the guessStlUnit heuristic result.\n   * Metadata only — coordinates are already in the faijs base unit (mm).\n   */\n  unit: UnitName\n  /**\n   * Total parts the single file declared (e.g. 3MF `<build>` object count),\n   * present only when > 1. Single-part mesh (STL, single-object 3MF) omits it.\n   * 保留为 `parts.length`（>1 时）；多零件不再折叠后该字段仅供旧宿主判断。\n   */\n  multiPartCount?: number\n  /**\n   * 整体级元数据（文件级；方案 §5.1 3MF `<model><metadata>`）。STL/STEP 视实现\n   * 是否解析；无声明则省略。仅随导入结果上抛，不挂 Shape。\n   */\n  fileMeta?: FileMeta\n  /**\n   * 本次导入的结构数据（P0 §5.1）：零件身份表 + Bambu 视图（3MF 分支填充）。\n   * 单/多零件均登记（单零件 parts 长度 1）。\n   */\n  importModel?: ImportModel\n}\n\n/** SI prefixes that may precede .METRE. in a STEP SI_UNIT, → faijs UnitName. */\nconst SI_PREFIX_TO_UNIT: Record<string, UnitName> = {\n  '.MILLI.': 'mm',\n  '.CENTI.': 'cm',\n  '$': 'm',\n}\n\n/** CONVERSION_BASED_UNIT names (uppercased) found in real-world STEP files. */\nconst CONVERSION_NAME_TO_UNIT: Record<string, UnitName> = {\n  'METRE': 'm',\n  'METER': 'm',\n  'MILLIMETRE': 'mm',\n  'MILLIMETER': 'mm',\n  'CENTIMETRE': 'cm',\n  'CENTIMETER': 'cm',\n  'MICROMETRE': 'micron',\n  'MICROMETER': 'micron',\n  'INCH': 'inch',\n  'FOOT': 'foot',\n}\n\n/**\n * Bounded scan window for `detectStepUnit`. Unit entities sit at the front of\n * the DATA section (right after the product/context blocks); 256 KiB covers\n * every real-world header+context preamble observed so far. Recomputable\n * constant — raise if a fixture ever misses.\n */\nexport const STEP_UNIT_SCAN_PREFIX = 256 * 1024\n\n/**\n * Parse the declared length unit from STEP text (unit-system §10.4).\n *\n * Unit entities live in the DATA section (not HEADER — ISO 10303-21 reserves\n * HEADER for FILE_DESCRIPTION/FILE_NAME/FILE_SCHEMA), near its start. We scan\n * a bounded prefix; the justification is \"unit entities sit at the front of\n * the DATA section\", not \"top of file\".\n *\n * Recognized forms, both attached to a LENGTH_UNIT():\n * - `SI_UNIT(<prefix>, .METRE.)` — prefix `.MILLI.`/`.CENTI.`/`.MICRO.` or `$`.\n * - `CONVERSION_BASED_UNIT('<NAME>', #n)` — inch/foot/etc.\n *\n * Metadata only — NEVER used to scale geometry (OCCT already normalizes on\n * read; re-scaling = double conversion).\n *\n * @param stepText - the full STEP file text to scan (only a bounded prefix is read).\n * @returns the faijs UnitName, or null when no length-unit declaration is found\n *   (STEP permits omitting it; caller falls back to the base unit).\n */\nexport function detectStepUnit(stepText: string): UnitName | null {\n  const head = stepText.slice(0, STEP_UNIT_SCAN_PREFIX)\n\n  // 1) CONVERSION_BASED_UNIT('<NAME>', #n) — non-SI units (inch/foot/…).\n  const conv = head.match(/CONVERSION_BASED_UNIT\\s*\\(\\s*'([^']+)'/i)\n  if (conv) {\n    const mapped = CONVERSION_NAME_TO_UNIT[conv[1].toUpperCase()]\n    if (mapped) return mapped\n  }\n\n  // 2) SI_UNIT(<prefix>, .METRE.) — the .METRE. guard excludes angle entities\n  //    (they carry .RADIAN./.STERADIAN., never .METRE.).\n  const si = head.match(/SI_UNIT\\s*\\(\\s*([^)]*?)\\s*,\\s*\\.METRE\\.\\s*\\)/i)\n  if (si) {\n    const prefix = si[1].trim().toUpperCase()\n    if (prefix === '.MICRO.') return 'micron'\n    const mapped = SI_PREFIX_TO_UNIT[prefix]\n    if (mapped) return mapped\n  }\n\n  return null\n}\n\n/**\n * Load geometry from raw file bytes (headless variant).\n *\n * @param buffer - the raw file bytes to parse (already decompressed; stpz\n *   unzipping is the caller's job — faijs never unzips implicitly).\n * @param format - format identifier such as 'stl', '3mf'/'threemf' or 'step'\n *   (defaults to 'stl').\n * @param opts - optional settings; `unit` (a UnitName string) declares the\n *   source unit for formats without unit metadata (e.g. STL). Defaults to\n *   the guessStlUnit heuristic when omitted.\n * @returns the shape with base-unit coordinates plus the file's source unit\n *   (`unit`, metadata only; always present — faijs is the single source of truth).\n */\nexport async function importFile(\n  buffer: ArrayBuffer,\n  format?: string,\n  opts?: { unit?: UnitName },\n): Promise<ImportFileResult> {\n  const fmt = (format ?? 'stl').toLowerCase()\n\n  if (fmt === '3mf' || fmt === 'threemf') {\n    const archive = await parseThreemf(buffer)\n    // P0（方案 §5.4）：不再折叠——返回全部 `<build><item>` 对象（declaration order，\n    // 坐标已在 parseThreemf 里折算为 faijs 基准单位）。`shape` 保留为 parts[0]\n    // （单零件兼容，过渡期）。\n    if (archive.objects.length === 0) {\n      throw new Error('[mesh/io] 3MF contains no objects')\n    }\n    // Bambu 元数据（盘号/挤出机/视图变换）：有 Bambu 配置才产生内容，普通 3MF 返回空表。\n    // P4：根 model XML 直传（3MF `<build>` 在 resources 前；id 两套编号经父\n    // object components 关联——leafParts 表承载）。\n    const bambu = parseBambu3mfFromEntries(archive.extraEntries, archive.modelXml)\n    const parts = archive.objects.map(threemfObjectToShape)\n    const multiPartCount = parts.length > 1 ? parts.length : undefined\n    const importModel: ImportModel = {\n      format: '3mf',\n      unit: archive.unit,\n      parts: archive.objects.map((obj, i) => {\n        const part: ImportModel['parts'][number] = {\n          index: i,\n          name: obj.name ?? `imported:${i}`,\n        }\n        if (obj.baseColor) part.color = [obj.baseColor[0], obj.baseColor[1], obj.baseColor[2]]\n        if (obj.meta) part.meta = obj.meta\n        // Bambu 身份：3MF `<object id>`（叶子实例）与 Bambu objects 表（键为\n        // model_settings 父对象 id）是两套编号——经父 object components 关联\n        // （ThreemfObject.parentObjectId/componentIndex → bambu.leafParts）。\n        const bm = obj.parentObjectId !== undefined\n          ? bambu.leafParts.get(`${obj.parentObjectId}:${obj.componentIndex ?? 1}`)\n          : undefined\n        if (bm) {\n          part.objectId = bm.objectId\n          if (bm.plateId > 0) part.plateId = bm.plateId\n          // Bambu extruder 1-based（默认 1）：显式登记文件声明值\n          part.extruder = bm.extruder\n          part.partId = bm.partId\n        }\n        return part\n      }),\n      ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),\n    }\n    const bambuViews = buildBambuViews(bambu)\n    if (bambuViews) importModel.bambuViews = bambuViews\n    return {\n      shape: parts[0],\n      parts,\n      unit: archive.unit,\n      multiPartCount,\n      importModel,\n      // 整体级元数据（`<model><metadata>`）随导入结果上抛（方案 §5.1）。\n      ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),\n    }\n  }\n\n  if (fmt === 'stl') {\n    const geo = parseStl(buffer)\n    // STL 无单位声明：opts.unit 显式声明优先；未声明时做启发式猜测\n    // （guessStlUnit —— 历史 host 行为，unified §6.1/§8 迁移基线）。猜测与\n    // 折算都在 faijs 内完成（红线 R0），G0 即基准值，宿主不再二次换算。\n    // unit 字段回传源单位（声明值或猜测值），供宿主记录 sourceUnit 元数据。\n    let scale = 1\n    let sourceUnit: UnitName = 'mm'\n    const declared = opts?.unit\n    if (declared) {\n      sourceUnit = declared\n      scale = unitScale(declared)\n    } else {\n      geo.computeBoundingBox()\n      const bb = geo.boundingBox\n      if (bb) {\n        sourceUnit = guessStlUnit({\n          min: [bb.min.x, bb.min.y, bb.min.z],\n          max: [bb.max.x, bb.max.y, bb.max.z],\n        })\n        scale = unitScale(sourceUnit)\n      }\n    }\n    if (scale !== 1) {\n      const attr = geo.getAttribute('position') as THREE.BufferAttribute\n      const arr = attr.array as Float32Array\n      for (let i = 0; i < arr.length; i++) arr[i] *= scale\n    }\n    const shape = geoToManifoldMesh(geo)\n    return { shape, parts: [shape], unit: sourceUnit }\n  }\n\n  // STEP goes through the BREP chain (loadBrep → OCCT, which normalizes to the\n  // base unit on read). The mesh io path has no kernel-independent STEP parser\n  // and must not fake one — a missing path is an error, not a fallback.\n  throw new Error(`[mesh/io] unsupported format: ${fmt}`)\n}\n\n/** 单个 3MF `<build><item>` 对象 → Shape（P0：逐对象构造，替换原\"只取第一个\"收敛）。 */\nfunction threemfObjectToShape(obj: ThreemfObject): Shape {\n  return {\n    positions: obj.positions as Float32Array,\n    indices: obj.indices as Uint32Array,\n    // P2（方案 §5 3MF 行）：对象级 baseColor → appearance.color（sRGB 原值，\n    // 宽容兼容：无 baseColor 不带 appearance）。colorgroup（vertexColors）与\n    // 逐三角形材质属 Phase 2（materialGroups / vertexColors），P2 不映射。\n    ...(obj.baseColor ? { appearance: { color: [obj.baseColor[0], obj.baseColor[1], obj.baseColor[2]] } } : {}),\n    // P4（方案 §5 3MF 行）：逐三角形 basematerials（p1=p2=p3）→ materialGroups\n    // （三角形区间 + appearance.color）；无则不带。vertexColors（colorgroup）\n    // 由上层（编辑器导入路径）消费，io 单零件收敛不展开为材质分组。\n    ...(obj.materialGroups && obj.materialGroups.length > 0\n      ? {\n          materialGroups: obj.materialGroups.map((g) => ({\n            start: g.start,\n            count: g.count,\n            appearance: { color: [g.color[0], g.color[1], g.color[2]] } as PbrAppearance,\n          })),\n        }\n      : {}),\n    // 零件级元数据（方案 §5.1 3MF 行）：对象 name/partnumber/metadatagroup → meta。\n    ...(obj.meta ? { meta: obj.meta } : {}),\n  }\n}\n\n/** Bambu 显示视图数据 → ImportModel.bambuViews（无任何 Bambu 结构时省略）。 */\nfunction buildBambuViews(\n  bambu: import('./threemf-bambu').Bambu3mfMetadata,\n): ImportModel['bambuViews'] | undefined {\n  const plates = [...bambu.plates.keys()].sort((a, b) => a - b)\n  if (plates.length === 0 && !bambu.assembleTransforms && !bambu.importTransforms) return undefined\n  const views: NonNullable<ImportModel['bambuViews']> = { plates }\n  if (bambu.assembleTransforms) {\n    views.assembleTransforms = Object.fromEntries(\n      [...bambu.assembleTransforms].map(([k, v]) => [k, { transform: v.transform, offset: v.offset }]),\n    )\n  }\n  if (bambu.importTransforms) {\n    views.importTransforms = Object.fromEntries(\n      [...bambu.importTransforms].map(([k, v]) => [k, { matrix: v.matrix, sourceOffset: v.sourceOffset }]),\n    )\n  }\n  // P4：完整消费面随结果回传——宿主重建 Bambu3mfMetadata 不再回读 archive。\n  if (bambu.buildItems) {\n    views.buildItems = bambu.buildItems.map((b) => ({\n      objectId: b.objectId,\n      transform: b.transform ?? null,\n    }))\n  }\n  if (bambu.filamentColors.length > 0) views.filamentColors = bambu.filamentColors\n  if (bambu.filamentTypes.length > 0) views.filamentTypes = bambu.filamentTypes\n  if (bambu.parts.length > 0) {\n    views.parts = bambu.parts.map((p) => ({\n      partIndex: p.partIndex,\n      objectId: p.objectId,\n      partId: p.partId,\n      name: p.name,\n      extruder: p.extruder,\n      plateId: p.plateId,\n    }))\n  }\n  return views\n}\n"]}
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/mesh/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,YAAY,EAAwC,MAAM,kBAAkB,CAAA;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAiB,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAoDzC,gFAAgF;AAChF,MAAM,iBAAiB,GAA6B;IAClD,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,GAAG,EAAE,GAAG;CACT,CAAA;AAED,+EAA+E;AAC/E,MAAM,uBAAuB,GAA6B;IACxD,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,MAAM;CACf,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAA;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAA;IAErD,uEAAuE;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAClE,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;QAC7D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;IAC3B,CAAC;IAED,4EAA4E;IAC5E,uDAAuD;IACvD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAA;IACtE,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QACzC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QACzC,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;IAC3B,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAmB,EACnB,MAAe,EACf,IAA0B;IAE1B,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IAE3C,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAChD,+DAA+D;QAC/D,0DAA0D;QAC1D,eAAe;QACf,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;QACtD,CAAC;QACD,sDAAsD;QACtD,0DAA0D;QAC1D,wCAAwC;QACxC,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;QACvD,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;QAClE,MAAM,WAAW,GAAgB;YAC/B,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;gBACpC,MAAM,IAAI,GAAiC;oBACzC,KAAK,EAAE,CAAC;oBACR,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,YAAY,CAAC,EAAE;iBAClC,CAAA;gBACD,IAAI,GAAG,CAAC,SAAS;oBAAE,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;gBACtF,IAAI,GAAG,CAAC,IAAI;oBAAE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAA;gBAClC,uDAAuD;gBACvD,uDAAuD;gBACvD,mEAAmE;gBACnE,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,KAAK,SAAS;oBACzC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;oBACzE,CAAC,CAAC,SAAS,CAAA;gBACb,IAAI,EAAE,EAAE,CAAC;oBACP,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;oBAC3B,IAAI,EAAE,CAAC,OAAO,GAAG,CAAC;wBAAE,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAA;oBAC7C,yCAAyC;oBACzC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;oBAC3B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAA;gBACzB,CAAC;gBACD,OAAO,IAAI,CAAA;YACb,CAAC,CAAC;YACF,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAA;QACD,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;QACzC,IAAI,UAAU;YAAE,WAAW,CAAC,UAAU,GAAG,UAAU,CAAA;QACnD,8DAA8D;QAC9D,iCAAiC;QACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,aAAa;YACzD,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC;YACpE,CAAC,CAAC,SAAS,CAAA;QACb,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;YACf,KAAK;YACL,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,cAAc;YACd,WAAW;YACX,+CAA+C;YAC/C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClC,CAAA;IACH,CAAC;IAED,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;QAC5B,wCAAwC;QACxC,wDAAwD;QACxD,0CAA0C;QAC1C,8CAA8C;QAC9C,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,IAAI,UAAU,GAAa,IAAI,CAAA;QAC/B,MAAM,QAAQ,GAAG,IAAI,EAAE,IAAI,CAAA;QAC3B,IAAI,QAAQ,EAAE,CAAC;YACb,UAAU,GAAG,QAAQ,CAAA;YACrB,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;QAC7B,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,kBAAkB,EAAE,CAAA;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAA;YAC1B,IAAI,EAAE,EAAE,CAAC;gBACP,UAAU,GAAG,YAAY,CAAC;oBACxB,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;oBACnC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;iBACpC,CAAC,CAAA;gBACF,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,UAAU,CAA0B,CAAA;YAClE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAqB,CAAA;YACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;gBAAE,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAA;QACtD,CAAC;QACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;QACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;IACpD,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAA;AACzD,CAAC;AAED,gEAAgE;AAChE,SAAS,oBAAoB,CAAC,GAAkB;IAC9C,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,SAAyB;QACxC,OAAO,EAAE,GAAG,CAAC,OAAsB;QACnC,4DAA4D;QAC5D,4DAA4D;QAC5D,yDAAyD;QACzD,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3G,+DAA+D;QAC/D,2DAA2D;QAC3D,mCAAmC;QACnC,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;YACrD,CAAC,CAAC;gBACE,cAAc,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7C,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAmB;iBAC7E,CAAC,CAAC;aACJ;YACH,CAAC,CAAC,EAAE,CAAC;QACP,iEAAiE;QACjE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,wBAAwB,CAC/B,SAAwB,EACxB,aAAyC;IAEzC,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACjG,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAA;IAEnC,MAAM,SAAS,GAAG,CAAC,IAAiB,EAAyB,EAAE;QAC7D,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC5C,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,uDAAuD;YACvD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAY,EAAE,CAAA;QAChF,CAAC;QACD,oBAAoB;QACpB,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YAC3C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;QAC3C,CAAC;QACD,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAA;QACtC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,CAAC;YAAC,IAAwC,CAAC,SAAS,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAA;QAC/F,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC,CAAA;IAED,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC;QAC3B,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,SAAS,CAAY,EAAE,CAAA;AACzE,CAAC;AAED,8DAA8D;AAC9D,SAAS,eAAe,CACtB,KAAiD;IAEjD,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,IAAI,CAAC,KAAK,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAA;IACjG,MAAM,KAAK,GAA2C,EAAE,MAAM,EAAE,CAAA;IAChE,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC;QAC7B,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,WAAW,CAC3C,CAAC,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CACjG,CAAA;IACH,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC3B,KAAK,CAAC,gBAAgB,GAAG,MAAM,CAAC,WAAW,CACzC,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CACrG,CAAA;IACH,CAAC;IACD,qDAAqD;IACrD,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9C,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI;SAC/B,CAAC,CAAC,CAAA;IACL,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAA;IAChF,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAA;IAC7E,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpC,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC,CAAA;IACL,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * mesh IO API — headless 文件加载\n *\n * STL 由 core 自持的 `mesh/stl-loader.ts` 解析（零 three addons）；3MF 由\n * `mesh/threemf-loader.ts` 解析（ZIP 解压 + XML，单位换算到 mm 基准）。\n * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。\n *\n * 单位换算边界（unit-system §5.2）：\n * - 本模块只处理 **mesh 格式（STL/3MF）**，坐标可直接折算 → `opts.unit` 提供即\n *   **强制设置模型的源单位**（直接指定，覆盖/忽略模型内部记录的单位——STL 无\n *   内部单位、3MF `<model unit>` 声明被覆盖），按 `unitScale(unit)` 折算坐标。\n *   它**只可能来自调用方的显式知识**（脚本作者手写 `cad.load({ file, unit })`、\n *   或宿主让用户选定单位后传入）；调用方不知道单位时**必须省略**——省略时：\n *   STL 走 faijs 启发式（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor\n *   迁移回归的单位断言依赖此行为）、3MF 走文件 `<model unit>`（无声明 →\n *   millimeter）。猜测/折算收敛在 faijs 内（红线 R0：宿主不自实现单位换算），\n *   G0 = 折算后坐标，渲染 = 拓扑 = G0。\n * - **STEP/.brep 不经过本模块**（走 BREP 链，load op 内 OCCT 读取）：OCCT 按\n *   文件内部单位声明折算（SI_UNIT），**不支持强制设置单位**——load op 对\n *   BREP 路径 + 用户显式 unit 直接**明确报错**（不缩放、不 workaround）。\n * - 3MF `<model unit>` 由解析器读取并换算（micron/mm/cm/inch/foot/meter）。\n *\n * 返回契约（unit-system §10.6）：`importFile` 返回 `{ shape, unit }` — `unit`\n * 是文件源单位（必然有值；faijs 是单一真源）：3MF 取 opts.unit（强制）或文件\n * 声明（无声明 → millimeter），STL 取 opts.unit 或 guessStlUnit 启发式猜测。\n * 坐标恒为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不\n * 参与几何缩放（读入折算已由解析器完成，二次缩放 = 双重换算）。\n */\n\nimport * as THREE from 'three'\nimport { geoToManifoldMesh } from '../boolean/geo-convert'\nimport { parseStl } from './stl-loader'\nimport { parseThreemf, type ThreemfObject, type ThreemfNode } from './threemf-loader'\nimport { parseBambu3mfFromEntries } from './threemf-bambu'\nimport { unitScale, type UnitName } from '../units'\nimport { guessStlUnit } from './stl-unit'\nimport type { Shape } from './types'\nimport type { CompoundShape } from '../shape'\nimport type { PbrAppearance } from '../api/appearance'\nimport type { FileMeta } from '../api/meta'\nimport type { ImportModel } from './import-model'\n\n/** Result of a unit-aware file import. */\nexport interface ImportFileResult {\n  shape: Shape\n  /**\n   * All parts the file declared, in declaration order (3MF `<build><item>` 序 /\n   * STL 单零件)。`shape` is `parts[0]`（单零件兼容，过渡期）。\n   * P0（2026-10-06-step-3mf-multipart-import-plan.md §5.4）：多对象 3MF 不再折叠。\n   */\n  parts: Shape[]\n  /**\n   * The file's source unit (always present; faijs is the single source of truth).\n   * 3MF: opts.unit (forced) if provided, else the file's declared unit\n   * (无声明 → millimeter). STL: opts.unit (forced) if provided, else the\n   * guessStlUnit heuristic result. STEP/BREP 不经过本模块（OCCT 链不支持\n   * 强制设置单位，load op 报错）。\n   * Metadata only — coordinates are already in the faijs base unit (mm).\n   */\n  unit: UnitName\n  /**\n   * Total parts the single file declared (e.g. 3MF `<build>` object count),\n   * present only when > 1. Single-part mesh (STL, single-object 3MF) omits it.\n   * 保留为 `parts.length`（>1 时）；多零件不再折叠后该字段仅供旧宿主判断。\n   */\n  multiPartCount?: number\n  /**\n   * 整体级元数据（文件级；方案 §5.1 3MF `<model><metadata>`）。STL/STEP 视实现\n   * 是否解析；无声明则省略。仅随导入结果上抛，不挂 Shape。\n   */\n  fileMeta?: FileMeta\n  /**\n   * 本次导入的结构数据（P0 §5.1）：零件身份表 + Bambu 视图（3MF 分支填充）。\n   * 单/多零件均登记（单零件 parts 长度 1）。\n   */\n  importModel?: ImportModel\n  /**\n   * 装配层级（方案 2026-10-08 §2.1 / 第 5 步「导入归一」）：当 3MF 含 `<components>`\n   * 装配结构时，按层级重建为 `CompoundShape`，每个子节点携带相对父的 `transform`\n   * （来自 3MF `<component transform>` / build `<item transform>`，行主序 3×4，平移在\n   * 末列，与写出器同源）。仅当存在真实装配（多 item 或任一 item 带 components）时存在；\n   * 单零件平铺导入不走它（`shape` / `parts` 已覆盖）。viewer 用 `parts`（已烘焙实例），\n   * 往返/层级消费者用 `assembly`（局部几何 + 节点 transform）。\n   */\n  assembly?: Shape | CompoundShape\n}\n\n/** SI prefixes that may precede .METRE. in a STEP SI_UNIT, → faijs UnitName. */\nconst SI_PREFIX_TO_UNIT: Record<string, UnitName> = {\n  '.MILLI.': 'mm',\n  '.CENTI.': 'cm',\n  '$': 'm',\n}\n\n/** CONVERSION_BASED_UNIT names (uppercased) found in real-world STEP files. */\nconst CONVERSION_NAME_TO_UNIT: Record<string, UnitName> = {\n  'METRE': 'm',\n  'METER': 'm',\n  'MILLIMETRE': 'mm',\n  'MILLIMETER': 'mm',\n  'CENTIMETRE': 'cm',\n  'CENTIMETER': 'cm',\n  'MICROMETRE': 'micron',\n  'MICROMETER': 'micron',\n  'INCH': 'inch',\n  'FOOT': 'foot',\n}\n\n/**\n * Bounded scan window for `detectStepUnit`. Unit entities sit at the front of\n * the DATA section (right after the product/context blocks); 256 KiB covers\n * every real-world header+context preamble observed so far. Recomputable\n * constant — raise if a fixture ever misses.\n */\nexport const STEP_UNIT_SCAN_PREFIX = 256 * 1024\n\n/**\n * Parse the declared length unit from STEP text (unit-system §10.4).\n *\n * Unit entities live in the DATA section (not HEADER — ISO 10303-21 reserves\n * HEADER for FILE_DESCRIPTION/FILE_NAME/FILE_SCHEMA), near its start. We scan\n * a bounded prefix; the justification is \"unit entities sit at the front of\n * the DATA section\", not \"top of file\".\n *\n * Recognized forms, both attached to a LENGTH_UNIT():\n * - `SI_UNIT(<prefix>, .METRE.)` — prefix `.MILLI.`/`.CENTI.`/`.MICRO.` or `$`.\n * - `CONVERSION_BASED_UNIT('<NAME>', #n)` — inch/foot/etc.\n *\n * Metadata only — NEVER used to scale geometry (OCCT already normalizes on\n * read; re-scaling = double conversion).\n *\n * @param stepText - the full STEP file text to scan (only a bounded prefix is read).\n * @returns the faijs UnitName, or null when no length-unit declaration is found\n *   (STEP permits omitting it; caller falls back to the base unit).\n */\nexport function detectStepUnit(stepText: string): UnitName | null {\n  const head = stepText.slice(0, STEP_UNIT_SCAN_PREFIX)\n\n  // 1) CONVERSION_BASED_UNIT('<NAME>', #n) — non-SI units (inch/foot/…).\n  const conv = head.match(/CONVERSION_BASED_UNIT\\s*\\(\\s*'([^']+)'/i)\n  if (conv) {\n    const mapped = CONVERSION_NAME_TO_UNIT[conv[1].toUpperCase()]\n    if (mapped) return mapped\n  }\n\n  // 2) SI_UNIT(<prefix>, .METRE.) — the .METRE. guard excludes angle entities\n  //    (they carry .RADIAN./.STERADIAN., never .METRE.).\n  const si = head.match(/SI_UNIT\\s*\\(\\s*([^)]*?)\\s*,\\s*\\.METRE\\.\\s*\\)/i)\n  if (si) {\n    const prefix = si[1].trim().toUpperCase()\n    if (prefix === '.MICRO.') return 'micron'\n    const mapped = SI_PREFIX_TO_UNIT[prefix]\n    if (mapped) return mapped\n  }\n\n  return null\n}\n\n/**\n * Load geometry from raw file bytes (headless variant).\n *\n * @param buffer - the raw file bytes to parse (already decompressed; stpz\n *   unzipping is the caller's job — faijs never unzips implicitly).\n * @param format - format identifier such as 'stl', '3mf'/'threemf' or 'step'\n *   (defaults to 'stl'). **仅 mesh 格式（STL/3MF）走本模块**；STEP/BREP 走\n *   BREP 链（load op 内 OCCT 读取，不支持强制设置单位）。\n * @param opts - optional settings; `unit` (a UnitName string) **force-sets the\n *   model's source unit** (STL/3MF): it is NOT a default, it directly specifies\n *   the unit and overrides/ignores any unit recorded inside the model (3MF\n *   `<model unit>`; STL has none), geometry scaled by `unitScale(unit)`. Only\n *   provide it when the caller actually knows the unit (author-written\n *   `cad.load({ file, unit })`, or a host unit picker). When the caller does\n *   NOT know the unit, it MUST omit `unit` — STL then guesses via\n *   `guessStlUnit` (the only allowed guessing path), 3MF uses the file\n *   declaration (none → millimeter). A wrong explicit unit scales geometry\n *   wrongly and is never re-guessed.\n * @returns the shape with base-unit coordinates plus the file's source unit\n *   (`unit`, metadata only; always present — faijs is the single source of truth).\n */\nexport async function importFile(\n  buffer: ArrayBuffer,\n  format?: string,\n  opts?: { unit?: UnitName },\n): Promise<ImportFileResult> {\n  const fmt = (format ?? 'stl').toLowerCase()\n\n  if (fmt === '3mf' || fmt === 'threemf') {\n    const archive = await parseThreemf(buffer, opts)\n    // P0（方案 §5.4）：不再折叠——返回全部 `<build><item>` 对象（declaration order，\n    // 坐标已在 parseThreemf 里折算为 faijs 基准单位）。`shape` 保留为 parts[0]\n    // （单零件兼容，过渡期）。\n    if (archive.objects.length === 0) {\n      throw new Error('[mesh/io] 3MF contains no objects')\n    }\n    // Bambu 元数据（盘号/挤出机/视图变换）：有 Bambu 配置才产生内容，普通 3MF 返回空表。\n    // P4：根 model XML 直传（3MF `<build>` 在 resources 前；id 两套编号经父\n    // object components 关联——leafParts 表承载）。\n    const bambu = parseBambu3mfFromEntries(archive.extraEntries, archive.modelXml)\n    const parts = archive.objects.map(threemfObjectToShape)\n    const multiPartCount = parts.length > 1 ? parts.length : undefined\n    const importModel: ImportModel = {\n      format: '3mf',\n      unit: archive.unit,\n      parts: archive.objects.map((obj, i) => {\n        const part: ImportModel['parts'][number] = {\n          index: i,\n          name: obj.name ?? `imported:${i}`,\n        }\n        if (obj.baseColor) part.color = [obj.baseColor[0], obj.baseColor[1], obj.baseColor[2]]\n        if (obj.meta) part.meta = obj.meta\n        // Bambu 身份：3MF `<object id>`（叶子实例）与 Bambu objects 表（键为\n        // model_settings 父对象 id）是两套编号——经父 object components 关联\n        // （ThreemfObject.parentObjectId/componentIndex → bambu.leafParts）。\n        const bm = obj.parentObjectId !== undefined\n          ? bambu.leafParts.get(`${obj.parentObjectId}:${obj.componentIndex ?? 1}`)\n          : undefined\n        if (bm) {\n          part.objectId = bm.objectId\n          if (bm.plateId > 0) part.plateId = bm.plateId\n          // Bambu extruder 1-based（默认 1）：显式登记文件声明值\n          part.extruder = bm.extruder\n          part.partId = bm.partId\n        }\n        return part\n      }),\n      ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),\n    }\n    const bambuViews = buildBambuViews(bambu)\n    if (bambuViews) importModel.bambuViews = bambuViews\n    // 装配层级重建（方案 §2.1 / 第 5 步）：含 `<components>` 时还原 CompoundShape，\n    // 叶节点携带相对父 transform；单零件平铺导入不挂载。\n    const assembly = archive.hierarchy && archive.localGeomById\n      ? buildAssemblyFromArchive(archive.hierarchy, archive.localGeomById)\n      : undefined\n    return {\n      shape: parts[0],\n      parts,\n      unit: archive.unit,\n      multiPartCount,\n      importModel,\n      // 整体级元数据（`<model><metadata>`）随导入结果上抛（方案 §5.1）。\n      ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),\n      ...(assembly ? { assembly } : {}),\n    }\n  }\n\n  if (fmt === 'stl') {\n    const geo = parseStl(buffer)\n    // STL 无单位声明：opts.unit 显式声明优先；未声明时做启发式猜测\n    // （guessStlUnit —— 历史 host 行为，unified §6.1/§8 迁移基线）。猜测与\n    // 折算都在 faijs 内完成（红线 R0），G0 即基准值，宿主不再二次换算。\n    // unit 字段回传源单位（声明值或猜测值），供宿主记录 sourceUnit 元数据。\n    let scale = 1\n    let sourceUnit: UnitName = 'mm'\n    const declared = opts?.unit\n    if (declared) {\n      sourceUnit = declared\n      scale = unitScale(declared)\n    } else {\n      geo.computeBoundingBox()\n      const bb = geo.boundingBox\n      if (bb) {\n        sourceUnit = guessStlUnit({\n          min: [bb.min.x, bb.min.y, bb.min.z],\n          max: [bb.max.x, bb.max.y, bb.max.z],\n        })\n        scale = unitScale(sourceUnit)\n      }\n    }\n    if (scale !== 1) {\n      const attr = geo.getAttribute('position') as THREE.BufferAttribute\n      const arr = attr.array as Float32Array\n      for (let i = 0; i < arr.length; i++) arr[i] *= scale\n    }\n    const shape = geoToManifoldMesh(geo)\n    return { shape, parts: [shape], unit: sourceUnit }\n  }\n\n  // STEP goes through the BREP chain (loadBrep → OCCT, which normalizes to the\n  // base unit on read). The mesh io path has no kernel-independent STEP parser\n  // and must not fake one — a missing path is an error, not a fallback.\n  throw new Error(`[mesh/io] unsupported format: ${fmt}`)\n}\n\n/** 单个 3MF `<build><item>` 对象 → Shape（P0：逐对象构造，替换原\"只取第一个\"收敛）。 */\nfunction threemfObjectToShape(obj: ThreemfObject): Shape {\n  return {\n    positions: obj.positions as Float32Array,\n    indices: obj.indices as Uint32Array,\n    // P2（方案 §5 3MF 行）：对象级 baseColor → appearance.color（sRGB 原值，\n    // 宽容兼容：无 baseColor 不带 appearance）。colorgroup（vertexColors）与\n    // 逐三角形材质属 Phase 2（materialGroups / vertexColors），P2 不映射。\n    ...(obj.baseColor ? { appearance: { color: [obj.baseColor[0], obj.baseColor[1], obj.baseColor[2]] } } : {}),\n    // P4（方案 §5 3MF 行）：逐三角形 basematerials（p1=p2=p3）→ materialGroups\n    // （三角形区间 + appearance.color）；无则不带。vertexColors（colorgroup）\n    // 由上层（编辑器导入路径）消费，io 单零件收敛不展开为材质分组。\n    ...(obj.materialGroups && obj.materialGroups.length > 0\n      ? {\n          materialGroups: obj.materialGroups.map((g) => ({\n            start: g.start,\n            count: g.count,\n            appearance: { color: [g.color[0], g.color[1], g.color[2]] } as PbrAppearance,\n          })),\n        }\n      : {}),\n    // 零件级元数据（方案 §5.1 3MF 行）：对象 name/partnumber/metadatagroup → meta。\n    ...(obj.meta ? { meta: obj.meta } : {}),\n  }\n}\n\n/**\n * 由 3MF 装配层级重建 `CompoundShape`（方案 §2.1 / 第 5 步「导入归一」）。\n *\n * 见 `ThreemfArchive.hierarchy` / `localGeomById`：节点带**相对父**位姿（行主序 3×4，\n * 平移在末列，与写出器 `transformToMatrix12` 同源）；几何来自 `localGeomById` 的**未烘焙**\n * 局部网格。叶节点的最终 `Shape.transform` 即该相对位姿（写回 `Shape.transform`，供\n * 后续导出按 3MF `<component transform>` 原样还原——D1 往返）。容器节点落为\n * `CompoundShape`（不含 `transform` / `meta`，与 `shape.ts` 的 `CompoundShape` 形态一致）。\n *\n * 注：`shape.ts` 的 `CompoundShape.children` 当前声明为 `Shape[]`（非递归），故嵌套装配\n * 在类型层面暂不表达；运行时子节点可为子 `CompoundShape`（由 `isCompoundLike` 结构判定消费）。\n * 把 `CompoundShape` 改为递归类型是独立的后续重构（会波及 faijs-extra / cad-runtime），本步\n * 以最小改动桥接——见下方 `children` 处的收窄断言。\n *\n * 仅在存在真实装配（多 item 或任一 item 带 components）时返回非空；单零件平铺导入返回\n * `undefined`（由调用方决定是否挂载到 `result.assembly`，避免改变单零件结果形状）。\n */\nfunction buildAssemblyFromArchive(\n  hierarchy: ThreemfNode[],\n  localGeomById: Map<number, ThreemfObject>,\n): Shape | CompoundShape | undefined {\n  const hasHierarchy = hierarchy.length > 1 || hierarchy.some((n) => (n.children?.length ?? 0) > 0)\n  if (!hasHierarchy) return undefined\n\n  const buildNode = (node: ThreemfNode): Shape | CompoundShape => {\n    const obj = localGeomById.get(node.objectId)\n    if (node.children && node.children.length > 0) {\n      // 收窄断言：共享 CompoundShape 非递归声明，运行时子节点可含子 CompoundShape。\n      return { kind: 'compound', children: node.children.map(buildNode) as Shape[] }\n    }\n    // 叶节点：局部几何 + 相对父位姿。\n    if (!obj || !obj.positions || !obj.indices) {\n      return { kind: 'compound', children: [] }\n    }\n    const leaf = threemfObjectToShape(obj)\n    if (node.transform) {\n      ;(leaf as Shape & { transform?: unknown }).transform = { matrix: Array.from(node.transform) }\n    }\n    return leaf\n  }\n\n  return hierarchy.length === 1\n    ? buildNode(hierarchy[0])\n    : { kind: 'compound', children: hierarchy.map(buildNode) as Shape[] }\n}\n\n/** Bambu 显示视图数据 → ImportModel.bambuViews（无任何 Bambu 结构时省略）。 */\nfunction buildBambuViews(\n  bambu: import('./threemf-bambu').Bambu3mfMetadata,\n): ImportModel['bambuViews'] | undefined {\n  const plates = [...bambu.plates.keys()].sort((a, b) => a - b)\n  if (plates.length === 0 && !bambu.assembleTransforms && !bambu.importTransforms) return undefined\n  const views: NonNullable<ImportModel['bambuViews']> = { plates }\n  if (bambu.assembleTransforms) {\n    views.assembleTransforms = Object.fromEntries(\n      [...bambu.assembleTransforms].map(([k, v]) => [k, { transform: v.transform, offset: v.offset }]),\n    )\n  }\n  if (bambu.importTransforms) {\n    views.importTransforms = Object.fromEntries(\n      [...bambu.importTransforms].map(([k, v]) => [k, { matrix: v.matrix, sourceOffset: v.sourceOffset }]),\n    )\n  }\n  // P4：完整消费面随结果回传——宿主重建 Bambu3mfMetadata 不再回读 archive。\n  if (bambu.buildItems) {\n    views.buildItems = bambu.buildItems.map((b) => ({\n      objectId: b.objectId,\n      transform: b.transform ?? null,\n    }))\n  }\n  if (bambu.filamentColors.length > 0) views.filamentColors = bambu.filamentColors\n  if (bambu.filamentTypes.length > 0) views.filamentTypes = bambu.filamentTypes\n  if (bambu.parts.length > 0) {\n    views.parts = bambu.parts.map((p) => ({\n      partIndex: p.partIndex,\n      objectId: p.objectId,\n      partId: p.partId,\n      name: p.name,\n      extruder: p.extruder,\n      plateId: p.plateId,\n    }))\n  }\n  return views\n}\n"]}

package/dist/mesh/threemf-loader.d.ts

@@ -56,12 +56,38 @@ export interface ThreemfObject {
      */
     meta?: ShapeMeta;
 }
+/**
+ * 装配层级节点（方案 2026-10-08 §2.1 / 第 5 步「导入归一」）：一个 `<build><item>`
+ * 或 `<components><component>` 引用，携带**相对父**的位姿（3MF `<component transform>`
+ * 或 build `<item transform>`）。`children` 递归展开嵌套装配。几何由 `localGeomById`
+ * 按 `objectId` 取未烘焙的局部网格（与 `objects` 的已烘焙实例不同轴：assembly 走
+ * 局部几何 + 节点 transform，viewer 走 `objects` 的已烘焙实例）。
+ */
+export interface ThreemfNode {
+    /** 引用的 `<object id>`（必为 `<resources>` 中的对象）。 */
+    objectId: number;
+    /** 相对父的位姿（行主序 3×4，平移在末列，与写出器 `transformToMatrix12` 同源）；无则缺省。 */
+    transform?: readonly number[] | null;
+    /** 子节点（嵌套装配）；叶节点缺省。 */
+    children?: ThreemfNode[];
+}
 /** Structured 3MF parse result. */
 export interface ThreemfArchive {
     /** The declared `<model unit>` mapped to a faijs UnitName. */
     unit: UnitName;
     /** One object per build `<item>` (transform baked), or per `<resources>` object. */
     objects: ThreemfObject[];
+    /**
+     * 装配层级（方案 §2.1 / 第 5 步）：`<build>` 顶层 item + 其 `<components>` 递归展开，
+     * 节点带**相对父**位姿。仅当文件含装配结构（多 item 或任一 item 带 components）时存在。
+     */
+    hierarchy?: ThreemfNode[];
+    /**
+     * 未烘焙的局部几何，按 `<object id>` 索引（mesh 对象 carrying positions/indices；
+     * 组件容器只带 meta）。assembly 重建走它 + `hierarchy` 的节点 transform，与 `objects`
+     * 的已烘焙实例互不干扰。
+     */
+    localGeomById?: Map<number, ThreemfObject>;
     /** Every non-model archive entry (key → raw bytes) for downstream consumers. */
     extraEntries: Map<string, Uint8Array>;
     /** P4：根 model 文档（3D/3dmodel.model）XML——Bambu 层解析 build/组件结构用。 */
@@ -78,9 +104,17 @@ export interface ThreemfArchive {
  * (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 declare function parseThreemf(buffer: ArrayBuffer): Promise<ThreemfArchive>;
+export declare function parseThreemf(buffer: ArrayBuffer, opts?: {
+    unit?: UnitName;
+}): Promise<ThreemfArchive>;
 //# sourceMappingURL=threemf-loader.d.ts.map

package/dist/mesh/threemf-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"threemf-loader.d.ts","sourceRoot":"","sources":["../../src/mesh/threemf-loader.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAyHtD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,YAAY,CAAA;IACvB,OAAO,EAAE,WAAW,CAAA;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAA;IACzF;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,IAAI,EAAE,QAAQ,CAAA;IACd,oFAAoF;IACpF,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,gFAAgF;IAChF,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACrC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAwpBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAwC/E"}
+{"version":3,"file":"threemf-loader.d.ts","sourceRoot":"","sources":["../../src/mesh/threemf-loader.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAkItD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,YAAY,CAAA;IACvB,OAAO,EAAE,WAAW,CAAA;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAA;IACzF;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACpC,uBAAuB;IACvB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,IAAI,EAAE,QAAQ,CAAA;IACd,oFAAoF;IACpF,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,WAAW,EAAE,CAAA;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC1C,gFAAgF;IAChF,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACrC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AA4tBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,GACzB,OAAO,CAAC,cAAc,CAAC,CA6CzB"}

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 名映射到
@@ -756,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.
@@ -770,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));
@@ -796,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.
@@ -809,6 +885,11 @@ export async function parseThreemf(buffer) {
     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 条目）。