机器人 / 系统课时

读取栅格地图的 YAML 元数据

读取栅格地图的 YAML 元数据

栅格地图的图像文件记录障碍分布,YAML 文件决定每个像素代表多少米、地图放在什么坐标位置,以及灰度如何转换为占据状态。本篇以 ROS 2 Jazzy 和 Nav2 为环境,检查地图文件引用、尺度、原点和占据阈值,并通过实际命令验证配置是否合理。

学习目标

  • 读懂地图 YAML 中的 image、resolution、origin、negate 和占据阈值。
  • 根据图像像素尺寸计算地图的实际米制范围,辨认地图原点和方向。
  • 使用 Python 检查地图文件与元数据是否匹配,定位常见配置错误。

找到 YAML 对应的地图图像

Nav2 的 Map Server 通常从 YAML 读取地图元数据,再打开其中指定的 PGM、PNG 等图像,将像素转换为 nav_msgs/msg/OccupancyGrid。只有 YAML 而没有对应图像,无法还原完整地图。

下面是一个假设保存在 ~/maps/map.yaml 中的片段示例,要求同目录存在 office.pgm。它不是 Nav2 节点参数文件,而是地图数据本身的描述文件。

yaml
image: office.pgm
mode: trinary
resolution: 0.05
origin: [-5.0, -4.0, 0.0]
negate: 0
occupied_thresh: 0.65
free_thresh: 0.25

各字段的含义如下。

字段 示例值 实际含义
image office.pgm 地图图像路径;相对路径以 YAML 所在目录为基准
mode trinary 三值占据模式:空闲、占据、未知
resolution 0.05 每个栅格边长 0.05 米,即 5 厘米
origin [-5.0, -4.0, 0.0] 地图栅格原点在世界坐标中的 x、y、yaw
negate 0 不反转通常的黑色障碍、白色空闲约定
occupied_thresh 0.65 占据概率达到该值时判为占据
free_thresh 0.25 占据概率不高于该值时判为空闲

origin 的第三个数字是绕 Z 轴旋转的角度,单位为弧度,不是角度制。0.0 表示栅格坐标轴与地图坐标轴对齐,约 1.5708 表示逆时针旋转约 90°。

计算地图尺寸与辨认坐标方向

假设 office.pgm 的实际尺寸为 400×200 像素,resolution 为 0.05 米/像素,那么地图覆盖的物理范围为:

  • X 方向长度:400 × 0.05 = 20 米。
  • Y 方向长度:200 × 0.05 = 10 米。
  • 每个栅格面积:0.05 × 0.05 = 0.0025 平方米。

当 origin: [-5.0, -4.0, 0.0] 时,地图左下边界对应 (-5, -4),右上边界对应 (15, 6)。这是地图覆盖范围的边界坐标,不是右上角栅格中心坐标。

容易混淆的是图像像素坐标与 ROS 栅格坐标:通常图像文件从左上角开始按行存储像素,行号向下增加;ROS 占据栅格使用左下角为栅格原点,Y 方向向上增加。加载器会处理这种行方向差异,不需要为了匹配 ROS 坐标而手工上下翻转图像。

图像像素坐标与 Nav2 地图原点、尺寸和方向的对应关系

如果 origin 的 yaw 不为零,地图覆盖范围也会随栅格坐标轴旋转,不能再直接通过原点加宽高求世界坐标轴对齐的边界。验证方向时,应找一条已知朝向的走廊或墙体,与地图显示的方向进行对照。

用命令检查元数据与实际图像

在 Ubuntu 24.04 上,可以使用 Python 3、PyYAML 和 Pillow 检查地图。若缺少依赖,先安装系统软件包 python3-yaml 和 python3-pil。

以下命令以 ~/maps/map.yaml 为输入;实际使用时将路径替换为自己的地图 YAML。脚本会解析相对路径,验证分辨率和阈值范围,并读取真实图像的宽高,而不是猜测图像尺寸。

bash
python3 - "$HOME/maps/map.yaml" <<'PY'
from pathlib import Path
import sys
import yaml
from PIL import Image

yaml_path = Path(sys.argv[1]).expanduser().resolve()
meta = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))

# 图像相对路径必须以 YAML 文件所在目录为基准
image_path = Path(meta["image"]).expanduser()
if not image_path.is_absolute():
    image_path = yaml_path.parent / image_path
assert image_path.is_file(), f"图像不存在: {image_path}"

resolution = float(meta["resolution"])
origin = meta["origin"]
free = float(meta["free_thresh"])
occupied = float(meta["occupied_thresh"])

# 检查几何参数及占据阈值的合法范围
assert resolution > 0 and len(origin) == 3
assert 0 <= free < occupied <= 1

with Image.open(image_path) as image:
    width, height = image.size

print(f"图像: {image_path.name} {width}x{height} px")
print(f"地图尺寸: {width * resolution:.2f}m x {height * resolution:.2f}m")
print(f"origin: {origin}")
print(f"mode: {meta.get('mode', 'trinary')}, negate: {meta['negate']}")
PY

预期输出:若使用上面的示例 YAML,且实际 office.pgm 为 400×200 像素,应得到以下结果。

text
图像: office.pgm 400x200 px
地图尺寸: 20.00m x 10.00m
origin: [-5.0, -4.0, 0.0]
mode: trinary, negate: 0

真实地图的文件名、尺寸、原点和模式可能不同。若提示 图像不存在,首先检查 YAML 中 image 的文件名和相对路径,而不是修改 resolution。若触发阈值断言,确认是否误把 0.65 写成了 65,以及是否将空闲阈值设置得高于占据阈值。

判断灰度对应的占据状态

在示例的 trinary 模式和 negate: 0 条件下,灰度值越低,占据概率越高。对不透明的普通灰度像素,可用以下近似关系理解阈值:占据概率等于 1 - 灰度值 / 255。

灰度值 占据概率约值 示例阈值下的判定
0(黑) 1.000 占据,对应障碍
128(中灰) 0.498 未知
255(白) 0.000 空闲

因此,free_thresh: 0.25 与 occupied_thresh: 0.65 之间的占据概率在三值模式下归为未知。阈值是 0~1 的概率界限,不是 0~255 的灰度值。带透明通道的图像还可能将透明像素作为未知区域处理。

当 negate: 1 时,灰度与占据概率的关系反向,不能继续套用上表。mode: scale 会保留部分中间占据值,mode: raw 则采用原始像素值解释;上述三值分类规则只适用于 trinary。

对照 Nav2 检查地图是否正确

完成静态检查后,在已启动并激活 Map Server 的 Nav2 环境中打开 RViz 2,确认 Global Options > Fixed Frame 为 map,并启用 Map 显示项。地图显示正常不代表坐标一定正确,建议依次核对三个具体条件。

  1. 尺度:若一条真实宽 2 米的走廊在图像中占 40 个像素,resolution: 0.05 才与该尺寸吻合。若只占 20 像素,应重新核实地图分辨率与原始测量,而不是任意修改显示缩放。
  2. 方向和位置:检查已知墙体、走廊朝向与 origin 的 yaw 是否一致。不要通过 negate 修正地图方向,它只影响占据解释,不会旋转图像。
  3. 障碍分布:黑色墙体应显示为占据,白色通道应为空闲,未知区域不应无故吞没可通行走廊。若整体黑白反转,优先核对 negate 与原始图像灰度;若大量区域显示未知,则核对阈值和图像灰度分布。

Nav2 的地图 YAML 由 Map Server 的 yaml_filename 参数或导航启动时的 map 参数指定。注意确认当前运行的系统加载的确实是刚刚检查的那份 YAML,而不是其他目录下同名地图。

完成这些检查后,应能明确回答:图像文件在哪里、一个像素对应多少米、整张地图覆盖多大范围、栅格原点与方向是什么,以及哪些灰度会被判定为障碍。这些结果将作为后续 AMCL 定位与导航坐标检查的基准。

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

目录与阅读设置

阅读设置

17

记录一个想法

读取栅格地图的 YAML 元数据

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

登录哪都通