在 onshape-to-robot 中解析 Onshape 表达式:单位换算与变量求值的完整指南

原创2026-11-09 21:22:241,707 阅读

在 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-to-robot 工具概览:Onshape 设计转换为 URDF、SDF、MuJoCo 机器人定义文件

什么是 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)在真正求值前,对表达式字符串做三处"字符串手术":

  1. 单位替换:遍历单位换算表,把"空格 + 单位名"替换为"乘以换算系数"。例如 100 mm 变成 100 * 0.001,90 deg 变成 90 * 0.017453...
  2. 去掉变量前缀:删除所有 #,让 #pitch 变成普通变量名 pitch
  3. 幂符号归一化:把 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):

  1. 配置参数(load_configuration):把装配体数据中的 fullConfiguration 按 ; 拆成 key=value 对,先把 URL 编码的空格 + 还原,再用 eval_expr 求值后写入 variables
  2. 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 表达式:

Onshape 机器人装配体设计:dof_ 前缀的关节生成机器人关节,其参数值可写成 Onshape 表达式

frame_ 前缀的 mate 则用于定义坐标帧(frame),同样常见于需要表达式求值的参数场景:

frame_ 前缀的 mate 生成坐标帧,关节限位参数以 Onshape 表达式形式给出

运动关联 BTMMateRelation 是表达式用法的典型代表,其 relationRatio 就是一个需要解析的比值表达式:

齿轮运动关联:BTMMateRelation 的 relationRatio 参数是 Onshape 表达式,用于解析传动比

动手验证:项目自带的表达式自检

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 端机器人建模约定说明
登录后查看全文
onshape-to-robot