1. 项目概述先把“地图”这件事想清楚做机器人导航、工业AGV调度或者室内巡检这类项目最绕不开的一个基础模块就是地图。那台设备能不能走对路、能不能避障、能不能在跨楼层之后还能把自己“找回来”全都压在“地图”这一层上。lingbot-map这个项目按照名字来理解就是一个面向自主移动设备的通用地图管理模块——它的核心任务不是帮某个机器人“一次性跑起来”而是把建图、存储、加载、坐标对齐、地图切换这些高频重复的活做成一套可以被复用的底层能力。说实话这类项目在业内并不少见。但绝大多数团队会把地图逻辑和导航逻辑耦合在一起地图数据散落在好几个类里坐标关系靠全局变量传递换一个底盘方案就要重新改一遍建图代码。短时间看确实跑得通一旦业务场景变多——比如同一台设备白天在单层厂房跑晚上要切到另一栋楼或者一台设备需要同时处理激光雷达和视觉定位两种输入源——这种“写死”的地图模块就成了最大的瓶颈。lingbot-map的定位恰恰是把地图这块松耦合出来让上层导航、调度、交互系统只关心“地图长什么样”而不必关心“地图是怎么来的、怎么存的、怎么对齐的”。适合什么样的人看这篇内容如果你正在做移动机器人导航相关项目或者准备接手一个包含地图功能的旧代码库再或者只是好奇机器人地图模块内部到底都做了哪些事这篇文章都值得往下看。我在这里讲的不是某个框架的官方文档翻译而是把地图模块从设计到落地过程中那些文档里很少写清楚的取舍、细节和实在问题完整拆开讲一遍。看完之后你可以直接带着这套思路去审视自己的项目看看哪些设计可以借鉴、哪些坑可以提前绕开。2. 模块架构与核心设计思路为什么地图模块值得单独立项2.1 被低估的地图模块它比你想象的更复杂先说一个很多初次接触机器人项目的人常犯的误解觉得地图模块了不起就是拿到激光扫描数据把它们拼成一张黑白图然后给路径规划算法当底层输入。真把一个地图模块拆到系统里跑起来你会发现它至少要管好几摊事。第一地图数据本身有生命周期。它要经历构建、保存、加载、更新、淘汰这几个阶段。建图阶段产生的地图是临时产物要经过拼接、清理、标注之后才能成为“正式地图”正式地图要落盘下次启动要能加载回来地图上的元素不是永远不变的比如某个区域后来加了货架那局部地图就得更新。如果你没有把地图生命周期这个状态机设计好很容易出现“地图文件在磁盘上但程序启动时找不到”“地图更新了但导航还在用旧数据”这种莫名其妙的问题。第二地图必须跟一堆坐标系统打交道。激光雷达坐标系、底盘坐标系、里程计坐标系、全局地图坐标系这四个坐标系的关系如果不理清楚哪怕地图画得再准设备一开动就会往错误方向跑。最典型的现象是建图的时候看起来一切正常一旦把地图重新加载机器人原地打转那是因为地图的初始姿态没有跟当前坐标对齐。地图模块要负责维护坐标系变换关系并且要提供一个明确的“对齐”接口而不是让业务代码到处手动去算TF。第三地图模块要应对不同的底盘和传感器组合。有的设备用的是一线激光雷达有的是多线有的是纯视觉有的是视觉加激光融合。不同传感器出来的地图数据格式、噪声水平、更新频率都不同。地图模块最好对上层暴露统一接口底层支持多种数据源适配否则每换一种传感器就要把上层代码重新改一遍。从我熟悉的情况来看很多项目是把上面这些逻辑拆散了塞进导航模块、建图模块和UI模块里表面上看类是解耦的实际上数据流是剪不断理还乱。lingbot-map的做法是把它们全部收敛到一个模块内对外只暴露少数几个控制接口和数据回调。这个思路值得借鉴的核心在于地图模块不是“画图工具”而是整个机器人系统中负责“空间记忆”的基础设施。2.2 模块内部结构四层分工各管一摊按照lingbot-map的设计思路一个可维护的地图模块内部应该至少包含四个层次。我在这里用工程上常见的分层方式来说对应到代码里就是四个相对独立的包或者目录。第一层是数据表示层。负责定义地图的数据结构——栅格地图用什么类型存每个栅格的值表示什么含义障碍物信息怎么编码地图的元数据分辨率、原点坐标、尺寸、创建时间放哪里。这一层是模块的地基数据结构定义得不好后面所有逻辑都要跟着别扭。举个具体例子如果地图用二维数组表示访问地图上某点的时候直接按下标索引速度很快但当地图特别大、需要多楼层管理时内存占用就会很吓人。如果改成稀疏存储却又要频繁做全图遍历性能又回不来。我见过不少项目在地图数据结构上反复改改一次上层代码就全部重构一次归根结底是这一层没想清楚。第二层是数据管理层。负责地图的构建、保存、加载、清理。说白了就是“地图对象的生命周期管理”。比如构建一张新地图需要哪些输入、地图保存成什么文件格式、加载时要不要校验文件完整性、更新局部地图时用哪种策略。这一层还要处理并发问题地图正在被路径规划线程读取时恰好建图线程往地图里写入新的障碍物数据如果处理不好轻则数据不一致重则程序崩溃。第三层是坐标与变换层。负责维护坐标系树、提供坐标变换接口。最常见的做法是使用TF树来管理不同坐标系之间的关系。地图模块会提供一个基础坐标系一般叫map所有其他坐标系都通过变换链路关联到它。这一层的核心接口包括把传感器坐标系下的点转换到地图坐标系、把地图坐标系下的路径点转换到机器人坐标系、查询任意两个坐标系之间的变换关系。还有一点容易被忽略坐标变换是有时间戳语义的。地图模块需要支持“历史时刻的坐标变换查询”即我在t1时刻获得某个点云数据当时机器人在地图上的位姿是P1建图完成之后要把这些历史数据重新对齐这就不能只存当前时刻的变换关系。第四层是接口与适配层。向外部导航模块、调度模块、UI模块提供稳定API同时屏蔽具体传感器和算法库的差异。比如接收激光数据的部分内部用的是某激光SLAM库的格式但对外发布的地图更新事件格式是模块自己定义的。这样将来换SLAM库的时候只需要改适配层代码外部完全无感。这四层结构看起来很简单但我在实际项目中吃过亏之后才明白它最大的价值不是“分层”本身而是每一层都有明确的职责边界。调试的时候只要根据问题现象就能快速定位是数据表示的问题、生命周期的问题、坐标的问题还是适配问题不用全项目翻代码。2.3 数据流设计:一张图看懂信息走向在真实系统中地图模块的数据流大致是这样的传感器数据比如2D激光雷达扫描进入模块后首先经过适配层被转换成内部统一的“扫描帧”格式。然后建图线程或者SLAM算法库利用这些扫描帧和里程计数据持续估计机器人在地图中的位姿并把新的障碍物信息融合进地图数据结构。这一步就是“建图”。当地图构建完成或者构建到一定阶段数据管理层负责把内存中的地图快照序列化到磁盘。序列化格式要包含地图数据主体、分辨率、原点、时间戳、地图编号等元数据。启动加载时模块读取磁盘文件反序列化恢复地图对象并通过坐标变换层检查地图的初始姿态是否和当前设备姿态兼容——这个检查极其重要我后面会专门讲。运行时上层导航模块通常会向地图模块发起“获取地图”请求。地图模块可以返回两种数据一种是完整的栅格地图图片用于可视化、路径规划前端处理另一种是“代价地图”数据即在原始地图上叠加了障碍物膨胀、动态障碍物等信息的衍生地图。这两种地图之间的关系也是地图模块中容易搞乱的点。原始地图是静态的、可信的代价地图是实时的、可变的。地图模块最好把这两种数据的更新职责分开避免代价地图的临时变化比如有人从激光雷达前走过污染到原始地图数据。最后设备在运行过程中如果发现某个区域有新的障碍物比如原本空旷的地方多了一个箱子地图模块需要有一套局部更新策略是通过新扫描数据直接修改原始地图还是先写入缓存、等确认后才合并进原始地图工程上我更推荐“先缓存、后合并”因为传感器单帧噪声很大直接写进地图会把噪声也固化进去时间久了地图质量会明显下降。2.4 为什么选择栅格地图作为基础表达很多项目在选地图表达方式时会在栅格地图、拓扑地图、特征点地图之间犹豫。lingbot-map这类做导航基础模块的项目最终往往都会落在栅格地图上原因很实际。第一栅格地图跟激光雷达数据天然兼容。激光扫描得到的是距离信息转成栅格占用概率非常直接——测到的距离内的区域标记为“空闲”距离点附近标记为“占用”没测到的地方标记为“未知”。后面做路径规划时A*算法、Dijkstra算法直接在一个二维代价栅格上跑就行不需要复杂几何计算。第二栅格地图便于多源融合。视觉感知出来的障碍物、超声波传感器数据、深度相机数据都可以通过坐标变换映射到同一张栅格图上以“更新概率”的方式融合起来。这是拓扑地图很难做到的。第三栅格地图可视化非常直观。直接转成PNG图片就能在Web界面、桌面客户端甚至调试工具里显示。这对于项目调试和现场交付都有很大价值。用户不会关心你的拓扑节点和边是怎么建的他只看得到“地图画得像不像”。但栅格地图也有一个显著缺点数据量大。一张边长100米的方形地图如果分辨率是5厘米/像素就是2000×2000个栅格每个栅格至少1字节那就是4MB左右。听起来不大但如果做多楼层管理、一张楼宇有10层地图的总内存就是40MB还要叠加膨胀地图、代价地图、标记层很容易冲到一两百MB。这在嵌入式设备上就是一个需要认真权衡的点。我记得之前在某一次项目评审里有同事提议把全楼地图一次性加载进内存理由是看起来“才几十MB”但实际跑起来之后由于地图要参加频繁的坐标变换查询和碰撞检测内存带宽占用把整机性能拖了不少。所以地图的分块加载、按需卸载、多楼层切换不是一个“锦上添花”的需求而是一个工程上绕不开的问题。3. 实操拆解lingbot-map的部署、配置与核心实现3.1 环境准备与工程移植先把骨架搭起来拿到lingbot-map这样的模块第一步要做的不是急着看代码而是先确认它的运行环境和依赖关系。按照通常这类项目的工程实践它有这么几类依赖需要提前准备好基础库涉及图像处理、矩阵运算、文件读写相关的通用库常见的有OpenCV、Eigen等用于处理栅格图像变换和坐标计算。坐标变换库一般会依赖TF库来管理坐标系树负责map、odom、base_link、laser_frame之间的变换关系。坐标变换库提供查询接口也是全局时钟同步的重要一环。建图算法库通常是SLAM算法库负责接收激光数据和里程计数据输出机器人位姿和地图。地图模块会与它深度集成但通过适配层隔开。序列化存储地图落盘和加载时一般会使用JSON元数据加二进制数据栅格主体的混合方案。在把自己的项目接入lingbot-map之前先跑通它自带的最小示例。这个示例通常会包含一个简单的仿真环境用一段预先录制好的激光扫描数据离线构建一张小地图然后保存到磁盘再重新加载回来。这个过程能让你快速确认整个模块的依赖是否安装完整、坐标系是否默认配置正确、地图文件格式是否符合预期。很多人在这一步跳过直接改代码结果后面查了半天发现是环境没配对得不偿失。工程移植上有一个建议不要直接把这个地图模块的源码整个塞进你的主项目。更好的做法是先把它编译成独立的库对外提供C或Python绑定接口主项目只依赖库和头文件。这样你的主项目构建系统不会被一堆地图模块的内部依赖拖累将来地图模块升级版本时只要保持接口兼容主项目完全不用动。这个小习惯在团队协作时能省掉非常多沟通成本。3.2 地图模块的核心流程从传感器数据到可导航地图这里有一个流程图思路可以走一遍不用图表按文字描述流程。核心链路是传感器数据进入适配层被转成标准扫描帧扫描帧连同里程计数据一起被送入建图核心建图核心持续输出当前机器人在地图坐标系中的位姿同时把扫描到的障碍物信息更新到地图栅格中。这个链路里的关键点在于“持续”。建图不是一个一次性动作而是一个随传感器数据流持续进行的概率更新过程。每一帧激光数据到来都相当于对地图上那些栅格进行了一次贝叶斯更新——用新的观测来修正旧的状态。这也是为什么地图不是简单的黑白图每个栅格存储的不是0或1而是一个连续的概率值表示“该栅格是障碍物的概率”。最终使用时会设定一个阈值超过这个阈值才被认为是障碍物。保留概率值是必要的因为单帧激光数据可能受噪声影响用概率持续累积可以让地图越来越稳而不是被一帧异常数据污染。完整的地图模块从不直接操作算法库工作。拿典型的2D激光雷达举例当一帧扫描数据到达时适配层会先做传感器畸变校正雷达运动时采集到的点会有一点拉伸再把它从激光坐标系下变换到全局地图坐标系然后才交给建图核心。这个纠正-变换-融合的链路易学难精。校正参数错误会导致扫描帧拉伸方向反了地图出现明显的螺旋纹变换顺序写错则会导致地图整体旋转。我在后面的常见问题部分会细说这类现象怎么排查。3.3 参数配置逐项讲解这些参数到底怎么去调地图模块的参数配置是最能看出一个工程师是“调过”还是“只是用过”的地方。下面我挑几个关键参数分别说明。分辨率resolution每个栅格对应真实世界的尺寸常见取值是0.05米/像素。分辨率越高地图细节越丰富代价是内存和计算量成平方上涨。实际工程中我不建议一味追求高分辨率。室外场景0.1米/像素通常足够室内场景0.05米/像素是常用值0.025米/像素只有在小范围高精度场景下才用得上。判断标准很简单你的导航精度要求是多少。如果机器人本体定位精度是±0.1米地图分辨率做到0.05米/像素就够再高只会白白增加计算压力。地图原点origin地图左上角像素在真实世界坐标系下的位置。这个参数会导致很多不明所以的bug。建图时地图原点是跟随机器人初始位姿的但如果加载地图时原点没有正确恢复或者不同来源的地图文件原点基准不一致那么地图的绝对坐标会整体偏移。我建议在模块里加一道自动校验加载地图时根据原点数据和当前机器人里程计数据的初始值计算一个偏差量如果偏差量超过某个阈值比如0.5米就直接拒绝加载而不是把它当“正常误差”吞掉。障碍物膨胀半径inflation radius路径规划时机器人本体是有物理尺寸的不能贴着障碍物走。膨胀半径就是在原始障碍物的基础上向外扩展出一圈“禁止通行区”。这个值应该取“机器人最大外接圆半径”再增加一个安全余量。很多新手设置膨胀半径时只考虑底盘半径忽略了安装在侧面或后方的传感器支架、线缆、悬挂物结果机器人导航时经常“蹭墙而过”就是因为膨胀半径设小了。正确做法是测量整机在旋转状态下的最大外包络半径在这个基础上加5-10厘米的安全余量。更新频率update rate地图模块从传感器接收数据的频率决定了建图的实时性。激光雷达一般10Hz视觉一般15-30Hz但地图更新不必等同于传感器频率。实践经验是建图阶段用10Hz更新绰绰有余运行阶段如果只需要导航5Hz就够。过高的更新频率不会提升导航效果只会让MCU忙死还可能造成数据队列积压。这些参数看起来琐碎但每一个背后都对应一个典型的失败场景。如果你在项目里被人问“为什么地图边缘都是毛刺”多半是分辨率配得不合理如果问“为什么明明地图上没障碍物机器人却绕路”多半是膨胀半径的问题。参数不是随便填的它承载的是整个物理系统在数学空间里的映射关系。3.4 关键接口函数的“为什么”读代码读的是什么看这种微服务式模块的源码最容易陷入的误区是逐行通读。正确做法是带着问题去看关键接口先搞清楚“这个函数被谁调用、为什么要存在”再去看它的实现细节。这里我挑几个典型接口来说明这种阅读方法。地图获取接口功能是返回当前完整地图。为什么要设计成“返回”而不是让外部直接访问内部地图对象因为地图是会被并发修改的。外部拿到一个内部对象引用刷的一下修改了某个栅格而地图模块自己的建图线程根本不知道这件事接下来行为就不可预测了。所以内部地图对象必须私有化所有对外访问都走拷贝或只读句柄。看这部分代码时重点关注拷贝的开销控制——如果每次获取地图都做深拷贝性能会难看得没法用合理方案是加引用计数或者只把修改部分作为增量事件发布出去。地图保存接口功能是序列化地图到磁盘。为什么要自定义文件格式而不是直接存成图片因为图片损失了概率值和元数据而这两个东西是后续导航和编辑必需的。自定义文件格式时要重点看头部元数据字段和栅格数据段的校验逻辑——有没有写文件长度有没有CRC校验如果这两样都没有将来跨平台加载大概率会踩坑。坐标系变换接口核心是拿时间戳和坐标系名称去查找变换。看这类接口的源码时有一个重要细节它是否返回了变换的置信度或有效时间范围。如果没返回外部就无法判断这个变换是否已经过期容易在机器人停下很久后还用过时的坐标去做路径计算。检查这种接口设计是否合理最简单的方法是看测试用例如果测试用例里没有“查询不存在的坐标系”和“查询过期时间变换”这两个分支那这个接口的健壮性就要打个问号。通过这种“场景驱动”的阅读方式你不需要读完每一行源码就能判断一个地图模块的设计水平和工作原理也能在实际编码时更快找到自己的切入位置。4. 常见问题与排查技巧实录这些坑我一个个蹚过4.1 建图完成的地图偏移或错位如何定位和修复这是低频但最气人的一类问题。现象往往是这样建图跑了半天地图画出来倒是挺漂亮可一旦机器人走一圈回到原点地图上出现明显错位墙和墙之间叠出了重影。先查坐标系。错位的一大原因是激光雷达坐标系到里程计坐标系的外参标定错误。典型的标定参数包括x、y、z平移量和yaw、pitch、roll旋转量。很多时候开发人员只标定了x、y和yaw忽略了z和pitch原因是2D激光雷达确实不需要z和pitch参与计算。但如果雷达安装稍微歪了一点哪怕pitch只有一两度在10米之外扫描到的点误差就会被放大到二三十厘米。这种偏差在建图回环时就会以重影形式暴露出来。我当时排查这个问题就是先固定机器人采集了几帧静态扫描数据转动雷达云台观察扫描点是否始终落在同一个位置——果然发现点云在远端形成了一圈扇形扩散说明雷达确实装了歪。重新标定pitch之后视觉上几乎看不出问题但重影就消失了。第二个嫌疑点是里程计时间戳。传感器数据在系统中传递时有延迟如果激光帧和里程计帧之间的时间没有同步对齐相当于机器人把“过去时刻的姿势”和“现在时刻的扫描”合在一起自然会出现错位。排查方法也简单录一段包含原地旋转的rosbag吧回去一帧帧去对时间戳。我记得当年查一个“只在天花板灯亮时才错位”的诡异bug最后发现是因为光照变化导致视觉里程计掉帧而里程计数据源却依然是固定频率在发时间戳错位在视觉里程计跳变时格外明显。解决方法是给地图模块加一个时间同步缓冲队列确保两个数据的时间戳差值在限定范围之内超过范围就丢弃本帧而不是强行融合。4.2 系统卡顿、地图加载速度慢性能瓶颈三板斧地图模块跑着跑着系统越来越卡绝大多数情况下都不是地图模块本身的问题而是数据流上某个环节出现了积压。常规排查分三步走。第一步看CPU占用。CPU被打满最常见的原因是地图更新回调里做了大量重复计算。比如每一帧激光数据到达后都把整个地图重新做了一次膨胀、一次序列化、一次可视化发布。正确的做法是建图线程只做局部更新膨胀计算放到单独线程异步执行可视化发布用节流方式控制在5-10Hz即可。第二步看内存占用。地图文件加载慢先看加载逻辑有没有做“一次性读入再整体解析”。当文件几百MB时这种做法基本就是灾难。正确做法是分块加载先读元数据再按需读取栅格区块。还有一种情况是地图模块内部缓存了较长时间的传感器数据如果机器人长时间停在原地不动雷达数据却仍然源源不断进入队列队列就会越堆越长。预防手段是给数据队列设置最大容量超出部分直接丢帧毕竟机器人不动时地图更新本身没有意义。第三步看锁竞争。地图数据往往被建图线程、导航线程、可视化线程同时访问。如果设计时用一个大锁保护整个地图并发再高也撑不住。优化思路是分区加锁、读写分离。可视化线程要的只是“最近一次的地图快照”完全可以靠一份原子指向的只读引用来实现导航线程关心的是“代价地图”跟原始地图分开维护建图线程独占写原始地图。这三者之间都通过消息事件触发而不是直接拿同一把锁。4.3 多楼层或跨区域场景中的地图切换如何不掉链子多楼层是地图模块一个非常常见的应用场景。典型需求是机器人在一楼要坐电梯上到三楼然后导航到某个房间。这里地图模块要做的不仅仅是“换一张图”而是处理切换过程中的坐标跳变和姿态重定位。最原始的方案是切图后直接把机器人在地图上的位姿设置到“电梯口”对应的坐标。但现实中电梯会停下来有微小偏差机器人下电梯后需要重新定位。正确做法是切图后地图模块立即进入“重定位模式”——在该模式下传感器的扫描数据不再更新地图内容而是用于匹配机器人相对于当前地图的位姿。匹配成功之后再把地图控制权交还给正常导航流程。有个关键细节很多人会忽略跨楼层切换时地图文件本身不变但机器人在电梯里的短暂时间激光可能会扫描到电梯壁形成一张“临时地图”。如果不清理这个临时地图机器人出了电梯、真正到了三楼走廊后它可能会认为自己还在一个电梯井一样的狭小空间里然后导航算法就彻底蒙圈。所以切图事件触发的第一件事不是加载新地图而是清空所有缓冲区包括激光匹配历史缓冲、临时地图缓冲、代价地图中的动态障碍物图层。把这些清理干净之后再加载新地图并启动重定位。顺序不要搞反。4.4 地图局部更新与静态障碍物之间的博弈和取舍在建图完成后的日常运行中地图不是一成不变的。公司换了个工位布局多了一排货架少了一堵临时挡板地图都需要做局部更新。这里有个两难选择更新太积极会把一些临时噪声例如清扫人员经过固化进地图更新太保守地图又会逐渐偏离真实环境导航精准度下降。比较成熟的方案是给地图数据加上“置信度”标签区分静态层和动态层。静态层的栅格值只能由多帧一致观测确认后才更新动态层的栅格值可以随单帧观测快速变化。代价地图直接使用静态层加动态层的叠加结果。一旦某个区域连续多帧被观测为“障碍物”并且来源不是动态物体分类器比如不是人、不是移动底盘系统就可以把这个区域从动态层提升到静态层实现一次可靠的局部更新。这个方法实现起来不复杂但收益非常明显。我接手一个旧的无人车项目时车间环境每天都有叉车穿梭原本的地图模块把所有移动障碍物直接写进了地图每天下班前机器人的地图就已经“面目全非”第二天早上启动时根本没法用。改成静态层动态层分离之后叉车走完之后动态层自动清理地图主体几乎不会漂移三天才需要人工做一次校准。而且校准也只是增加了一个“一键确认更新”的接口比从头重新建图快得多。4.5 一张踩坑速查表拿到现象就能定位问题现象直接原因排查入口地图出现同心圆纹/螺旋纹激光畸变校正参数不对检查雷达到里程计的标定外参地图整体旋转一定角度地图原点或初始航向角没恢复检查地图文件的origin字段与设备启动航向地图上有大量随机噪点动态障碍物被写入静态层检查静态层置信度阈值和更新条件地图加载速度极慢一次性读取完整大图未分块检查文件IO逻辑改按需加载机器人运行一段时间后定位漂移地图未局部更新环境已变化检查动态层/静态层分离逻辑跨楼层加载后导航失效切换流程缺少重定位检查切图事件后的缓冲清理和重定位触发时机这张表不是说“照着查一定能解决”但它能帮你把问题范围快速缩到一个合理的区间。我在实际排查中经常发现团队内很多人解决不了问题不是能力不行而是花太多时间在错误的方向上乱试。地图模块相关的坑绝大多数都是坐标系、数据同步、生命周期管理这三类问题看到现象先入座排查效率会高非常非常多。5. 写在地图模块交付之后几条值得带走的工程经验如果你正在做一个类似lingbot-map这样的基础设施模块有几条经验我想特别分享出来。第一条接口设计时宁可多暴露只读接口不要暴露可变对象引用。我见过太多因为地图对象被外部直接修改而导致的疑难bug。地图模块的内部状态应当只允许通过固定接口进行受控修改。也许短期内这会增加一点代码量但长期来看排查难度和协作成本都会显著下降。第二条日志要留足“时间戳”和“坐标”信息。地图模块的大部分问题都和坐标、时间有关排查时最痛苦的就是日志里没有记录机器人当时的位姿和时间。如果日志里能记录“t1时刻机器人位于地图坐标点(x, y)”很多事就不用靠猜了。我自己的习惯是所有关键接口都打一条包含stamp和坐标的debug日志平时关闭排查时打开效率提高非常明显。第三条面向场景去测试而不是面向函数去测试。地图模块的单元测试当然要有但真正考验模块质量的是几个端到端场景从一张空地图开始建图保存重新加载走一段路确认地图对齐模拟局部环境变化确认地图能更新跨楼层切图确认定位恢复。这套场景测试跑通了模块才算真正在工程上可用。如果只是单测通过率高但在真实场景里稍一出状况就崩那这个模块离“交付”还差得远。最后再分享一个小技巧。地图模块往往需要维护多套设备的不同地图命名规范建议统一为“区域名_版本号_日期.gpm”这种格式并且在地图文件内部写入创建设备的唯一标识和传感器型号的hash值。一旦搞混可以通过内部元数据快速溯源。这个习惯在一次现场交付中救过我一次——现场有两台设备型号相同但雷达安装高度不同一开始大家把地图文件互相拷贝结果导致两台设备定位全偏。后来靠地图文件内的传感器hash迅速找出了不匹配的地图文件并重新分配半小时就解决了。做基础设施模块很多时候比写新功能更重要的是让运行中的系统可维护、可诊断、可追溯。
