机器人 / 系统课时

怎样建立可复现的建图回归验证流程

怎样建立可复现的建图回归验证流程

本篇把一次 ROS 2 激光建图变成可重复运行的回归测试:固定 rosbag2 数据、slam_toolbox 参数和运行环境,保存地图与位姿图,用统一指标判断改动是否造成退化,并保留能追查故障的证据。

学习目标

  • 固定输入数据、TF、参数与软件版本,建立可追溯的建图基线。
  • 用相同回放流程产出地图、位姿图和指标记录。
  • 通过地图差异及可选的轨迹真值指标设置回归门槛。

固定输入与基线条件

以下以 Ubuntu 24.04、ROS 2 Jazzy、二维激光和 slam_toolbox 同步在线建图为例。准备一份闭环行走数据包 office_loop,至少包含 /scan、/tf、/tf_static;odom 到机器人基座的变换必须可用。数据包不应重放旧建图程序产生的 map 到 odom 变换,否则会和本次建图冲突。

首次运行前,固定数据包的文件哈希、ROS 发行版、slam_toolbox 软件包版本和参数文件。参数以发行版自带模板为起点,检查 scan_topic: /scan、odom_frame: odom、map_frame: map,将 base_frame 设为数据中实际存在的 base_link 或 base_footprint;示例地图分辨率固定为 0.05 米/格。

bash
source /opt/ros/jazzy/setup.bash
ROOT="<PATH>"  # 替换为数据与测试结果所在的绝对目录
mkdir -p "$ROOT/runs"
test -f "$ROOT/mapper.yaml" || cp /opt/ros/jazzy/share/slam_toolbox/config/mapper_params_online_sync.yaml "$ROOT/mapper.yaml"
ros2 bag info "$ROOT/office_loop"
sha256sum "$ROOT/mapper.yaml"
find "$ROOT/office_loop" -type f -print0 | sort -z | xargs -0 sha256sum
dpkg-query -W ros-jazzy-slam-toolbox ros-jazzy-rosbag2 ros-jazzy-nav2-map-server

预期结果:ros2 bag info 列出实际录制的话题和消息数量,其余命令给出参数文件与数据文件的 SHA-256,以及安装的软件包版本;哈希、版本号和时间均随环境变化。若缺少 /scan 或必要的 TF,先修正数据集,不进入算法比较。编辑 mapper.yaml 后必须重新计算并记录哈希,不能继续使用修改前的值。

固定输入、建图执行和回归判定的数据流

重放并保存同一组产物

将 mapper.yaml 中的 mode 保持为 mapping,统一回放速度为 1.0、use_sim_time=true,每次从空建图状态启动。不要同时运行 AMCL 或另一套会发布 map 到 odom 的节点;若要更改算法参数,只改候选实验需要评估的字段,并留下原文件哈希。

先在终端 A 启动建图,保持进程运行:

bash
source /opt/ros/jazzy/setup.bash
ROOT="<PATH>"
ros2 launch slam_toolbox online_sync_launch.py slam_params_file:="$ROOT/mapper.yaml" use_sim_time:=true

预期结果:/slam_toolbox 完成生命周期激活;回放开始后会生成 /map。若节点无法激活,检查参数路径、插件和帧名称,不要继续采集结果。

确认节点已启动后,在终端 B 回放;--delay 3.0 为订阅发现留出时间:

bash
source /opt/ros/jazzy/setup.bash
ROOT="<PATH>"
ros2 bag play "$ROOT/office_loop" --clock --delay 3.0 --rate 1.0

预期结果:按录制时间发布 /clock 和数据,回放至数据包末尾后正常结束。若原始数据包已经录制 /clock,应先统一时钟来源,避免两个发布者竞争。

待处理队列完成、最后一版 /map 已发布后,在终端 C 保存静态地图与可恢复的位姿图:

bash
source /opt/ros/jazzy/setup.bash
ROOT="<PATH>"
mkdir -p "$ROOT/runs/001"
ros2 run nav2_map_server map_saver_cli -t /map -f "$ROOT/runs/001/map" --fmt pgm --mode trinary --occ 0.65 --free 0.25
ros2 service call /slam_toolbox/serialize_map slam_toolbox/srv/SerializePoseGraph "{filename: '$ROOT/runs/001/graph'}"

预期结果:成功时生成 map.pgm、map.yaml,以及可用于恢复建图的位姿图文件(通常是 graph.posegraph 和 graph.data)。如果保存失败,先检查 /map 是否可用、保存目录权限及服务是否存在。参数、数据、日志和输出文件均以运行编号归档;基线放在独立只读目录,不能被候选结果覆盖。

用相同指标比较地图

地图验收至少包含两项:基线已知区域在候选地图中变成未知区域的比例,以及双方都已知的栅格中,占据类别发生变化的比例。比较前必须检查地图分辨率、尺寸、世界坐标原点和朝向;任一项不相同,应先以统一坐标系配准并重采样,不能直接对两张 PGM 按像素相减。

下面脚本适用于前述 --mode trinary --fmt pgm 输出,使用 ROS 地图保存器的灰度约定:0 为障碍,254 为空闲,205 为未知。安装 python3-yaml 和 python3-pil 后,将脚本保存为 compare_maps.py,用基线与候选两份 map.yaml 运行。

python
from pathlib import Path
import sys
import yaml
from PIL import Image

def load_map(name):
    path = Path(name)
    info = yaml.safe_load(path.read_text(encoding="utf-8"))
    with Image.open(path.parent / info["image"]) as im:
        shape = im.size
        pixels = list(im.convert("L").getdata())
    geometry = (shape, info["resolution"], tuple(info["origin"]))
    if info.get("mode", "trinary") != "trinary":
        raise SystemExit("FAIL: 仅支持 trinary 地图")
    return geometry, pixels

# 仅比较位于同一世界网格的地图,不做隐式对齐。
ref_geom, ref = load_map(sys.argv[1])
new_geom, cur = load_map(sys.argv[2])
if ref_geom != new_geom:
    raise SystemExit("INVALID: 网格几何不一致,先配准重采样")

# 分别统计新增未知区域和共同已知区域的类别变化。
ref_known = sum(v != 205 for v in ref)
common = sum(a != 205 and b != 205 for a, b in zip(ref, cur))
if ref_known == 0 or common == 0:
    raise SystemExit("INVALID: 可比较的已知格为空")
lost = sum(a != 205 and b == 205 for a, b in zip(ref, cur))
changed = sum(a != 205 and b != 205 and a != b for a, b in zip(ref, cur))
loss_rate = lost / ref_known
change_rate = changed / common
print(f"known_loss={loss_rate:.2%}, class_change={change_rate:.2%}")
print("PASS" if loss_rate <= 0.03 and change_rate <= 0.02 else "FAIL")

预期结果:脚本读取两份地图,先检验尺寸、分辨率与世界坐标原点,再计算两个变化率;遇到不可比较的网格会输出 INVALID 并停止。运行命令如下:

bash
python3 compare_maps.py "<PATH>/runs/baseline/map.yaml" "<PATH>/runs/001/map.yaml"

预期输出:若两张地图的网格与像素完全相同,将得到:

text
known_loss=0.00%, class_change=0.00%
PASS

实际结果数值可能不同;失败的指标会输出 FAIL,不能把示例中的通过结果当成验证证据。

这里 3% 和 2% 是演示用的项目门槛,应结合基线重复实验的自然波动和可接受的地图误差确定。若有独立真值轨迹,还应按同一时间戳关联、二维刚体坐标对齐后计算 ATE RMSE,并以固定 1 s 间隔计算 RPE;例如将相对基线恶化超过 0.05 m 的 ATE 或超过 0.03 m 的 RPE 标记为退化。没有真值时把这两项记为“不适用”,不可把里程计轨迹当成真值。

将失败转为可追查证据

每次修改只改变一个算法因素,先运行基线三次,记录指标的最大、最小值,再用相同数据做候选三次;同步建图也可能因调度、TF 可用时间和回环处理时序产生小幅差异,不应要求地图文件逐字节相同。

观察结果 优先核查 处置
地图突然缺大片区域 /scan 数量、TF 可用性、回放启动时序 修复丢帧或等待关系,重跑同一包
地图重影、回环位置错开 回环匹配阈值、轨迹偏差、错误闭环 对照位姿图与日志,回退单项改动
脚本报告 INVALID map.yaml 的原点、分辨率与尺寸 对齐同一世界网格后再比较
只有一次运行超阈值 重放时序、CPU 负载、处理队列 重复三次并记录波动,不直接判定算法退化

归档时至少保存数据文件哈希、mapper.yaml 哈希、ROS 软件包版本、回放参数、完整日志、地图、位姿图和指标结果。只有输入与比较坐标一致,且候选结果超出基线波动区间,回归失败才有明确的算法诊断意义。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

怎样建立可复现的建图回归验证流程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通