ROS 导航算法双路对比学习平台

把全局搜索、DWB / TEB 局部控制和在线动态障碍变成可观察、可比较、可复现的教学实验

English · Windows 直接运行 · 发布说明 · 参与开发

这是一个独立运行的 Python + PyQt5 导航算法教学模拟器。它把全局搜索、DWB/TEB 局部控制、在线地图变化、安全停车和恢复过程放在同一张地图的左右双路实验中，便于逐帧观察和对比。

本项目不接入真实 ROS 2、OccupancyGrid、TF 或传感器话题，也不是 Nav2 官方插件的替代品。项目与 ROS / Open Robotics 无隶属、赞助或背书关系。

演示视频

A* 与 Dijkstra 搜索过程对比

A_D.mp4

DWB 与 TEB 动态重规划对比

DWB_TEB.mp4

项目一览

在线地图变化	双路算法教学	安全状态机	正式发布工程
障碍笔画原子提交，两侧从各自当前位置即时 A* 重规划	A* / Dijkstra / BFS / Greedy 与 DWB / TEB 同图对比	平滑制动、安全急停、等待路径和按原意图恢复	中英文 UI、Windows EXE/ZIP、Linux AppImage、SHA256 与自动发布

Important

只想在 Windows 上直接运行？ 请先看 WINDOWS.md。普通用户使用便携 EXE 时不需要 Python、PyQt5、虚拟环境或管理员权限。

快速入口

你的目标	第一步
直接体验软件	Windows 查看 WINDOWS.md；Linux 查看下方“发布包”
观察 DWB 与 TEB 动态避障	启动后选择任一动态场景，点击“一键自动演示”
从源码运行	跳转到 从源码运行
构建 Windows EXE	在项目根目录运行 build_windows.bat
修改代码或提交贡献	阅读 CONTRIBUTING.md

Windows 开箱即用

Tip

Windows 10/11 Intel/AMD 64 位用户使用便携版时，不需要安装 Python、PyQt5、Git 或虚拟环境。项目不是传统安装程序：下载单文件 EXE 后即可直接打开，关闭后不会常驻后台服务。

路线 A：直接运行发布版 EXE

1. 在项目的 GitHub Release 中下载：

   ROS-Navigation-Learning-Platform-v1.0.0-win-x86_64.exe
   

2. 可选但推荐：使用同一 Release 中的 SHA256SUMS-windows.txt 校验文件完整性。

3. 双击 EXE。首版未签名，如果 SmartScreen 显示“Windows 已保护你的电脑”或“未知发布者”，点击“更多信息”，核对文件名和 SHA256 后选择“仍要运行”。

4. 单文件版本首次启动会先解压 Qt 运行组件，可能需要数秒，请不要连续重复双击。

第一次打开后这样体验

1. 在“动态场景”中选择“前方突然封路”。
2. 点击“加载场景”。
3. 点击“一键自动演示”。
4. 观察左侧 DWB、右侧 TEB 在障碍突然出现后保留机器人历史轨迹，并分别从当前位置重规划。
5. 点击右上角 English 可以无重启切换语言。

Note

ZIP 目录包同样不需要 Python，但必须先“全部解压”，再运行解压目录中的 ROS-Navigation-Learning-Platform.exe，不要直接在压缩包预览窗口中启动。

源码包里没有 EXE？展开查看一键构建方法

在 Windows 项目根目录打开 CMD，运行：

build_windows.bat

脚本会自动识别现有的 64 位 Python 3.10-3.14，创建隔离构建环境并生成经过启动检查的 EXE、ZIP 和 SHA256：

dist\ROS-Navigation-Learning-Platform-v1.0.0-win-x86_64.exe
dist\ROS-Navigation-Learning-Platform-v1.0.0-win-x86_64.zip
dist\SHA256SUMS-windows.txt

构建电脑需要 Python；构建出来的 EXE 发给其他用户后不需要 Python。完整说明和错误排查见 WINDOWS.md。

源码包文档导航

Windows 用户请先阅读 WINDOWS.md：里面包含免 Python 的 EXE 使用方式、build_windows.bat 一键构建、GitHub Actions 云端构建、SmartScreen 提示、SHA256 校验，以及 py -3.12 找不到运行时的原因和解决方法。

源码包中的其他文档按用途整理如下：

你想了解的内容	应阅读的文档
Windows 直接运行、生成 EXE、构建失败排查	WINDOWS.md
项目功能、动态场景、算法实验和源码运行	当前 README.md
英文项目教程	README_EN.md
开发环境、测试方法和贡献要求	CONTRIBUTING.md
v1.0.0 发布内容与支持平台	RELEASE_NOTES.md
每个版本的功能变化	CHANGELOG.md
安全问题、未签名程序和漏洞报告	SECURITY.md
PyQt5、Qt、PyInstaller 等第三方许可	THIRD_PARTY_NOTICES.md
项目许可证全文	LICENSE
社区参与规范	CODE_OF_CONDUCT.md

Windows 开发者也可以直接运行源码包根目录的 build_windows.bat。构建成功后，单文件 EXE、ZIP 和 SHA256 文件会出现在 dist 目录。

v1.0.0 核心亮点

• 在线动态障碍：运行、暂停、等待和快速完成期间，新增或擦除障碍不会重置机器人。
• 双侧独立重规划：DWB 与 TEB 各自从当前机器人位置执行 A*，不共享固定起点缓存。
• 原子障碍笔画：拖动时只显示预览，松开后整笔一次提交并最多触发一次重规划。
• 整笔冲突拒绝：笔画只要与活动机器人足迹、起点或终点重叠，就会整体拒绝并在冲突位置红色警示。
• 安全停车与恢复：无路时按加速度约束制动；下一控制步存在碰撞风险时立即急停；通路恢复后按原运行意图继续。
• 三套动态场景：前方突然封路、可用通道切换、3.2 秒临时障碍。
• 一键自动演示：自动配置左侧 DWB、右侧 TEB，同步运行，在安全观察点触发事件。
• 教学指标：每侧显示重规划次数、上次耗时、剩余路径变化和累计等待路径时长。
• 中英文实时切换：无需重启，语言和窗口尺寸由 QSettings 记忆。
• 无蓝色工作台：炭灰、暖白、绿色、琥珀和珊瑚色承担全部视觉编码。

动态地图语义

鼠标拖动障碍
    -> 画布预览
    -> 松手形成 MapEdit 原子事件
    -> 足迹 / 起点 / 终点冲突检查
    -> 地图版本只增加一次
    -> 左右活动控制器分别从当前位姿执行 A*
    -> 有路：立即替换参考路径
    -> 无路：平滑制动或安全急停 -> waiting
    -> 擦除障碍恢复连通：运行侧自动继续，暂停侧保持暂停

活动 DWB/TEB 会保留机器人位姿、速度、控制步数和已行驶轨迹。就绪或已经完成的局部实验仍使用静态编辑语义并重置。修改起点或终点始终执行全局重置。

三套可复现实验

实验一：前方突然封路

1. 在“动态场景”选择“前方突然封路”，点击“加载场景”。
2. 选择左侧 DWB、右侧 TEB，点击“同时开始 / 继续”。
3. 两台机器人接近中间分隔墙前点击“触发事件”。
4. 观察原短路径消失、两侧独立路径改道，以及步数和橙色历史轨迹继续累计。

这个事件会用三格障碍切断共享短路，替代路线至少增加 8 个栅格步。

实验二：可用通道切换

1. 加载“可用通道切换”。
2. 启动 DWB 与 TEB 后触发事件。
3. 同一次原子更新会关闭原通道并开放备用通道。
4. 对比 DWB 速度窗口候选和 TEB 弹性带对新路径的不同跟踪方式。

实验三：临时障碍

1. 加载“临时障碍（3.2 s）”。
2. 手动启动并在需要的时刻触发，或直接点击“一键自动演示”。
3. 障碍出现后保持 3.2 秒仿真时间，然后自动消失。
4. 观察两次重规划计数、剩余路径变化和路径恢复信息。

自动演示会让较快的一侧在约 35% 路径进度处等待另一侧，保证事件位于双方至少 5 个路径单元之前；最多等待 8 秒仿真时间。

动态场景画廊

可用通道切换	临时障碍出现与恢复
关闭原通道并在同一原子事件中开放备用通道。	障碍保留 3.2 秒仿真时间，自动移除并触发第二次重规划。

其他算法

算法	可观察内容
BFS	单位代价栅格上的逐层搜索波纹
Dijkstra	无启发式的最优搜索前沿
A*	f = g + h 对搜索范围的压缩
Greedy	只使用 h 时的速度与最优性取舍
DWB	动态速度窗口、候选轨迹、碰撞淘汰、critic 评分和加速度约束
TEB	弹性带节点、时间间隔、障碍推力、曲率降速和连续控制量

混合全局/局部对比也支持动态地图。地图变化时，运行中的全局搜索从第 0 步重播，暂停中的搜索回到第 0 步并保持暂停，已完成结果立即重新计算并显示。

操作

• 左键拖动：绘制障碍；从已有障碍开始拖动则擦除。
• 右键：设置终点。
• 鼠标中键：设置起点。
• “开始本侧”：开始、暂停或继续当前面板。
• “快速完成”：批量执行局部控制，但仍可随时停止。
• “重置本侧”：只重置当前面板，不停止另一侧。
• “停止全部”：暂停所有正在运行的实验。

从源码运行

普通 Windows 用户应优先使用发布页中的便携 EXE，不需要安装 Python、PyQt5 或创建虚拟环境。Windows 构建与直接运行说明见 WINDOWS.md。

需要修改源码时，支持 Python 3.10-3.14，PyQt5 固定在兼容的 5.15.x 范围。

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python run_nav.py

Windows CMD：

python -m venv .venv
.venv\Scripts\activate.bat
python -m pip install -r requirements.txt
python run_nav.py

不需要指定 py -3.12。如果目的是生成可分发 EXE，直接运行项目根目录中的：

build_windows.bat

发布包

平台	产物
Windows 10/11 Intel/AMD 64 位	单文件便携 EXE、ZIP 目录包
Ubuntu 22.04 及兼容发行版 x86_64	AppImage
Ubuntu/Debian 兼容发行版 aarch64	原生 ARM64 AppImage

v1.0.0 不包含 macOS 或 Windows ARM64。首发产物不签名，因此 Windows SmartScreen 可能显示“未知发布者”。请在下载目录验证 SHA256：

Get-FileHash .\ROS-Navigation-Learning-Platform-v1.0.0-win-x86_64.exe -Algorithm SHA256

sha256sum ROS-Navigation-Learning-Platform-v1.0.0-linux-x86_64.AppImage

将结果与 Release 中对应的 SHA256SUMS-*.txt 比较。

测试

QT_QPA_PLATFORM=offscreen python -m unittest discover -s tests -v
python run_nav.py --smoke-test

测试覆盖自定义起点 A*、地图原子更新、足迹冲突拒绝、独立路径、动态指标、运行/暂停/等待/恢复、三套场景、速度和加速度边界、无碰撞、双语切换、两种窗口尺寸、无蓝色像素扫描及按钮点击。

项目结构

nav_app/
  models.py             数据类、地图版本和原子编辑
  global_planners.py    BFS / Dijkstra / A* / Greedy
  local_planners.py     教学版 DWB / TEB 与制动约束
  scenarios.py          三套 25x41 动态场景
  canvas.py             绘图、笔画预览和原子提交
  i18n.py               中英文资源
  main_window.py        双侧状态机、在线重规划和 UI
packaging/               Windows / AppImage 构建脚本
.github/workflows/       多版本测试和标签发布

开发约定、安全策略、第三方许可和版本记录分别见 CONTRIBUTING.md、SECURITY.md、THIRD_PARTY_NOTICES.md 和 CHANGELOG.md。