@faicad/fai-cq-warehouse 0.13.0

package/dist/thread.d.ts

@@ -0,0 +1,189 @@
+/**
+ * thread.ts — 螺纹五类移植（上游 `cq_warehouse/thread.py` 1003 行，方案 §8 W3）。
+ *
+ * 类映射（方案 §4.2）：`Thread` 基类 → `buildThread()`；具体类 → `isoThread()` /
+ * `acmeThread()` / `metricTrapezoidalThread()` / `plasticBottleThread()`（纯函数），
+ * 派生量 → `isoThreadDimensions()` / `acmeThreadSizes()` / `…`。
+ * 抽象基类 `TrapezoidalThread` 不单独导出（TS 用共享的 parse/轮廓数学承接）。
+ *
+ * ## 几何路线（W2/W3 probe 实测裁决）
+ *
+ * 上游三步：`Wire.makeHelix` / `parametricCurve` 造 4 条曲线 → `Face.makeRuledSurface`
+ * 造 4 条带 + 2 端帽 → `Shell.makeShell` + `Solid.makeSolid`。本包对应：
+ *
+ * | 上游 | 本包 | 依据 |
+ * |---|---|---|
+ * | `Wire.makeHelix` / `parametricCurve` | 解析采样点列（helix / fade 公式直写） | 内核 `makeHelixWire` 无 lefthand 参数；解析式可控且免内核往返 |
+ * | `Face.makeRuledSurface(a, b)` | `primitives.ruledFace(a, b)` = 逐行 `approximatePoints` + `loft(ruled)` | probe：`bsplineSurface(rows=2)` 是**逼近**且系统性外扩 Δ=3.70e-4（与采样密度无关），换路后 Δ=9.8e-7（紧 375×）——见 `kernel-conformance.test.ts` 陷阱回归 |
+ * | `Shell.makeShell` + `Solid.makeSolid` | `primitives.solidFromFaces(faces, 1e-3)` | probe：**makeSolid 朝向不可靠（实测 −8）→ 自动翻正**；容差 1e-3 对齐上游（旧注释「1e-6 不缝合」未复现，已订正） |
+ *
+ * ## 与上游一致的三处「怪癖」（照抄，不修）
+ *
+ * 1. `root_radius` 的 fudge `±0.001`，且 `tooth_height` 用 **fudge 后**的值
+ *    （`thread.py:98,105`）。
+ * 2. `square_off_ends` 对两端都是 `square` 时只生效**后一次**切割（每次以传入的
+ *    `cq_object` 为基而非累积的 `squared`，`thread.py:216-231`）——上游 bug，
+ *    为 STEP 等价必须复刻。
+ * 3. fade 的根曲线 z 位移是 `t` 相关的复合式（`thread.py:292-310`），不是常偏移。
+ *
+ * ## 未实现（W3 已知缺口）
+ *
+ * `end_finishes` 含 `"chamfer"` 时**显式抛错**：上游用 `BRepFilletAPI_MakeChamfer`
+ * 的**非对称** `chamfer(0.5·tooth_height, 0.75·tooth_height)` + `RadiusNthSelector`
+ * 选边，本内核只提供单距离 `chamfer` / `chamferDistAngle`；未取得 A 侧等价证据前
+ * 不做启发式实现（方案 §5.4 红线）。
+ */
+import type { BrepHandle } from '@faicad/faijs';
+/** 螺纹两端的收尾方式（thread.py:20 `end_finishes` 的取值域）。 */
+export type EndFinish = 'raw' | 'square' | 'fade' | 'chamfer';
+/** 旋向：右旋或左旋。 */
+export type Hand = 'right' | 'left';
+/** `Thread.__init__` 的入参（thread.py:68）——参数名逐字沿用上游 snake_case。 */
+export interface ThreadSpec {
+    apex_radius: number;
+    apex_width: number;
+    root_radius: number;
+    root_width: number;
+    pitch: number;
+    length: number;
+    apex_offset?: number;
+    hand?: Hand;
+    end_finishes?: [EndFinish, EndFinish];
+    /** 上游语义：True = 只算参数、不建几何（`wrapped` 置空）。 */
+    simple?: boolean;
+}
+/** `buildThread` 的结果：几何句柄（simple=true 时为 null）+ 派生量。 */
+export interface ThreadResult {
+    handle: BrepHandle | null;
+    external: boolean;
+    toothHeight: number;
+    /** fudge 之后的根半径（上游 `self.root_radius`）。 */
+    rootRadius: number;
+    apexRadius: number;
+    pitch: number;
+    length: number;
+    apexOffset: number;
+    apexWidth: number;
+    rootWidth: number;
+    hand: Hand;
+    endFinishes: [EndFinish, EndFinish];
+    simple: boolean;
+}
+/**
+ * Helical thread（`Thread` 基类）。`simple=true` 时只算参数、返回 `handle: null`
+ * （对齐上游把 `wrapped` 置空的语义）。
+ * @param spec - `Thread.__init__` 的入参（snake_case，逐字沿用上游）。
+ * @returns 派生尺寸 + 实体句柄（`simple=true` 时 `handle` 为 null）。
+ */
+export declare function buildThread(spec: ThreadSpec): ThreadResult;
+/** `IsoThread.__init__` 的入参（thread.py:471）——参数名逐字沿用上游 snake_case。 */
+export interface IsoThreadParams {
+    major_diameter: number;
+    pitch: number;
+    length: number;
+    external?: boolean;
+    hand?: Hand;
+    end_finishes?: [EndFinish, EndFinish];
+    simple?: boolean;
+}
+/**
+ * `IsoThread` 的派生尺寸（对应上游 `thread_angle` / `h_parameter` / `min_radius`）。
+ * @param p - 大径 / 螺距 / 内外螺纹三要素。
+ * @returns 锥角、h 参数、最小半径，以及内外螺纹各自的口顶/齿根半径与宽度。
+ */
+export declare function isoThreadDimensions(p: Pick<IsoThreadParams, 'major_diameter' | 'pitch' | 'external'>): {
+    threadAngle: number;
+    hParameter: number;
+    minRadius: number;
+    apexRadius: number;
+    apexWidth: number;
+    rootRadius: number;
+    rootWidth: number;
+};
+/**
+ * ISO 60° 螺纹（`IsoThread`）。默认 `end_finishes=("fade","square")`。
+ * @param p - 入参（同 {@link IsoThreadParams}）。
+ * @returns 螺纹实体与派生尺寸。
+ */
+export declare function isoThread(p: IsoThreadParams): ThreadResult;
+/** `TrapezoidalThread.__init__`（thread.py:583）的共享轮廓数学。
+ *  该基类在上游**没有** `simple` 参数（梯形螺纹恒建几何）。 */
+export interface TrapezoidalParams {
+    size: string;
+    length: number;
+    external?: boolean;
+    hand?: Hand;
+    end_finishes?: [EndFinish, EndFinish];
+}
+/** `AcmeThread.acme_pitch`（thread.py:672）——英寸规格 → 螺距（mm）。 */
+export declare const ACME_PITCH: Readonly<Record<string, number>>;
+/**
+ * `AcmeThread.sizes()`（thread.py:691）。
+ * @returns 全部 ACME 英寸规格（`ACME_PITCH` 的键，按上游插入序）。
+ */
+export declare function acmeThreadSizes(): string[];
+/**
+ * `AcmeThread.parse_size`（thread.py:696）→ (diameter mm, pitch mm)。
+ * @param size - 英寸规格字符串，如 `"1/2"`、`"1 1/4"`。
+ * @returns `[直径 mm, 螺距 mm]`。
+ */
+export declare function acmeThreadParseSize(size: string): [number, number];
+/**
+ * ACME 29° 梯形螺纹（`AcmeThread`）。默认 `end_finishes=("fade","fade")`。
+ * @param p - 入参（同 {@link TrapezoidalParams}）。
+ * @returns 螺纹实体与派生尺寸。
+ */
+export declare function acmeThread(p: TrapezoidalParams): ThreadResult;
+/** `MetricTrapezoidalThread.standard_sizes`（thread.py:746）——ISO 2904 公制规格表。 */
+export declare const METRIC_TRAPEZOIDAL_SIZES: readonly string[];
+/**
+ * `MetricTrapezoidalThread.sizes()`（thread.py:779）。
+ * @returns ISO 2904 公制规格表的副本（调用方改动不影响内部表）。
+ */
+export declare function metricTrapezoidalThreadSizes(): string[];
+/**
+ * `MetricTrapezoidalThread.parse_size`（thread.py:784）→ (diameter mm, pitch mm)。
+ * @param size - 公制规格字符串，形如 `"20x4"`。
+ * @returns `[直径 mm, 螺距 mm]`。
+ */
+export declare function metricTrapezoidalThreadParseSize(size: string): [number, number];
+/**
+ * ISO 2904 公制 30° 梯形螺纹（`MetricTrapezoidalThread`）。
+ * @param p - 入参（同 {@link TrapezoidalParams}）。
+ * @returns 螺纹实体与派生尺寸。
+ */
+export declare function metricTrapezoidalThread(p: TrapezoidalParams): ThreadResult;
+/** `PlasticBottleThread.__init__` 的入参（thread.py:926）。 */
+export interface PlasticBottleThreadParams {
+    size: string;
+    external?: boolean;
+    hand?: Hand;
+    /** 3D 打印过挤补偿：外部螺纹半径减、内部加（thread.py:813）。 */
+    manufacturingCompensation?: number;
+}
+/**
+ * `PlasticBottleThread` 的派生尺寸（覆盖上游全部属性）。
+ * @param p - 入参（规格串 + 内外螺纹 + 过挤补偿）。
+ * @returns 上游实例的全部派生属性（半径 / 宽度 / 螺距 / 长度 / 两段牙侧角）。
+ */
+export declare function plasticBottleThreadDimensions(p: PlasticBottleThreadParams): {
+    style: string;
+    diameter: number;
+    finish: number;
+    tpi: number;
+    apexRadius: number;
+    rootRadius: number;
+    apexWidth: number;
+    apexOffset: number;
+    pitch: number;
+    length: number;
+    threadAngles: [number, number];
+    rootWidth: number;
+};
+/**
+ * ASTM D2911 塑料瓶口螺纹（`PlasticBottleThread`），端部恒为 ("fade","fade")。
+ * @param p - 入参（规格串 + 内外螺纹 + 过挤补偿）。
+ * @returns 螺纹实体与派生尺寸。
+ */
+export declare function plasticBottleThread(p: PlasticBottleThreadParams): ThreadResult;
+//# sourceMappingURL=thread.d.ts.map

package/dist/thread.d.ts.map

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