SolidCraft FreeCAD Oracle:用第二个内核生成几何参考值的实战指南
SolidCraft FreeCAD Oracle:用第二个内核生成几何参考值的实战指南
SolidCraft 是纯 Rust 实现的开源参数化 3D CAD 应用。为了让几何内核的数值结果可信,项目在 tests/oracle/ 下建立了一套参考测试(oracle):每个用例用项目自定义的 recipe.json 描述一个零件,再由 cargo xtask oracle 回放并与 expected.json 比对。其中一部分用例的期望值并非手算闭式解,而是由 FreeCAD(OpenCASCADE 内核)作为外部程序二次构建同一份 recipe.json 测得的——这套工具就存放在 tools/freecad-oracle/。读完本文,你将掌握这套工具的目录结构、build.py 支持的建模操作映射、run.sh 的用法、expected.json / reference.stl 的输出格式,以及如何在自己机器上安装 FreeCAD 并独立复现参考值。
为什么 SolidCraft 需要一个 FreeCAD 参考值生成器
SolidCraft 的几何内核(crates/kernel/、crates/engine/)是从零实现的自研内核。要验证它的正确性,仅靠自比对是不够的——需要一个独立的第三方几何内核作为参照系。
tools/freecad-oracle/README.md 明确指出:参考测试中一部分用例的期望值,是通过在**不同的内核(FreeCAD/OpenCASCADE)**里二次构建该用例自己的 recipe.json 计算出来的。这些用例的 expected.json 中带有 "source": "freecad <version>" 标记;而能用闭式公式手算的用例则标为 "source": "analytic",由 tools/oracle-analytic/ 中的纯 Python 脚本负责(见其 README:棱柱、圆柱、圆锥、球、环面、Pappus 旋转体、等半径倒角、壳、钣金弯边等)。
由此形成了参考值的双来源体系,记录在 tests/oracle/README.md:
- analytic:闭式几何,手算推导,
method给出公式; - freecad
:同一份 recipe.json由tools/freecad-oracle/用 FreeCAD 公共 Python 脚本 API 构建。
两者都无法覆盖的形状(例如倒角相交处的过渡面补丁,两个内核合法地构建出不同形状)则只比较体积和面积,并在 expected.json 中通过 compare 字段限定比较范围。当前状态(见 docs/oracle.md)为 76 / 76 用例全部通过,其中 55 个 analytic、21 个 freecad。
目录与文件
tools/freecad-oracle/ 下只有三个文件,职责分明:
| 文件 | 运行环境 | 职责 |
|---|---|---|
build.py |
FreeCAD 解释器(freecadcmd)内部 |
读取用例的 recipe.json,用 FreeCAD 的建模操作构建零件并测量 |
emit.py |
FreeCAD 解释器(纯 Python,不使用 FreeCAD API) | 打印测量结果,或将其写为 expected.json / reference.stl |
run.sh |
宿主机 shell | 入口点:解析参数、定位 freecadcmd、调度两个脚本 |
注意,run.sh 本身并不包含构建逻辑:它通过环境变量(ORACLE_CASE、ORACLE_OUT、ORACLE_STL)把用例目录和输出路径传给 freecadcmd -c "exec(open('.../build.py').read())",随后用同样的方式运行 emit.py,并过滤掉 FreeCAD 启动时的横幅输出。
核心工作流:recipe.json 如何在 FreeCAD 中重建
build.py 的头部注释写明了它的输入输出契约:
ORACLE_CASE 用例目录(含 recipe.json)
ORACLE_OUT 测量结果 JSON 的输出路径
ORACLE_STL 可选:二进制 STL 输出路径(reference.stl)
recipe.json 的格式与语义是 SolidCraft 自己的(见 apps/solidcraft-cli/src/recipe.rs,它把 recipe 翻译成 SolidCraft 命令脚本;实际测量回放在 apps/solidcraft-cli/src/oracle.rs)。build.py 的任务就是用 FreeCAD 的建模操作重新实现这份语义。以 tests/oracle/17-loft/recipe.json 为例,其 features 依次为:XY 平面上的 40×40 正方形草图(四条线 l1–l4 首尾引用共享端点)、construction_plane(以 offset: 40 偏移出 Plane40)、第二个草图(偏移平面上的圆)、最后 loft。该用例的 expected.json 中 method 为 FreeCAD (OpenCASCADE) build of recipe.json by tools/freecad-oracle/build.py: Part.makeLoft,即由 FreeCAD 的 Part.makeLoft 完成。
草图:约束求解与直接坐标两条路径
build.py 中的 Sketch 类根据 recipe 是否带 constraints / dimensions 选择两条路径:
- 无约束(如 17-loft 的草图):按记录的坐标直接构造几何。
point_refs语义(l1.end复用已有点)通过维护局部pts字典实现,支持 line、circle、三点圆弧、圆心-起点-扫掠圆弧、point、fitted_spline(3D 拟合点被解释为螺旋线采样点)。 - 有约束(如 tests/oracle/19-l-bracket-constrained/recipe.json 的"粗略画出 L 形、用 H/V 约束 + 4 个尺寸 + 角点固定于原点完全约束"):通过 FreeCAD 的
Sketcher模块真实求解。脚本把 recipe 的约束逐一映射为Sketcher.Constraint——coincident、horizontal/vertical、point_on_curve、midpoint、symmetric、tangent、equal、parallel、perpendicular、concentric、collinear、fix/block,以及 distance/length/offset/radius/diameter/angle 各类尺寸;重合点先经并查集(union-find)归并,再sk.solve()求解,失败则抛出RecipeError。求解出的世界坐标边缘随后按草图平面的 placement 变换到全局。
轮廓面(profile)的提取也值得一提:profile_face 首先尝试把 recipe 的 loops 闭合成 wire 并 Part.Face 成面;对"相切线段夹圆弧片段"这类无法整体成链的环,则退回 BOPTools.SplitAPI.booleanFragments 求曲线排布的最小区域,再按外边界使用的曲线集合匹配目标区域——保证了与 SolidCraft 的 profile 语义对齐。
建模操作映射表
Model.run() 按 features 顺序分派,construction_note() 会把实际使用的操作序列写进 method。支持的 op 及对应 FreeCAD 实现如下:
| recipe op | FreeCAD 实现 | 说明 |
|---|---|---|
extrude |
Part.Face.extrude |
支持 distance / symmetric / two_sides / through_all(按零件包围盒尺寸自动取贯穿长度)与 taper(用 makeOffset2D + makeLoft 构造斜度) |
revolve |
Part.Face.revolve |
轴可取草图边或显式 origin/dir,角度支持部分旋转 |
loft |
Part.makeLoft |
支持截面含点(Part.Vertex)、ruled 选项 |
sweep |
makePipeShell |
路径为草图曲线链;fitted 3D 样条路径被识别为螺旋线并拟合出 pitch / 半径 / 圈数后用 Part.makeHelix 重建(对应 tests/oracle/49-helical-sweep 一类的螺旋扫掠) |
hole |
圆柱/圆锥布尔剪除 | 支持 simple / drilled(118° 锥尖)/ counterbore / countersink;on_surface 处理孔心不在面上时的投影;positions_from sketch ... points ... 从草图点取孔位(见 hole() 与 56/57 号用例) |
fillet / chamfer |
makeFillet / makeChamfer |
边选择:用 recipe 记录的世界坐标点取最近边;边被分割时沿 G1 相切邻接生长(tangent_chain)补全;tangent_chain 字段开启全链倒角 |
shell |
Part.makeThickness |
按 recipe 的移除面与内侧厚度开壳 |
draft |
PartDesign::Draft |
两种反向都试建,再按"沿 pull 方向材料一侧的点应在体外"判定与 SolidCraft 语义相符的变体 |
combine |
fuse / cut / common |
join / cut / intersect 三种布尔 |
split_body |
BOPTools.SplitAPI.slice |
用构造平面切分实体 |
construction_plane |
平面登记 | offset 或显式 origin/normal,供后续特征引用 |
rectangular/circular/path_pattern、mirror |
变换后重放源特征 | 把每个源特征的刀具按变换矩阵移动后再次应用其操作(replay),而非调用 FreeCAD 的 Pattern 对象;mirror 对负行列式矩阵还原为关于平面的镜像(xform) |
build.py 中有一个细节值得注意:CASE_META 字典(当前为空)用于按用例追加 compare / tolerance / note / method_extra,注释说明目前已写入的所有用例都能在默认容差内与 SolidCraft 一致,因此没有放宽任何比较。
测量与输出格式
构建完成后 measure(shape) 用 FreeCAD 的 Shape.Volume、Shape.Area、CenterOfMass 和 optimalBoundingBox() 汇总:
body_count(len(shape.Solids))volume_mm3、area_mm2(对所有实体求和)center_of_mass(按体积加权)bbox(optimalBoundingBox()的 min/max)valid(所有实体isValid())
emit.py 在非写入模式下把结果打印为一行摘要,例如(格式见其源码):
<case>: bodies N V <volume> A <area> com [x, y, z] bbox [min]..[max] [notes...]
若结果含 error 则打印 ERROR 与(在 ORACLE_VERBOSE 下的)traceback。
生成 expected.json 与 reference.stl
run.sh 带 --write 时,emit.py 会把结果写成用例目录下的 expected.json。完整字段为:
| 字段 | 来源 | 含义 |
|---|---|---|
source |
"freecad " + App.Version() |
标记参考值内核及版本 |
method |
construction_note(recipe) |
实际构建操作序列(+ method_extra) |
body_count / volume_mm3 / area_mm2 / center_of_mass / bbox |
measure() |
期望测量值 |
compare / tolerance / note |
CASE_META |
按用例的比较约束与说明 |
note(追加) |
stl_skipped 时 |
说明未生成 STL 的原因 |
写入前的两道保护:
- 绝不覆盖 analytic 来源:若已存在
expected.json且其source以analytic开头,直接跳过并提示; - 无效形状不写:若
valid为 false,拒绝写入并返回失败。
reference.stl 是二进制 STL,由 write_stl() 用 MeshPart.meshFromShape 生成:线性挠度依次尝试 0.005 → 0.01 → 0.015 → 0.02 mm(角挠度固定 0.2),取第一个大小不超过约 400 KB 的结果;四种挠度都超限则跳过 STL 并在 note 中说明(如 tests/oracle/60-pipe-flange/expected.json 的 "No reference.stl: over 409600 bytes even at 0.02 mm deflection (11380 facets)")。emit.py 在写入成功时打印文件大小与所用挠度。
这份 STL 在 apps/solidcraft-cli/src/oracle.rs 的 reference_checks() 中被用来做表面几何核对:SolidCraft 自建部分以 0.01 mm 弦容差三角化,计算两个网格的双向(对称)Hausdorff 距离(max / mean / worst_at,默认阈值为 tolerance.surface_mm,缺省 0.05 mm),并比较两个网格的体积主二阶矩(惯量,INERTIA_REL = 2e-3)。docs/oracle.md 表格中的 Surface distance mm (max / mean) 一列即来源于此,例如 42-overlapping-patterns 为 0.030 / 0.0010。
命令行用法与 freecadcmd 查找
run.sh 的完整用法(摘自其 --help 输出区间与 README):
tools/freecad-oracle/run.sh tests/oracle/17-loft tests/oracle/42-overlapping-patterns # 仅打印
tools/freecad-oracle/run.sh --write tests/oracle/17-loft # 写 expected.json / reference.stl
- 不带
--write:每个用例打印一行测量摘要,适合快速目检; - 带
--write:写<case>/expected.json与<case>/reference.stl(受上文两道保护); - 参数可一次传多个用例目录;无用例时打印 usage 并以状态码 2 退出;
- 单个用例失败不影响其余用例,最终以非零状态码汇总。
freecadcmd 的查找顺序(run.sh 第 23–30 行):
- 环境变量
FREECADCMD; PATH上的freecadcmd;PATH上的FreeCADCmd;- 本目录下解包好的 AppImage:
squashfs-root/usr/bin/freecadcmd(该目录已被 gitignore)。
本地安装建议(README 原文要点):从发行版安装 FreeCAD 1.x,或解包 AppImage(./FreeCAD_*.AppImage --appimage-extract)并把 FREECADCMD 指向 squashfs-root/usr/bin/freecadcmd。CI(Debian/Ubuntu)只需 apt install freecad 后直接运行脚本——全程无需图形界面(脚本通过 freecadcmd -c 无头执行,</dev/null 输入、日志重定向到临时目录)。
版本敏感性与更新流程
README 特别提醒:参考值是使用 FreeCAD 1.1.4 生成的;其他 FreeCAD 版本可能在最后几位小数上有差异。因此:
- 只有当 recipe 变化时才重新生成参考值;
- 提交新值前,必须用
solidcraft-cli oracle与 SolidCraft 自己的结果核对(见 apps/solidcraft-cli/src/main.rs 的solidcraft-cli oracle <case-dir>...子命令); - 完整的回归入口是
cargo xtask oracle(实现在 xtask/src/main.rs):回放tests/oracle/下所有 recipe、逐项比对(体积/面积相对容差默认 1e-3、质心与包围盒绝对容差默认 1e-3 × 包围盒对角线、面数精确匹配、STL 表面距离、主二阶矩、STEP 导出后回读校验),并生成 docs/oracle.md。
tests/oracle/README.md 还记录了 expected.json 中 tolerance 的可选键:rel(体积/面积,默认 1e-3)、abs_mm(质心与 bbox,默认 1e-3 × 对角线)、surface_mm(STL 表面距离);以及 compare 数组可把比较限定到指定键。任何参考值都不得为迁就 SolidCraft 的输出而修改——若两者不一致,需要查明哪一方才是错的(tools/oracle-analytic/README.md 的原文原则,对 FreeCAD 侧同样适用)。
许可证边界:外部工具 ≠ 依赖
tools/freecad-oracle/README.md 用一节专门澄清这一点,这也是该目录存在的重要前提:
- FreeCAD 是以独立程序(
freecadcmd)运行的,通过其公开 Python 脚本 API(Part、PartDesign、Sketcher、MeshPart)执行build.py; - SolidCraft 不使用、不链接、不 vendor、不随包分发 FreeCAD 或 OpenCASCADE 的任何代码、库或二进制;本目录任何内容都不参与 SolidCraft 的构建;
- 因此 FreeCAD 的 LGPL 许可不适用于 SolidCraft 的代码;
- 这里的脚本是 SolidCraft 自己的,仅依据 FreeCAD 公开 API 文档编写,从未参考其源码;
- 产出的只有 SolidCraft 自己 recipe 的值:
expected.json中的 body count、体积、面积、质心、包围盒,以及reference.stl的三角化曲面。
小结:如何复现一份 FreeCAD 参考值
- 安装 FreeCAD 1.x(发行版包或解包 AppImage),确认
freecadcmd可执行(或设置FREECADCMD); - 对目标用例运行
tools/freecad-oracle/run.sh tests/oracle/<case>先行打印核对; - 需要落盘时加
--write,生成expected.json与reference.stl; - 运行
cargo xtask oracle全量回归,或solidcraft-cli oracle tests/oracle/<case>单用例核对,确认与 SolidCraft 在默认容差内一致; - 只在 recipe 变更时重新生成,并把新值与 SolidCraft 比对后再提交。
这套"第二内核交叉验证"机制,配合 tools/oracle-analytic/ 的闭式解,构成了 SolidCraft 参考测试的完整证据链:手算公式负责几何简单的情形,独立 CAD 内核负责无法闭式求解的情形,而 SolidCraft 的命令引擎、布尔内核与曲面网格化在两者之上接受逐项数值与表面距离的双重检验。