SolidCraft 解析基准(Analytic Oracle):用闭式几何公式为 CAD 内核回归测试提供独立期望值
SolidCraft 解析基准(Analytic Oracle):用闭式几何公式为 CAD 内核回归测试提供独立期望值
本指南围绕 SolidCraft 仓库中 tools/oracle-analytic/README.md 所描述的"解析基准值"(analytic reference values)体系展开:它讲解如何用纯 Python 3 标准库、基于棱柱/圆柱/圆锥/球/圆环/旋转体(帕普斯定理)等闭式几何公式,为 tests/oracle/ 下的每个回归用例计算出可与 CAD 内核输出比对的理论期望值。读完本文,你将掌握三个解析脚本的运行方式、expected.json 的完整字段语义、背后用到的质量属性组合、格林定理与帕普斯定理等数学工具,以及钣金用例中 SolidCraft 特有折弯约定的解析建模方法,并理解它如何在 cargo xtask oracle 回归门禁中充当"独立裁判"。
什么是解析基准值:为什么需要"手算"的期望值
SolidCraft 是一个纯 Rust 的参数化 3D CAD 内核,它对每个特征(拉伸、旋转、扫描、抽壳、钣金折弯……)的布尔求交、曲面求值、网格化结果都可能是错的。要抓住这些错误,需要一个与内核实现完全无关的"答案来源"。
tools/oracle-analytic/ 提供的正是这样一套答案:对 tests/oracle/ 中那些形状存在闭式解的用例(棱柱、圆柱、圆锥与圆台、球与球冠、圆环与旋转体——后者用帕普斯定理、常量半径直棱边圆角、抽壳、上述元素的阵列,以及钣金展开件:平板加上作为环形扇区的折弯),用初等几何公式直接算出体积、表面积、质心与包围盒,写入用例目录下的 expected.json,并标记 "source": "analytic"。
这套工具遵循一条根本原则:所有数值都从第一性原理推导,绝不从任何 CAD 内核中测量得出(cases_basic.py 的模块注释明确写道 "Nothing here is measured from a CAD kernel"),tests/oracle/README.md 也在结尾声明 "No value here was measured in, or exported from, any commercial CAD product"。这正是它能作为独立裁判的关键前提。
三个脚本与运行方式
tools/oracle-analytic/ 下共有三个独立的 Python 3 脚本(仅使用标准库,无第三方依赖),按用例编号分段覆盖不同特征:
| 脚本 | 覆盖用例 | 核心特征主题 |
|---|---|---|
| cases_basic.py | 01–29(除 17/23/28 外的 26 个) | 盒子、孔、旋转体、草图求解拉伸 |
| cases_features.py | 32–66(共 19 个) | 圆角、抽壳、扫描、阵列、螺纹孔、散热片 |
| cases_sheet_metal.py | 67–76(共 10 个) | 钣金:基体法兰、边线法兰、托盘、折边、展开/折回 |
在仓库根目录执行任一脚本,它会把对应用例的 expected.json 重写为 "source": "analytic",并附带一个 method 字符串完整给出所用公式:
python3 tools/oracle-analytic/cases_basic.py # 01-29: boxes, holes, revolves, sketches
python3 tools/oracle-analytic/cases_features.py # 32-66: fillets, shells, sweeps, patterns
python3 tools/oracle-analytic/cases_sheet_metal.py # 67-76: sheet metal
cases_basic.py 还支持按需过滤单个用例:python3 tools/oracle-analytic/cases_basic.py 01-box 04-revolve-vase(无参数时运行全部)。脚本退出前会在终端打印每个用例的体积、面积与质心,例如 01-box: V=24000.0 A=5200.0 com=[20.0, 15.0, 10.0]。
运行时的写入位置由脚本内部基于 __file__ 定位:ROOT = <脚本目录>/../..,再拼接 tests/oracle/<case>/expected.json,因此必须从仓库根目录运行,脚本通过路径锚定保证不会写到错误位置。
生成结果与 FreeCAD 基准的关系
需要说明的是,expected.json 有两种 source:"analytic"(闭式几何手算)与 "freecad <version>"(用同一份 recipe.json 在独立内核 FreeCAD/OpenCASCADE 中重建,见 tools/freecad-oracle/README.md)。两者分工是:凡是存在闭式解的用例一律用解析脚本(占 76 个用例中的 55 个,见 docs/oracle.md),不存在闭式解的复杂特征(如自由曲面放样、变半径圆角)才交给 FreeCAD 生成。因此解析脚本是 oracle 体系的主力。
expected.json 字段语义
tests/oracle/README.md 给出了 expected.json 的完整规范。以解析脚本生成的 01-box 为例:
{
"source": "analytic",
"method": "box 40 x 30 x 20 from the origin: V = abc, A = 2(ab + bc + ca)",
"body_count": 1,
"volume_mm3": 24000.0,
"area_mm2": 5200.0,
"center_of_mass": [20.0, 15.0, 10.0],
"bbox": { "min": [0.0, 0.0, 0.0], "max": [40.0, 30.0, 20.0] },
"faces": 6
}
各字段含义:
| 字段 | 含义 |
|---|---|
source |
数值来源:"analytic"(闭式几何,method 给出公式)或 "freecad <version>" |
method |
数值如何得到:解析用例给出公式,FreeCAD 用例给出构造步骤 |
body_count |
实体(solid body)数量 |
volume_mm3、area_mm2 |
所有实体的总量 |
center_of_mass |
均匀密度下的体积加权质心 |
bbox |
所有实体的轴对齐包围盒 |
faces |
可选,仅在几何可确定面数时给出:一个面定义为单一曲面的最大光滑片(完整圆柱侧面算 1 个面;共面相邻算 1 个面) |
compare |
可选,将比较限制在这些键上(例如内核在圆角交汇处合法地生成不同补片时只比 ["volume_mm3", "area_mm2"]),note 说明原因 |
tolerance |
可选覆盖:rel(体积/面积,默认 1e-3)、abs_mm(质心与包围盒,默认 1e-3 × 包围盒对角线)、surface_mm(STL 曲面距离) |
note |
可选备注 |
解析脚本统一通过 result()/record()/write() 输出函数生成上述结构(cases_basic.py 的 result()、cases_features.py 的 write()、cases_sheet_metal.py 的 record()),三者字段一致。cases_sheet_metal.py 额外支持 known_failure 字段(详见下文钣金章节)。
解析计算的数学工具箱
三个脚本共享一套"从第一性原理"推导质量属性的方法,值得展开说明。
质量属性组合:MP 类
所有脚本的核心都是 MP 类——一个只记录体积与一阶矩(first moments)的小结构,支持带符号累加:+1 表示材料,-1 表示挖除的材料:
class MP:
"""Volume and first moments; add pieces with sign +1 (material) or -1 (removed)."""
def __init__(self):
self.v = 0.0
self.m = [0.0, 0.0, 0.0]
def add(self, v, c, sign=1.0):
self.v += sign * v
for i in range(3):
self.m[i] += sign * v * c[i]
return self
def com(self):
return [self.m[i] / self.v for i in range(3)]
这种"先体积、后一阶矩、最后相除得质心"的组合方式,让诸如 03-box-through-hole(盒子减圆柱)、09-shell(盒子减内腔)、13-combine-join(盒子并半圆柱加整圆柱)这类加减体用例只需要把各子体分别 add 进去即可,质心自动由矩量相除得到,无需逐块做几何布尔。
格林定理与高斯-勒让德求积
凡是由直线与圆弧围成的二维草图区域(面积、一阶矩、∫x·dA、∫x·y·dA),脚本统一用格林定理把面积分转化为沿边界的线积分:A = ∮ x dy、Sx = ∮ x²/2 dy、Sy = ∮ x y dy 等(cases_basic.py 的 region())。直线段的积分是精确的;圆弧段用48 点高斯-勒让德求积(cases_features.py 用 24 点,并先把弧按 ≤ π/36 的角度切成小段),对这类低阶三角多项式积分可以达到机器精度。脚本头注释明确说明这是 "exact to machine precision"。
对于三点定圆的圆弧,arc3(p0, pm, p1) 会解出圆心、半径,并自动选择经过中间点的那段扫掠方向;circle_seg(c, r) 则直接给出整圆。旋转体用例(如 04 花瓶)正是用这些工具把 (r, z) 剖面区域积分出来后套用帕普斯定理。
帕普斯定理与旋转体
对绕轴旋转生成的实体,脚本遵循帕普斯(Pappus)定理的两个结论:
- 体积 = 剖面面积 × 剖面形心绕轴旋转的路径长:
V = 2π · ∫x·dA(x 为半径方向坐标); - 表面积 = 边界弧长 × 其形心路径长:
A = 2π · ∮ x·ds。
cases_basic.py 中的 seg_rev_area() 与 cases_features.py 中的 revolve()/revolve_area() 正是这两个式子的直接实现。04 花瓶、48 滑轮、52 带圆角凸台的圆周阵列都用此法,method 字符串会明确写出 "Pappus/Green: V = 2 pi * int x dA, z_c = int x z dA / int x dA" 等完整公式。
常用闭式公式库
脚本内置了一批可直接调用的几何公式函数,它们构成了整套解析值的"零件库":
box_mp(lo, hi)/box_area(a, b, c):长方体体积/质心/表面积2(ab+bc+ca);frustum_v / frustum_zc / frustum_lat:圆台的体积πh/3(r1²+r1·r2+r2²)、形心高度h(r1²+2r1·r2+3r2²)/(4(r1²+r1·r2+r2²))、侧面积π(r1+r2)·√(h²+(r1−r2)²);sq_frustum(h, a0, a1):正方形圆台(四棱台)体积与 z 向形心——被 05 锥度拉伸、21 拔模两个用例复用;cap_v(R, h):球冠体积πh²(3R−h)/3——15 球体与立方体求交、40 球体穿出盒子底部等场景使用;spandrel_area(R)/spandrel_offset(R):圆角"余隙片"(边长 R 的方角减去四分之一圆盘)的面积R²(1−π/4)及其形心距角面的距离R(10−3π)/(3(4−π))——33 号圆角链用例的核心。
另外值得单独一提的是 Steiner 公式:07 号"所有棱边圆角"用例把 40×30×20 盒子所有 12 条棱倒 R3 圆角后的体积写为 V = abc + 2r(ab+bc+ca) + πr²(a+b+c) + 4/3πr³(内盒 34×24×14 被半径 r 的球"生长"),并指出 26 个面 = 6 平面 + 12 四分之一圆柱面 + 8 球面八分片。这是"常量半径圆角"在直棱边上的标准闭式表达。
基础用例(01–29):从盒子到求解后的草图
cases_basic.py 覆盖的 26 个用例展示了闭式推导的典型套路,method 字段完整记录公式。几个代表性例子:
- 01-box / 02-cylinder:最基础的长方体与圆柱,直接套用
V = abc、V = πr²h; - 03-box-through-hole:盒子减同心圆柱,质心因对称仍在盒子中心——这是"用对称性简化推导"的典型示范;
- 04-revolve-vase:由直线 + 三点圆弧剖面绕 Z 轴旋转 360° 的花瓶,用
arc3求弧圆心与半径、region()求矩量、帕普斯求体积与面积,甚至还要枚举弧的 x 极值来确定包围盒最大半径; - 05-taper-extrude / 21-draft:正锥度拉伸与拔模都归结为正方形圆台公式,
a1 = a0 + 2h·tan(θ)(锥度向外生长),侧面为 4 个梯形,斜高h/cos(θ); - 07-fillet-all-edges:Steiner 生长公式(见上);
- 08-chamfer:顶部 4 棱倒角 2 mm,拆成 40×30×18 下盒 + 截面
(36+2u)×(26+2u)的上部斜台,用辛普森公式对二次/三次多项式精确积分; - 09-shell:50×40×30 盒子向内抽壳 2 mm、顶面开口 = 盒子减
[2,48]×[2,38]×[2,30]内腔; - 10 / 11 / 12:矩形阵列孔、圆周阵列孔(6 重对称使质心保持在轴上)、镜像特征——都通过"对称性保持质心"这一几何论证大幅简化推导;
- 13/14/15-combine:并(盒子+半圆柱+整圆柱)、减(盒子−半球)、交(立方体∩球 R25,球减去 6 个互不重叠、高度 5 的球冠);
- 16-sweep:圆 r3 沿"直线 30 + 相切 R20 四分之一圆弧 + 直线 30"扫描,拆为两圆柱 + 四分之一圆环,圆环段用帕普斯公式
V = πr²Rθ,其形心距离弯轴ρ = (R²+r²/4)/R · sin(θ/2)/(θ/2); - 18-hole-features:沉头孔(counterbore)、锥形沉孔(countersink,90° 锥台)、盲孔(118° 钻尖锥体,尖高
r/tan59°,质心在锥尖上方 1/4 处)的完整解析; - 19/20:带约束的 L 形支架与腰形槽(obround,
A2 = 2rL + πr²); - 25/26/27-sketch:求解型草图的精华——三角形通过
t²−50t+475=0解出顶点(t = 25+√150);皮带轮轮廓是两圆的外公切线凸包减孔;梯形A2减两个 d6 孔。所有平面区域矩量均用格林定理在直线/圆弧边界上积分; - 29-two-sided-and-partial-revolve:块体减去 270° 部分旋转体,被切截面是环形扇区减去超出块体边界的圆弓形(
R²·acos(d/R) − d·√(R²−d²))。
特征用例(32–66):圆角、抽壳、扫描与阵列的解析建模
cases_features.py 的 19 个用例进一步展示了"把 CAD 特征翻译成解析几何"的高级技巧:
- 32-boss-plate-fillets:带 R3 内凹根部圆角 + R2 外凸顶部圆角的凸台被整体视为一个旋转体,直接在
(r,z)剖面上用帕普斯/格林求体积、z 矩与侧面积,圆角就是剖面上的四分之一圆弧; - 33-fillet-tangent-chain:腰形槽(R8,中心距 40)整体高度 10,顶部 R2 圆角、底部 1 mm 倒角。圆角余隙片与倒角三角形沿整圈轮廓"扫掠"(帕普斯:截面面积 × 形心路径长),圆角曲面按弧的形心偏移
R−2R/π计算——这是"扫描体"类特征的通用闭式解法; - 44 / 45-shell:两个抽壳用例明确编码了 SolidCraft 的交线连接(intersection-join)抽壳约定——内壁由外表面内偏 2 mm 后延伸至相交(sharp 内角),而非圆角连接。44 号 L 形支架的内腔就是 L 形缩小 2 mm 的带尖角多边形(内角点 (6,6)),
method还给出"若采用圆角连接"的对比值V 8368.5487, A 8768.5487; - 49-helical-sweep:真螺旋线圈(轴向 d4 截面绕 R20、螺距 8、3 圈)体积
V = 圈数·2πR·πa²(螺旋运动中只有旋转贡献体积),侧面积用周期梯形法则对√(r²+(p/2π)²(dr/ds)²)数值积分(4096 点,精度到舍入误差),质心 z = 螺距×圈数/2; - 50-sweep-tight-bend:r5 圆管沿"直线 20 + R5 四分之一弯 + 直线 20",弯径等于管径(内侧重合为线),弯段形心
(R²+r²/4)/R·sinc(π/4); - 52-circular-pattern-fillet:圆盘 r40 + 6 个带 R2 内凹根部圆角的凸台圆周阵列,每个凸台是独立旋转体在半径 28 处平移;
- 53-path-pattern:路径阵列孔——7 个 d6 通孔沿过三点 (100,15)/(60,45)/(20,15) 的圆弧(圆心 (60,10/3)、R=125/3)按弧长
17.875031等距分布,先解圆参数再逐个减去平移圆柱; - 55-tapped-hole-cosmetic:带 118° 钻尖的螺纹孔,装饰性螺纹不计几何;
- 62-heat-sink:60×50×5 底座 + 15 片 1.5×50×25 散热鳍(
x = 2+4k),各鳍与底座端面共面,note说明 66 个面的构成(底面、x=0/x=60 端面、y 向两面各与鳍端合并、16 条底座顶面条带、15×3 鳍面); - 64-sketch-tangent-arc-chain:由 4 段 R12 相切圆弧(弦长 20,弓高
12−√44)交替上下起伏构成的 80×20 顶部轮廓,用reverse()把顺时针边界翻转为逆时针后按格林定理求矩; - 66-sketch-linkage:R12 与 R8 两圆的外公切线凸包减 4 个孔(d12、d8 同心,d4 在 (30,±4)),对称性保证半径约束相等等价。
钣金用例(67–76):展开与折弯的闭式建模
cases_sheet_metal.py 是最具 SolidCraft 特色的部分:它把折弯钣金件从第一性原理建为"平板棱柱 + 环形扇区棱柱"的拼合体,并显式编码了 SolidCraft 在 crates/doc/src/sheet.rs 模块文档与 docs/book/src/guide/sheet-metal.md 中声明的钣金语义约定。
Steel (mm) 规则
脚本用 STEEL = dict(t=2.5, R=2.5, K=0.44, gap=2.5, hem_gap=0.01) 对应 SolidCraft 内置的 "Steel (mm)" 规则(源码见 sheet.rs 中 SheetRule::steel():厚度 2.5 mm、K 因子 0.44、折弯半径 = Thickness、角间隙 = Thickness、折边间隙 0.01 mm)。规则中的所有值都是表达式,Thickness 在其中代表规则自身厚度。
边线法兰(Edge Flange)约定
68 号用例(90° 边线法兰)的 method 与 note 精确记录了 SolidCraft 的语义:
- 高度基准 "outer faces":法兰高度从虚拟尖点(virtual sharp,两外表面延长相交处)沿法兰外表面量取;
- 折弯位置 "inside":虚拟尖点落在所选棱边的外角上;母板被回退量(setback)
(R+t)·tan(θ/2)修剪;本例(2.5+2.5)·tan45° = 5; - 折弯带是内半径 R、外半径 R+t 的环形扇区;平板腿长为
height − setback。
70 号用例把同一套语义推广到 45° 折弯:setback = (R+t)·tan22.5° = 2.071068,外顶角在 (−15·cos45°, 15·sin45°)。71 号自定义规则(t=1.5、R=3、K=0.33)与 76 号厚度变体(t=3,折弯半径 = Thickness = 3)验证了规则编辑会重建整个钣金实体。
角部与展开/折回约定
- 69-sm-tray(托盘):四条 90° 折弯在四个角相遇时,每个折弯止于被修剪的基角,每块壁板超过折弯端延伸
ext = (R+t) − (t + gap/√2) = 0.732233,使两壁板内角间距恰为规则间隙 gap——转角开放、无角部填充; - 75-sm-bracket-holes:后加的法兰会修剪其下方先前的折弯区,先前的折弯止于被修剪的基角,而先前壁板独自延伸——开放角部让位(open corner relief);该用例当前在
KNOWN_FAILURES = {"75-sm-bracket-holes": "#296"}中登记为已知失败,cargo xtask oracle会将其报告为 known failure,一旦修复即移除标记; - 72-sm-contour-flange(轮廓法兰):草图线代表背离材料一侧的板面(材料在行进方向右侧,material right of travel);朝材料弯的角以草图角为外虚拟尖点(setback
(R+t)·tan),另一侧为内虚拟尖点(setbackR·tan); - 73-sm-hem(折边):180° 折弯,内半径 =
hem_gap0.01 mm,长度从折边外表面量取,腿长L − (gap + t); - 74-sm-unfold-refold(展开/折回):折弯区平板宽度
BA = θ·(R + K·t)(K 因子中性层),折弯区内距离 s 处的点映射为角度s/(R+K·t);展开图上的槽(x 35..45、y −12..10)折回后移除基板 y 5..10、整个 y=0 折弯带及法兰自 z=5 至5 + (12 − (BA−5)) = 16.345133的部分。
所有钣金用例的 method 都标注了所用约定,并在 note 中指出源码位置(如 "sheet.rs add_flanges"、"sheet.rs close_corners")。
从解析值到回归门禁:cargo xtask oracle
解析值最终通过 cargo xtask oracle 变成可执行的回归测试。根据 xtask/src/main.rs 中的实现:
- 它重放 tests/oracle/ 下每个
recipe.json(SolidCraft 的命令脚本格式),用 SolidCraft 命令引擎重建零件(apps/solidcraft-cli/src/oracle.rs通过recipe::to_script转脚本后以Session::run_script执行),再用inspect.measure取实测结果; - 实测结果与
expected.json逐键比较:体积/面积默认相对容差REL_TOL = 1e-3(源码注释说明"我们的曲面网格化在 ~2e-4 以内"),质心与包围盒默认绝对容差1e-3 × 包围盒对角线,faces精确相等;用例可用tolerance覆盖; - 对于带
reference.stl的用例(当前为 FreeCAD 生成的 21 个),还会做对称曲面距离(Hausdorff,默认 0.05 mm)与两个网格主二阶矩(相对容差 2e-3)的比较; - 每个重建的零件还会导出为 STEP、校验并读回,验证体积/面积一致且无警告、面朝向正确;
- 全部通过后把结果写成 docs/oracle.md 汇总表。当前状态为 76/76 用例通过,55 个解析来源、21 个 FreeCAD 来源。
正是由于解析脚本覆盖了 55 个用例,整个 oracle 的"独立真相源"主体不依赖任何外部 CAD 软件——这是 SolidCraft 能在 CI 中随时验证内核几何正确性的根基。
铁律:绝不迁就内核输出
tools/oracle-analytic/README.md 在结尾立下一条方法论铁律:
Never change a value to match SolidCraft's output: if they disagree, find out which one is wrong.
(绝不为了匹配 SolidCraft 的输出而修改数值:若两者不一致,应查明是哪一方错了。)
这条规则的工程含义值得展开:解析脚本是"期望值生成器",而 SolidCraft 是"被测对象",两者身份必须严格隔离。当用例失败时,先要判断是推导公式错了(例如某处 SolidCraft 约定理解有误)、用例 recipe 与预期不符,还是内核真的存在几何缺陷——而不是简单地把 expected.json 改成与内核输出一致。这也是 tests/oracle/README.md 强调 "No value here was measured in, or exported from, any commercial CAD product"、freecad-oracle 用独立内核交叉验证的原因:只有当期望值来源与实现完全独立时,回归测试才有意义。
小结
SolidCraft 的解析基准体系是一套"教科书式"的测试方法论:用纯标准库 Python、以棱柱/圆柱/圆锥/球/圆环等闭式公式和帕普斯/格林定理为核心工具,为 55 个回归用例独立计算理论期望值;用 method 字符串把公式完整记录进 expected.json;再通过 cargo xtask oracle 与内核输出在既定容差内比对。对于涉及 SolidCraft 特有约定(抽壳尖角连接、边线法兰高度基准、K 因子展开、角部让位)的数值,它显式标注约定来源;并坚守"期望值绝不迁就实现"的底线。这套工具既可作为 CAD 内核开发者的回归测试范本,也可作为任何需要"独立可复现几何基准"的项目参考实现。