@faicad/faijs 0.13.0

package/dist/brep/export/stl.js

@@ -0,0 +1,93 @@
+/**
+ * buildStlBufferFromMesh — L1 纯数据 STL 导出（无 THREE 依赖）
+ *
+ *
+ * 从原始 positions + indices 构建 binary STL buffer。
+ * 与 src/renderer/lib/build-stl.ts 的 buildStlBuffer() 功能相同，
+ * 但不依赖 THREE.BufferGeometry，可在 Node 环境直接使用。
+ *
+ * Binary STL format:
+ *   bytes 0-79:    80-byte header
+ *   bytes 80-83:   4-byte uint32 triangle count N
+ *   bytes 84+:     N × 50-byte triangles
+ *     - normal:   3 × float32 (12 bytes)
+ *     - vertex1:  3 × float32 (12 bytes)
+ *     - vertex2:  3 × float32 (12 bytes)
+ *     - vertex3:  3 × float32 (12 bytes)
+ *     - attr:     2 bytes (0)
+ */
+/**
+ * Build a binary STL buffer from raw positions and indices (no THREE dependency).
+ * @param positions - the interleaved vertex positions (x,y,z per vertex).
+ * @param indices - the triangle indices (3 indices per triangle).
+ * @param header - optional 80-byte header text (defaults to 'Faicad STL').
+ * @returns an ArrayBuffer holding the binary STL data.
+ */
+export function buildStlBufferFromMesh(positions, indices, header) {
+    const triCount = indices.length / 3;
+    const headerSize = 80;
+    const countSize = 4;
+    const triByteSize = 50; // 12 (normal) + 12*3 (vertices) + 2 (attr)
+    const totalSize = headerSize + countSize + triCount * triByteSize;
+    const buffer = new ArrayBuffer(totalSize);
+    const dv = new DataView(buffer);
+    // Header (80 bytes)
+    const headerStr = header ?? 'Faicad STL';
+    for (let i = 0; i < Math.min(headerStr.length, 80); i++) {
+        dv.setUint8(i, headerStr.charCodeAt(i));
+    }
+    // Triangle count
+    dv.setUint32(80, triCount, true);
+    // Triangles
+    for (let i = 0; i < triCount; i++) {
+        const base = 84 + i * 50;
+        const ia = indices[i * 3];
+        const ib = indices[i * 3 + 1];
+        const ic = indices[i * 3 + 2];
+        const ax = positions[ia * 3];
+        const ay = positions[ia * 3 + 1];
+        const az = positions[ia * 3 + 2];
+        const bx = positions[ib * 3];
+        const by = positions[ib * 3 + 1];
+        const bz = positions[ib * 3 + 2];
+        const cx = positions[ic * 3];
+        const cy = positions[ic * 3 + 1];
+        const cz = positions[ic * 3 + 2];
+        // Compute face normal: cross(B-A, C-A)
+        const ux = bx - ax;
+        const uy = by - ay;
+        const uz = bz - az;
+        const vx = cx - ax;
+        const vy = cy - ay;
+        const vz = cz - az;
+        let nx = uy * vz - uz * vy;
+        let ny = uz * vx - ux * vz;
+        let nz = ux * vy - uy * vx;
+        const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz);
+        if (nlen > 0) {
+            nx /= nlen;
+            ny /= nlen;
+            nz /= nlen;
+        }
+        // Normal
+        dv.setFloat32(base + 0, nx, true);
+        dv.setFloat32(base + 4, ny, true);
+        dv.setFloat32(base + 8, nz, true);
+        // Vertex A
+        dv.setFloat32(base + 12, ax, true);
+        dv.setFloat32(base + 16, ay, true);
+        dv.setFloat32(base + 20, az, true);
+        // Vertex B
+        dv.setFloat32(base + 24, bx, true);
+        dv.setFloat32(base + 28, by, true);
+        dv.setFloat32(base + 32, bz, true);
+        // Vertex C
+        dv.setFloat32(base + 36, cx, true);
+        dv.setFloat32(base + 40, cy, true);
+        dv.setFloat32(base + 44, cz, true);
+        // Attribute (2 bytes, usually 0)
+        dv.setUint16(base + 48, 0, true);
+    }
+    return buffer;
+}
+//# sourceMappingURL=stl.js.map

package/dist/brep/export/stl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stl.js","sourceRoot":"","sources":["../../../src/brep/export/stl.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * buildStlBufferFromMesh — L1 纯数据 STL 导出（无 THREE 依赖）\n *\n *\n * 从原始 positions + indices 构建 binary STL buffer。\n * 与 src/renderer/lib/build-stl.ts 的 buildStlBuffer() 功能相同，\n * 但不依赖 THREE.BufferGeometry，可在 Node 环境直接使用。\n *\n * Binary STL format:\n *   bytes 0-79:    80-byte header\n *   bytes 80-83:   4-byte uint32 triangle count N\n *   bytes 84+:     N × 50-byte triangles\n *     - normal:   3 × float32 (12 bytes)\n *     - vertex1:  3 × float32 (12 bytes)\n *     - vertex2:  3 × float32 (12 bytes)\n *     - vertex3:  3 × float32 (12 bytes)\n *     - attr:     2 bytes (0)\n */\n\n/**\n * Build a binary STL buffer from raw positions and indices (no THREE dependency).\n * @param positions - the interleaved vertex positions (x,y,z per vertex).\n * @param indices - the triangle indices (3 indices per triangle).\n * @param header - optional 80-byte header text (defaults to 'Faicad STL').\n * @returns an ArrayBuffer holding the binary STL data.\n */\nexport function buildStlBufferFromMesh(\n  positions: Float32Array,\n  indices: Uint32Array,\n  header?: string,\n): ArrayBuffer {\n  const triCount = indices.length / 3\n\n  const headerSize = 80\n  const countSize = 4\n  const triByteSize = 50 // 12 (normal) + 12*3 (vertices) + 2 (attr)\n  const totalSize = headerSize + countSize + triCount * triByteSize\n\n  const buffer = new ArrayBuffer(totalSize)\n  const dv = new DataView(buffer)\n\n  // Header (80 bytes)\n  const headerStr = header ?? 'Faicad STL'\n  for (let i = 0; i < Math.min(headerStr.length, 80); i++) {\n    dv.setUint8(i, headerStr.charCodeAt(i))\n  }\n\n  // Triangle count\n  dv.setUint32(80, triCount, true)\n\n  // Triangles\n  for (let i = 0; i < triCount; i++) {\n    const base = 84 + i * 50\n    const ia = indices[i * 3]!\n    const ib = indices[i * 3 + 1]!\n    const ic = indices[i * 3 + 2]!\n\n    const ax = positions[ia * 3]\n    const ay = positions[ia * 3 + 1]\n    const az = positions[ia * 3 + 2]\n    const bx = positions[ib * 3]\n    const by = positions[ib * 3 + 1]\n    const bz = positions[ib * 3 + 2]\n    const cx = positions[ic * 3]\n    const cy = positions[ic * 3 + 1]\n    const cz = positions[ic * 3 + 2]\n\n    // Compute face normal: cross(B-A, C-A)\n    const ux = bx - ax\n    const uy = by - ay\n    const uz = bz - az\n    const vx = cx - ax\n    const vy = cy - ay\n    const vz = cz - az\n    let nx = uy * vz - uz * vy\n    let ny = uz * vx - ux * vz\n    let nz = ux * vy - uy * vx\n    const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz)\n    if (nlen > 0) {\n      nx /= nlen\n      ny /= nlen\n      nz /= nlen\n    }\n\n    // Normal\n    dv.setFloat32(base + 0, nx, true)\n    dv.setFloat32(base + 4, ny, true)\n    dv.setFloat32(base + 8, nz, true)\n\n    // Vertex A\n    dv.setFloat32(base + 12, ax, true)\n    dv.setFloat32(base + 16, ay, true)\n    dv.setFloat32(base + 20, az, true)\n\n    // Vertex B\n    dv.setFloat32(base + 24, bx, true)\n    dv.setFloat32(base + 28, by, true)\n    dv.setFloat32(base + 32, bz, true)\n\n    // Vertex C\n    dv.setFloat32(base + 36, cx, true)\n    dv.setFloat32(base + 40, cy, true)\n    dv.setFloat32(base + 44, cz, true)\n\n    // Attribute (2 bytes, usually 0)\n    dv.setUint16(base + 48, 0, true)\n  }\n\n  return buffer\n}\n"]}

package/dist/brep/face-evolution.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 面演化（face evolution）工具：hash 映射 ↔ ordinal 映射转换
+ *
+ * See docs/api-contract.md §11 (topology contract) for face evolution context.
+ *
+ * occt-wasm 的 *WithHistory API 返回 BrepEvolutionData，其中 modified/generated
+ * 用面 hash（内存指针哈希）编码。本模块将其解码为 ordinal 映射（面枚举序号），
+ * 可安全持久化进 faijs 文本。
+ *
+ * 核心原理（分析文档 §4.4）：
+ * getSubShapes(shape,'face')[i] ↔ subShapeHashes(shape,'face',B)[i] 一一对应
+ * 因此可以把 hash 映射无损转换为 ordinal 映射。
+ */
+import type { BrepHandle, BrepEvolutionData } from './engine/types.js';
+import type { BrepEngineApi } from './engine/primitives.js';
+/** hash 上界（与 occt-wasm kernel.cpp 一致：`% 2147483647`） */
+export declare const HASH_UPPER_BOUND = 2147483647;
+/**
+ * 面演化映射：输入面 ordinal → 输出面 ordinal 列表
+ *
+ * - 1→1：面被修改但未被切割（如面带孔仍是单面）
+ * - 1→N：面被切割成多个面
+ * - 不在 map 中：面未被修改或被删除
+ */
+export type FaceEvolution = Map<number, number[]>;
+/**
+ * Collect the hash list of all faces of a shape (via subShapeHashes; efficient, no handles allocated).
+ * @param kernel - the OCCT kernel.
+ * @param shape - the shape whose face hashes to collect.
+ * @returns the array of face hashes.
+ */
+export declare function getFaceHashes(kernel: BrepEngineApi, shape: BrepHandle): number[];
+/**
+ * Collect the union of face hashes of two shapes (for WithHistory calls of binary boolean operations).
+ *
+ * Analysis doc §4.2: fuse/cut/intersect must pass subShapeHashes(A) ∪ subShapeHashes(B)
+ * to track both inputs' face evolution.
+ * @param kernel - the OCCT kernel.
+ * @param shapeA - the first input shape.
+ * @param shapeB - the second input shape.
+ * @returns the union of the two shapes' face hashes.
+ */
+export declare function getUnionFaceHashes(kernel: BrepEngineApi, shapeA: BrepHandle, shapeB: BrepHandle): number[];
+/**
+ * 解码 BrepEvolutionData 的 modified 数组为 ordinal 映射。
+ *
+ * modified 分段编码格式：[inputHash, count, outHash1, outHash2, ...] × N
+ *
+ * @param kernel      the OCCT kernel.
+ * @param evo         the BrepEvolutionData (from a *WithHistory API).
+ * @param inputShape  the input shape (for the input face hash → ordinal mapping).
+ * @param resultShape the result shape (for the output face hash → ordinal mapping).
+ * @returns the FaceEvolution: inOrdinal → outOrdinal[].
+ */
+export declare function decodeEvolution(kernel: BrepEngineApi, evo: BrepEvolutionData, inputShape: BrepHandle, resultShape: BrepHandle): FaceEvolution;
+/**
+ * Hash 键面演化：输入面 hash → 输出面 hash 列表（1→多分裂时多个）。
+ *
+ * 与序号键 FaceEvolution 并列、同源（同一次 *WithHistory 打包结果解出），
+ * 一个供 role 传播（hash 键）、一个供选择器/文本（序号键），零额外 wasm 调用。
+ */
+export interface HashEvolution {
+    /** 输入面 hash → 输出面 hash 列表（1→多分裂时多个）。 */
+    readonly modified: ReadonlyMap<number, readonly number[]>;
+    /** 输入面中已不存在的面 hash。 */
+    readonly deleted: ReadonlySet<number>;
+}
+/**
+ * 把 BrepEvolutionData 解码为 hash 键演化（§2.4）。
+ *
+ * modified 分段编码格式：[inHash, count, outHash1, ...] × N —— 本身就是
+ * hash→hash[] 的 1→多映射，直接按同一格式解出 hash 键版本，不需要
+ * getSubShapes 逐句柄 hashCode，也不分配任何句柄。
+ *
+ * generated 刻意不进 role 传播（§1.3 事实：occt 系 generated hash 指向中间形、
+ * 对布尔实测 0 个存活），生成面改由 DerivedFaceTopoRef 以 lineage 命名。
+ *
+ * @param evo - the BrepEvolutionData (from a *WithHistory API).
+ * @returns the hash-keyed evolution.
+ */
+export declare function decodeHashEvolution(evo: BrepEvolutionData): HashEvolution;
+/**
+ * 把一次双输入布尔（cut/fuse/intersect）的打包演化按「inHash 属于 A 还是 B」
+ * 拆成 A、B 两张 hash 演化（§3.4 布尔合流，faijs 对 brepjs 的必要扩展）。
+ *
+ * 现有 *WithHistoryBrep 包装只用 getUnionFaceHashes 传入 A∪B 两边 hash、且只对
+ * 基体 a 解码序号演化。本函数对同一份 evo 零额外内核调用：用 subShapeHashes(a)
+ * / subShapeHashes(b) 两个集合判定每个 inHash 的归属，各自传播各自的 role 表。
+ *
+ * @param evo     - the BrepEvolutionData (from a binary boolean *WithHistory API).
+ * @param hashesA - the face hashes of input A (target), via subShapeHashes.
+ * @param hashesB - the face hashes of input B (tool), via subShapeHashes.
+ * @returns the A/B split hash evolutions (faces from neither input are dropped).
+ */
+export declare function splitHashEvolutionByOrigin(evo: BrepEvolutionData, hashesA: readonly number[], hashesB: readonly number[]): {
+    a: HashEvolution;
+    b: HashEvolution;
+};
+/**
+ * 构造 hash 键恒等演化（§2.4：变换类 translate/rotate/scale/copy 用）。
+ *
+ * 刚体变换/深拷贝不改变面数量与顺序：输入第 i 面 hash → 输出第 i 面 hash，
+ * 用 subShapeHashes 两端对齐合成 hash 恒等（避免调用 *WithHistory 的签名兼容问题）。
+ *
+ * @param kernel       - the OCCT kernel.
+ * @param inputShape   - the input shape.
+ * @param resultShape  - the transformed/copied output shape.
+ * @returns the hash identity evolution (modified: in[i] → [out[i]]).
+ */
+export declare function identityHashEvolution(kernel: BrepEngineApi, inputShape: BrepHandle, resultShape: BrepHandle): HashEvolution;
+/**
+ * 双输入布尔 + roleTable 合流组合封装（§3.4，stdlib boolean 链式调用用）。
+ *
+ * 一次 *WithHistory 内核调用同时产出：
+ * - result：结果实体
+ * - faceEvolution：序号键演化（进 faceEvolutionCache，服务选择器/可视化）
+ * - roleTable：A/B 两侧 role 表各自传播后合并（进 roleTableCache，服务命名）
+ *
+ * 缝面（generated）刻意不进 role 传播（§1.3/R2：generated hash 指向中间形、
+ * 实测 0 存活），以本次语句 LHS 为 outPart 新 origin 的位置名由调用方决定。
+ *
+ * @param kernel  - the OCCT kernel.
+ * @param op      - the boolean operation ('fuse' | 'cut' | 'intersect').
+ * @param a       - the target shape.
+ * @param b       - the tool shape.
+ * @param tableA  - the target's role table.
+ * @param tableB  - the tool's role table.
+ * @param outPart - the boolean statement's LHS variable name (new origin for seam faces).
+ * @returns the result handle, ordinal evolution and merged role table.
+ */
+export declare function booleanWithRoleTable(kernel: BrepEngineApi, op: 'fuse' | 'cut' | 'intersect', a: BrepHandle, b: BrepHandle, tableA: ReadonlyMap<unknown, unknown>, tableB: ReadonlyMap<unknown, unknown>, outPart: string): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+    roleTable: ReadonlyMap<unknown, unknown>;
+};
+/**
+ * Decode a BrepEvolutionData deleted array into the ordinal list of deleted faces.
+ * @param kernel     - the OCCT kernel.
+ * @param evo        - the BrepEvolutionData (from a *WithHistory API).
+ * @param inputShape - the input shape (for the hash → ordinal mapping).
+ * @returns the array of deleted face ordinals.
+ */
+export declare function decodeDeleted(kernel: BrepEngineApi, evo: BrepEvolutionData, inputShape: BrepHandle): number[];
+/**
+ * cutWithHistory 封装：执行切割并返回结果 + 面演化映射。
+ *
+ * @param kernel OCCT 内核
+ * @param a 基体
+ * @param b 工具（从基体中减去）
+ * @returns { result: 结果 BrepHandle, faceEvolution: 面演化映射 }
+ */
+export declare function cutWithHistoryBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+};
+/**
+ * fuseWithHistory wrapper: performs the fuse and returns the result plus the face evolution mapping.
+ * @param kernel - the OCCT kernel.
+ * @param a - the base shape.
+ * @param b - the tool shape to fuse into the base.
+ * @returns the result BrepHandle plus the face evolution mapping.
+ */
+export declare function fuseWithHistoryBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+};
+/**
+ * intersectWithHistory wrapper: performs the intersection and returns the result plus the face evolution mapping.
+ * @param kernel - the OCCT kernel.
+ * @param a - the first input shape.
+ * @param b - the second input shape.
+ * @returns the result BrepHandle plus the face evolution mapping.
+ */
+export declare function intersectWithHistoryBrep(kernel: BrepEngineApi, a: BrepHandle, b: BrepHandle): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+};
+/**
+ * 构造恒等面演化映射（用于 translate/rotate/scale 等不改变拓扑的操作）。
+ *
+ * 变换操作不改变面的数量和顺序，每个面 ordinal i → [i]。
+ * 避免调用 *WithHistory API（rotate/scale 的 WithHistory 签名与现有 Euler/Vec3 参数不兼容）。
+ *
+ * @param kernel OCCT 内核
+ * @param shape 输入形状（用于获取面数量）
+ * @returns 恒等 FaceEvolution
+ */
+export declare function identityEvolution(kernel: BrepEngineApi, shape: BrepHandle): FaceEvolution;
+/**
+ * 单输入 directEdit（fillet/chamfer）+ roleTable 传播封装。
+ *
+ * 与 `booleanWithRoleTable`（双输入）对应：单输入只有一张输入 role 表，
+ * 一次 `*WithHistory` 内核调用产出结果 + 面演化，沿 hash 演化推进所有 origin。
+ *
+ * generated 刻意不进 role 传播（§1.3 事实：generated hash 指向中间形，
+ * 实测 0 存活），过渡面的命名由 DerivedFaceTopoRef 在 M2 处理。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param op              - the directEdit operation ('fillet' | 'chamfer').
+ * @param solid          - the input solid (single input, unlike boolean's a/b).
+ * @param edgeHandles     - the resolved Edge handles to fillet/chamfer.
+ * @param radius          - the fillet radius or chamfer distance (uniform only).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name (for new origin allocation).
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export declare function directEditWithRoleTable(kernel: BrepEngineApi, op: 'fillet' | 'chamfer', solid: BrepHandle, edgeHandles: BrepHandle[], radius: number, inputRoleTable: ReadonlyMap<unknown, unknown>, outPart: string): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+    roleTable: ReadonlyMap<unknown, unknown>;
+};
+/**
+ * 单输入 directEdit 的便捷别名：fillet。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param solid          - the input solid.
+ * @param edgeHandles     - the resolved Edge handles.
+ * @param radius          - the fillet radius (uniform).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name.
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export declare function filletWithRoleTable(kernel: BrepEngineApi, solid: BrepHandle, edgeHandles: BrepHandle[], radius: number, inputRoleTable: ReadonlyMap<unknown, unknown>, outPart: string): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+    roleTable: ReadonlyMap<unknown, unknown>;
+};
+/**
+ * 单输入 directEdit 的便捷别名：chamfer。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param solid          - the input solid.
+ * @param edgeHandles     - the resolved Edge handles.
+ * @param distance        - the chamfer distance (uniform).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name.
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export declare function chamferWithRoleTable(kernel: BrepEngineApi, solid: BrepHandle, edgeHandles: BrepHandle[], distance: number, inputRoleTable: ReadonlyMap<unknown, unknown>, outPart: string): {
+    result: BrepHandle;
+    faceEvolution: FaceEvolution;
+    roleTable: ReadonlyMap<unknown, unknown>;
+};
+//# sourceMappingURL=face-evolution.d.ts.map

package/dist/brep/face-evolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-evolution.d.ts","sourceRoot":"","sources":["../../src/brep/face-evolution.ts"],"names":[],"mappings":"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"}