Files
make-cad/tools/research/cadqueryftc
NiJingzhe aac0fbb29d feat(cache): script-anchored part cache, keyword-form corpus, 2.1.2
- @scad.part/@scad.assemble anchor defaults to the builder script's own
  directory: cache + interface state land beside the source, standalone
  scripts run anywhere, and the pyproject.toml walk-up requirement is
  gone (explicit project_root still relocates the anchor)
- file_input() paths resolve relative to the anchor; in-repo examples
  rewritten to script-relative declarations
- HistCAD translator emits keyword-form sketch-family calls (corpus
  self-documentation), pinned by tests; booleans stay positional by
  *solids signature
- both translators emit project_root=Path(__file__).parent explicitly;
  examples/histcad_demo regenerated (STEP volume reconciliation held)
- FTC convention documents @scad.part parameters and the cache contract
- version stamps 2.1.2 + bilingual update notes
2026-09-10 00:11:28 +08:00
..

CadQuery → FTC 翻译工具集

把 CadQuery 程序(单个源文件或 BenchCAD parquet)翻译成本仓现行 FTC (Feature Tree Convention)Python 源码,可附带从几何快照恢复的推断约束。 结构与 tools/research/histjson 对齐:四件工具 + 责任墙——翻译器只翻译, 对不对、准不准的问题全部外置给验证器。

CadQuery 源码 ──(stage 1 真实执行+插桩)──▶ trace.json ──(stage 2 纯翻译)──▶ *.ftc.py
              .venv-cq (Python 3.11)      唯一握手物        仓库 .venv (3.10)

快速开始

环境一次性设置(cadquery 2.8 要求 Python ≥ 3.11;仓库官方 pin 仍是 3.10,不动):

uv venv .venv-cq --python 3.11
uv pip install --python .venv-cq/bin/python 'cadquery==2.8.0' pyarrow

翻译一个 CadQuery 文件(三步):

OUT=tools/research/cadqueryftc/out

# 1. 捕获 trace(用 cadquery 真实执行一次)
.venv-cq/bin/python tools/research/cadqueryftc/cadquery_trace.py \
    --input my_part.cq.py --stem my_part --out $OUT/traces

# 2. 翻译成 FTC 源码(纯 Python,无需 cadquery)
.venv/bin/python tools/research/cadqueryftc/cadquery_to_ftc.py \
    --trace $OUT/traces/my_part.trace.json --out $OUT/ftc

# 3. 验收对账(执行生成的 FTC,体积/包围盒 vs CadQuery 真值)
.venv/bin/python tools/research/cadqueryftc/cadquery_validate.py \
    --ftc-dir $OUT/ftc --traces-dir $OUT/traces

带约束恢复(第 2 步加 --constraints on,其余不变):

.venv/bin/python tools/research/cadqueryftc/cadquery_to_ftc.py \
    --trace $OUT/traces/my_part.trace.json --out $OUT/ftc --constraints on

BenchCAD parquet 批处理(stage 1 直接吃数据集;--stride 采样保复现):

.venv-cq/bin/python tools/research/cadqueryftc/cadquery_trace.py \
    --dataset /path/to/BenchCAD --out $OUT/traces --limit 200 --stride 7

产物清单

文件 产生于 内容
<stem>.trace.json stage 1 op 步骤(实参/平面标架/选择器/几何指纹)+ 真值体积与包围盒
<stem>.ftc.py stage 2 FTC 源码:@scad.part + # ---- feature: slug (role) ---- 块链
<stem>.meta.json stage 2 翻译状态、特征表、unsupported 备注、约束恢复报告
<stem>.sketches.json stage 2 逐 block 草图快照(平面标架 + 类型化实体局部坐标 + 闭合性)——来源无关的公共接口
validate.json stage 3 逐行验收:build 状态、体积/包围盒误差、质量分级

四件工具参考

工具 运行环境 职责
cadquery_trace.py .venv-cq(需真 cadquery) 捕获:--input 单文件 / --dataset parquet 批处理;--limit/--stride/--timeout
cadquery_to_ftc.py 仓库 .venv 翻译:--trace 单个 / --traces-dir 批量;--constraints on|off(默认 off)
cadquery_validate.py 仓库 .venv 对账:体积阈值 1e-3、包围盒阈值 1e-3(相对);分级 accepted / partial / rejected
cadquery_profile.py 仓库 .venv 摸底:op 直方图、选择器分布、unsupported op 覆盖(--traces-dir 或 --dataset)

工作原理

Stage 1(tracer,cqftc/tracer/) monkey-patch cq.Workplane 构造器与 ~37 个方法,记录每次调用的实参(Vector/Location 已序列化)、resolve 后的 平面标架(origin/normal/xDir)、选择器字符串,以及实际选中面/边的几何 指纹(type/center/normal/direction/length/area)——不记 CQ 拓扑索引 (不可移植),记几何特征,翻译期按几何重匹配。执行结束把 ground truth (体积+包围盒)写进 trace 头部。

Stage 2(replayer,cqftc/replay.py) 单遍状态机扫 trace:平面标架 跟踪、pending 剖面累积(moveTo→lineTo→threePointArc→close)、rarray/ polarArray/pushPoints 网格、嵌套工具链(cut(tool_workplane))整段切出 递归重放,逐块发射 FTC。草图捕获只有一个咽喉点(SketchScript.render 触发 sink)——任何发射路径(剖面、loft/taper 截面、沉孔锥、sweep 路径、 pattern 种子)构造即捕获。

输出契约要点

  • 块头 # ---- feature: <slug> (<role>[, profile=geometry][, path=geometry]) ----, 角色闭集 build|add|subtract|intersect|modify|pattern|annotate;slug 用 op 语义名(pocket-cut、through-cut、countersink-hole…),撞名才加 去重后缀(去重计数不是位置身份)。
  • 平面剖面走 sketch API(make_sketch_rsketch + add_*_rsketch + make_face_from_sketch_rface,局部坐标、点池去重、三点弧过外心),诚实 标注 profile=geometry(转录几何、约束未知——几何档第 2 条豁免)。 插值样条/螺旋线 sketch API 表达不了:走 make_interpolated_spline_rwire / make_helix_rwire,标 path=geometry。
  • 布尔一律列表形 cut_rsolid(_b, [tools]);多体走 histjson 同款 bodies 数据流(加=逐体 try-union 循环,减/交=列表推导,修改=守卫循环),末端 _merge_bodies。
  • fillet/chamfer/shell 的选择集从指纹合成 QL 谓词(geom.type + geom.center.*/geom.normal.* 容差带 + 基数 .take(n).exactly(n)); 生成源码里不存在免参拓扑枚举。
  • 通孔/穿透刀具长度由 trace 包围盒推导,不用魔法数 1000。
  • API 调用一律 keyword 实参(add_circle_rsketch(sketch=s, entity_id=…, center=…, radius=…))——语料即文档,参数名自带语义。唯一例外是布尔 *solids 变长实参(无键可取)。
  • 生成源码零自检(无 print/assert/体积校验);数字全字面量(trace 没有 命名参数,翻译器不发明参数名)。翻译完整性提示只出现在块尾注释与 *.meta.json(unsupported 列表——未知 op 也记 note,永不静默丢弃)。

约束恢复(--constraints on)

CadQuery 源码没有约束,默认翻译只发几何声明。--constraints on 额外从 几何快照恢复推断约束组,引擎在 cqftc/constraints.py,公理 P1–P5:

  • P2 无中生有禁止:候选全部是被快照实际满足的关系;
  • P3 恰好满 DOF:准入判据是生产 solver(SolveSpace)的 DOF 下降,引入 冗余的候选拒收——DOF 计数器会被秩亏系统欺骗(dof=0 但雅可比奇异);
  • P1 铆钉:扰动重建后必须收敛回快照坐标(盆地检验)是最终裁决;
  • P4 不美化数字:测量值原样发射;
  • P5 出处诚实:id 一律 inf<N>_<Kind> 前缀(推断,非数据集原生)。

候选按意图典型性分层贪心:锚定(fix) → 水平/竖直 → 平行/垂直 → 相切/等 半径/等长/同心 → 边长/半径 → 定向 dx → 相邻角 → 半格网净距。结果分级: riveted(dof 0 + 坐标复现 + 盆地通过)/ partial(部分约束、坐标仍复现) / none|error|timeout;约束行只在坐标复现时发射。相邻线端点是点引用, 重合是结构事实、不占约束名额(恒真 coincident 不发射,同 histjson 方言)。

复现基线(内置 fixture)

OUT=tools/research/cadqueryftc/out
for f in washer hexnut rarray_plate revolve_ring; do
  .venv-cq/bin/python tools/research/cadqueryftc/cadquery_trace.py \
    --input test/cadquery_traces/$f.cq.py --stem $f --out $OUT/traces
done
.venv/bin/python tools/research/cadqueryftc/cadquery_to_ftc.py \
  --traces-dir $OUT/traces --out $OUT/ftc --constraints on
.venv/bin/python tools/research/cadqueryftc/cadquery_validate.py \
  --ftc-dir $OUT/ftc --traces-dir $OUT/traces --report $OUT/validate.json

当前基线:体积误差 washer 1.6e-16 / rarray 0.0 / revolve 1.8e-16 / hexnut 2.2e-12(含 edges(">Y").chamfer 的 QL 选边对账);约束恢复全部 riveted。test/cadquery_traces/ 烘焙了真实捕获的 trace 与源程序(另含 pulley 双锥台 16 销孔案例),两个测试文件(26 用例)在不装 cadquery 的普通 CI 环境钉住格式契约 + 体积对账 + 语料 keyword 化 + 快照捕获完整性。

已知边界(meta 里如实记 note)

  • extrude(taper=) 仅圆剖面(锥台=两圆截面 loft,精确);非圆 taper 记 note 跳过。开口线剖面无法 sweep(SDK 需闭合面)。pattern 内仅 rect/circle/闭合 wire 剖面。
  • 60+ 点自由轮廓(如 63 点轮辐线)的约束恢复受逐层试探预算限制常落 timeout——诚实降级优于无界贪心;几何翻译不受影响。
  • CQ 相切/离散复合体:逐体 union 失败的部件留在 bodies 外(单流形 契约),体积对账如实暴露差值——翻译器不做几何修补(不 nudge、不吞)。
  • 源程序手写展开的阵列(如 16 个逐实例 cut)按数据原样翻译为 16 块; 特征级阵列识别/折叠(pattern detection)是尚未实现的已知能力缺口。
  • 静态 AST 翻译路径与打分/edit-bench(上游 PR 的 scoring/、Code-QA) 未移植:其自标 exploratory,不在四阶段规范内。

历史注记

  • tracer/(instrument、fingerprint、cq_runner、worker)与 replayer 状态机 骨架移植自上游 PR #30(feat/cadquery_converter,zhuxiaohai;NiJingzhe/ SimpleCADAPI 仓库);其发射层(SFTC 模板、@scad.model/scad.var 自检、 list-comprehension 选边)按现行 FTC 正典全部重写。
  • 测试 fixture 的 trace 由 cadquery 2.8.0 真实执行捕获(2026-09),非手工 构造。