- @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
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),非手工 构造。