@faicad/fai-cq-gears 0.13.0

package/dist/math.js

@@ -0,0 +1,274 @@
+/**
+ * math — cq_gears `utils.py` 的 numpy 子集（零依赖，TS 手写）
+ *
+ * 约定（**与 Python 逐字对齐，不要"修正"**）：
+ *
+ * - `rotationMatrix(axis, alpha)` 返回 cq 的同款 Rodrigues 矩阵 R（列向量约定 `p' = R·p`）。
+ * - cq 里齿轮点集用的是 `pts @ r_mat`（**行向量**左乘），等价于 `Rᵀ·p`，即**绕轴转 −alpha**。
+ *   这不是笔误——`spur_gear.py::_build_tooth_faces` 就是这么写的，实测
+ *   （`spur-helix15` 参考数据）确认齿面扭转方向与 `−twist_angle` 一致。
+ *   所以本模块同时提供 `applyRowMatrix()`（忠实复刻）与 `rotateRows()`（语义命名）。
+ */
+/**
+ * 构造一个 `Vec3`。
+ *
+ * @param x x 分量
+ * @param y y 分量
+ * @param z z 分量
+ * @returns 三维向量
+ */
+export const vec3 = (x, y, z) => ({ x, y, z });
+/**
+ * 向量加法。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a + b`
+ */
+export const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
+/**
+ * 向量减法。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a - b`
+ */
+export const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+/**
+ * 标量乘法。
+ *
+ * @param a 向量
+ * @param k 标量
+ * @returns `k·a`
+ */
+export const scale = (a, k) => ({ x: a.x * k, y: a.y * k, z: a.z * k });
+/**
+ * 点积。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a·b`
+ */
+export const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+/**
+ * 叉积。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a×b`
+ */
+export const cross = (a, b) => ({
+    x: a.y * b.z - a.z * b.y,
+    y: a.z * b.x - a.x * b.z,
+    z: a.x * b.y - a.y * b.x,
+});
+/**
+ * 向量模长。
+ *
+ * @param a 向量
+ * @returns 模长
+ */
+export const norm = (a) => Math.sqrt(dot(a, a));
+/**
+ * 归一化；零向量返回零向量（避免除零）。
+ *
+ * @param a 向量
+ * @returns 单位向量（零向量输入返回零向量）
+ */
+export const normalize = (a) => {
+    const n = norm(a);
+    return n === 0 ? { x: 0, y: 0, z: 0 } : scale(a, 1 / n);
+};
+/**
+ * `np.linspace(a, b, n)` —— 闭区间，含两端。
+ *
+ * @param a 起始值
+ * @param b 结束值
+ * @param n 点数
+ * @returns n 个等距点（n <= 1 时只含 a）
+ */
+export function linspace(a, b, n) {
+    if (n <= 1)
+        return [a];
+    const out = new Array(n);
+    const step = (b - a) / (n - 1);
+    for (let i = 0; i < n; i++)
+        out[i] = a + step * i;
+    return out;
+}
+/**
+ * 弧度夹到 [0, 2π)。
+ *
+ * @param t 任意弧度角
+ * @returns 归一化后的弧度角
+ */
+export function normalizeAngle2pi(t) {
+    const twoPi = Math.PI * 2;
+    let r = t % twoPi;
+    if (r < 0)
+        r += twoPi;
+    return r;
+}
+/**
+ * `cq_gears.utils.rotation_matrix` 的逐字移植（Rodrigues，列向量约定）。
+ *
+ * @param axis  旋转轴（无需归一化，内部归一）
+ * @param alpha 旋转角（弧度）
+ * @returns 3×3 Rodrigues 旋转矩阵（行主序）
+ */
+export function rotationMatrix(axis, alpha) {
+    const n = norm(axis);
+    const ux = axis.x / n;
+    const uy = axis.y / n;
+    const uz = axis.z / n;
+    const sina = Math.sin(alpha);
+    const cosa = Math.cos(alpha);
+    const k = 1 - cosa;
+    return [
+        [cosa + k * ux * ux, ux * uy * k - uz * sina, ux * uz * k + uy * sina],
+        [uy * ux * k + uz * sina, cosa + k * uy * uy, uy * uz * k - ux * sina],
+        [uz * ux * k - uy * sina, uz * uy * k + ux * sina, cosa + k * uz * uz],
+    ];
+}
+/**
+ * 行向量左乘：`pts @ m`（cq 的实际用法）。
+ *
+ * 结果第 j 分量 = Σᵢ pᵢ·m[i][j]，等价于 `mᵀ · p`。
+ *
+ * @param points 行向量点集
+ * @param m 3×3 矩阵
+ * @returns 变换后的点集
+ */
+export function applyRowMatrix(points, m) {
+    return points.map((p) => ({
+        x: p.x * m[0][0] + p.y * m[1][0] + p.z * m[2][0],
+        y: p.x * m[0][1] + p.y * m[1][1] + p.z * m[2][1],
+        z: p.x * m[0][2] + p.y * m[1][2] + p.z * m[2][2],
+    }));
+}
+/**
+ * 语义化包装：`applyRowMatrix(pts, rotationMatrix(axis, alpha))`。
+ *
+ * ⚠️ 因为 cq 用行向量左乘，实际旋转角是 **−alpha**。
+ *
+ * @param points 点集
+ * @param axis 旋转轴
+ * @param alpha 名义旋转角（弧度，实际为 −alpha）
+ * @returns 旋转后的点集
+ */
+export function rotateRows(points, axis, alpha) {
+    return applyRowMatrix(points, rotationMatrix(axis, alpha));
+}
+/**
+ * 真正按 +alpha 旋转（标准列向量约定），用于 TS 侧需要正向旋转的场景。
+ *
+ * @param points 点集
+ * @param axis 旋转轴
+ * @param alpha 旋转角（弧度）
+ * @returns 旋转后的点集
+ */
+export function rotatePoints(points, axis, alpha) {
+    const m = rotationMatrix(axis, -alpha);
+    return points.map((p) => ({
+        x: m[0][0] * p.x + m[0][1] * p.y + m[0][2] * p.z,
+        y: m[1][0] * p.x + m[1][1] * p.y + m[1][2] * p.z,
+        z: m[2][0] * p.x + m[2][1] * p.y + m[2][2] * p.z,
+    }));
+}
+/**
+ * `cq_gears.utils.sphere_to_cartesian` 的逐字移植：球坐标 → 笛卡尔。
+ *
+ * ⚠️ 注意极点角 `gamma` 是**从 +Z 轴量起**（`z = r·cos(gamma)`），
+ * 而不是数学习惯里从 XY 平面量起的仰角——BevelGear 的整套公式都建立在这个约定上。
+ *
+ * @param r 球半径
+ * @param gamma 极角（弧度，自 +Z 轴）
+ * @param theta 方位角（弧度）
+ * @returns 笛卡尔坐标
+ */
+export function sphereToCartesian(r, gamma, theta) {
+    return {
+        x: r * Math.sin(gamma) * Math.sin(theta),
+        y: r * Math.sin(gamma) * Math.cos(theta),
+        z: r * Math.cos(gamma),
+    };
+}
+/**
+ * `cq_gears.utils.s_inv` 的逐字移植：球面渐开线（给定极角 → 方位角）。
+ *
+ * `phi = arccos(tan(gamma0)/tan(gamma))`；
+ * `return arccos(cos(gamma)/cos(gamma0))/sin(gamma0) − phi`。
+ *
+ * 定义域外（`|tan(gamma0)/tan(gamma)| > 1`）与 Python 的 numpy 一样返回 NaN——
+ * 由调用方决定是否报错，本函数不静默替换。
+ *
+ * @param gamma0 基锥极角（弧度）
+ * @param gamma 曲线上点的极角（弧度）
+ * @returns 该点的方位角（弧度）
+ */
+export function sInv(gamma0, gamma) {
+    const phi = Math.acos(Math.tan(gamma0) / Math.tan(gamma));
+    return Math.acos(Math.cos(gamma) / Math.cos(gamma0)) / Math.sin(gamma0) - phi;
+}
+/**
+ * `cq_gears.utils.s_arc` 的逐字移植：球面上的一段圆弧。
+ *
+ * Python 侧是 `cos(t)·a + sin(t)·(k×a) + (k·a)(1−cos t)·k`（`a` = 球心到弧心方向
+ * 偏移 `r_delta` 后的单位向量，`k` = 弧心的单位向量），再整体乘球半径。
+ *
+ * @param sr 球半径
+ * @param cGamma 弧心的极角（弧度）
+ * @param cTheta 弧心的方位角（弧度）
+ * @param rDelta 弧心与弧上任一点的夹角（弧度）
+ * @param start 起始角（弧度）
+ * @param end 终止角（弧度）
+ * @param n 点数（含两端）
+ * @returns 弧上 n 个点
+ */
+export function sArc(sr, cGamma, cTheta, rDelta, start, end, n = 32) {
+    const a = sphereToCartesian(1.0, cGamma + rDelta, cTheta);
+    const k = sphereToCartesian(1.0, cGamma, cTheta);
+    const ka = cross(k, a);
+    const kdota = dot(k, a);
+    return linspace(start, end, n).map((t) => {
+        const ct = Math.cos(t);
+        const st = Math.sin(t);
+        const w = 1 - ct;
+        return vec3(sr * (ct * a.x + st * ka.x + kdota * w * k.x), sr * (ct * a.y + st * ka.y + kdota * w * k.y), sr * (ct * a.z + st * ka.z + kdota * w * k.z));
+    });
+}
+/**
+ * `cq_gears.utils.angle_between` 的移植：向量 OA 与 OB 的夹角。
+ *
+ * @param o 公共起点
+ * @param a 向量 OA 的终点
+ * @param b 向量 OB 的终点
+ * @returns 夹角（弧度）
+ */
+export function angleBetween(o, a, b) {
+    const p = sub(a, o);
+    const q = sub(b, o);
+    return Math.acos(dot(p, q) / (norm(p) * norm(q)));
+}
+/**
+ * `cq_gears.utils.circle3d_by3points` 的移植：三点定圆。
+ *
+ * @param a 第一点
+ * @param b 第二点
+ * @param c 第三点
+ * @returns `{ radius, center }`
+ */
+export function circle3dBy3points(a, b, c) {
+    let u = sub(b, a);
+    let w = cross(sub(c, a), u);
+    u = normalize(u);
+    w = normalize(w);
+    const v = cross(w, u);
+    const bx = dot(sub(b, a), u);
+    const cx = dot(sub(c, a), u);
+    const cy = dot(sub(c, a), v);
+    const h = ((cx - bx / 2) ** 2 + cy ** 2 - (bx / 2) ** 2) / (2 * cy);
+    const center = add(a, add(scale(u, bx / 2), scale(v, h)));
+    return { radius: norm(sub(a, center)), center };
+}
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

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

package/dist/pairs.d.ts

@@ -0,0 +1,161 @@
+/**
+ * pairs — 齿轮对（装配体）构造
+ *
+ * 对应 cq_gears `bevel_gear.py::BevelGearPair`：把两个单体锥齿轮按轴交角装配成一个
+ * Compound（`asm.toCompound()`），本包返回**两件各自的 solid**，由调用方决定导出方式
+ * （`exportStepFromSolids` 把它们各写成一个 XCAF 条目/产品）。
+ *
+ * ## 装配定位链（2026-09-12 在 cadquery-env 实测确定，非推断）
+ *
+ * Python 侧：
+ *
+ * ```python
+ * loc = cq.Location()
+ * loc *= cq.Location(cq.Vector(0, 0, gear.cone_h), cq.Vector(0, 1, 0), degrees(axis_angle))
+ * loc *= cq.Location(cq.Vector(0, 0, -pinion.cone_h))
+ * if pinion.z % 2 == 0:
+ *     loc *= cq.Location(cq.Vector(0, 0, 0), cq.Vector(0, 0, 1), degrees(pi / pinion.z))
+ * ```
+ *
+ * 两条实测结论（`out/probe-loc.py`，输出见当日日志）：
+ *
+ * 1. `LocA * LocB` 的复合是**右到左**——先应用 B，再应用 A
+ *    （实测 `(r*t)·(1,0,0) = (0,11,0)`：先平移 +10x 再绕 Z 转 90°，而非反过来）。
+ *    故 `loc = A*B*C` 的施加顺序是 **C → B → A**。
+ * 2. `Location(t, ax, angle)` 的 `t` 是**平移分量**，旋转轴恒是**过原点**的
+ *    `gp_Ax1(Vector(0,0,0), ax)`——不是「绕 t 点旋转」。
+ *    实测 `Location((0,0,5), Y, 90)` 作用在 `(1,0,0)` 上得 `(0,0,4)`
+ *    =「先绕原点 Y 转 90° 得 (0,0,-1)，再平移 +5z」，且 `toTuple()` 为 `((0,0,5),(0,90,0))`。
+ *
+ * 所以 pinion 的最终位姿是，按施加顺序：
+ *
+ * | 步 | 对应 Python | 本文件实现 |
+ * |---|---|---|
+ * | C | `Location((0,0,0), Z, degrees(pi/z))`，**仅 pinion 齿数为偶** | 绕 Z 转过原点转 `π/z` |
+ * | B | `Location((0,0,-pinion.cone_h))` | 沿 Z 平移 `-pinionConeH` |
+ * | A | `Location((0,0,gear.cone_h), Y, degrees(axis_angle))` | 绕 Y 转过原点转 `axisAngle`，再沿 Z 平移 `+gearConeH` |
+ *
+ * gear 不加任何定位（Python 用 `cq.Location()` 恒等）。
+ *
+ * ## 与 Python 的两处差异（照抄，不改）
+ *
+ * - **pinion 不传 `clearance`**：Python 侧 `BevelGearPair.__init__` 给 gear 传了
+ *   `clearance`、给 pinion 只传了 `backlash`（`clearance` 落回默认 0.0）。
+ *   本实现逐字保持这个不对称。
+ * - **pinion 的螺旋角取负**：`-helix_angle`（一对锥齿轮的旋向相反）。
+ */
+import type { BrepHandle } from '@faicad/faijs';
+import type { GearKernel } from '@faicad/cq-compat';
+import { type BevelGearGeometry } from './profile.js';
+import type { SplineFaceStrategy } from './spline-face.js';
+/** 锥齿轮副参数（逐字沿用 Python `BevelGearPair.__init__` 的构造参数名）。 */
+export interface BevelGearPairParams {
+    module: number;
+    /** 大轮齿数（cq `gear_teeth`）。 */
+    gear_teeth: number;
+    /** 小轮齿数（cq `pinion_teeth`）。 */
+    pinion_teeth: number;
+    face_width: number;
+    /** 轴交角（度，cq `axis_angle`，默认 90）。 */
+    axis_angle?: number;
+    pressure_angle?: number;
+    helix_angle?: number;
+    clearance?: number;
+    backlash?: number;
+}
+/** 齿轮对构造选项。 */
+export interface BuildBevelGearPairOptions {
+    /** 齿面建面策略（两件共用）。 */
+    strategy?: SplineFaceStrategy;
+    /** 轴孔直径（两件共用，cq `bore_d`）。 */
+    boreD?: number;
+    /** 是否裁底（两件共用）。 */
+    trimBottom?: boolean;
+    /** 是否裁顶（两件共用）。 */
+    trimTop?: boolean;
+    /** 是否对 pinion 施加装配定位（cq `transform_pinion`，默认 true）。 */
+    transformPinion?: boolean;
+    /** 是否构建大轮（cq `build_gear`，默认 true）。 */
+    buildGear?: boolean;
+    /** 是否构建小轮（cq `build_pinion`，默认 true）。 */
+    buildPinion?: boolean;
+}
+/** pinion 定位链的输入量（拆出来便于单测直接验证定位本身）。 */
+export interface PinionPlacement {
+    /** 轴交角（度）。 */
+    axisAngleDeg: number;
+    /** 大轮锥顶到底面的距离 `BevelGear.cone_h`。 */
+    gearConeH: number;
+    /** 小轮锥顶到底面的距离 `BevelGear.cone_h`。 */
+    pinionConeH: number;
+    /** 小轮齿数（决定是否施加绕 Z 的 π/z 对齿旋转）。 */
+    pinionTeeth: number;
+}
+/** 一对锥齿轮的构建结果。 */
+export interface BevelGearPairBuild {
+    /** 大轮 solid（未加定位）。 */
+    gear?: BrepHandle;
+    /** 小轮 solid（**已加**定位，除非 `transformPinion: false`）。 */
+    pinion?: BrepHandle;
+    /** 大轮几何量（含 `coneH`）。 */
+    gearGeometry: BevelGearGeometry;
+    /** 小轮几何量（含 `coneH`）。 */
+    pinionGeometry: BevelGearGeometry;
+    /** 实际使用的轴交角（度）。 */
+    axisAngleDeg: number;
+}
+/**
+ * 齿轮对的导出条目（名字 + solid），供 `exportStepFromSolids` 一件一个产品。
+ *
+ * ⚠️ 不带颜色：cq 侧的装配色（`BevelGearPair.asm_gear_color = 'goldenrod'` /
+ * `asm_pinion_color = 'lightsteelblue'`）在 `assemble()` 里赋给 `cq.Assembly`，
+ * 而 `_build()` 返回的是 `asm.toCompound()`——**颜色在这一步就被丢掉了**。
+ * 实测参考 STEP（`out/ref-pairs/bp-basic.step`）里 `MANIFOLD_SOLID_BREP` 计数为 2、
+ * `COLOUR_RGB` 计数为 **0**。故 B 侧同样不着色，两侧才逐项可比。
+ *
+ * @param build `buildBevelGearPair` 的结果
+ * @returns 按 gear → pinion 顺序排列的条目（缺件则跳过）
+ */
+export declare function bevelPairExportParts(build: BevelGearPairBuild): Array<{
+    name: string;
+    solid: BrepHandle;
+}>;
+/**
+ * 复刻 `BevelGearPair.__init__` 的分锥角分配。
+ *
+ * `delta_gear = atan(sin(A) / (pinion_teeth/gear_teeth + cos(A)))`、
+ * `delta_pinion = atan(sin(A) / (gear_teeth/pinion_teeth + cos(A)))`。
+ *
+ * @param params 齿轮副参数
+ * @returns 大轮 / 小轮的分度锥角（度）
+ */
+export declare function bevelPairConeAngles(params: BevelGearPairParams): {
+    gearDeg: number;
+    pinionDeg: number;
+};
+/**
+ * 把小轮摆到与大轮啮合的位姿（复刻 Python 的三步 `loc *=`，见文件头表格）。
+ *
+ * 施加顺序 **C → B → A**，对应内核操作的调用顺序：
+ * 先绕 Z 转（仅齿数为偶）、再沿 Z 平移 `-pinionConeH`、
+ * 再绕 Y 转过原点转 `axisAngle`、最后沿 Z 平移 `+gearConeH`。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param pinion 小轮 solid
+ * @param place 定位链输入量
+ * @returns 定位后的小轮 solid
+ */
+export declare function placePinion(kernel: GearKernel, pinion: BrepHandle, place: PinionPlacement): BrepHandle;
+/**
+ * 构建一对锥齿轮（`BevelGearPair`）。
+ *
+ * 两件都走 `buildBevelGearSolid`；差异只在参数：pinion 拿 `-helix_angle`，
+ * 且**不传** `clearance`（逐字复刻 Python 的不对称传参）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 齿轮副参数
+ * @param options 构造选项
+ * @returns 两件 solid（pinion 默认已定位）与两件几何量
+ */
+export declare function buildBevelGearPair(kernel: GearKernel, params: BevelGearPairParams, options?: BuildBevelGearPairOptions): BevelGearPairBuild;
+//# sourceMappingURL=pairs.d.ts.map

package/dist/pairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairs.d.ts","sourceRoot":"","sources":["../src/pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAqB,KAAK,iBAAiB,EAAwB,MAAM,WAAW,CAAA;AAE3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvD,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,eAAe;AACf,MAAM,WAAW,yBAAyB;IACxC,oBAAoB;IACpB,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kBAAkB;IAClB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kBAAkB;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wDAAwD;IACxD,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAKD,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,cAAc;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,kBAAkB;AAClB,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,wBAAwB;IACxB,YAAY,EAAE,iBAAiB,CAAA;IAC/B,wBAAwB;IACxB,cAAc,EAAE,iBAAiB,CAAA;IACjC,mBAAmB;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,GACxB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC,CAK5C;AAGD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CASvG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,GAC7D,UAAU,CAWZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAqDpB"}

package/dist/pairs.js

@@ -0,0 +1,183 @@
+/**
+ * pairs — 齿轮对（装配体）构造
+ *
+ * 对应 cq_gears `bevel_gear.py::BevelGearPair`：把两个单体锥齿轮按轴交角装配成一个
+ * Compound（`asm.toCompound()`），本包返回**两件各自的 solid**，由调用方决定导出方式
+ * （`exportStepFromSolids` 把它们各写成一个 XCAF 条目/产品）。
+ *
+ * ## 装配定位链（2026-09-12 在 cadquery-env 实测确定，非推断）
+ *
+ * Python 侧：
+ *
+ * ```python
+ * loc = cq.Location()
+ * loc *= cq.Location(cq.Vector(0, 0, gear.cone_h), cq.Vector(0, 1, 0), degrees(axis_angle))
+ * loc *= cq.Location(cq.Vector(0, 0, -pinion.cone_h))
+ * if pinion.z % 2 == 0:
+ *     loc *= cq.Location(cq.Vector(0, 0, 0), cq.Vector(0, 0, 1), degrees(pi / pinion.z))
+ * ```
+ *
+ * 两条实测结论（`out/probe-loc.py`，输出见当日日志）：
+ *
+ * 1. `LocA * LocB` 的复合是**右到左**——先应用 B，再应用 A
+ *    （实测 `(r*t)·(1,0,0) = (0,11,0)`：先平移 +10x 再绕 Z 转 90°，而非反过来）。
+ *    故 `loc = A*B*C` 的施加顺序是 **C → B → A**。
+ * 2. `Location(t, ax, angle)` 的 `t` 是**平移分量**，旋转轴恒是**过原点**的
+ *    `gp_Ax1(Vector(0,0,0), ax)`——不是「绕 t 点旋转」。
+ *    实测 `Location((0,0,5), Y, 90)` 作用在 `(1,0,0)` 上得 `(0,0,4)`
+ *    =「先绕原点 Y 转 90° 得 (0,0,-1)，再平移 +5z」，且 `toTuple()` 为 `((0,0,5),(0,90,0))`。
+ *
+ * 所以 pinion 的最终位姿是，按施加顺序：
+ *
+ * | 步 | 对应 Python | 本文件实现 |
+ * |---|---|---|
+ * | C | `Location((0,0,0), Z, degrees(pi/z))`，**仅 pinion 齿数为偶** | 绕 Z 转过原点转 `π/z` |
+ * | B | `Location((0,0,-pinion.cone_h))` | 沿 Z 平移 `-pinionConeH` |
+ * | A | `Location((0,0,gear.cone_h), Y, degrees(axis_angle))` | 绕 Y 转过原点转 `axisAngle`，再沿 Z 平移 `+gearConeH` |
+ *
+ * gear 不加任何定位（Python 用 `cq.Location()` 恒等）。
+ *
+ * ## 与 Python 的两处差异（照抄，不改）
+ *
+ * - **pinion 不传 `clearance`**：Python 侧 `BevelGearPair.__init__` 给 gear 传了
+ *   `clearance`、给 pinion 只传了 `backlash`（`clearance` 落回默认 0.0）。
+ *   本实现逐字保持这个不对称。
+ * - **pinion 的螺旋角取负**：`-helix_angle`（一对锥齿轮的旋向相反）。
+ */
+import { bevelGearGeometry } from './profile.js';
+import { buildBevelGearSolid } from './bevel_gear.js';
+const Z_AXIS = { point: { x: 0, y: 0, z: 0 }, direction: { x: 0, y: 0, z: 1 } };
+const Y_AXIS = { point: { x: 0, y: 0, z: 0 }, direction: { x: 0, y: 1, z: 0 } };
+/**
+ * 齿轮对的导出条目（名字 + solid），供 `exportStepFromSolids` 一件一个产品。
+ *
+ * ⚠️ 不带颜色：cq 侧的装配色（`BevelGearPair.asm_gear_color = 'goldenrod'` /
+ * `asm_pinion_color = 'lightsteelblue'`）在 `assemble()` 里赋给 `cq.Assembly`，
+ * 而 `_build()` 返回的是 `asm.toCompound()`——**颜色在这一步就被丢掉了**。
+ * 实测参考 STEP（`out/ref-pairs/bp-basic.step`）里 `MANIFOLD_SOLID_BREP` 计数为 2、
+ * `COLOUR_RGB` 计数为 **0**。故 B 侧同样不着色，两侧才逐项可比。
+ *
+ * @param build `buildBevelGearPair` 的结果
+ * @returns 按 gear → pinion 顺序排列的条目（缺件则跳过）
+ */
+export function bevelPairExportParts(build) {
+    const parts = [];
+    if (build.gear)
+        parts.push({ name: 'gear', solid: build.gear });
+    if (build.pinion)
+        parts.push({ name: 'pinion', solid: build.pinion });
+    return parts;
+}
+/**
+ * 复刻 `BevelGearPair.__init__` 的分锥角分配。
+ *
+ * `delta_gear = atan(sin(A) / (pinion_teeth/gear_teeth + cos(A)))`、
+ * `delta_pinion = atan(sin(A) / (gear_teeth/pinion_teeth + cos(A)))`。
+ *
+ * @param params 齿轮副参数
+ * @returns 大轮 / 小轮的分度锥角（度）
+ */
+export function bevelPairConeAngles(params) {
+    const axis = ((params.axis_angle ?? 90.0) * Math.PI) / 180.0;
+    const sinA = Math.sin(axis);
+    const cosA = Math.cos(axis);
+    const ratio = params.pinion_teeth / params.gear_teeth;
+    return {
+        gearDeg: (Math.atan(sinA / (ratio + cosA)) * 180.0) / Math.PI,
+        pinionDeg: (Math.atan(sinA / (1.0 / ratio + cosA)) * 180.0) / Math.PI,
+    };
+}
+/**
+ * 把小轮摆到与大轮啮合的位姿（复刻 Python 的三步 `loc *=`，见文件头表格）。
+ *
+ * 施加顺序 **C → B → A**，对应内核操作的调用顺序：
+ * 先绕 Z 转（仅齿数为偶）、再沿 Z 平移 `-pinionConeH`、
+ * 再绕 Y 转过原点转 `axisAngle`、最后沿 Z 平移 `+gearConeH`。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param pinion 小轮 solid
+ * @param place 定位链输入量
+ * @returns 定位后的小轮 solid
+ */
+export function placePinion(kernel, pinion, place) {
+    let s = pinion;
+    if (place.pinionTeeth % 2 === 0) {
+        // C：`degrees(pi/z)` 传进 `Location` 后被 radians() 转回，净效果 = π/z 弧度。
+        s = kernel.rotate(s, Z_AXIS, Math.PI / place.pinionTeeth);
+    }
+    // B
+    s = kernel.translate(s, 0, 0, -place.pinionConeH);
+    // A：绕 Y（过原点）转轴交角，再沿 Z 平移 gear.cone_h
+    s = kernel.rotate(s, Y_AXIS, (place.axisAngleDeg * Math.PI) / 180.0);
+    return kernel.translate(s, 0, 0, place.gearConeH);
+}
+/**
+ * 构建一对锥齿轮（`BevelGearPair`）。
+ *
+ * 两件都走 `buildBevelGearSolid`；差异只在参数：pinion 拿 `-helix_angle`，
+ * 且**不传** `clearance`（逐字复刻 Python 的不对称传参）。
+ *
+ * @param kernel 原始 OCCT 内核
+ * @param params 齿轮副参数
+ * @param options 构造选项
+ * @returns 两件 solid（pinion 默认已定位）与两件几何量
+ */
+export function buildBevelGearPair(kernel, params, options = {}) {
+    const axisAngleDeg = params.axis_angle ?? 90.0;
+    const { gearDeg, pinionDeg } = bevelPairConeAngles(params);
+    const common = {};
+    if (options.strategy !== undefined)
+        common.strategy = options.strategy;
+    if (options.boreD !== undefined)
+        common.boreD = options.boreD;
+    if (options.trimBottom !== undefined)
+        common.trimBottom = options.trimBottom;
+    if (options.trimTop !== undefined)
+        common.trimTop = options.trimTop;
+    const gearParams = {
+        module: params.module,
+        teeth_number: params.gear_teeth,
+        cone_angle: gearDeg,
+        face_width: params.face_width,
+    };
+    if (params.pressure_angle !== undefined)
+        gearParams.pressure_angle = params.pressure_angle;
+    if (params.helix_angle !== undefined)
+        gearParams.helix_angle = params.helix_angle;
+    if (params.clearance !== undefined)
+        gearParams.clearance = params.clearance;
+    if (params.backlash !== undefined)
+        gearParams.backlash = params.backlash;
+    const pinionParams = {
+        module: params.module,
+        teeth_number: params.pinion_teeth,
+        cone_angle: pinionDeg,
+        face_width: params.face_width,
+    };
+    if (params.pressure_angle !== undefined)
+        pinionParams.pressure_angle = params.pressure_angle;
+    // 旋向相反；`clearance` 故意不传（Python 同样没传）。
+    pinionParams.helix_angle = -(params.helix_angle ?? 0.0);
+    if (params.backlash !== undefined)
+        pinionParams.backlash = params.backlash;
+    const gearGeometry = bevelGearGeometry(gearParams);
+    const pinionGeometry = bevelGearGeometry(pinionParams);
+    const out = { gearGeometry, pinionGeometry, axisAngleDeg };
+    if (options.buildGear !== false) {
+        out.gear = buildBevelGearSolid(kernel, gearParams, common);
+    }
+    if (options.buildPinion !== false) {
+        let pinion = buildBevelGearSolid(kernel, pinionParams, common);
+        if (options.transformPinion !== false) {
+            pinion = placePinion(kernel, pinion, {
+                axisAngleDeg,
+                gearConeH: gearGeometry.coneH,
+                pinionConeH: pinionGeometry.coneH,
+                pinionTeeth: params.pinion_teeth,
+            });
+        }
+        out.pinion = pinion;
+    }
+    return out;
+}
+//# sourceMappingURL=pairs.js.map

package/dist/pairs.js.map

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