从“看截图联调”到“真实地图联调”：我做了一个开源机器人巡检平台

前言

在机器人项目里，真正折磨人的，很多时候不是算法本身，而是联调过程。

明明是地图问题，却只能看静态截图。
明明是定位问题，却只能靠日志猜。
明明要验证导航链路，却只能拿假数据做页面。
明明现场最需要的是“能看、能调、能下发”的工具，最后却经常变成一个只能演示、不能实战的 Web Demo。

于是我做了这个项目：

Open Inspection Platform

一个面向四足机器人巡检场景的开源原型平台。
它不是单纯的点云浏览器，而是把：

• 地图可视化
• 机器人实时定位
• 初始位姿发布
• 任务点编辑
• 顺序导航下发
• 充电控制
• 导航状态查询
• 建图控制

真正串成一条可联调、可观察、可扩展的链路。

---

一、我们到底在被什么问题折磨？

做机器人巡检平台时，最常见的几个痛点几乎人人都遇到过。

1. 地图能力被“图片展示”替代

很多系统嘴上说“支持地图”，实际上只是：

• 一张栅格图片
• 一张截图
• 一个不能交互的平面视图

但机器人真正工作的地图，不是图片，而是：

• PCD 点云
• occ_grid.pgm + yaml
• 定位坐标系
• 真实地图边界
• 任务点与机器人姿态关系

如果前端看不到真实地图数据，那么很多问题根本无从判断。

2. 联调靠猜，不靠看

现场最常见的对话是这样的：

• “机器人是不是定位漂了？”
• “可能是地图不对齐。”
• “是不是初始位姿发错了？”
• “导航是不是没成功？”
• “你看看日志。”

问题在于，日志不是现场联调的第一观察面。

现场更需要的是：

• 机器人当前在哪
• 朝向是什么
• 当前加载的是哪张地图
• 初始位姿发到哪里了
• 导航状态是什么
• 建图服务是不是正常

如果这些都不能在一个界面里看到，联调效率就会非常低。

3. 前端和真实机器人链路是割裂的

不少页面做得很“漂亮”，但有一个致命问题：

它不接真实协议。

结果就是：

• 页面能演示，但不能联调
• 功能看起来很多，实际上不能下发
• 状态看起来齐全，实际上是 mock
• 真到现场，前端几乎要推倒重来

一个真正有价值的巡检平台，不应该只是“展示层”，而应该是：

地图、协议、状态、交互、任务编排都能打通的联调工具。

4. 地图、定位、导航、建图分散在多个工具里

很多现场联调为什么累？

因为你要在多个窗口来回切换：

• 一个工具看点云
• 一个工具看机器人状态
• 一个工具发初始化定位
• 一个工具发导航点
• 一个工具控制建图
• 一个终端查日志

信息是碎的，操作链路也是碎的。

而现场真正需要的是：

在一个界面内完成“看图 -> 定位 -> 发点 -> 看状态 -> 切图 -> 建图”整条流程。

---

二、所以我做了什么？

我做了一个开源项目：Open Inspection Platform

它的目标不是做一个“能展示的网页”，而是做一个：

面向机器人巡检和实机联调的开源前后端基础工程。

当前项目主要围绕云深处 M20 / M20 Pro 联调场景展开，支持：

• PCD 点云地图显示
• 2D occ_grid 栅格地图叠加
• 机器人实时位姿显示
• 初始位姿发布
• 地图切换
• 楼层分割
• 地图上交互式任务点编辑
• 顺序导航下发
• 充电控制
• 导航状态轮询
• 建图 UDP 网关控制

换句话说，它已经不是一个“点云查看器”，而是一个可以直接参与机器人联调流程的平台雏形。

---

三、这个项目解决了哪些核心痛点？

1. 让前端真正看到“真实地图”

项目支持直接加载 PCD 点云，并可切换不同地图资源。

不再是：

• 看截图
• 看图片
• 看离线导出结果

而是直接在浏览器里看真实地图数据。

同时支持：

• 点大小调节
• 圆点 / 方格点渲染
• XYZ 坐标轴显示
• 顶视角 / 前视角切换
• 栅格叠加显示

这让地图问题第一次可以在 Web 端被直观看清。

2. 让 3D 点云和 2D 栅格在同一界面联动

很多机器人项目里，3D 地图和 2D 栅格地图是割裂的：

• 点云在一个工具里
• 栅格在另一个工具里
• 坐标对不对只能靠猜

这个项目支持：

• 自动读取 occ_grid.yaml + occ_grid.pgm
• 按原点、分辨率、朝向把 2D 栅格叠加到点云场景中
• 切换地图时自动联动对应的 2D 栅格
• 如果是 sample 点云，则自动隐藏 2D 栅格

这样做的意义很直接：

你终于能同时看“真实 3D 地图”和“导航使用的 2D 地图”。

3. 让初始化定位不再是“盲发坐标”

现场一个很典型的问题是：

初始位姿到底发到哪了？
当前地图是不是和定位坐标一致？
yaw 角到底对没对？

所以我把初始化定位做成了更接近 RViz 使用习惯的方式：

• 在画布上按下并拖动
• 起点确定 x / y
• 拖动方向确定 yaw
• 最终按完整格式下发 x / y / z / yaw
• 其中 z 默认按 0

并且对错误码做了中文化处理，比如：

• 缺少必要字段
• 数据格式不支持
• 操作失败
• 定位异常

这会极大降低现场“协议返回了错误码，但没人知道啥意思”的沟通成本。

4. 让任务点编辑从“表单录坐标”变成“地图上直接打点”

过去很多导航平台的点位编辑方式都很反人类：

• 手动输入坐标
• 手动填 yaw
• 手动配参数
• 反复改、反复试

这个项目支持直接在地图上：

• 长按拖动添加任务点
• 拖动方向写入点位朝向
• 支持过渡点 / 任务点 / 充电点
• 自动生成顺序任务 payload
• 支持每个点独立配置步态、速度、运动方式、停避障、导航方式

这比纯表单式交互更贴近实际业务。

5. 让导航状态、定位状态、建图状态集中展示

过去现场最怕什么？

怕状态散在各处。

所以这个项目把多个关键运行态尽量合并到一个界面中：

• 机器人定位状态
• 当前位姿
• 导航任务状态
• 导航错误码
• 建图运行状态
• 地图切换状态
• 充电动作状态

你不需要再来回切工具看。

这对于实机联调特别重要，因为你最怕的是：

前端看不到、机器人在动、现场又没法快速判断到底是哪一段链路出了问题。

6. 让建图、切图、导航真正串起来

这个项目已经接入了 2200 建图 UDP 网关协议，支持：

• 开始建图
• 停止建图并保存
• 轮询建图状态
• 获取地图列表
• 切换导航地图

这意味着它不再只是“看已有地图”，而是在往完整流程走：

建图 -> 保存 -> 切换地图 -> 定位 -> 导航

这才是一个巡检平台应该具备的闭环能力。

---

四、项目当前具备哪些能力？

目前已经实现的核心能力包括：

• 加载和渲染 PCD 点云
• 自动发现样例点云和地图目录中的 PCD
• 支持 2D occ_grid 叠加与自动联动
• 地图切换与手动刷新
• 楼层分割与楼层预设
• 机器人实时位姿轮询
• 多机器人结构预留
• 初始位姿交互式发布
• 地图上任务点打点与朝向编辑
• 顺序导航任务下发
• 导航状态轮询与中文状态提示
• 自主充电控制
• 建图控制与地图切换
• Docker 一键部署

从“原型工具”的角度看，这已经具备比较完整的现场联调价值了。

---

五、技术上我怎么做的？

项目技术栈并不复杂，但强调“够直接、够好改、够能联调”。

主要使用：

• React + TypeScript + Vite
• Three.js
• Zustand
• Vite Middleware
• Docker + Docker Compose

为什么这样选？

因为这个项目更偏向：

• 快速落地
• 协议接入方便
• 前端结构清晰
• 容器化部署简单
• 后续好扩展

而不是一开始就追求复杂架构。

---

六、为什么我要把它开源？

因为这类工具的价值，不在于“页面长得多炫”，而在于：

• 它能不能帮助真实机器人项目提升效率
• 它能不能成为别人继续二开的基础
• 它能不能让更多机器人开发者少踩一点坑

很多机器人团队其实都缺一套这样的基础工程：

• 能直接看地图
• 能看状态
• 能发协议
• 能接机器人
• 能快速改
• 能现场部署

如果每个团队都从零开始重复造轮子，其实非常浪费时间。

所以我更希望把这个项目做成一个：

适合二次开发、适合协议扩展、适合实机联调的开源底座。

---

七、部署端也考虑了实用性

这个项目支持 Docker 一键部署：

git clone https://github.com/zuyichengkuaishisu/pcd_ws.git
cd open-inspection-platform
cp .env.example .env
./start-docker.sh

浏览器打开：

http://localhost:4174

这意味着部署端不需要额外装 Node、npm，现场环境会更干净。

针对 RK3588 这类 ARM 设备，前端也已经做了一轮偏机载部署的优化，包括：

• 自动限制 DPR
• 大点云自动抽样
• 交互限帧、空闲降频
• 自动放慢轮询频率

目的不是追求桌面端极致画质，而是尽量保证：

在狗子上也能更稳地跑起来。

---

八、这个项目最想表达的，不只是功能

如果只是功能列表，其实很多项目都能写得很好看。

但我更想表达的是一个态度：

• 地图系统就应该看真实地图，而不是看截图
• 巡检平台就应该把定位、导航、建图、充电串在一起
• 工程效率应该建立在真实链路打通之上
• 前端不该只是“假数据展示层”，而应该成为联调工具的一部分

很多问题不是“技术不会做”，而是方向经常从一开始就偏了。

而这个项目，本质上就是一次很直接的回答：

与其继续在低效流程里打转，不如自己把真实链路做通。

---

九、后续还会继续做什么？

接下来准备继续补这些能力：

• 接入取消导航
• 增加更多机器人基础状态
• 把多机器人从“接口预留”推进到“同场景多 marker 同显”
• 支持建图完成后自动刷新当前地图资源
• 持续补充部署文档、演示截图和录屏
• 优化机载端大点云加载体验

---

十、项目地址

如果你也在做：

• 四足机器人巡检
• 地图可视化
• 机器人导航联调
• 建图与定位前端工具
• Web 端机器人控制台

欢迎交流，也欢迎直接基于这个项目继续改。

项目名：

Open Inspection Platform

仓库地址：https://github.com/zuyichengkuaishisu/pcd_ws.git。

---

结语

机器人项目里最怕的，不是问题多，而是问题看不见。

看不见真实地图，看不见状态变化，看不见定位结果，看不见协议是否真正打通。
一旦“看不见”，团队就只能靠猜、靠截图、靠口头同步，效率会极低。

所以我做这个项目的目标很简单：

让地图、定位、导航、建图、充电这些原本割裂的东西，尽量在一个界面里变得可见、可操作、可联调。

如果它能帮你少走一点弯路，那这个项目就值了。