在 onshape-to-robot 中解析 Onshape 表达式:单位换算与变量求值的完整指南
在 onshape-to-robot 中解析 Onshape 表达式:单位换算与变量求值的完整指南
onshape-to-robot 是一款将 Onshape 装配体转换为 URDF、SDF、MuJoCo 机器人定义文件的开源工具。在 Onshape 模型里,关节限位、运动关联比值等参数常常不是固定数字,而是 Onshape 表达式(如 100 mm、#pitch * 2 deg)。onshape-to-robot 如何解析这些表达式,并把它们统一换算成机器人描述文件需要的国际单位制数值?本文结合核心模块 onshape_to_robot/expression.py,带你弄懂 Onshape 表达式解析、单位换算与变量求值背后的完整原理。
什么是 Onshape 表达式:为什么必须"解析"
在 Onshape 中输入尺寸或关节参数时,你可以直接写一个表达式,而不仅是一个纯数字。Onshape 表达式通常包含四类语法:
- 单位:
100 mm、2 in、90 deg - 函数:
sin(30 deg)、sqrt(4) - 变量引用:
#pitch、#radius(以#前缀引用 Onshape 变量) - 幂运算:
2 ^ 3
当 onshape-to-robot 通过 Onshape API 读取关节参数(例如关节限位、关联比值)时,拿到的是表达式字符串原文,而不是算好的数值。为了能生成正确的 URDF/SDF/MuJoCo 模型,工具必须自己把表达式求值出来,并把结果统一到米(m)和弧度(rad)。
这个工作由 ExpressionParser 类完成(onshape_to_robot/expression.py),它基于 Python 标准库 ast 模块实现,不执行任意代码,安全可控。
单位换算三步预处理:从 mm、deg 到 SI 单位
eval_expr 方法(onshape_to_robot/expression.py)在真正求值前,对表达式字符串做三处"字符串手术":
- 单位替换:遍历单位换算表,把"空格 + 单位名"替换为"乘以换算系数"。例如
100 mm变成100 * 0.001,90 deg变成90 * 0.017453... - 去掉变量前缀:删除所有
#,让#pitch变成普通变量名pitch - 幂符号归一化:把 Onshape 的
^替换成 Python 的**
内置的单位换算系数表(onshape_to_robot/expression.py)如下:
| Onshape 单位 | 换算方式 |
|---|---|
mm / millimeter |
× 0.001(米) |
cm / centimeter |
× 0.01(米) |
m / meter |
保持(米) |
in / inch |
× 0.0254(米) |
ft / foot |
× 0.3048(米) |
yd / yard |
× 0.9144(米) |
deg / degree |
× π/180(弧度) |
rad / radian |
保持(弧度) |
换算完成后,表达式里"一切都是米或弧度"——这正是 URDF、SDF 以及 MuJoCo 等仿真引擎所要求的单位制。
⚠️ 小提示:单位替换只匹配"空格 + 单位",所以书写时数字和单位之间必须留空格,这和 Onshape 本身的输入习惯一致。
变量求值原理:基于 AST 的安全求值
预处理之后,表达式就是一条合法的 Python 数学表达式。eval_ 方法(onshape_to_robot/expression.py)用 ast.parse 把它解析成抽象语法树(AST),然后递归遍历节点逐个求值——全程没有使用 Python 的 eval(),Onshape 表达式文本不可能执行任意代码:
- 数字节点(
ast.Constant):直接返回浮点数 - 二元运算(
ast.BinOp):从operators表查出对应运算,支持+ - * / ^、xor、mod及一元负号 - 函数调用(
ast.Call):从functions表查 numpy 函数,三角函数(sin/cos/tan及反三角)、双曲函数、sqrt、abs、log、log10、exp、max、min、ceil、floor、round一应俱全 - 变量(
ast.Name):查variables字典;pi、Pi、PI默认内置。若变量未找到且设置了懒加载回调,会先触发一次变量加载(见下一节) - 兜底:未知变量或未知函数抛
ValueError,无法识别的节点抛TypeError
变量从哪来:配置参数与 Onshape 变量的两级加载
variables 字典是所有可用名字的"仓库"。Assembly 类通过两条通道往里填充(onshape_to_robot/assembly.py):
- 配置参数(
load_configuration):把装配体数据中的fullConfiguration按;拆成key=value对,先把 URL 编码的空格+还原,再用eval_expr求值后写入variables - Onshape 变量(
load_variables):调用 Onshape API 拉取文档级变量。每个变量的值本身也是表达式(可以引用其他变量),因此同样通过eval_expr求值后入表
为了避免一次多余的 API 请求,load_variables 不在启动时立即执行,而是被挂成解析器的懒加载回调(onshape_to_robot/assembly.py):
self.expression_parser = ExpressionParser()
self.expression_parser.variables_lazy_loading = self.load_variables
当 eval_ 第一次遇到一个未知变量时,才真正回调 load_variables 拉取全部变量,随后把回调置空。之后的表达式求值就不会再发起请求——这是典型的"按需加载"优化。
实战落点:关节限位、运动关联与配置化参数
表达式求值的结果直接写进机器人定义,几个典型调用点:
- 关节限位:
get_limits(onshape_to_robot/assembly.py)通过read_parameter_value读取limitAxialZMin、limitZMax等参数并求值,再减去关节初始偏移量,得到相对零位置的上下限 - 运动关联:
find_relations(onshape_to_robot/assembly.py)读取BTMMateRelation的relationRatio参数,实现两个关节之间的齿轮式传动比 - 配置化参数:
read_parameter_value(onshape_to_robot/assembly.py)支持BTMParameterNullableQuantity(直接给表达式)和BTMParameterConfigured(按布尔/枚举配置选择不同表达式)两类参数,让同一模型在不同 Onshape 配置下导出不同的机器人
下图展示了 Onshape 中机器人装配体的建模约定:以 dof_ 前缀命名的 mate 会生成机器人关节,而这些关节上的参数值就可以是 Onshape 表达式:
frame_ 前缀的 mate 则用于定义坐标帧(frame),同样常见于需要表达式求值的参数场景:
运动关联 BTMMateRelation 是表达式用法的典型代表,其 relationRatio 就是一个需要解析的比值表达式:
动手验证:项目自带的表达式自检
expression.py 文件末尾内置了可以直接运行的自检示例(onshape_to_robot/expression.py):
ep = ExpressionParser()
ep.variables["x"] = 5
print(ep.eval_expr("(cos(5 deg)) mm + #x inch"))
print(ep.eval_expr("-sin(3/(2^2) deg)"))
第一行同时考察了单位换算(mm、in)、三角函数(角度输入)和变量引用(#x);第二行考察一元负号与幂运算。跑通这两行,说明表达式解析的核心链路是完好的。
总结
ExpressionParser是 onshape-to-robot 处理 Onshape 表达式的"守门人":三次字符串替换(单位换算、去#、^→**)+ AST 安全求值- 单位体系统一换算为米和弧度,可直接被 URDF、SDF、MuJoCo 使用
- 变量来自两级通道:Onshape 配置参数(加载配置时立即求值)与文档变量(懒加载回调,用到才拉取)
- 求值结果用于关节限位、运动关联比值、配置化参数等关键环节,保证导出的机器人模型数值正确
核心文件速查:
| 文件 | 职责 |
|---|---|
| onshape_to_robot/expression.py | 表达式解析器:单位换算、AST 求值、函数与变量表 |
| onshape_to_robot/assembly.py | 变量加载、关节限位/关联/配置化参数读取 |
| onshape_to_robot/onshape_api/onshape.py | Onshape REST API 客户端:鉴权与请求 |
| docs/source/design.rst | Onshape 端机器人建模约定说明 |



