Webots R2020 版本变更记录详解：Mesh 节点、URDF 导出与坐标系重构的技术演进

• 科研
• 自动驾驶
• 物理引擎

本文基于 Webots 官方文档中的 R2020 版本变更记录（changelog-r2020.md），系统梳理 Webots R2020a、R2020a Revision 1、R2020b 及 R2020b Revision 1 四个发布节点的完整变更内容，并结合当前仓库中的参考文档与 C++ 源码，深入剖析其中影响最深远的几项技术演进：WorldInfo坐标系统重构、Mesh节点对外部 3D 文件的引入、wb_robot_get_urdfURDF 导出 API 的实现机制，以及 R2020b Revision 1 中对 URDF 导出与 Supervisor API 的一系列稳定性修复。读者读完后可以准确掌握 R2020 各版本的 API 行为差异，并在升级或迁移 Webots 项目时定位到对应的破坏性变更。

R2020 是 Webots 从数字版本号（Webots 8.6）切换为年份版本号（R2020）后的首个完整年度版本，也是 ROS 2 生态深度整合、外部 3D 资源导入能力成型的关键版本。以下按发布时间从早到晚依次展开。

版本发布时间线

完整的版本索引可在 changelog.md 中查看，其中按 R2025、R2023、R2022、R2021、R2020 等年份版本及 Webots 8/7/6/5/4 数字版本归档了全部历史变更记录。

Webots R2020a：Background 重构与 Supervisor 力学 API（2019-12-18）

R2020a 是 2020 年的第一个大版本，其变更按官方记录可分为新机器人、新样例、新功能、增强、依赖更新与清理六大类。

新机器人与新样例

• 新增多款 PAL Robotics 的 TIAGo 机器人：TIAGo Base、TIAGo Iron、TIAGo Steel、TIAGo Titanium 与 TIAGopp；
• 新增 Festo 的 Robotino 3 模型；
• 新增 Robotis 的 TurtleBot3 Burger 及其LDS-01激光雷达传感器；
• 新增complete_apartment公寓世界样例。

Background 节点重构

R2020a 对 Background 节点做了一次较为彻底的重构，官方记录列出了以下要点：

• 新增Background.luminosity字段，指定 Background 节点对光照的贡献度，该字段在TexturedBackground与TexturedBackgroundLight两个 PROTO 节点中开放；
• 为加快加载速度，移除了对等距柱状投影（equirectangular）纹理的支持；
• 移除Cubemap节点以提升一致性；
• 弃用非 HDR 背景；
• 恢复Background.*Url字段，且这些字段仅支持JPEG与PNG格式；
• 引入Background.*IrradianceUrl字段用于定义HDR辐照度贴图；
• 新增图像处理工具，辅助完成HDR格式与等距柱状投影的转换（对应仓库中的 scripts/image_tools/ 目录，包含equirectangular_to_cubemap.py、downscale_hdr.py等脚本）；
• 新增entrance_hallHDR 背景。

新增 Supervisor 力学与节点导入 API

R2020a 新增了若干 Supervisor API，使控制器可以在运行中直接对物理世界施加外力并动态导入/删除节点：

• 对 Solid 节点施加速度/力/力矩的三个函数：wb_supervisor_node_add_force、wb_supervisor_node_add_force_with_offset与wb_supervisor_node_add_torque；
• 对SFNode字段进行节点导入与移除的三个函数：wb_supervisor_field_remove_sf、wb_supervisor_field_import_sf_node与wb_supervisor_field_import_sf_node_from_string。

这些函数的完整签名与行为说明见 supervisor.md。值得注意的是，R2020a 还带来了一处破坏性 API 变更：wb_robot_set_mode()的参数类型由void *改为const char *，直接调用该函数的 C/C++ 控制器在升级后需要相应修改传参方式。

其他增强与 bug 修复

R2020a 的主要增强还包括：

• MultiSenseS21与SickLdMrsPROTO 的physics字段更名为enablePhysics；
• Sick LD MRS PROTO 支持400001、400102、400001S01、400102S01与800001S01五种型号；
• 改进wb_supervisor_simulation_reset，使其不再重启控制器；如确需重启，可单独调用wb_supervisor_node_restart_controller；
• ABB IRB 4600/40 PROTO 根节点由 Solid 改为 Robot，便于任意场景插入；
• 当Robot.synchronization字段为TRUE时，Webots 会等待外部控制器连接后再启动仿真；
• 场景树中节点名旁边显示设备名；
• 拆分 Webots 库与控制器库，避免与外部库冲突；
• E-puck2 新增 pi-puck 扩展、距离传感器噪声标定修复及网格与外观改进；
• 在线 3D 查看器webots.min.js改进：支持 Bloom 后处理效果、支持ImageTexture.filtering字段、控制台增加清屏按钮；
• robotbenchmark 世界整体画质提升（PBR 材质与 HDR 背景）；
• 新增 Webots 偏好设置清理脚本，参见 scripts/preferences_cleaner/README.md；
• Linux 平台新增 Python 3.8 支持。

修复方面涵盖了wb_supervisor_node_reset_physics()/wb_supervisor_simulation_reset_physics()对动态物体失效、Lidar 点云访问、PythonDisplay.imageNew()的列主序数据重排与内存泄漏、Nao.selfCollision脚部包围体重叠、红外距离传感器与 Plane 的碰撞检测、相机渲染顺序的确定性、MATLAB API 中缺失的WB_NODE_NORMAL类型与wb_robot_set_mode()等。

依赖方面，R2020a 将 Windows 与 macOS 上的 Qt 升级至 5.13.1；清理项中则彻底移除了原生 Qt 机器人窗口（robot window）的支持，包括其文档、默认 Makefile.include 中自动链接 Qt 库的逻辑、samples/howto/gui_tracker.wbt仿真及 OSM 导入机器人窗口。

Webots R2020a Revision 1：SUMO 接口与 HDR 深度图导出（2020-01-14）

R2020a Revision 1 是一个小幅修订版，变更集中在：

• 新增ScratchedPaint外观材质；
• SUMO 接口改进：优先使用系统中已安装的 SUMO 版本（如有），并兼容 SUMO 1.4；
• 工厂大厅环境样例改进；
• 修复wb_supervisor_node_add_force_with_offset()施力方向错误；
• 修复 ABB IRB 4600/40 的默认控制器；
• 修复 libController 依赖导致的外部控制器问题；
• 破坏性变更：wb_range_finder_save_image改为支持 HDR 格式输出，取代了原来的 TIFF 格式。该函数的当前行为说明见 rangefinder.md——函数返回 0 表示保存成功，且不应在wb_robot_step_begin与wb_robot_step_end之间调用；
• 清理项：OpenCV 不再随 Webots 一起分发，用户如需 OpenCV 需自行安装。

Webots R2020b：Mesh 节点、URDF 导出与 ENU 坐标系（2020-07-29）

R2020b 是 2020 年变更最密集的版本，官方发布说明见 Webots-2020-b-release.md。以下按新机器人、新功能、增强、依赖与修复逐项展开。

新机器人

• Boston Dynamics 的Spot四足机器人模型（PR #1553）；
• F&P Robotics 的P-Rob 3协作机械臂（PR #1657）；
• 由 Matt Denton 贡献的、受《星球大战》启发的 scout RX28 双足行走机器人演示（PR #1742，世界文件位于 projects/robots/micromagic/scout/worlds/scout.wbt）；
• Mercedes-Benz Sprinter 厢式货车模型（PR #1540）。

Mesh 节点：外部 3D 文件导入

R2020b 最重要的新节点是 Mesh。该节点表示从 3D 建模软件导出的外部 3D 文件形状，既可用作图元，也可作为碰撞检测基元（boundingObject）使用，字段定义如下：

Mesh { field MFString url [ ] field SFBool ccw TRUE field SFString name "" field SFInt32 materialIndex -1 }

从 mesh.md 的字段说明可以确认其行为细节：

• url字段定义 3D 文件，支持http:///https://远程地址或相对路径（搜索规则与 ImageTexture 相同），不推荐绝对路径；
• ccw指示面顶点是否按逆时针排列；
• name指定包含哪个子网格，空字符串表示全部包含，仅对 Collada 文件有效；
• materialIndex仅对 Collada 文件有效，取负值时表示包含文件中全部几何体。

配合 PR #1463，R2020b 支持导入的文件格式包括：3D Studio mesh（.3ds）、Blender（.blend）、Biovision Hierarchy（.bvh）、Collada（.dae）、Filmbox（.fbx）、STL（.stl）、Wavefront（.obj）与 X3D。若文件包含多个网格，将被合并为一个。R2020b 同时依赖此次升级的 Assimp 5.0.1（Linux 与 macOS）完成实际的多格式解析，这也是该版本依赖更新条目中"Upgraded to Assimp 5.0.1"与 Mesh 导入共用同一 PR（#1463）的原因。

wb_robot_get_urdf：URDF 导出 API

R2020b 为 Robot 节点新增了wb_robot_get_urdf函数（PR #1706），允许控制器将当前机器人模型导出为 URDF（ROS 生态中表示机器人模型的 XML 格式）。该函数在各语言控制器库中的声明为：

const char *wb_robot_get_urdf(const char *prefix);

class Robot: def getUrdf(self, prefix=''):

public class Robot { public String getUrdf(String prefix); }

prefix参数用于在多机器人系统中为导出的 link/joint 名称添加前缀以区分不同机器人。从 robot.md 的函数说明可知其导出规则：Webots 节点在尽可能合并时会被压缩为单个 URDF link 以简化模型；若希望某个 Webots 节点作为独立 URDF link 导出，只需为其定义name字段；URDF joint 以对应 Webots 关节上的 position sensor 命名。

从源码结构看，该功能的实现位于 src/webots/nodes/WbRobot.cpp：控制器请求触发mNeedToWriteUrdf标志后，Webots 在回包中写入C_ROBOT_URDF消息类型，内部通过WbWriter以modelName() + ".urdf"为文件名写出 URDF 头部、调用write(writer)递归遍历机器人子树写出 link/joint 数据、再写尾部，最后将序列化后的 URDF 字符串通过数据流回传给控制器。这一实现路径也解释了 R2020b Revision 1 中随后修复的两类问题——导出的 joint 缺少limit元素、axis元素错误（均由 PR #2062 修复）。

WorldInfo 坐标系统重构（ENU/NUE）

R2020b 中最具迁移影响力的破坏性变更是 WorldInfo 节点的重构：

• gravity字段由三维向量改为单一浮点值（重力加速度大小）；
• northDirection字段被coordinateSystem字段取代，可取"NUE"（Webots 传统坐标系）或"ENU"（ROS 坐标系，后成为默认值），用于定义重力与笛卡尔轴向。

结合当前仓库中的 worldinfo.md 参考文档，WorldInfo的完整字段现状为：

WorldInfo { SFString coordinateSystem "ENU" # {"ENU", "NUE", "EUN"} SFFloat gravity 9.81 # [0, inf) ... }

coordinateSystem当前实际支持三种取值："ENU"（East 沿 +X、North 沿 +Y、Up 沿 +Z，机器人与 ROS 中最通用的轴向约定，即 REP-0103 所规定的约定）、"NUE"（North 沿 +X、Up 沿 +Y、East 沿 +Z，Webots 传统约定）、"EUN"（East 沿 +X、Up 沿 +Y、North 沿 +Z）。切换坐标系会直接影响 Accelerometer、Altimeter、Compass、InertialUnit 与 GPS 等设备的返回值。R2020b 官方发布说明中明确指出，这一变更使 Webots 完整支持了 ROS 所采用的 ENU 轴向约定，是 ROS 2 集成（webots_ros2包，支持 Eloquent 与 Foxy）的基础设施。

Track 纹理动画自动适配时间步

R2020b 改进了 Track 的textureAnimation字段（SFVec2f textureAnimation 0 0）：纹理滚动速度现在会自动考虑世界basicTimeStep的取值，无需用户按时间步手动换算滚动速率；同时ConveyorBeltPROTO 移除了该字段（因为传送带速度已由自身参数定义）。

其他新功能与增强

R2020b 的功能与增强清单还包括：

• 新增两个获取 PROTO 内部字段的 Supervisor 函数：wb_supervisor_node_get_from_proto_def与wb_supervisor_node_get_proto_field（PR #1331）；
• 新增mjpegWeb 流媒体模式（PR #1352），相比 X3D 模式加载更快、图像保真度更高，代价是更高的带宽与服务端 CPU/GPU 占用；
• Webots 偏好设置中新增全局纹理最大过滤参数选项（PR #1851）；
• 新增 "Show Normals" 可选渲染模式（PR #1740）；
• macOS 与 Windows 新增 Python 3.8 支持；
• 上下文菜单新增 "Convert Root to Base Node(s)"，可将 PROTO 节点转为基础节点而不转换其嵌套 PROTO（PR #1309）；
• 新增OfficeChairPROTO 对象与ConveyorPlatform传送平台 PROTO 对象；
• TruckPROTO 新增wheelbase、kingPinDistance、mass字段；TruckTrailerPROTO 新增length、kingPinDistance、wheelAxles、mass字段，且其texture字段被替换为appearance字段；
• 新增七种外观材质：Marble、MetalStainlessSteelCable、Pavement、Plastic、Parquetry、PerforatedMetal与SolarCell；
• CarPROTO 的maxWheelVelocity字段被替换为表示整车最大速度的maxVelocity字段（PR #1552）；
• S/MFRotation字段支持四元数编辑，字段编辑器自旋框仅递增最后一位小数；
• ros_python与universal_robots_ros仿真改为使用外部控制器（extern controllers）而非内嵌 ROS 库；
• RobotisOp2、RobotisOp3、UR3e、UR5e、UR10e机器人新增supervisor字段；
• e-puck PROTO 新增 Gyro 节点；
• wb_supervisor_movie_is_ready与wb_supervisor_movie_failed在未调用wb_robot_step时也能返回更新值；
• 控制台三项改进：可按日志类型与来源过滤显示的上下文菜单、支持同时打开多个控制台、支持更多 ANSI 转义码并移除控制器名前缀；
• View > Scene Interactions 菜单新增禁用 3D 场景交互的选项；
• KUKA youBot 支持可变数量机械臂；ABBIrb4600-40PROTO 新增staticBase字段；
• Universal Robots UR3e/UR5e/UR10e 的 ROS 控制器新增--node-name参数以支持多机器人仿真；
• ROS 库从默认控制器路径中移除，避免与其他库冲突；
• 几何节点编辑器中显示三角形数量。

依赖更新方面，R2020b 宣布支持 Ubuntu 20.04 LTS，并将 Windows 与 Linux 上的 Qt 升级至 5.15.0、Linux 与 macOS 上的 Assimp 升级至 5.0.1。

R2020b 清理项（破坏性变更提示）

官方用加粗标记的两项清理对升级用户影响最大：

• Robot.controllerArgs的类型由SFString修正为MFString（PR #1718）——多控制器参数世界文件需按字符串数组书写；
• 移除无用的wb_robot_get_controller_arguments()函数并弃用wb_robot_get_controller_name()（PR #1718）。

另有：ChequeredParquetry、DarkParquetry、SlatePavement、SquarePavement、StonePavement五种外观材质被弃用；使用已弃用 Qt 机器人窗口的控制器不再自动获得 Qt 库路径，需改在runtime.ini中显式指定。

R2020b 主要 bug 修复

R2020b 的修复列表覆盖了渲染、物理、PROTO 机制与 API 正确性四大类，摘录关键项：

• 3D 视图中旋转手柄的可用性问题（PR #2019）；
• 三角网格的随机碰撞检测错误（PR #1994）；
• Accelerometer 测量值错误（PR #1947）；
• 程序化 PROTO 重新生成后控制器程序中节点/字段引用失效（PR #1922）；
• 设置触发父 PROTO 重新生成的字段为非法值、将此类字段中的 PROTO 转基础节点、删除此类字段中的节点时的崩溃（PR #1868）；
• 含 Display 设备的仿真重新加载或复位时的崩溃（PR #1865）；
• UnevenTerrain包围体与视觉形状不匹配问题，并移除了其textureScale字段（PR #1792）；
• DistanceSensor 探测无纹理形状时返回值错误（PR #1826）；
• 异步控制器下视频录制异常（PR #1927）；
• Windows 下从cmd.exe启动的 JPEG 纹理错误，通过重命名为webots-bin.exe并创建webotsw.exe/webots.exe两个启动器解决（PR #1532）；
• wb_supervisor_node_add_force()等函数未唤醒节点的问题（PR #1953）；
• wb_camera_save_image保存 JPEG 图像时的缺陷（PR #1285）；
• wb_supervisor_field_set_sf_rotation/wb_supervisor_field_set_mf_rotation对非归一化旋转的处理（PR #1459）；
• 零重力下 InertialUnit 节点崩溃（PR #1466）；
• MATLAB API 修复（PR #1378）及 Windows 上 MATLAB R2017b 的支持（PR #1462）。

Webots R2020b Revision 1：URDF 与 Supervisor API 稳定性修复（2020-09-01）

R2020b Revision 1 以增强与 bug 修复为主，其中几项直接完善了 R2020b 引入的新 API。

增强

• inverse_kinematics控制器改用 URDF 定义替代硬编码机器人模型（PR #2062），这是wb_robot_get_urdf上线后的第一个内部受益者——IK 求解器直接消费导出的 URDF 结构；
• macOS 支持 Homebrew 安装的 Python 3.7 与 3.8（PR #2079）；
• wb_robot_get_urdf的导出改进为包含 bounding object（PR #2113），使 URDF 中的 link 拥有与 Webots 一致的碰撞几何描述；
• 在 Shape 包含 PointSet 或 IndexedLineSet 几何体时使用 PBRAppearance 会给出警告（PR #2142），因为 PBR 材质不适用于这两类非面几何；
• 移除 ODE 的全部断言以加快仿真速度（PR #2141）；
• OSM importer 升级至 Python 3。

bug 修复

修复集中于 Supervisor API、PROTO 机制与 URDF 导出：

• 删除父节点后 Supervisor API 内部节点列表残留的问题（PR #2123）；
• 使用 Supervisor API 移除 Robot 节点本身的崩溃（PR #2006）；
• 外部 Robot 控制器退出后新控制器连接同一机器人的多种问题（PR #2152）；
• 选择含机械闭环的机器人时的崩溃（PR #2117）；
• 插入空 PointSet 节点的崩溃（PR #2182）；
• UnevenTerrain尺寸错误与 ElevationGrid 纹理映射问题（PR #2185）；
• wb_supervisor_node_get_orientation返回矩阵中残留的缩放因子（PR #2112）；ROS API 中单位矩阵到四元数的转换错误（PR #2112）；ROS 控制器发布 topic 的时间戳错误（PR #2127）；
• camera/recognition_objects topic 在 camera/image topic 无订阅者时不发布的问题（PR #2115）；
• PROTO 默认参数值中定义的 DEF 节点查找失败（PR #2107）；
• 从场景树修改触发 PROTO 重新生成的字段时部分 PROTO 节点崩溃（PR #2100）；嵌套 PROTO 节点的字段修改不生效（PR #2063）；
• Windows 上使用gd模块生成程序化 PROTO 节点的问题（PR #2070）；
• vision 样例仿真修复（PR #2143）；
• 流媒体服务器协议 bug 修复，并新增仿真服务器中 X3D/MJPEG 模式选择支持（PR #2077）；
• Linux 上 firejail 运行机器人控制器的问题（PR #2071）；
• HelicoidalRoadSegmentPROTO 的roadBorderWidth字段错误（PR #2099）；
• Camera、Lidar、RangeFinder 在异步控制器中的使用问题（PR #2138）；
• URDF 导出补全 joint 的limit元素并修正axis元素（PR #2062）；
• macOS 移除内置ros控制器，官方记录明确要求改用自定义 Python ROS 控制器实现；
• robotino3世界中 Robotino3Webcam 相机的near字段错误与 Lights 朝向错误（PR #2051）；
• automobile_window机器人窗口中多余显示的indicator_lever_motor电机（PR #2162）。

对升级与迁移的实际影响

从四个版本节点的变更密度与破坏性标记来看，基于 R2020 分支开发的项目在升级检查时应当重点关注以下事项：

1. 坐标系：WorldInfo中northDirection已不存在，世界文件应显式声明coordinateSystem（"ENU"/"NUE"/"EUN"），gravity为标量；ROS 集成项目应保持默认的 ENU；
2. URDF 导出：wb_robot_get_urdf从 R2020b 可用，R2020b Revision 1 起才包含 bounding object 且 joint 的limit/axis正确，对 URDF 精度敏感的工具链（RViz 显示、MoveIt 规划）建议在 R2020b Revision 1 上使用；
3. RangeFinder 图像保存：R2020a Revision 1 起wb_range_finder_save_image输出 HDR 而非 TIFF，依赖 TIFF 后处理的脚本需调整；
4. 控制器参数：Robot.controllerArgs自 R2020b 起为MFString数组；wb_robot_get_controller_arguments()已被移除；
5. 外部 3D 资源：Mesh 节点与文件导入（.obj/.dae/.stl/.fbx/.3ds/.blend/.bvh/.x3d）自 R2020b 可用，解析依赖 Assimp 5.0.1（Linux/macOS）；
6. 运行环境：R2020b 起支持 Ubuntu 20.04 LTS，Qt 5.15.0（Windows/Linux）与 Python 3.8（全平台），macOS 于 R2020b Revision 1 起支持 Homebrew 的 Python 3.7/3.8。

以上结论均可在当前仓库中交叉验证：变更明细见 docs/reference/changelog-r2020.md，两个年度版本的发布说明见 docs/blog/Webots-2020-a-release.md 与 docs/blog/Webots-2020-b-release.md，涉及的节点与 API 参考文档分别位于 worldinfo.md、mesh.md、robot.md、supervisor.md、track.md、rangefinder.md，URDF 导出的底层实现位于 src/webots/nodes/WbRobot.cpp。

• 科研
• 自动驾驶
• 物理引擎