@faicad/fai-cq-gears 0.13.0

package/dist/index.js

@@ -0,0 +1,223 @@
+/**
+ * index — fai_cq_gears 公共 API 入口（15 个齿轮类 + contractVersion）
+ *
+ * ## 现状（2026-09-13）
+ *
+ * 本包经 `@faicad/cq-compat` 的齿轮原语层消费内核（`getGearKernel()`，
+ * cq-compat 内部统一归属 occt 内核访问），入口签名（参数名逐字沿用 Python、
+ * 返回 `Result`）保持不变。
+ *
+ * 每个导出函数：
+ * - 参数名**逐字沿用 Python**（module / teeth_number / width / helix_angle …），见 `profile.ts`；
+ * - 返回 `Promise<Result<…>>`：单体齿轮返回 `BrepHandle`；齿轮对/轮系返回具名记录
+ *   （`{gear, pinion}` / `{gear1, gear2}` / `{sun, planets, ring}`）并挂 `fn.outputs`
+ *   （`library-dev-guide.md` §2.6 / 方案 §6.4），宿主据此逐件收编、导出 STEP。
+ * - `GearAssembly`（`{name, solid}[]`）保留为脚本侧逐件导出的形态（`*ExportParts`）。
+ */
+import { ok, err, CONTRACT_VERSION } from '@faicad/faijs';
+import { getGearKernel } from '@faicad/cq-compat';
+import { buildSpurGearSolid, buildHerringboneGearSolid, buildHyperbolicGearSolid, } from './spur_gear.js';
+import { buildRingGearSolid, buildHerringboneRingGearSolid, } from './ring_gear.js';
+import { buildCrossedHelicalSolid } from './crossed_helical_gear.js';
+import { buildRackGearSolid } from './rack_gear.js';
+import { buildWormSolid } from './worm_gear.js';
+import { buildBevelGearSolid } from './bevel_gear.js';
+import { buildBevelGearPair, } from './pairs.js';
+import { buildCrossedGearPair, buildHyperbolicGearPair, } from './crossed_pair.js';
+import { buildPlanetaryGearset, buildHerringbonePlanetaryGearset, } from './planetary.js';
+/** 库契约版本（与 faijs 引擎对齐，勿硬编码）。 */
+export const contractVersion = CONTRACT_VERSION;
+/**
+ * 统一内核执行包装：取单例内核、运行构建、失败转 `err`。
+ *
+ * @param fn 接收原始内核、返回 solid 或装配
+ * @returns `Result<T>`
+ */
+async function run(fn) {
+    try {
+        const kernel = await getGearKernel();
+        return ok(fn(kernel));
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+// ── A 族：直纹/扭纹齿面（网格样条曲面）──────────────────────────────────────────
+/**
+ * SpurGear（直齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `SpurGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function spurGear(params, options = {}) {
+    return run((k) => buildSpurGearSolid(k, params, options));
+}
+/**
+ * HerringboneGear（人字齿圆柱齿轮）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneGear(params, options = {}) {
+    return run((k) => buildHerringboneGearSolid(k, params, options));
+}
+/**
+ * RingGear（内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `RingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function ringGear(params, options = {}) {
+    return run((k) => buildRingGearSolid(k, params, options));
+}
+/**
+ * HerringboneRingGear（人字内齿圈）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HerringboneRingGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneRingGear(params, options = {}) {
+    return run((k) => buildHerringboneRingGearSolid(k, params, options));
+}
+/**
+ * CrossedHelicalGear（交错轴斜齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `CrossedHelicalGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function crossedHelicalGear(params, options = {}) {
+    return run((k) => buildCrossedHelicalSolid(k, params, options));
+}
+/**
+ * HyperbolicGear（双曲面齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `HyperbolicGear.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function hyperbolicGear(params, options = {}) {
+    return run((k) => buildHyperbolicGearSolid(k, params, options));
+}
+// ── B 族：球面渐开线（BevelGear）───────────────────────────────────────────────
+/**
+ * BevelGear（锥齿轮，单体）。
+ *
+ * @param params 齿轮参数（逐字沿用 Python `BevelGear.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function bevelGear(params, options = {}) {
+    return run((k) => buildBevelGearSolid(k, params, options));
+}
+/**
+ * BevelGearPair（锥齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `BevelGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / bore_d / trim）
+ * @returns `Result<BevelGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function bevelGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildBevelGearPair(k, params, options);
+        return { gear: b.gear, pinion: b.pinion };
+    });
+}
+;
+bevelGearPair.outputs = ['gear', 'pinion'];
+// ── C 族：齿条 / 蜗杆 ───────────────────────────────────────────────────────────
+/**
+ * RackGear（齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `RackGear.__init__`）
+ * @param options 构建选项（齿面策略）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function rackGear(params, options = {}) {
+    return run((k) => buildRackGearSolid(k, params, options));
+}
+/**
+ * HerringboneRackGear（人字齿条）。
+ *
+ * @param params 齿条参数（逐字沿用 Python `HerringboneRackGear.__init__`）
+ * @param options 构建选项（齿面策略；内部强制 `herringbone: true`）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function herringboneRackGear(params, options = {}) {
+    return run((k) => buildRackGearSolid(k, params, { ...options, herringbone: true }));
+}
+/**
+ * Worm（蜗杆）。
+ *
+ * @param params 蜗杆参数（逐字沿用 Python `Worm.__init__`）
+ * @param options 构建选项（策略默认 grid-approx / 缝合与组线容差 / boreD）
+ * @returns `Result<BrepHandle>`——solid 句柄，失败转 `err`
+ */
+export function worm(params, options = {}) {
+    return run((k) => buildWormSolid(k, params, options));
+}
+/**
+ * CrossedGearPair（交错轴斜齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `CrossedGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function crossedGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildCrossedGearPair(k, params, options);
+        return { gear1: b.gear1, gear2: b.gear2 };
+    });
+}
+;
+crossedGearPair.outputs = ['gear1', 'gear2'];
+/**
+ * HyperbolicGearPair（双曲面齿轮副，装配体）。
+ *
+ * @param params 齿轮副参数（逐字沿用 Python `HyperbolicGearPair.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<CrossedGearPairOutput>`——具名记录，失败转 `err`
+ */
+export function hyperbolicGearPair(params, options = {}) {
+    return run((k) => {
+        const b = buildHyperbolicGearPair(k, params, options);
+        return { gear1: b.gear1, gear2: b.gear2 };
+    });
+}
+;
+hyperbolicGearPair.outputs = ['gear1', 'gear2'];
+/**
+ * PlanetaryGearset（行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `PlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export function planetaryGearset(params, options = {}) {
+    return run((k) => {
+        const b = buildPlanetaryGearset(k, params, options);
+        return { sun: b.sun, planets: b.planets, ring: b.ring };
+    });
+}
+;
+planetaryGearset.outputs = ['sun', 'planets', 'ring'];
+/**
+ * HerringbonePlanetaryGearset（人字行星轮系，装配体）。
+ *
+ * @param params 轮系参数（逐字沿用 Python `HerringbonePlanetaryGearset.__init__`）
+ * @param options 构建选项（齿面策略 / 特征字段）
+ * @returns `Result<PlanetaryGearsetOutput>`——具名记录，失败转 `err`
+ */
+export function herringbonePlanetaryGearset(params, options = {}) {
+    return run((k) => {
+        const b = buildHerringbonePlanetaryGearset(k, params, options);
+        return { sun: b.sun, planets: b.planets, ring: b.ring };
+    });
+}
+;
+herringbonePlanetaryGearset.outputs = ['sun', 'planets', 'ring'];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/math.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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()`（语义命名）。
+ */
+/** 三维点 / 向量（与 `BrepVec3` 同构）。 */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * 构造一个 `Vec3`。
+ *
+ * @param x x 分量
+ * @param y y 分量
+ * @param z z 分量
+ * @returns 三维向量
+ */
+export declare const vec3: (x: number, y: number, z: number) => Vec3;
+/**
+ * 向量加法。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a + b`
+ */
+export declare const add: (a: Vec3, b: Vec3) => Vec3;
+/**
+ * 向量减法。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a - b`
+ */
+export declare const sub: (a: Vec3, b: Vec3) => Vec3;
+/**
+ * 标量乘法。
+ *
+ * @param a 向量
+ * @param k 标量
+ * @returns `k·a`
+ */
+export declare const scale: (a: Vec3, k: number) => Vec3;
+/**
+ * 点积。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a·b`
+ */
+export declare const dot: (a: Vec3, b: Vec3) => number;
+/**
+ * 叉积。
+ *
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns `a×b`
+ */
+export declare const cross: (a: Vec3, b: Vec3) => Vec3;
+/**
+ * 向量模长。
+ *
+ * @param a 向量
+ * @returns 模长
+ */
+export declare const norm: (a: Vec3) => number;
+/**
+ * 归一化；零向量返回零向量（避免除零）。
+ *
+ * @param a 向量
+ * @returns 单位向量（零向量输入返回零向量）
+ */
+export declare const normalize: (a: Vec3) => Vec3;
+/**
+ * `np.linspace(a, b, n)` —— 闭区间，含两端。
+ *
+ * @param a 起始值
+ * @param b 结束值
+ * @param n 点数
+ * @returns n 个等距点（n <= 1 时只含 a）
+ */
+export declare function linspace(a: number, b: number, n: number): number[];
+/**
+ * 弧度夹到 [0, 2π)。
+ *
+ * @param t 任意弧度角
+ * @returns 归一化后的弧度角
+ */
+export declare function normalizeAngle2pi(t: number): number;
+/** 3×3 矩阵（行主序）。 */
+export type Mat3 = number[][];
+/**
+ * `cq_gears.utils.rotation_matrix` 的逐字移植（Rodrigues，列向量约定）。
+ *
+ * @param axis  旋转轴（无需归一化，内部归一）
+ * @param alpha 旋转角（弧度）
+ * @returns 3×3 Rodrigues 旋转矩阵（行主序）
+ */
+export declare function rotationMatrix(axis: Vec3, alpha: number): Mat3;
+/**
+ * 行向量左乘：`pts @ m`（cq 的实际用法）。
+ *
+ * 结果第 j 分量 = Σᵢ pᵢ·m[i][j]，等价于 `mᵀ · p`。
+ *
+ * @param points 行向量点集
+ * @param m 3×3 矩阵
+ * @returns 变换后的点集
+ */
+export declare function applyRowMatrix(points: Vec3[], m: Mat3): Vec3[];
+/**
+ * 语义化包装：`applyRowMatrix(pts, rotationMatrix(axis, alpha))`。
+ *
+ * ⚠️ 因为 cq 用行向量左乘，实际旋转角是 **−alpha**。
+ *
+ * @param points 点集
+ * @param axis 旋转轴
+ * @param alpha 名义旋转角（弧度，实际为 −alpha）
+ * @returns 旋转后的点集
+ */
+export declare function rotateRows(points: Vec3[], axis: Vec3, alpha: number): Vec3[];
+/**
+ * 真正按 +alpha 旋转（标准列向量约定），用于 TS 侧需要正向旋转的场景。
+ *
+ * @param points 点集
+ * @param axis 旋转轴
+ * @param alpha 旋转角（弧度）
+ * @returns 旋转后的点集
+ */
+export declare function rotatePoints(points: Vec3[], axis: Vec3, alpha: number): Vec3[];
+/**
+ * `cq_gears.utils.sphere_to_cartesian` 的逐字移植：球坐标 → 笛卡尔。
+ *
+ * ⚠️ 注意极点角 `gamma` 是**从 +Z 轴量起**（`z = r·cos(gamma)`），
+ * 而不是数学习惯里从 XY 平面量起的仰角——BevelGear 的整套公式都建立在这个约定上。
+ *
+ * @param r 球半径
+ * @param gamma 极角（弧度，自 +Z 轴）
+ * @param theta 方位角（弧度）
+ * @returns 笛卡尔坐标
+ */
+export declare function sphereToCartesian(r: number, gamma: number, theta: number): Vec3;
+/**
+ * `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 declare function sInv(gamma0: number, gamma: number): number;
+/**
+ * `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 declare function sArc(sr: number, cGamma: number, cTheta: number, rDelta: number, start: number, end: number, n?: number): Vec3[];
+/**
+ * `cq_gears.utils.angle_between` 的移植：向量 OA 与 OB 的夹角。
+ *
+ * @param o 公共起点
+ * @param a 向量 OA 的终点
+ * @param b 向量 OB 的终点
+ * @returns 夹角（弧度）
+ */
+export declare function angleBetween(o: Vec3, a: Vec3, b: Vec3): number;
+/**
+ * `cq_gears.utils.circle3d_by3points` 的移植：三点定圆。
+ *
+ * @param a 第一点
+ * @param b 第二点
+ * @param c 第三点
+ * @returns `{ radius, center }`
+ */
+export declare function circle3dBy3points(a: Vec3, b: Vec3, c: Vec3): {
+    radius: number;
+    center: Vec3;
+};
+//# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

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