@faicad/faijs 0.13.0

package/dist/brep/brep-ops.js

@@ -0,0 +1,545 @@
+/**
+ * 核心 BREP 操作 — 使用 OCCT 精确实体运算
+ *
+ * See docs/api-contract.md §8 (dual-path geometry contract: BREP / Mesh).
+ *
+ * 与 mesh 路径（transform.ts / boolean/ / drill.ts / split.ts / extrude.ts）对照：
+ * - mesh 路径：消费 Shape（三角网格），走 manifold-3d（mesh-CSG）
+ * - BREP 路径：消费 BrepHandle（OCCT 实体句柄），走 OCCT 精确布尔/变换
+ *
+ * 所有函数都是纯函数（可 import occtWasmKernel，不读 store）。
+ * 输入输出均为 OCCT BrepHandle，调用方负责句柄生命周期。
+ *
+ * 坐标系：Z-up、毫米，与 mesh 路径一致。
+ */
+import * as THREE from 'three';
+import { getSolidBoundingBox } from './brep-utils.js';
+// ─── 通用工具 ───
+/**
+ * 将 OCCT solid 三角化为 Shape（供显示用）。
+ *
+ * 如果传入 brepChain + stmtId，同时把完整 BrepMeshResult（含 faceGroups）缓存到
+ * brepChain.meshShapeCache，供 buildBrepTopology 复用——确保拓扑 mesh 与显示 mesh
+ * 完全一致（规则 1：拓扑数据生成所使用的 mesh，必须是当前用户看到的 mesh）。
+ *
+ * @param kernel     the initialized OCCT kernel.
+ * @param solid      the CAD solid handle.
+ * @param segments   optional tessellation segment count (affects precision).
+ * @param brepChain  optional - caches the BrepMeshResult when provided.
+ * @param partName   optional - the part this solid belongs to, paired with brepChain as the cache key.
+ * @returns the tessellated Shape.
+ */
+export function solidToShape(kernel, solid, segments, brepChain, partName) {
+    const angularDeflection = segments
+        ? (2 * Math.PI) / Math.max(3, segments)
+        : (2 * Math.PI) / 64; // 缺省 64 = brepjs standard 等效（§5.0/§5.1）
+    const mesh = kernel.meshShape(solid, {
+        linearDeflection: 0.1,
+        angularDeflection,
+    });
+    // 规则 1：缓存完整 BrepMeshResult（含 faceGroups），供 buildBrepTopology 复用
+    if (brepChain?.meshShapeCache && partName) {
+        brepChain.meshShapeCache.set(partName, mesh);
+    }
+    return {
+        positions: new Float32Array(mesh.positions),
+        indices: new Uint32Array(mesh.indices),
+    };
+}
+// ─── 变换操作 ───
+/**
+ * BREP 平移：使用 OCCT translate（精确，不损失几何精度）。
+ *
+ * @param kernel  OCCT 内核
+ * @param solid   输入实体
+ * @param offset  平移量 [dx, dy, dz]
+ * @returns 新实体（调用方负责释放输入实体）
+ */
+export function translateBrep(kernel, solid, offset) {
+    return kernel.translate(solid, offset[0], offset[1], offset[2]);
+}
+/**
+ * BREP 旋转：使用 OCCT transform（3x4 仿射矩阵）。
+ *
+ * 与 mesh 路径 rotate_euler(shape, anglesDeg, pivot?) 一致：
+ * - anglesDeg 为 XYZ 欧拉角（角度制）
+ * - pivot 为旋转中心（可选，默认原点）
+ *
+ * @param kernel    OCCT 内核
+ * @param solid     输入实体
+ * @param anglesDeg XYZ 欧拉角（角度制）
+ * @param pivot     旋转中心（可选）
+ * @returns 新实体
+ */
+export function rotateBrep(kernel, solid, anglesDeg, pivot) {
+    const euler = new THREE.Euler((anglesDeg[0] * Math.PI) / 180, (anglesDeg[1] * Math.PI) / 180, (anglesDeg[2] * Math.PI) / 180);
+    const matrix = new THREE.Matrix4().makeRotationFromEuler(euler);
+    if (pivot) {
+        matrix.premultiply(new THREE.Matrix4().makeTranslation(pivot[0], pivot[1], pivot[2]));
+        matrix.multiply(new THREE.Matrix4().makeTranslation(-pivot[0], -pivot[1], -pivot[2]));
+    }
+    return kernel.transform(solid, matrixToArray(matrix));
+}
+/**
+ * BREP 缩放：使用 OCCT transform（3x4 仿射矩阵）。
+ *
+ * 与 mesh 路径 scale（P6 §4.6）一致：
+ * - factor 为 number（均匀缩放）或 Vec3 [sx, sy, sz]（非均匀）
+ * - center 为缩放不动点（p' = center + S·(p − center)）；缺省 [0,0,0]（原点），
+ *   与 vendored brepjs `scale(shape, factor, { center? })` 的默认一致。
+ *
+ * @param kernel  OCCT 内核
+ * @param solid   输入实体
+ * @param factor  缩放因子
+ * @param center  缩放不动点（可选，默认原点）
+ * @returns 新实体
+ */
+export function scaleBrep(kernel, solid, factor, center) {
+    const f = typeof factor === 'number' ? [factor, factor, factor] : factor;
+    const scale = new THREE.Matrix4().makeScale(f[0], f[1], f[2]);
+    // T(c)·S·T(−c)：不动点为 center；缺省时退化为原点缩放（现状行为）。
+    const matrix = center
+        ? new THREE.Matrix4()
+            .makeTranslation(center[0], center[1], center[2])
+            .multiply(scale)
+            .multiply(new THREE.Matrix4().makeTranslation(-center[0], -center[1], -center[2]))
+        : scale;
+    const isUniform = f[0] === f[1] && f[1] === f[2];
+    // OCCT gp_Trsf (kernel.transform) only supports uniform scaling.
+    // Non-uniform scaling requires gp_GTrsf (kernel.generalTransform).
+    if (isUniform) {
+        return kernel.transform(solid, matrixToArray(matrix));
+    }
+    return kernel.generalTransform(solid, matrixToArray(matrix));
+}
+// ─── 装配变换 ───
+/**
+ * BREP 版 applyTransform：与 mesh ops/assemble.ts 的 applyTransform 同语义（绕 pivot 旋转 + 平移）。
+ *
+ * 数学公式：p' = R·(p − pivot) + pivot + translation
+ * 等价 Matrix4 = T(pivot) · R · T(−pivot) · T(translation)
+ *
+ * 用四元数而非欧拉角，是因为装配变换源是 api/assembly 的四元数；
+ * 转欧拉会引入顺序/万向锁歧义。与 mesh applyTransform 顶点公式完全等价。
+ *
+ * @param kernel      OCCT 内核
+ * @param solid       输入实体
+ * @param quaternion  旋转四元数 [x, y, z, w]
+ * @param pivot       旋转中心
+ * @param translation 平移量
+ * @returns 新实体（调用方负责释放输入实体）
+ */
+export function applyTransformBrep(kernel, solid, quaternion, pivot, translation) {
+    const rotation = new THREE.Matrix4().makeRotationFromQuaternion(new THREE.Quaternion(quaternion[0], quaternion[1], quaternion[2], quaternion[3]));
+    // T(translation) · T(pivot) · R · T(-pivot) = T(pivot+translation) · R · T(-pivot)
+    // 先绕 pivot 旋转，再平移 translation（与 mesh 路径 applyTransform 一致）
+    const matrix = new THREE.Matrix4()
+        .makeTranslation(pivot[0] + translation[0], pivot[1] + translation[1], pivot[2] + translation[2])
+        .multiply(rotation)
+        .multiply(new THREE.Matrix4().makeTranslation(-pivot[0], -pivot[1], -pivot[2]));
+    return kernel.transform(solid, matrixToArray(matrix));
+}
+// ─── 布尔操作 ───
+/**
+ * BREP 布尔并集：使用 OCCT fuse（BRepAlgoAPI_Fuse）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      实体 A
+ * @param b      实体 B
+ * @returns 融合后的实体
+ */
+export function fuseBrep(kernel, a, b) {
+    return kernel.fuse(a, b);
+}
+/**
+ * BREP 布尔差集：使用 OCCT cut（BRepAlgoAPI_Cut）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      基体
+ * @param b      工具（从基体中减去）
+ * @returns 切割后的实体
+ */
+export function cutBrep(kernel, a, b) {
+    return kernel.cut(a, b);
+}
+/**
+ * BREP 布尔交集：使用 OCCT common（BRepAlgoAPI_Common）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      实体 A
+ * @param b      实体 B
+ * @returns 交集实体
+ */
+export function commonBrep(kernel, a, b) {
+    return kernel.common(a, b);
+}
+/**
+ * BREP 钻孔：创建圆柱工具实体并用 OCCT cut 减去。
+ *
+ * 仅支持圆柱孔（holeType='simple'）。
+ * 螺丝孔（holeType='screw'）由调用方判断为 mesh-only，触发 BREP 链断裂。
+ *
+ * 通孔（depth=0）：创建一个足够长的圆柱体穿透整个零件。
+ * 盲孔（depth>0）：创建指定深度的圆柱体。
+ *
+ * @param kernel OCCT 内核
+ * @param solid  目标实体
+ * @param params 钻孔参数
+ * @returns 钻孔后的实体
+ */
+export function drillBrep(kernel, solid, params) {
+    const radius = params.diameter / 2;
+    const direction = new THREE.Vector3(...params.direction).normalize();
+    // 确保方向指向材料内部
+    const faceNormal = new THREE.Vector3(...params.faceNormal);
+    if (direction.dot(faceNormal) > 0) {
+        direction.negate();
+    }
+    // 计算孔的高度和中心
+    const bbox = getSolidBoundingBox(kernel, solid);
+    const bboxSize = new THREE.Vector3(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2]);
+    const bboxMax = Math.max(bboxSize.x, bboxSize.y, bboxSize.z);
+    let holeHeight;
+    let holeCenter;
+    const pos = new THREE.Vector3(...params.position);
+    // 通孔：depth <= 0（契约：depth<=0 表示通孔，与 mesh 路径 `depth>0 ? 'blind':'through'` 一致）。
+    // ⚠️ 只判 `=== 0` 会让 depth<0 落入盲孔分支 → safeDepth=0 → 零高圆柱 → OCCT transform 崩溃。
+    if (params.depth <= 0) {
+        const d = direction.clone().normalize();
+        const bbMin = new THREE.Vector3(bbox.min[0], bbox.min[1], bbox.min[2]);
+        const bbMax = new THREE.Vector3(bbox.max[0], bbox.max[1], bbox.max[2]);
+        let tNear = -Infinity;
+        let tFar = Infinity;
+        const axes = [
+            [0, d.x, bbMin.x, bbMax.x],
+            [1, d.y, bbMin.y, bbMax.y],
+            [2, d.z, bbMin.z, bbMax.z],
+        ];
+        const pArr = [pos.x, pos.y, pos.z];
+        for (const [axis, di, lo, hi] of axes) {
+            const pi = pArr[axis];
+            if (Math.abs(di) > 1e-12) {
+                const t1 = (lo - pi) / di;
+                const t2 = (hi - pi) / di;
+                tNear = Math.max(tNear, Math.min(t1, t2));
+                tFar = Math.min(tFar, Math.max(t1, t2));
+            }
+            else if (pi < lo || pi > hi) {
+                // 与 slab 平行且在外部 — 无交点（与 mesh 行为一致：几乎不钻孔）
+                tNear = 0;
+                tFar = 0;
+            }
+        }
+        if (!isFinite(tNear) || !isFinite(tFar) || tFar < tNear) {
+            // 不穿过 bbox：与 mesh 一致，只留 0.2mm 微小孔
+            holeHeight = 0.2;
+            holeCenter = pos.clone();
+        }
+        else {
+            holeHeight = tFar - tNear + 0.2;
+            holeCenter = pos.clone().add(direction.clone().normalize().multiplyScalar((tNear + tFar) / 2));
+        }
+    }
+    else {
+        // 盲孔：深度钳制到 bboxMax（与 mesh cad-core/drill.ts 一致）
+        const safeDepth = Math.max(0, Math.min(params.depth, bboxMax));
+        holeHeight = safeDepth;
+        holeCenter = pos.clone().add(direction.clone().normalize().multiplyScalar(safeDepth / 2));
+    }
+    // OCCT makeCylinder 创建 Z 轴方向的圆柱体（从 Z=0 到 Z=height）
+    // 需要将圆柱体旋转到钻孔方向，并平移到孔中心
+    const cylinder = kernel.makeCylinder(radius, holeHeight);
+    // 计算从 Z 轴到 direction 的旋转
+    const zAxis = new THREE.Vector3(0, 0, 1);
+    const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, direction);
+    const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat);
+    // 平移矩阵：到孔中心，并减去 height/2（因为圆柱从 Z=0 开始）
+    const transMatrix = new THREE.Matrix4().makeTranslation(holeCenter.x, holeCenter.y, holeCenter.z);
+    // 组合：先旋转，再平移
+    const finalMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix);
+    // 还需要补偿圆柱的起始位置（从 Z=0 开始 → 需要先下移 height/2）
+    const offsetMatrix = new THREE.Matrix4().makeTranslation(0, 0, -holeHeight / 2);
+    const fullMatrix = new THREE.Matrix4().multiplyMatrices(finalMatrix, offsetMatrix);
+    const toolSolid = kernel.transform(cylinder, matrixToArray(fullMatrix));
+    kernel.release(cylinder);
+    try {
+        const result = kernel.cut(solid, toolSolid);
+        kernel.release(toolSolid);
+        return result;
+    }
+    catch (err) {
+        kernel.release(toolSolid);
+        throw new Error(`[drillBrep] OCCT cut failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+/**
+ * BREP 平面分割：使用 OCCT cut + common 实现平面分割。
+ *
+ * 仅支持平面分割（cutMode='plane'）。
+ * 燕尾/定位销/直榫等复杂分割由 joinery-brep.ts 处理。
+ *
+ * 实现方式：
+ * 1. 创建一个大的半空间盒子（法线正方向一侧）
+ * 2. common(solid, box) → 法线正方向的半部分
+ * 3. cut(solid, box) → 法线负方向的半部分
+ *
+ * @param kernel OCCT 内核
+ * @param solid  目标实体
+ * @param params 分割参数
+ * @returns 两个半部分
+ */
+export function splitBrep(kernel, solid, params) {
+    const bbox = getSolidBoundingBox(kernel, solid);
+    const bboxSize = new THREE.Vector3(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2]);
+    const bboxMax = Math.max(bboxSize.x, bboxSize.y, bboxSize.z);
+    const bboxCenter = new THREE.Vector3((bbox.min[0] + bbox.max[0]) / 2, (bbox.min[1] + bbox.max[1]) / 2, (bbox.min[2] + bbox.max[2]) / 2);
+    // 创建一个大的盒子代表法线正方向的半空间
+    const normal = new THREE.Vector3(...params.normal).normalize();
+    const halfSize = bboxMax * 3; // 足够大
+    // 先在局部坐标系（Z 轴 = 法线方向）创建盒子
+    // 然后旋转到世界坐标系
+    const zAxis = new THREE.Vector3(0, 0, 1);
+    const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, normal);
+    const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat);
+    // 在局部坐标系中，盒子从 Z=0（切割平面）延伸到 Z=halfSize
+    const localBox = kernel.makeBoxFromCorners({ x: -halfSize, y: -halfSize, z: 0 }, { x: halfSize, y: halfSize, z: halfSize });
+    // 计算切割平面的世界坐标原点
+    const planeOrigin = params.planeCenter
+        ? new THREE.Vector3(...params.planeCenter)
+        : bboxCenter.clone().add(normal.clone().multiplyScalar(params.originOffset));
+    const transMatrix = new THREE.Matrix4().makeTranslation(planeOrigin.x, planeOrigin.y, planeOrigin.z);
+    const finalMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix);
+    const halfSpaceBox = kernel.transform(localBox, matrixToArray(finalMatrix));
+    kernel.release(localBox);
+    try {
+        const front = kernel.common(solid, halfSpaceBox);
+        const back = kernel.cut(solid, halfSpaceBox);
+        kernel.release(halfSpaceBox);
+        return { front, back };
+    }
+    catch (err) {
+        kernel.release(halfSpaceBox);
+        throw new Error(`[splitBrep] OCCT split failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+/**
+ * BREP 拉伸：在切割平面处将实体切开，中段沿法线拉伸 length，三段 fuse。
+ *
+ * 实现方式：
+ * 1. 用平面分割得到 front + back
+ * 2. 获取截面线（section edges → wire → face）
+ * 3. 沿法线拉伸截面 face → 中段实体
+ * 4. fuse(front, extruded, back)
+ *
+ * 如果截面无法构建 face（开放线框等），抛出错误由调用方处理为链断裂。
+ *
+ * @param kernel OCCT 内核
+ * @param solid  目标实体
+ * @param params 拉伸参数
+ * @returns 拉伸后的实体
+ */
+export function extrudeBrep(kernel, solid, params) {
+    const mode = params.mode ?? 'centered';
+    const normal = new THREE.Vector3(...params.normal).normalize();
+    const length = params.length;
+    // 1. 创建切割平面盒子
+    const bbox = getSolidBoundingBox(kernel, solid);
+    const bboxCenter = new THREE.Vector3((bbox.min[0] + bbox.max[0]) / 2, (bbox.min[1] + bbox.max[1]) / 2, (bbox.min[2] + bbox.max[2]) / 2);
+    const planeOrigin = bboxCenter.clone().add(normal.clone().multiplyScalar(params.originOffset));
+    // 2. 分割实体
+    const splitResult = splitBrep(kernel, solid, {
+        normal: [normal.x, normal.y, normal.z],
+        originOffset: params.originOffset,
+        planeCenter: [planeOrigin.x, planeOrigin.y, planeOrigin.z],
+    });
+    // 3. 获取截面
+    // 使用 section 获取切割平面与实体的交线
+    const zAxis = new THREE.Vector3(0, 0, 1);
+    const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, normal);
+    const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat);
+    const transMatrix = new THREE.Matrix4().makeTranslation(planeOrigin.x, planeOrigin.y, planeOrigin.z);
+    const planeMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix);
+    // 创建一个大的矩形面作为切割平面
+    const bboxSize = new THREE.Vector3(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2]);
+    const planeSize = Math.max(bboxSize.x, bboxSize.y, bboxSize.z) * 3;
+    const planeRect = kernel.makeRectangle(planeSize, planeSize);
+    // makeRectangle creates a face from [0,0] to [width,height] — center it at origin first
+    const centerMatrix = new THREE.Matrix4().makeTranslation(-planeSize / 2, -planeSize / 2, 0);
+    const centeredRect = kernel.transform(planeRect, matrixToArray(centerMatrix));
+    kernel.release(planeRect);
+    const planeFace = kernel.transform(centeredRect, matrixToArray(planeMatrix));
+    kernel.release(centeredRect);
+    // 获取截面边
+    const sectionEdges = kernel.section(solid, planeFace);
+    kernel.release(planeFace);
+    // 4. 构建截面 wire → face → 拉伸
+    let extrudedSolid;
+    try {
+        // 尝试从截面边构建 wire
+        const subShapes = kernel.getSubShapes(sectionEdges, 'edge');
+        if (subShapes.length === 0) {
+            kernel.release(sectionEdges);
+            kernel.release(splitResult.front);
+            kernel.release(splitResult.back);
+            throw new Error('no section edges from plane intersection');
+        }
+        const wire = kernel.makeWire(subShapes);
+        const face = kernel.makeFace(wire);
+        kernel.release(wire);
+        // 计算拉伸向量
+        let extrudeVec;
+        if (mode === 'centered') {
+            extrudeVec = normal.clone().multiplyScalar(length);
+        }
+        else if (mode === 'forward') {
+            extrudeVec = normal.clone().multiplyScalar(length);
+        }
+        else {
+            // backward
+            extrudeVec = normal.clone().multiplyScalar(-length);
+        }
+        extrudedSolid = kernel.extrude(face, extrudeVec.x, extrudeVec.y, extrudeVec.z);
+        kernel.release(face);
+        kernel.release(sectionEdges);
+    }
+    catch {
+        // 截面构建失败 — 释放资源并抛出
+        if (sectionEdges)
+            kernel.release(sectionEdges);
+        kernel.release(splitResult.front);
+        kernel.release(splitResult.back);
+        throw new Error('[extrudeBrep] failed to build extrusion from section');
+    }
+    // 5. 计算各段位置
+    let frontOffset;
+    let backOffset;
+    if (mode === 'centered') {
+        frontOffset = length / 2;
+        backOffset = -length / 2;
+    }
+    else if (mode === 'forward') {
+        frontOffset = length;
+        backOffset = 0;
+    }
+    else {
+        frontOffset = 0;
+        backOffset = -length;
+    }
+    // 平移 front 和 back
+    const frontTranslated = kernel.translate(splitResult.front, normal.x * frontOffset, normal.y * frontOffset, normal.z * frontOffset);
+    kernel.release(splitResult.front);
+    const backTranslated = kernel.translate(splitResult.back, normal.x * backOffset, normal.y * backOffset, normal.z * backOffset);
+    kernel.release(splitResult.back);
+    // 6. Fuse 三段
+    let result;
+    try {
+        const fused1 = kernel.fuse(frontTranslated, extrudedSolid);
+        kernel.release(frontTranslated);
+        kernel.release(extrudedSolid);
+        result = kernel.fuse(fused1, backTranslated);
+        kernel.release(fused1);
+        kernel.release(backTranslated);
+    }
+    catch (err) {
+        kernel.release(frontTranslated);
+        kernel.release(extrudedSolid);
+        kernel.release(backTranslated);
+        throw new Error(`[extrudeBrep] fuse failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    return result;
+}
+// ─── STEP/BREP 导入操作 ───
+/**
+ * BREP-native STEP 导入：使用 OCCT kernel.importStep 导入 STEP 文件为精确实体。
+ *
+ * 与 mesh 路径（cad-core/io.ts importFile → loadFormat → meshes）对照：
+ * - mesh 路径：STEP → 三角网格，丢弃 OCCT BrepHandle
+ * - BREP 路径：STEP → kernel.importStep → 保留 BrepHandle，同时三角化为显示 mesh
+ *
+ * 导入的 solid 存入 brepChain.solidCache，后续操作（drillBrep/splitBrep 等）
+ * 将其作为"基座特征"进行精确运算。
+ *
+ * **设计决策（I5 不准合并）**：
+ * - 单 solid STEP：`importStep` 返回 Compound 包裹（顶层是 `TopoDS_Compound`，
+ *   内含 1 个 `TopoDS_Solid`）。此处**解包**返回真实 Solid（`solids[0]`），
+ *   下游 `isValid`/编辑/导出都针对真实实体。
+ * - 多 solid STEP：返回顶层 Compound **不 fuse**。`meshShape(compound)` 整体显示，
+ *   导出时 Compound 仍含全部 solid（非三角化）。逐 part 编辑由 Phase 1 XCAF 负责。
+ * - **不调用 `kernel.isValid`**：`importStep` 对单 solid STEP 也返回 Compound 包裹，
+ *   `isValid(compound)` 返回 false（Compound 不是 Solid），这会误杀合法 STEP。
+ *   合法性判据改为 `getSubShapes(top, 'solid').length >= 1`（含 ≥1 个 solid 即合法），
+ *   与装配路径 `walkLabel` 一致。
+ *
+ * @param kernel     the initialized OCCT kernel.
+ * @param buffer     the raw STEP file bytes (a text-encoded ArrayBuffer).
+ * @param brepChain  optional - caches the tessellated BrepMeshResult when provided.
+ * @param stmtId     optional - the part this solid belongs to, paired with brepChain as the cache key.
+ * @param partIndex  optional - for multi-solid files, return the N-th sub-solid
+ *                   (host emits one load statement per part with its index).
+ * @returns { solid: the OCCT solid handle, shape: the display tessellated mesh }
+ */
+export function loadBrep(kernel, buffer, brepChain, stmtId, partIndex) {
+    // BREP 文件（CASCADE Topology 文本格式）必须用 kernel.fromBREP 解析；
+    // 误用 STEP 解析器（importStep）读 BREP 会抛 "failed to read STEP data"。
+    const decoder = new TextDecoder('utf-8');
+    const head = decoder.decode(buffer.slice(0, 64));
+    const top = head.includes('CASCADE Topology')
+        ? kernel.fromBREP(decoder.decode(buffer))
+        : kernel.importStep(buffer);
+    // 校验：含至少一个 solid 子形即合法（不调用 isValid，见上文设计决策）
+    const solids = kernel.getSubShapes(top, 'solid');
+    if (solids.length < 1) {
+        kernel.release(top);
+        throw new Error(`[loadBrep] imported shape contains no solid sub-shapes ` +
+            `(solidCount=0) — wireframe/surface/invalid shapes are not supported`);
+    }
+    // 单 solid：解包返回真实 Solid（非 Compound 包裹）
+    if (solids.length === 1) {
+        const realSolid = solids[0];
+        kernel.release(top); // 释放 Compound 包裹，realSolid 独立持有
+        const shape = solidToShape(kernel, realSolid, undefined, brepChain, stmtId);
+        return { solid: realSolid, shape };
+    }
+    // 多 solid + partIndex：提取第 partIndex 个子 solid（逐 part load 语句使用）。
+    // 宿主为多 part 文件的每个 part 生成独立 load 语句并携带 partIndex，
+    // 使每条 load 输出对应 part 的几何，而不是整个文件的 Compound。
+    if (partIndex !== undefined) {
+        const target = solids[partIndex];
+        if (!target) {
+            kernel.release(top);
+            throw new Error(`[loadBrep] partIndex ${partIndex} out of range (${solids.length} solids)`);
+        }
+        kernel.release(top); // 释放 Compound 包裹，target 独立持有（同单 solid 模式）
+        const shape = solidToShape(kernel, target, undefined, brepChain, stmtId);
+        return { solid: target, shape };
+    }
+    // 多 solid：保留 Compound 不合并（I5），逐 part 编辑由 Phase 1 XCAF 负责
+    // 释放提取的子形句柄（它们是 top 的子引用，top 本身持有几何）
+    for (const s of solids) {
+        try {
+            kernel.release(s);
+        }
+        catch { /* already released */ }
+    }
+    const shape = solidToShape(kernel, top, undefined, brepChain, stmtId);
+    return { solid: top, shape };
+}
+// ─── 辅助函数 ───
+/**
+ * Convert a THREE.Matrix4 into the 3x4 row-major array (12 doubles) the OCCT
+ * transform expects.
+ *
+ * OCCT transform accepts [r00,r01,r02,tx, r10,r11,r12,ty, r20,r21,r22,tz].
+ * @param matrix - the source matrix to convert.
+ * @returns the 3x4 row-major array of 12 doubles.
+ */
+export function matrixToArray(matrix) {
+    const e = matrix.elements;
+    // THREE.Matrix4 是 column-major，OCCT 需要 row-major 3x4
+    return [
+        e[0], e[4], e[8], e[12],
+        e[1], e[5], e[9], e[13],
+        e[2], e[6], e[10], e[14],
+    ];
+}
+//# sourceMappingURL=brep-ops.js.map

package/dist/brep/brep-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brep-ops.js","sourceRoot":"","sources":["../../src/brep/brep-ops.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 核心 BREP 操作 — 使用 OCCT 精确实体运算\n *\n * See docs/api-contract.md §8 (dual-path geometry contract: BREP / Mesh).\n *\n * 与 mesh 路径（transform.ts / boolean/ / drill.ts / split.ts / extrude.ts）对照：\n * - mesh 路径：消费 Shape（三角网格），走 manifold-3d（mesh-CSG）\n * - BREP 路径：消费 BrepHandle（OCCT 实体句柄），走 OCCT 精确布尔/变换\n *\n * 所有函数都是纯函数（可 import occtWasmKernel，不读 store）。\n * 输入输出均为 OCCT BrepHandle，调用方负责句柄生命周期。\n *\n * 坐标系：Z-up、毫米，与 mesh 路径一致。\n */\n\nimport * as THREE from 'three'\nimport type { BrepHandle, BrepMeshResult } from './engine/types'\nimport type { BrepEngineApi } from './engine/primitives'\nimport type { Shape, Vec3 } from '../mesh/types'\nimport type { BrepChainState } from './brep-chain'\nimport type { PartName } from '../identity'\nimport { getSolidBoundingBox } from './brep-utils'\n\n// ─── 通用工具 ───\n\n/**\n * 将 OCCT solid 三角化为 Shape（供显示用）。\n *\n * 如果传入 brepChain + stmtId，同时把完整 BrepMeshResult（含 faceGroups）缓存到\n * brepChain.meshShapeCache，供 buildBrepTopology 复用——确保拓扑 mesh 与显示 mesh\n * 完全一致（规则 1：拓扑数据生成所使用的 mesh，必须是当前用户看到的 mesh）。\n *\n * @param kernel     the initialized OCCT kernel.\n * @param solid      the CAD solid handle.\n * @param segments   optional tessellation segment count (affects precision).\n * @param brepChain  optional - caches the BrepMeshResult when provided.\n * @param partName   optional - the part this solid belongs to, paired with brepChain as the cache key.\n * @returns the tessellated Shape.\n */\nexport function solidToShape(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  segments?: number,\n  brepChain?: BrepChainState,\n  partName?: PartName,\n): Shape {\n  const angularDeflection = segments\n    ? (2 * Math.PI) / Math.max(3, segments)\n    : (2 * Math.PI) / 64 // 缺省 64 = brepjs standard 等效（§5.0/§5.1）\n  const mesh: BrepMeshResult = kernel.meshShape(solid, {\n    linearDeflection: 0.1,\n    angularDeflection,\n  })\n\n  // 规则 1：缓存完整 BrepMeshResult（含 faceGroups），供 buildBrepTopology 复用\n  if (brepChain?.meshShapeCache && partName) {\n    brepChain.meshShapeCache.set(partName, mesh)\n  }\n\n  return {\n    positions: new Float32Array(mesh.positions),\n    indices: new Uint32Array(mesh.indices),\n  }\n}\n\n// ─── 变换操作 ───\n\n/**\n * BREP 平移：使用 OCCT translate（精确，不损失几何精度）。\n *\n * @param kernel  OCCT 内核\n * @param solid   输入实体\n * @param offset  平移量 [dx, dy, dz]\n * @returns 新实体（调用方负责释放输入实体）\n */\nexport function translateBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  offset: Vec3,\n): BrepHandle {\n  return kernel.translate(solid, offset[0], offset[1], offset[2])\n}\n\n/**\n * BREP 旋转：使用 OCCT transform（3x4 仿射矩阵）。\n *\n * 与 mesh 路径 rotate_euler(shape, anglesDeg, pivot?) 一致：\n * - anglesDeg 为 XYZ 欧拉角（角度制）\n * - pivot 为旋转中心（可选，默认原点）\n *\n * @param kernel    OCCT 内核\n * @param solid     输入实体\n * @param anglesDeg XYZ 欧拉角（角度制）\n * @param pivot     旋转中心（可选）\n * @returns 新实体\n */\nexport function rotateBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  anglesDeg: Vec3,\n  pivot?: Vec3,\n): BrepHandle {\n  const euler = new THREE.Euler(\n    (anglesDeg[0] * Math.PI) / 180,\n    (anglesDeg[1] * Math.PI) / 180,\n    (anglesDeg[2] * Math.PI) / 180,\n  )\n  const matrix = new THREE.Matrix4().makeRotationFromEuler(euler)\n  if (pivot) {\n    matrix.premultiply(new THREE.Matrix4().makeTranslation(pivot[0], pivot[1], pivot[2]))\n    matrix.multiply(new THREE.Matrix4().makeTranslation(-pivot[0], -pivot[1], -pivot[2]))\n  }\n  return kernel.transform(solid, matrixToArray(matrix))\n}\n\n/**\n * BREP 缩放：使用 OCCT transform（3x4 仿射矩阵）。\n *\n * 与 mesh 路径 scale（P6 §4.6）一致：\n * - factor 为 number（均匀缩放）或 Vec3 [sx, sy, sz]（非均匀）\n * - center 为缩放不动点（p' = center + S·(p − center)）；缺省 [0,0,0]（原点），\n *   与 vendored brepjs `scale(shape, factor, { center? })` 的默认一致。\n *\n * @param kernel  OCCT 内核\n * @param solid   输入实体\n * @param factor  缩放因子\n * @param center  缩放不动点（可选，默认原点）\n * @returns 新实体\n */\nexport function scaleBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  factor: number | Vec3,\n  center?: Vec3,\n): BrepHandle {\n  const f = typeof factor === 'number' ? [factor, factor, factor] : factor\n  const scale = new THREE.Matrix4().makeScale(f[0], f[1], f[2])\n  // T(c)·S·T(−c)：不动点为 center；缺省时退化为原点缩放（现状行为）。\n  const matrix = center\n    ? new THREE.Matrix4()\n        .makeTranslation(center[0], center[1], center[2])\n        .multiply(scale)\n        .multiply(new THREE.Matrix4().makeTranslation(-center[0], -center[1], -center[2]))\n    : scale\n  const isUniform = f[0] === f[1] && f[1] === f[2]\n  // OCCT gp_Trsf (kernel.transform) only supports uniform scaling.\n  // Non-uniform scaling requires gp_GTrsf (kernel.generalTransform).\n  if (isUniform) {\n    return kernel.transform(solid, matrixToArray(matrix))\n  }\n  return kernel.generalTransform(solid, matrixToArray(matrix))\n}\n\n// ─── 装配变换 ───\n\n/**\n * BREP 版 applyTransform：与 mesh ops/assemble.ts 的 applyTransform 同语义（绕 pivot 旋转 + 平移）。\n *\n * 数学公式：p' = R·(p − pivot) + pivot + translation\n * 等价 Matrix4 = T(pivot) · R · T(−pivot) · T(translation)\n *\n * 用四元数而非欧拉角，是因为装配变换源是 api/assembly 的四元数；\n * 转欧拉会引入顺序/万向锁歧义。与 mesh applyTransform 顶点公式完全等价。\n *\n * @param kernel      OCCT 内核\n * @param solid       输入实体\n * @param quaternion  旋转四元数 [x, y, z, w]\n * @param pivot       旋转中心\n * @param translation 平移量\n * @returns 新实体（调用方负责释放输入实体）\n */\nexport function applyTransformBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  quaternion: [number, number, number, number],\n  pivot: [number, number, number],\n  translation: [number, number, number],\n): BrepHandle {\n  const rotation = new THREE.Matrix4().makeRotationFromQuaternion(\n    new THREE.Quaternion(quaternion[0], quaternion[1], quaternion[2], quaternion[3]),\n  )\n  // T(translation) · T(pivot) · R · T(-pivot) = T(pivot+translation) · R · T(-pivot)\n  // 先绕 pivot 旋转，再平移 translation（与 mesh 路径 applyTransform 一致）\n  const matrix = new THREE.Matrix4()\n    .makeTranslation(pivot[0] + translation[0], pivot[1] + translation[1], pivot[2] + translation[2])\n    .multiply(rotation)\n    .multiply(new THREE.Matrix4().makeTranslation(-pivot[0], -pivot[1], -pivot[2]))\n  return kernel.transform(solid, matrixToArray(matrix))\n}\n\n// ─── 布尔操作 ───\n\n/**\n * BREP 布尔并集：使用 OCCT fuse（BRepAlgoAPI_Fuse）。\n *\n * @param kernel OCCT 内核\n * @param a      实体 A\n * @param b      实体 B\n * @returns 融合后的实体\n */\nexport function fuseBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): BrepHandle {\n  return kernel.fuse(a, b)\n}\n\n/**\n * BREP 布尔差集：使用 OCCT cut（BRepAlgoAPI_Cut）。\n *\n * @param kernel OCCT 内核\n * @param a      基体\n * @param b      工具（从基体中减去）\n * @returns 切割后的实体\n */\nexport function cutBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): BrepHandle {\n  return kernel.cut(a, b)\n}\n\n/**\n * BREP 布尔交集：使用 OCCT common（BRepAlgoAPI_Common）。\n *\n * @param kernel OCCT 内核\n * @param a      实体 A\n * @param b      实体 B\n * @returns 交集实体\n */\nexport function commonBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): BrepHandle {\n  return kernel.common(a, b)\n}\n\n// ─── 钻孔操作 ───\n\n/** drillBrep 的参数 */\nexport interface DrillBrepParams {\n  /** 孔直径 */\n  diameter: number\n  /** 孔深度（0 = 通孔） */\n  depth: number\n  /** 孔位置（世界空间） */\n  position: Vec3\n  /** 钻孔方向（世界空间，指向材料内部） */\n  direction: Vec3\n  /** 面法向（世界空间） */\n  faceNormal: Vec3\n  /** 孔类型 */\n  holeType?: 'simple' | 'screw'\n}\n\n/**\n * BREP 钻孔：创建圆柱工具实体并用 OCCT cut 减去。\n *\n * 仅支持圆柱孔（holeType='simple'）。\n * 螺丝孔（holeType='screw'）由调用方判断为 mesh-only，触发 BREP 链断裂。\n *\n * 通孔（depth=0）：创建一个足够长的圆柱体穿透整个零件。\n * 盲孔（depth>0）：创建指定深度的圆柱体。\n *\n * @param kernel OCCT 内核\n * @param solid  目标实体\n * @param params 钻孔参数\n * @returns 钻孔后的实体\n */\nexport function drillBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  params: DrillBrepParams,\n): BrepHandle {\n  const radius = params.diameter / 2\n  const direction = new THREE.Vector3(...params.direction).normalize()\n  // 确保方向指向材料内部\n  const faceNormal = new THREE.Vector3(...params.faceNormal)\n  if (direction.dot(faceNormal) > 0) {\n    direction.negate()\n  }\n\n  // 计算孔的高度和中心\n  const bbox = getSolidBoundingBox(kernel, solid)\n  const bboxSize = new THREE.Vector3(\n    bbox.max[0] - bbox.min[0],\n    bbox.max[1] - bbox.min[1],\n    bbox.max[2] - bbox.min[2],\n  )\n  const bboxMax = Math.max(bboxSize.x, bboxSize.y, bboxSize.z)\n\n  let holeHeight: number\n  let holeCenter: THREE.Vector3\n  const pos = new THREE.Vector3(...params.position)\n\n  // 通孔：depth <= 0（契约：depth<=0 表示通孔，与 mesh 路径 `depth>0 ? 'blind':'through'` 一致）。\n  // ⚠️ 只判 `=== 0` 会让 depth<0 落入盲孔分支 → safeDepth=0 → 零高圆柱 → OCCT transform 崩溃。\n  if (params.depth <= 0) {\n    const d = direction.clone().normalize()\n    const bbMin = new THREE.Vector3(bbox.min[0], bbox.min[1], bbox.min[2])\n    const bbMax = new THREE.Vector3(bbox.max[0], bbox.max[1], bbox.max[2])\n\n    let tNear = -Infinity\n    let tFar = Infinity\n    const axes: Array<[number, number, number, number]> = [\n      [0, d.x, bbMin.x, bbMax.x],\n      [1, d.y, bbMin.y, bbMax.y],\n      [2, d.z, bbMin.z, bbMax.z],\n    ]\n    const pArr = [pos.x, pos.y, pos.z]\n    for (const [axis, di, lo, hi] of axes) {\n      const pi = pArr[axis]\n      if (Math.abs(di) > 1e-12) {\n        const t1 = (lo - pi) / di\n        const t2 = (hi - pi) / di\n        tNear = Math.max(tNear, Math.min(t1, t2))\n        tFar = Math.min(tFar, Math.max(t1, t2))\n      } else if (pi < lo || pi > hi) {\n        // 与 slab 平行且在外部 — 无交点（与 mesh 行为一致：几乎不钻孔）\n        tNear = 0\n        tFar = 0\n      }\n    }\n    if (!isFinite(tNear) || !isFinite(tFar) || tFar < tNear) {\n      // 不穿过 bbox：与 mesh 一致，只留 0.2mm 微小孔\n      holeHeight = 0.2\n      holeCenter = pos.clone()\n    } else {\n      holeHeight = tFar - tNear + 0.2\n      holeCenter = pos.clone().add(direction.clone().normalize().multiplyScalar((tNear + tFar) / 2))\n    }\n  } else {\n    // 盲孔：深度钳制到 bboxMax（与 mesh cad-core/drill.ts 一致）\n    const safeDepth = Math.max(0, Math.min(params.depth, bboxMax))\n    holeHeight = safeDepth\n    holeCenter = pos.clone().add(direction.clone().normalize().multiplyScalar(safeDepth / 2))\n  }\n\n  // OCCT makeCylinder 创建 Z 轴方向的圆柱体（从 Z=0 到 Z=height）\n  // 需要将圆柱体旋转到钻孔方向，并平移到孔中心\n  const cylinder = kernel.makeCylinder(radius, holeHeight)\n\n  // 计算从 Z 轴到 direction 的旋转\n  const zAxis = new THREE.Vector3(0, 0, 1)\n  const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, direction)\n  const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat)\n\n  // 平移矩阵：到孔中心，并减去 height/2（因为圆柱从 Z=0 开始）\n  const transMatrix = new THREE.Matrix4().makeTranslation(\n    holeCenter.x,\n    holeCenter.y,\n    holeCenter.z,\n  )\n  // 组合：先旋转，再平移\n  const finalMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix)\n  // 还需要补偿圆柱的起始位置（从 Z=0 开始 → 需要先下移 height/2）\n  const offsetMatrix = new THREE.Matrix4().makeTranslation(0, 0, -holeHeight / 2)\n  const fullMatrix = new THREE.Matrix4().multiplyMatrices(finalMatrix, offsetMatrix)\n\n  const toolSolid = kernel.transform(cylinder, matrixToArray(fullMatrix))\n  kernel.release(cylinder)\n\n  try {\n    const result = kernel.cut(solid, toolSolid)\n    kernel.release(toolSolid)\n    return result\n  } catch (err) {\n    kernel.release(toolSolid)\n    throw new Error(`[drillBrep] OCCT cut failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err })\n  }\n}\n\n// ─── 分割操作 ───\n\n/** splitBrep 的参数 */\nexport interface SplitBrepParams {\n  /** 切割平面法线 */\n  normal: Vec3\n  /** 切割平面原点偏移（法线方向上的距离） */\n  originOffset: number\n  /** 切割平面中心点 */\n  planeCenter: Vec3\n}\n\n/** splitBrep 的结果 */\nexport interface SplitBrepResult {\n  /** 法线正方向的半部分 */\n  front: BrepHandle\n  /** 法线负方向的半部分 */\n  back: BrepHandle\n}\n\n/**\n * BREP 平面分割：使用 OCCT cut + common 实现平面分割。\n *\n * 仅支持平面分割（cutMode='plane'）。\n * 燕尾/定位销/直榫等复杂分割由 joinery-brep.ts 处理。\n *\n * 实现方式：\n * 1. 创建一个大的半空间盒子（法线正方向一侧）\n * 2. common(solid, box) → 法线正方向的半部分\n * 3. cut(solid, box) → 法线负方向的半部分\n *\n * @param kernel OCCT 内核\n * @param solid  目标实体\n * @param params 分割参数\n * @returns 两个半部分\n */\nexport function splitBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  params: SplitBrepParams,\n): SplitBrepResult {\n  const bbox = getSolidBoundingBox(kernel, solid)\n  const bboxSize = new THREE.Vector3(\n    bbox.max[0] - bbox.min[0],\n    bbox.max[1] - bbox.min[1],\n    bbox.max[2] - bbox.min[2],\n  )\n  const bboxMax = Math.max(bboxSize.x, bboxSize.y, bboxSize.z)\n  const bboxCenter = new THREE.Vector3(\n    (bbox.min[0] + bbox.max[0]) / 2,\n    (bbox.min[1] + bbox.max[1]) / 2,\n    (bbox.min[2] + bbox.max[2]) / 2,\n  )\n\n  // 创建一个大的盒子代表法线正方向的半空间\n  const normal = new THREE.Vector3(...params.normal).normalize()\n  const halfSize = bboxMax * 3 // 足够大\n\n  // 先在局部坐标系（Z 轴 = 法线方向）创建盒子\n  // 然后旋转到世界坐标系\n  const zAxis = new THREE.Vector3(0, 0, 1)\n  const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, normal)\n  const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat)\n\n  // 在局部坐标系中，盒子从 Z=0（切割平面）延伸到 Z=halfSize\n  const localBox = kernel.makeBoxFromCorners(\n    { x: -halfSize, y: -halfSize, z: 0 },\n    { x: halfSize, y: halfSize, z: halfSize },\n  )\n\n  // 计算切割平面的世界坐标原点\n  const planeOrigin = params.planeCenter\n    ? new THREE.Vector3(...params.planeCenter)\n    : bboxCenter.clone().add(normal.clone().multiplyScalar(params.originOffset))\n\n  const transMatrix = new THREE.Matrix4().makeTranslation(\n    planeOrigin.x,\n    planeOrigin.y,\n    planeOrigin.z,\n  )\n  const finalMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix)\n\n  const halfSpaceBox = kernel.transform(localBox, matrixToArray(finalMatrix))\n  kernel.release(localBox)\n\n  try {\n    const front = kernel.common(solid, halfSpaceBox)\n    const back = kernel.cut(solid, halfSpaceBox)\n    kernel.release(halfSpaceBox)\n    return { front, back }\n  } catch (err) {\n    kernel.release(halfSpaceBox)\n    throw new Error(`[splitBrep] OCCT split failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err })\n  }\n}\n\n// ─── 拉伸操作 ───\n\n/** extrudeBrep 的参数 */\nexport interface ExtrudeBrepParams {\n  /** 拉伸法线方向 */\n  normal: Vec3\n  /** 平面原点偏移 */\n  originOffset: number\n  /** 拉伸长度 */\n  length: number\n  /** 拉伸模式 */\n  mode?: 'centered' | 'forward' | 'backward'\n}\n\n/**\n * BREP 拉伸：在切割平面处将实体切开，中段沿法线拉伸 length，三段 fuse。\n *\n * 实现方式：\n * 1. 用平面分割得到 front + back\n * 2. 获取截面线（section edges → wire → face）\n * 3. 沿法线拉伸截面 face → 中段实体\n * 4. fuse(front, extruded, back)\n *\n * 如果截面无法构建 face（开放线框等），抛出错误由调用方处理为链断裂。\n *\n * @param kernel OCCT 内核\n * @param solid  目标实体\n * @param params 拉伸参数\n * @returns 拉伸后的实体\n */\nexport function extrudeBrep(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  params: ExtrudeBrepParams,\n): BrepHandle {\n  const mode = params.mode ?? 'centered'\n  const normal = new THREE.Vector3(...params.normal).normalize()\n  const length = params.length\n\n  // 1. 创建切割平面盒子\n  const bbox = getSolidBoundingBox(kernel, solid)\n  const bboxCenter = new THREE.Vector3(\n    (bbox.min[0] + bbox.max[0]) / 2,\n    (bbox.min[1] + bbox.max[1]) / 2,\n    (bbox.min[2] + bbox.max[2]) / 2,\n  )\n  const planeOrigin = bboxCenter.clone().add(normal.clone().multiplyScalar(params.originOffset))\n\n  // 2. 分割实体\n  const splitResult = splitBrep(kernel, solid, {\n    normal: [normal.x, normal.y, normal.z],\n    originOffset: params.originOffset,\n    planeCenter: [planeOrigin.x, planeOrigin.y, planeOrigin.z],\n  })\n\n  // 3. 获取截面\n  // 使用 section 获取切割平面与实体的交线\n  const zAxis = new THREE.Vector3(0, 0, 1)\n  const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, normal)\n  const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat)\n  const transMatrix = new THREE.Matrix4().makeTranslation(\n    planeOrigin.x,\n    planeOrigin.y,\n    planeOrigin.z,\n  )\n  const planeMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix)\n\n  // 创建一个大的矩形面作为切割平面\n  const bboxSize = new THREE.Vector3(\n    bbox.max[0] - bbox.min[0],\n    bbox.max[1] - bbox.min[1],\n    bbox.max[2] - bbox.min[2],\n  )\n  const planeSize = Math.max(bboxSize.x, bboxSize.y, bboxSize.z) * 3\n  const planeRect = kernel.makeRectangle(planeSize, planeSize)\n  // makeRectangle creates a face from [0,0] to [width,height] — center it at origin first\n  const centerMatrix = new THREE.Matrix4().makeTranslation(-planeSize / 2, -planeSize / 2, 0)\n  const centeredRect = kernel.transform(planeRect, matrixToArray(centerMatrix))\n  kernel.release(planeRect)\n  const planeFace = kernel.transform(centeredRect, matrixToArray(planeMatrix))\n  kernel.release(centeredRect)\n\n  // 获取截面边\n  const sectionEdges = kernel.section(solid, planeFace)\n  kernel.release(planeFace)\n\n  // 4. 构建截面 wire → face → 拉伸\n  let extrudedSolid: BrepHandle\n  try {\n    // 尝试从截面边构建 wire\n    const subShapes = kernel.getSubShapes(sectionEdges, 'edge')\n    if (subShapes.length === 0) {\n      kernel.release(sectionEdges)\n      kernel.release(splitResult.front)\n      kernel.release(splitResult.back)\n      throw new Error('no section edges from plane intersection')\n    }\n\n    const wire = kernel.makeWire(subShapes)\n    const face = kernel.makeFace(wire)\n    kernel.release(wire)\n\n    // 计算拉伸向量\n    let extrudeVec: THREE.Vector3\n    if (mode === 'centered') {\n      extrudeVec = normal.clone().multiplyScalar(length)\n    } else if (mode === 'forward') {\n      extrudeVec = normal.clone().multiplyScalar(length)\n    } else {\n      // backward\n      extrudeVec = normal.clone().multiplyScalar(-length)\n    }\n\n    extrudedSolid = kernel.extrude(face, extrudeVec.x, extrudeVec.y, extrudeVec.z)\n    kernel.release(face)\n    kernel.release(sectionEdges)\n  } catch {\n    // 截面构建失败 — 释放资源并抛出\n    if (sectionEdges) kernel.release(sectionEdges)\n    kernel.release(splitResult.front)\n    kernel.release(splitResult.back)\n    throw new Error('[extrudeBrep] failed to build extrusion from section')\n  }\n\n  // 5. 计算各段位置\n  let frontOffset: number\n  let backOffset: number\n  if (mode === 'centered') {\n    frontOffset = length / 2\n    backOffset = -length / 2\n  } else if (mode === 'forward') {\n    frontOffset = length\n    backOffset = 0\n  } else {\n    frontOffset = 0\n    backOffset = -length\n  }\n\n  // 平移 front 和 back\n  const frontTranslated = kernel.translate(\n    splitResult.front,\n    normal.x * frontOffset,\n    normal.y * frontOffset,\n    normal.z * frontOffset,\n  )\n  kernel.release(splitResult.front)\n\n  const backTranslated = kernel.translate(\n    splitResult.back,\n    normal.x * backOffset,\n    normal.y * backOffset,\n    normal.z * backOffset,\n  )\n  kernel.release(splitResult.back)\n\n  // 6. Fuse 三段\n  let result: BrepHandle\n  try {\n    const fused1 = kernel.fuse(frontTranslated, extrudedSolid)\n    kernel.release(frontTranslated)\n    kernel.release(extrudedSolid)\n    result = kernel.fuse(fused1, backTranslated)\n    kernel.release(fused1)\n    kernel.release(backTranslated)\n  } catch (err) {\n    kernel.release(frontTranslated)\n    kernel.release(extrudedSolid)\n    kernel.release(backTranslated)\n    throw new Error(`[extrudeBrep] fuse failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err })\n  }\n\n  return result\n}\n\n// ─── STEP/BREP 导入操作 ───\n\n/**\n * BREP-native STEP 导入：使用 OCCT kernel.importStep 导入 STEP 文件为精确实体。\n *\n * 与 mesh 路径（cad-core/io.ts importFile → loadFormat → meshes）对照：\n * - mesh 路径：STEP → 三角网格，丢弃 OCCT BrepHandle\n * - BREP 路径：STEP → kernel.importStep → 保留 BrepHandle，同时三角化为显示 mesh\n *\n * 导入的 solid 存入 brepChain.solidCache，后续操作（drillBrep/splitBrep 等）\n * 将其作为\"基座特征\"进行精确运算。\n *\n * **设计决策（I5 不准合并）**：\n * - 单 solid STEP：`importStep` 返回 Compound 包裹（顶层是 `TopoDS_Compound`，\n *   内含 1 个 `TopoDS_Solid`）。此处**解包**返回真实 Solid（`solids[0]`），\n *   下游 `isValid`/编辑/导出都针对真实实体。\n * - 多 solid STEP：返回顶层 Compound **不 fuse**。`meshShape(compound)` 整体显示，\n *   导出时 Compound 仍含全部 solid（非三角化）。逐 part 编辑由 Phase 1 XCAF 负责。\n * - **不调用 `kernel.isValid`**：`importStep` 对单 solid STEP 也返回 Compound 包裹，\n *   `isValid(compound)` 返回 false（Compound 不是 Solid），这会误杀合法 STEP。\n *   合法性判据改为 `getSubShapes(top, 'solid').length >= 1`（含 ≥1 个 solid 即合法），\n *   与装配路径 `walkLabel` 一致。\n *\n * @param kernel     the initialized OCCT kernel.\n * @param buffer     the raw STEP file bytes (a text-encoded ArrayBuffer).\n * @param brepChain  optional - caches the tessellated BrepMeshResult when provided.\n * @param stmtId     optional - the part this solid belongs to, paired with brepChain as the cache key.\n * @param partIndex  optional - for multi-solid files, return the N-th sub-solid\n *                   (host emits one load statement per part with its index).\n * @returns { solid: the OCCT solid handle, shape: the display tessellated mesh }\n */\nexport function loadBrep(\n  kernel: BrepEngineApi,\n  buffer: ArrayBuffer,\n  brepChain?: BrepChainState,\n  stmtId?: PartName,\n  partIndex?: number,\n): { solid: BrepHandle; shape: Shape } {\n  // BREP 文件（CASCADE Topology 文本格式）必须用 kernel.fromBREP 解析；\n  // 误用 STEP 解析器（importStep）读 BREP 会抛 \"failed to read STEP data\"。\n  const decoder = new TextDecoder('utf-8')\n  const head = decoder.decode(buffer.slice(0, 64))\n  const top = head.includes('CASCADE Topology')\n    ? kernel.fromBREP(decoder.decode(buffer))\n    : kernel.importStep(buffer)\n\n  // 校验：含至少一个 solid 子形即合法（不调用 isValid，见上文设计决策）\n  const solids = kernel.getSubShapes(top, 'solid')\n  if (solids.length < 1) {\n    kernel.release(top)\n    throw new Error(\n      `[loadBrep] imported shape contains no solid sub-shapes ` +\n      `(solidCount=0) — wireframe/surface/invalid shapes are not supported`\n    )\n  }\n\n  // 单 solid：解包返回真实 Solid（非 Compound 包裹）\n  if (solids.length === 1) {\n    const realSolid = solids[0]\n    kernel.release(top) // 释放 Compound 包裹，realSolid 独立持有\n    const shape = solidToShape(kernel, realSolid, undefined, brepChain, stmtId)\n    return { solid: realSolid, shape }\n  }\n\n  // 多 solid + partIndex：提取第 partIndex 个子 solid（逐 part load 语句使用）。\n  // 宿主为多 part 文件的每个 part 生成独立 load 语句并携带 partIndex，\n  // 使每条 load 输出对应 part 的几何，而不是整个文件的 Compound。\n  if (partIndex !== undefined) {\n    const target = solids[partIndex]\n    if (!target) {\n      kernel.release(top)\n      throw new Error(\n        `[loadBrep] partIndex ${partIndex} out of range (${solids.length} solids)`,\n      )\n    }\n    kernel.release(top) // 释放 Compound 包裹，target 独立持有（同单 solid 模式）\n    const shape = solidToShape(kernel, target, undefined, brepChain, stmtId)\n    return { solid: target, shape }\n  }\n\n  // 多 solid：保留 Compound 不合并（I5），逐 part 编辑由 Phase 1 XCAF 负责\n  // 释放提取的子形句柄（它们是 top 的子引用，top 本身持有几何）\n  for (const s of solids) {\n    try { kernel.release(s) } catch { /* already released */ }\n  }\n  const shape = solidToShape(kernel, top, undefined, brepChain, stmtId)\n  return { solid: top, shape }\n}\n\n// ─── 辅助函数 ───\n\n/**\n * Convert a THREE.Matrix4 into the 3x4 row-major array (12 doubles) the OCCT\n * transform expects.\n *\n * OCCT transform accepts [r00,r01,r02,tx, r10,r11,r12,ty, r20,r21,r22,tz].\n * @param matrix - the source matrix to convert.\n * @returns the 3x4 row-major array of 12 doubles.\n */\nexport function matrixToArray(matrix: THREE.Matrix4): number[] {\n  const e = matrix.elements\n  // THREE.Matrix4 是 column-major，OCCT 需要 row-major 3x4\n  return [\n    e[0], e[4], e[8], e[12],\n    e[1], e[5], e[9], e[13],\n    e[2], e[6], e[10], e[14],\n  ]\n}\n"]}