@faicad/fai-cq-gears 0.13.0

package/dist/ring_gear.js

@@ -0,0 +1,133 @@
+/**
+ * ring_gear — RingGear（内部齿）实体构造
+ *
+ * 对应 `RingGear._build_gear_faces()` + `_build_rim_face()` + `_build()`：
+ *
+ * ```
+ * ① 4z 个齿面（复用 SpurGear 的 `buildToothFaces`，因为点集布局一致）
+ * ② 外圈 rim：两圈圆环 wire（z=0 / z=width）经 `loft(ruled=true)` 蒙成圆柱面
+ * ③ 顶/底面：在 z=width / z=0 收齿面边界边 → 组线成内孔 wire，
+ *    再用 `Face.makeFromWires(rimWire, [toothWire])` 做成**环形**盖面（外圆 rim_r、内孔齿廓）
+ * ④ sew(齿面 + rim + 2 盖面) → makeSolid → fixFaceOrientations
+ * ```
+ *
+ * 与 SpurGear 的关键差异：端面是**环形**（外 rim 圆 + 内齿廓孔），不是实心圆盘；
+ * 多了外圈 rim 圆柱面。倒角（chamfer）/ 轴孔（bore）属于 `_make_chamfer` / `_make_bore`，
+ * 在 sew 之后以旋转体 cutter 布尔差实现（见 `features.ts`，A1 已验证几何），
+ * 由 `BuildRingGearOptions.chamfer` / `boreD` 驱动。
+ */
+import { ringGearGeometry, GEAR_BASE_CONSTANTS } from './profile.js';
+import { DEFAULT_SPLINE_FACE_STRATEGY, soleFace, } from './spline-face.js';
+import { buildToothFaces, buildHerringboneToothFaces } from './spur_gear.js';
+import { connectEdgesToWires, gearFaceFromWires as faceFromWires } from '@faicad/cq-compat';
+import { applyChamfer, applyBore, } from './features.js';
+/** 判定「边是否落在某个 z 平面上」的容差（远小于 wire_comb_tol）。 */
+const PLANAR_PICK_TOL = 1e-6;
+/**
+ * 一个半径 `radius`、圆心在 `(0,0,z)`、法向 +Z 的整圆 wire。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param radius 圆半径
+ * @param z 圆所在高度
+ * @returns 闭合圆 wire
+ */
+function circleWire(kernel, radius, z) {
+    const arc = kernel.makeCircleArc({ x: 0, y: 0, z }, { x: 0, y: 0, z: 1 }, radius, 0, Math.PI * 2);
+    return kernel.makeWire([arc]);
+}
+/**
+ * 外圈 rim 圆柱面（cq `Face.makeRuledSurface(w1, w2)` 的等价物）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param rimR 外圈半径（`rd + rim_width`）
+ * @param width 齿宽
+ * @returns 圆柱侧面（Face）
+ */
+function buildRimFace(kernel, rimR, width) {
+    const w0 = circleWire(kernel, rimR, 0);
+    const w1 = circleWire(kernel, rimR, width);
+    // `loft(wires, isSolid=false, ruled=true)` 在两圈之间蒙出 ruled 圆柱面
+    return soleFace(kernel, kernel.loft([w0, w1], false, true));
+}
+/**
+ * 在高度 `z` 收齿面边界边 → 组线成内孔 wire，与外圈 rim 圆合成**环形**盖面。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param toothFaces 全部齿面（含 z 向厚度）
+ * @param rimR 外圈半径
+ * @param z 目标平面高度
+ * @param wireCombTol 组线容差（mm）
+ * @returns 环形盖面（外 rim 圆、内齿廓孔）
+ */
+function ringCapAtZ(kernel, toothFaces, rimR, z, wireCombTol) {
+    const edges = [];
+    for (const f of toothFaces) {
+        for (const e of kernel.getSubShapes(f, 'edge')) {
+            const bb = kernel.getBoundingBox(e);
+            if (Math.abs(bb.zmin - z) <= PLANAR_PICK_TOL && Math.abs(bb.zmax - z) <= PLANAR_PICK_TOL) {
+                edges.push(e);
+            }
+        }
+    }
+    if (edges.length === 0) {
+        throw new Error(`ringCapAtZ: no tooth boundary edges found at z=${z}`);
+    }
+    const toothWires = connectEdgesToWires(kernel, edges, wireCombTol ?? GEAR_BASE_CONSTANTS.wire_comb_tol);
+    if (toothWires.length !== 1) {
+        throw new Error(`ringCapAtZ: expected one closed tooth-profile loop at z=${z}, got ${toothWires.length} wires from ${edges.length} edges`);
+    }
+    const rimWire = circleWire(kernel, rimR, z);
+    return faceFromWires(kernel, rimWire, [toothWires[0]]);
+}
+/** ①–④：完整 RingGear 实体（内部齿，非倒角）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 齿轮参数
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export function buildRingGearSolid(kernel, params, build = {}) {
+    const strategy = build.strategy ?? DEFAULT_SPLINE_FACE_STRATEGY;
+    const geom = ringGearGeometry(params);
+    const toothFaces = build.herringbone
+        ? buildHerringboneToothFaces(kernel, geom, strategy, build)
+        : buildToothFaces(kernel, geom, strategy, build);
+    const rimR = geom.rd + params.rim_width;
+    const rimFace = buildRimFace(kernel, rimR, geom.width);
+    const top = ringCapAtZ(kernel, toothFaces, rimR, geom.width, build.wireCombTol);
+    const bottom = ringCapAtZ(kernel, toothFaces, rimR, 0, build.wireCombTol);
+    const all = [...toothFaces, rimFace, top, bottom];
+    const shell = kernel.sew(all, build.shellSewingTol ?? GEAR_BASE_CONSTANTS.shell_sewing_tol);
+    const solid = kernel.makeSolid(shell);
+    const oriented = kernel.fixFaceOrientations(solid);
+    if (!kernel.isSolid(oriented)) {
+        throw new Error(`buildRingGearSolid: result is not a solid (got ${String(kernel.getShapeType(oriented))})`);
+    }
+    // 镀铬特征（倒角 / 轴孔）：cq RingGear `_make_chamfer` 用内齿版 cutter 轮廓（isRing=true）。
+    let result = oriented;
+    if (build.chamfer !== undefined || build.chamferTop !== undefined || build.chamferBottom !== undefined) {
+        result = applyChamfer(kernel, result, geom.ra, geom.width, build, true);
+    }
+    if (build.boreD !== undefined) {
+        result = applyBore(kernel, result, build.boreD, geom.width);
+    }
+    if (!kernel.isSolid(result)) {
+        throw new Error(`buildRingGearSolid: result is not a solid after features (got ${String(kernel.getShapeType(result))})`);
+    }
+    return result;
+}
+/** ①–④：完整 HerringboneRingGear 实体（人字内齿，裸齿轮）。
+ *
+ * 齿廓数学与 RingGear 同构（`gearGeometryForClass` 已分派到 `ringGearGeometry`），
+ * 差异只在建面阶段：齿面拆成上下两半、反向螺旋形成 V 形（复用
+ * `buildHerringboneToothFaces`）；rim 圆柱面与环形盖面与 RingGear 一致。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 内齿参数（逐字沿用 Python 构造参数名）
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export function buildHerringboneRingGearSolid(kernel, params, build = {}) {
+    return buildRingGearSolid(kernel, params, { ...build, herringbone: true });
+}
+//# sourceMappingURL=ring_gear.js.map

package/dist/ring_gear.js.map

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

package/dist/spline-face.d.ts

@@ -0,0 +1,99 @@
+/**
+ * spline-face — thin adapter over cq-compat's gear spline-face primitives.
+ *
+ * The three B-spline face strategies (probed in the v1 spike, 2026-09-08) moved
+ * INTO cq-compat per the port plan (§4/§5): raw kernel knowledge lives there,
+ * fai_cq_gears only consumes. This file preserves the v1 import names for
+ * existing call sites and keeps the measurement helpers (they are test/report
+ * tooling, not geometry ops — they stay in this package but consume the
+ * cq-compat kernel type).
+ *
+ * | strategy | how | semantic delta vs cq |
+ * |---|---|---|
+ * | `grid-approx` | `kernel.bsplineSurface(flat, rows, cols)` | OCCT default DegMin/DegMax/Tol3D; cq passes 3/8/1e-2 explicitly |
+ * | `row-approx-loft` | per-row `approximatePoints(row, tol)` → `loft(wires, false, false)` | curve-level tol same name/meaning; surface is skinned, not fitted at once |
+ * | `row-interp-loft` | per-row `interpolatePoints(row)` → `loft` | passes through every sample point (interpolation) |
+ */
+import type { BrepHandle } from '@faicad/faijs';
+import { soleGearFace as soleFace, type GearDeviationStats, type GearKernel, type GearSplineFaceOptions, type GearSplineFaceStrategy } from '@faicad/cq-compat';
+import type { Vec3 } from './math.js';
+import type { ToothGrid } from './profile.js';
+export { soleFace };
+/** 齿面样条生成策略（cq-compat `Workplane.splineFace` 的 `strategy` 取值）。 */
+export type SplineFaceStrategy = GearSplineFaceStrategy;
+/** `splineFace` 的构造选项（行/列策略与容差）。 */
+export type SplineFaceOptions = GearSplineFaceOptions;
+/** 与解析齿面的偏差统计（面积相对偏差 + 采样点最大距离）。 */
+export type DeviationStats = GearDeviationStats;
+/**
+ * P0 实测选定的默认策略（2026-09-08）。
+ *
+ * 依据 `spline-face.test.ts` 的实测表：S2 的面积相对偏差 5.6e-7 / 采样点最大距离
+ * 2.6e-6 mm，比 S1、S3 好约 3 个数量级。详见
+ * `docs/analysis/2026-09-08-fai-cq-gears-spike.md`。
+ */
+export declare const DEFAULT_SPLINE_FACE_STRATEGY: GearSplineFaceStrategy;
+/** 全部可选策略（测试按此顺序遍历出偏差表）。 */
+export declare const SPLINE_FACE_STRATEGIES: readonly GearSplineFaceStrategy[];
+/**
+ * 用给定策略把一个 row×col 点阵建成面。
+ *
+ * @throws 内核抛错时原样上抛（不吞错误——这是红线）
+ *
+ * @param kernel 原始 OCCT 内核（经 cq-compat 的 `GearKernel`）
+ * @param grid row×col 点阵
+ * @param strategy 建面策略
+ * @param options 容差/次数选项
+ * @returns 单个面句柄（Face）
+ */
+export declare function buildSplineFace(kernel: GearKernel, grid: ToothGrid, strategy: SplineFaceStrategy, options?: SplineFaceOptions): BrepHandle;
+/** 点到面的最近距离（`projectPointOnFace`）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param face 目标面
+ * @param p 查询点
+ * @returns 欧氏距离（mm）
+ */
+export declare function distanceToFace(kernel: GearKernel, face: BrepHandle, p: Vec3): number;
+/** 距离统计（最大值 / RMS / 样本数）。 */
+/**
+ * 参考采样点到本面的距离统计。
+ *
+ * 参数化无关：采样点取自 cq 侧的 (u,v) 网格，两侧曲面参数化不同也能比。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param face 本侧面
+ * @param samplePoints 参考采样点（3D）
+ * @returns 最大距离 / RMS / 样本数
+ */
+export declare function faceDeviation(kernel: GearKernel, face: BrepHandle, samplePoints: Vec3[]): DeviationStats;
+/** 单个齿面的实测结果（面积 + 偏差 + 拓扑计数），供测试与报告使用。 */
+export interface SplineFaceMeasurement {
+    segment: string;
+    strategy: SplineFaceStrategy;
+    rows: number;
+    cols: number;
+    area: number;
+    isFace: boolean;
+    isValid: boolean;
+    deviation: DeviationStats;
+    /** Python 侧的参考面积（来自 manifest） */
+    refArea: number;
+    /** 面积相对偏差 |Δ|/ref */
+    areaRelDiff: number;
+}
+/**
+ * 建面并测量（参考面积与采样点由 Python 侧 manifest 提供）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param grid row×col 点阵
+ * @param strategy 建面策略
+ * @param ref 参考面积与采样点
+ * @param options 容差/次数选项
+ * @returns 实测结果（面积、偏差、拓扑计数）
+ */
+export declare function measureSplineFace(kernel: GearKernel, grid: ToothGrid, strategy: SplineFaceStrategy, ref: {
+    area: number;
+    sample_points: number[][];
+}, options?: SplineFaceOptions): SplineFaceMeasurement;
+//# sourceMappingURL=spline-face.d.ts.map

package/dist/spline-face.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline-face.d.ts","sourceRoot":"","sources":["../src/spline-face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAIL,YAAY,IAAI,QAAQ,EAGxB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,CAAA;AAEnB,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,CAAA;AACvD,oCAAoC;AACpC,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,CAAA;AACrD,oCAAoC;AACpC,MAAM,MAAM,cAAc,GAAG,kBAAkB,CAAA;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,wBAAoC,CAAA;AAE7E,4BAA4B;AAC5B,eAAO,MAAM,sBAAsB,mCAA8B,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAEZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAEpF;AAED,6BAA6B;AAE7B;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,YAAY,EAAE,IAAI,EAAE,GACnB,cAAc,CAEhB;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,cAAc,CAAA;IACzB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,qBAAqB;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,EAChD,OAAO,GAAE,iBAAsB,GAC9B,qBAAqB,CAoBvB"}

package/dist/spline-face.js

@@ -0,0 +1,94 @@
+/**
+ * spline-face — thin adapter over cq-compat's gear spline-face primitives.
+ *
+ * The three B-spline face strategies (probed in the v1 spike, 2026-09-08) moved
+ * INTO cq-compat per the port plan (§4/§5): raw kernel knowledge lives there,
+ * fai_cq_gears only consumes. This file preserves the v1 import names for
+ * existing call sites and keeps the measurement helpers (they are test/report
+ * tooling, not geometry ops — they stay in this package but consume the
+ * cq-compat kernel type).
+ *
+ * | strategy | how | semantic delta vs cq |
+ * |---|---|---|
+ * | `grid-approx` | `kernel.bsplineSurface(flat, rows, cols)` | OCCT default DegMin/DegMax/Tol3D; cq passes 3/8/1e-2 explicitly |
+ * | `row-approx-loft` | per-row `approximatePoints(row, tol)` → `loft(wires, false, false)` | curve-level tol same name/meaning; surface is skinned, not fitted at once |
+ * | `row-interp-loft` | per-row `interpolatePoints(row)` → `loft` | passes through every sample point (interpolation) |
+ */
+import { buildGearSplineFace, gearDistanceToFace, gearFaceDeviation, soleGearFace as soleFace, DEFAULT_GEAR_SPLINE_FACE_STRATEGY, GEAR_SPLINE_FACE_STRATEGIES, } from '@faicad/cq-compat';
+export { soleFace };
+/**
+ * P0 实测选定的默认策略（2026-09-08）。
+ *
+ * 依据 `spline-face.test.ts` 的实测表：S2 的面积相对偏差 5.6e-7 / 采样点最大距离
+ * 2.6e-6 mm，比 S1、S3 好约 3 个数量级。详见
+ * `docs/analysis/2026-09-08-fai-cq-gears-spike.md`。
+ */
+export const DEFAULT_SPLINE_FACE_STRATEGY = DEFAULT_GEAR_SPLINE_FACE_STRATEGY;
+/** 全部可选策略（测试按此顺序遍历出偏差表）。 */
+export const SPLINE_FACE_STRATEGIES = GEAR_SPLINE_FACE_STRATEGIES;
+/**
+ * 用给定策略把一个 row×col 点阵建成面。
+ *
+ * @throws 内核抛错时原样上抛（不吞错误——这是红线）
+ *
+ * @param kernel 原始 OCCT 内核（经 cq-compat 的 `GearKernel`）
+ * @param grid row×col 点阵
+ * @param strategy 建面策略
+ * @param options 容差/次数选项
+ * @returns 单个面句柄（Face）
+ */
+export function buildSplineFace(kernel, grid, strategy, options = {}) {
+    return buildGearSplineFace(kernel, grid, strategy, options);
+}
+/** 点到面的最近距离（`projectPointOnFace`）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param face 目标面
+ * @param p 查询点
+ * @returns 欧氏距离（mm）
+ */
+export function distanceToFace(kernel, face, p) {
+    return gearDistanceToFace(kernel, face, p);
+}
+/** 距离统计（最大值 / RMS / 样本数）。 */
+/**
+ * 参考采样点到本面的距离统计。
+ *
+ * 参数化无关：采样点取自 cq 侧的 (u,v) 网格，两侧曲面参数化不同也能比。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param face 本侧面
+ * @param samplePoints 参考采样点（3D）
+ * @returns 最大距离 / RMS / 样本数
+ */
+export function faceDeviation(kernel, face, samplePoints) {
+    return gearFaceDeviation(kernel, face, samplePoints);
+}
+/**
+ * 建面并测量（参考面积与采样点由 Python 侧 manifest 提供）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param grid row×col 点阵
+ * @param strategy 建面策略
+ * @param ref 参考面积与采样点
+ * @param options 容差/次数选项
+ * @returns 实测结果（面积、偏差、拓扑计数）
+ */
+export function measureSplineFace(kernel, grid, strategy, ref, options = {}) {
+    const face = buildSplineFace(kernel, grid, strategy, options);
+    const area = kernel.getSurfaceArea(face);
+    const deviation = faceDeviation(kernel, face, ref.sample_points.map((p) => ({ x: p[0], y: p[1], z: p[2] })));
+    return {
+        segment: grid.segment,
+        strategy,
+        rows: grid.rows,
+        cols: grid.cols,
+        area,
+        isFace: kernel.isFace(face),
+        isValid: kernel.isValid(face),
+        deviation,
+        refArea: ref.area,
+        areaRelDiff: Math.abs(area - ref.area) / ref.area,
+    };
+}
+//# sourceMappingURL=spline-face.js.map

package/dist/spline-face.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline-face.js","sourceRoot":"","sources":["../src/spline-face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,IAAI,QAAQ,EACxB,iCAAiC,EACjC,2BAA2B,GAK5B,MAAM,mBAAmB,CAAA;AAI1B,OAAO,EAAE,QAAQ,EAAE,CAAA;AASnB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,iCAAiC,CAAA;AAE7E,4BAA4B;AAC5B,MAAM,CAAC,MAAM,sBAAsB,GAAG,2BAA2B,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAkB,EAClB,IAAe,EACf,QAA4B,EAC5B,UAA6B,EAAE;IAE/B,OAAO,mBAAmB,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB,EAAE,IAAgB,EAAE,CAAO;IAC1E,OAAO,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED,6BAA6B;AAE7B;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAkB,EAClB,IAAgB,EAChB,YAAoB;IAEpB,OAAO,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAA;AACtD,CAAC;AAkBD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAkB,EAClB,IAAe,EACf,QAA4B,EAC5B,GAAgD,EAChD,UAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;IACxC,MAAM,SAAS,GAAG,aAAa,CAC7B,MAAM,EACN,IAAI,EACJ,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAC9D,CAAA;IACD,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI;QACJ,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,SAAS;QACT,OAAO,EAAE,GAAG,CAAC,IAAI;QACjB,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI;KAClD,CAAA;AACH,CAAC"}

package/dist/spur_gear.d.ts

@@ -0,0 +1,112 @@
+/**
+ * spur_gear — SpurGear 最小实体构造（P0/P1：裸齿轮，无 bore/hub/spokes/chamfer）
+ *
+ * 对应 `SpurGear._build_gear_faces()` + `make_shell` + `Solid.makeSolid`：
+ *
+ * ```
+ * ① 4 段齿廓 → 4 个齿面（spline-face 三方案可切换）
+ * ② 每个齿面绕 Z 旋转 tau*i，得到 z 个齿的 4z 个面
+ * ③ 顶/底面：取所有位于 z=0 / z=width 的边 → 组线 → 成面
+ * ④ sew(faces, shell_sewing_tol) → makeSolid(shell)
+ * ```
+ *
+ * cq 用 `Wire.combine(edges, tol)` 组线（带容差排序）；faijs 侧用
+ * `makeWire(edges)` + `healWire(wire, tol)` 复现，容差取同一个 `wire_comb_tol`。
+ */
+import type { BrepHandle } from '@faicad/faijs';
+import type { GearKernel } from '@faicad/cq-compat';
+import { type SpurGearGeometry, type SpurGearParams } from './profile.js';
+import { type HyperbolicGearParams } from './profile.js';
+import { type SplineFaceOptions, type SplineFaceStrategy } from './spline-face.js';
+import { type GearFeatureOptions } from './features.js';
+/** SpurGear 实体构造选项（在 `SplineFaceOptions` 上加容差、策略与镀铬特征覆盖）。 */
+export interface BuildSpurGearOptions extends SplineFaceOptions, GearFeatureOptions {
+    strategy?: SplineFaceStrategy;
+    /** 缝合容差（cq `shell_sewing_tol`）。 */
+    shellSewingTol?: number;
+    /** 组线容差（cq `wire_comb_tol`）。 */
+    wireCombTol?: number;
+    /** 人字齿：齿面沿宽度方向拆成上下两半、各以相反螺旋扭转（V 形）。 */
+    herringbone?: boolean;
+}
+/**
+ * 把一批面中位于 `z` 平面上的边界边收集成一个平面盖面。
+ *
+ * @throws 内核抛错时原样上抛
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param faces 齿面集合（已含 z 向厚度）
+ * @param z 目标平面高度
+ * @param wireCombTol 组线容差（mm）
+ * @returns 平面盖面（Face）
+ */
+export declare function planarCapAtZ(kernel: GearKernel, faces: BrepHandle[], z: number, wireCombTol?: number): BrepHandle;
+/** ①+②：4z 个齿面（不含顶/底面）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param geom 齿轮几何量
+ * @param strategy 齿面建面策略
+ * @param options 容差/次数选项
+ * @returns 齿面列表（4z 个 Face）
+ */
+export declare function buildToothFaces(kernel: GearKernel, geom: SpurGearGeometry, strategy: SplineFaceStrategy, options?: SplineFaceOptions): BrepHandle[];
+/**
+ * ①+②：人字齿（Herringbone）的 8z 个齿面（上下两半 V 形）。
+ *
+ * 对应 cq_gears `HerringboneGear._build_tooth_faces`：调父类两次，
+ * 上半 `(0, +twist, 0, w/2)`、下半 `(+twist, 0, w/2, w/2)`，两半在 z=w/2 处
+ * 以相同扭转角衔接（点集重合，sew 自动并合）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param geom 齿廓几何量
+ * @param strategy 齿面建面策略
+ * @param options 容差/次数选项
+ * @returns 齿面列表（8z 个 Face：4 段 × 2 半 × z 齿）
+ */
+export declare function buildHerringboneToothFaces(kernel: GearKernel, geom: SpurGearGeometry, strategy: SplineFaceStrategy, options?: SplineFaceOptions): BrepHandle[];
+/** ③–④：由**已算好**的齿廓几何量构造裸齿轮实体（SpurGear 全族共用）。
+ *
+ * 与类无关：只吃 `SpurGearGeometry`（Spur / Herringbone / CrossedHelical 的齿廓布局
+ * 同构），所以子类（如 CrossedHelical）只要先用自己的公式算出 `geom`，即可复用它。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param geom 齿廓几何量（`spurGearGeometry` / `crossedHelicalGearGeometry` 的产物）
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export declare function buildGearSolid(kernel: GearKernel, geom: SpurGearGeometry, build?: BuildSpurGearOptions): BrepHandle;
+/** ①–④：完整 SpurGear 实体（裸齿轮）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 齿轮参数
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export declare function buildSpurGearSolid(kernel: GearKernel, params: SpurGearParams, build?: BuildSpurGearOptions): BrepHandle;
+/** ①–④：完整 HerringboneGear 实体（人字齿，裸齿轮）。
+ *
+ * 齿廓数学与 SpurGear 同构（`gearGeometryForClass` 已分派到 `spurGearGeometry`），
+ * 差异只在建面阶段：齿面沿宽度拆成上下两半、反向螺旋形成 V 形，由
+ * `buildHerringboneToothFaces` 实现；顶/底盖面与 SpurGear 一致（z=0 与 z=width 处
+ * 截面均为基准渐开线，净扭转回零）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 齿轮参数（逐字沿用 Python 构造参数名）
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export declare function buildHerringboneGearSolid(kernel: GearKernel, params: SpurGearParams, build?: BuildSpurGearOptions): BrepHandle;
+/**
+ * ①–④：完整 HyperbolicGear 实体（双曲面齿轮，裸齿轮）。
+ *
+ * 齿廓数学与 SpurGear 同构，差异只在 `twist_angle` 来自显式构造参数（见
+ * `hyperbolicGearGeometry`）、`surfaceSplines=2`；实体构造完全复用通用的
+ * `buildGearSolid`。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 双曲面齿轮参数（逐字沿用 Python 构造参数名）
+ * @param build 构造选项（策略/容差覆盖）
+ * @returns 朝向归一化后的 solid
+ */
+export declare function buildHyperbolicGearSolid(kernel: GearKernel, params: HyperbolicGearParams, build?: BuildSpurGearOptions): BrepHandle;
+//# sourceMappingURL=spur_gear.d.ts.map

package/dist/spur_gear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spur_gear.d.ts","sourceRoot":"","sources":["../src/spur_gear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AACtF,OAAO,EAA4C,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAC/F,OAAO,EAEL,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAChD,MAAM,eAAe,CAAA;AAEtB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAA;AAKnB,6DAA6D;AAC7D,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB,EAAE,kBAAkB;IACjF,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EAAE,EACnB,CAAC,EAAE,MAAM,EACT,WAAW,GAAE,MAA0C,GACtD,UAAU,CAoBZ;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,EAAE,CAad;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,EAAE,CAgBd;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,EACtB,KAAK,GAAE,oBAAyB,GAC/B,UAAU,CAyDZ;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,oBAAyB,GAC/B,UAAU,CAEZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,oBAAyB,GAC/B,UAAU,CAEZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,oBAAoB,EAC5B,KAAK,GAAE,oBAAyB,GAC/B,UAAU,CAEZ"}