@faicad/faijs 0.13.0

package/dist/brep/brep-ops.d.ts

@@ -0,0 +1,251 @@
+/**
+ * 核心 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 type { BrepHandle } from './engine/types.js';
+import type { BrepEngineApi } from './engine/primitives.js';
+import type { Shape, Vec3 } from '../mesh/types.js';
+import type { BrepChainState } from './brep-chain.js';
+import type { PartName } from '../identity.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 declare function solidToShape(kernel: BrepEngineApi, solid: BrepHandle, segments?: number, brepChain?: BrepChainState, partName?: PartName): Shape;
+/**
+ * BREP 平移：使用 OCCT translate（精确，不损失几何精度）。
+ *
+ * @param kernel  OCCT 内核
+ * @param solid   输入实体
+ * @param offset  平移量 [dx, dy, dz]
+ * @returns 新实体（调用方负责释放输入实体）
+ */
+export declare function translateBrep(kernel: BrepEngineApi, solid: BrepHandle, offset: Vec3): BrepHandle;
+/**
+ * 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 declare function rotateBrep(kernel: BrepEngineApi, solid: BrepHandle, anglesDeg: Vec3, pivot?: Vec3): BrepHandle;
+/**
+ * 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 declare function scaleBrep(kernel: BrepEngineApi, solid: BrepHandle, factor: number | Vec3, center?: Vec3): BrepHandle;
+/**
+ * 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 declare function applyTransformBrep(kernel: BrepEngineApi, solid: BrepHandle, quaternion: [number, number, number, number], pivot: [number, number, number], translation: [number, number, number]): BrepHandle;
+/**
+ * BREP 布尔并集：使用 OCCT fuse（BRepAlgoAPI_Fuse）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      实体 A
+ * @param b      实体 B
+ * @returns 融合后的实体
+ */
+export declare function fuseBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): BrepHandle;
+/**
+ * BREP 布尔差集：使用 OCCT cut（BRepAlgoAPI_Cut）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      基体
+ * @param b      工具（从基体中减去）
+ * @returns 切割后的实体
+ */
+export declare function cutBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): BrepHandle;
+/**
+ * BREP 布尔交集：使用 OCCT common（BRepAlgoAPI_Common）。
+ *
+ * @param kernel OCCT 内核
+ * @param a      实体 A
+ * @param b      实体 B
+ * @returns 交集实体
+ */
+export declare function commonBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): BrepHandle;
+/** drillBrep 的参数 */
+export interface DrillBrepParams {
+    /** 孔直径 */
+    diameter: number;
+    /** 孔深度（0 = 通孔） */
+    depth: number;
+    /** 孔位置（世界空间） */
+    position: Vec3;
+    /** 钻孔方向（世界空间，指向材料内部） */
+    direction: Vec3;
+    /** 面法向（世界空间） */
+    faceNormal: Vec3;
+    /** 孔类型 */
+    holeType?: 'simple' | 'screw';
+}
+/**
+ * BREP 钻孔：创建圆柱工具实体并用 OCCT cut 减去。
+ *
+ * 仅支持圆柱孔（holeType='simple'）。
+ * 螺丝孔（holeType='screw'）由调用方判断为 mesh-only，触发 BREP 链断裂。
+ *
+ * 通孔（depth=0）：创建一个足够长的圆柱体穿透整个零件。
+ * 盲孔（depth>0）：创建指定深度的圆柱体。
+ *
+ * @param kernel OCCT 内核
+ * @param solid  目标实体
+ * @param params 钻孔参数
+ * @returns 钻孔后的实体
+ */
+export declare function drillBrep(kernel: BrepEngineApi, solid: BrepHandle, params: DrillBrepParams): BrepHandle;
+/** splitBrep 的参数 */
+export interface SplitBrepParams {
+    /** 切割平面法线 */
+    normal: Vec3;
+    /** 切割平面原点偏移（法线方向上的距离） */
+    originOffset: number;
+    /** 切割平面中心点 */
+    planeCenter: Vec3;
+}
+/** splitBrep 的结果 */
+export interface SplitBrepResult {
+    /** 法线正方向的半部分 */
+    front: BrepHandle;
+    /** 法线负方向的半部分 */
+    back: BrepHandle;
+}
+/**
+ * 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 declare function splitBrep(kernel: BrepEngineApi, solid: BrepHandle, params: SplitBrepParams): SplitBrepResult;
+/** extrudeBrep 的参数 */
+export interface ExtrudeBrepParams {
+    /** 拉伸法线方向 */
+    normal: Vec3;
+    /** 平面原点偏移 */
+    originOffset: number;
+    /** 拉伸长度 */
+    length: number;
+    /** 拉伸模式 */
+    mode?: 'centered' | 'forward' | 'backward';
+}
+/**
+ * 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 declare function extrudeBrep(kernel: BrepEngineApi, solid: BrepHandle, params: ExtrudeBrepParams): BrepHandle;
+/**
+ * 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 declare function loadBrep(kernel: BrepEngineApi, buffer: ArrayBuffer, brepChain?: BrepChainState, stmtId?: PartName, partIndex?: number): {
+    solid: BrepHandle;
+    shape: 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 declare function matrixToArray(matrix: THREE.Matrix4): number[];
+//# sourceMappingURL=brep-ops.d.ts.map

package/dist/brep/brep-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brep-ops.d.ts","sourceRoot":"","sources":["../../src/brep/brep-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,gBAAgB,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAK3C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,cAAc,EAC1B,QAAQ,CAAC,EAAE,QAAQ,GAClB,KAAK,CAkBP;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,IAAI,GACX,UAAU,CAEZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,IAAI,EACf,KAAK,CAAC,EAAE,IAAI,GACX,UAAU,CAYZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,MAAM,CAAC,EAAE,IAAI,GACZ,UAAU,CAiBZ;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC5C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC/B,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACpC,UAAU,CAWZ;AAID;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,aAAa,EACrB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,UAAU,CAEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,aAAa,EACrB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,UAAU,CAEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,UAAU,CAEZ;AAID,oBAAoB;AACpB,MAAM,WAAW,eAAe;IAC9B,UAAU;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB;IAChB,QAAQ,EAAE,IAAI,CAAA;IACd,wBAAwB;IACxB,SAAS,EAAE,IAAI,CAAA;IACf,gBAAgB;IAChB,UAAU,EAAE,IAAI,CAAA;IAChB,UAAU;IACV,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,eAAe,GACtB,UAAU,CAiGZ;AAID,oBAAoB;AACpB,MAAM,WAAW,eAAe;IAC9B,aAAa;IACb,MAAM,EAAE,IAAI,CAAA;IACZ,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc;IACd,WAAW,EAAE,IAAI,CAAA;CAClB;AAED,oBAAoB;AACpB,MAAM,WAAW,eAAe;IAC9B,gBAAgB;IAChB,KAAK,EAAE,UAAU,CAAA;IACjB,gBAAgB;IAChB,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,eAAe,GACtB,eAAe,CAsDjB;AAID,sBAAsB;AACtB,MAAM,WAAW,iBAAiB;IAChC,aAAa;IACb,MAAM,EAAE,IAAI,CAAA;IACZ,aAAa;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW;IACX,MAAM,EAAE,MAAM,CAAA;IACd,WAAW;IACX,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,GACxB,UAAU,CA0IZ;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,cAAc,EAC1B,MAAM,CAAC,EAAE,QAAQ,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAkDrC;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,MAAM,EAAE,CAQ7D"}