机器人 / 系统课时
读取栅格地图的 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 节点参数文件,而是地图数据本身的描述文件。
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 坐标而手工上下翻转图像。

如果 origin 的 yaw 不为零,地图覆盖范围也会随栅格坐标轴旋转,不能再直接通过原点加宽高求世界坐标轴对齐的边界。验证方向时,应找一条已知朝向的走廊或墙体,与地图显示的方向进行对照。
用命令检查元数据与实际图像
在 Ubuntu 24.04 上,可以使用 Python 3、PyYAML 和 Pillow 检查地图。若缺少依赖,先安装系统软件包 python3-yaml 和 python3-pil。
以下命令以 ~/maps/map.yaml 为输入;实际使用时将路径替换为自己的地图 YAML。脚本会解析相对路径,验证分辨率和阈值范围,并读取真实图像的宽高,而不是猜测图像尺寸。
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 像素,应得到以下结果。
图像: 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 显示项。地图显示正常不代表坐标一定正确,建议依次核对三个具体条件。
- 尺度:若一条真实宽 2 米的走廊在图像中占 40 个像素,
resolution: 0.05才与该尺寸吻合。若只占 20 像素,应重新核实地图分辨率与原始测量,而不是任意修改显示缩放。 - 方向和位置:检查已知墙体、走廊朝向与
origin的 yaw 是否一致。不要通过negate修正地图方向,它只影响占据解释,不会旋转图像。 - 障碍分布:黑色墙体应显示为占据,白色通道应为空闲,未知区域不应无故吞没可通行走廊。若整体黑白反转,优先核对
negate与原始图像灰度;若大量区域显示未知,则核对阈值和图像灰度分布。
Nav2 的地图 YAML 由 Map Server 的 yaml_filename 参数或导航启动时的 map 参数指定。注意确认当前运行的系统加载的确实是刚刚检查的那份 YAML,而不是其他目录下同名地图。
完成这些检查后,应能明确回答:图像文件在哪里、一个像素对应多少米、整张地图覆盖多大范围、栅格原点与方向是什么,以及哪些灰度会被判定为障碍。这些结果将作为后续 AMCL 定位与导航坐标检查的基准。