入行做机器人导航那段时间，我一直以为“地图颜色”就是数据直接渲染出来的：自由区域是白的，障碍物是黑的，未知区域是灰的。直到有一次调试某巡检机器人项目，我在 RViz 里看得好好的栅格地图，用 OpenCV 一画出来竟然是整张黑图，当时我还以为是订阅话题的数据坏了，折腾了大半宿才发现，问题不在数据，而在 OccupancyGrid 的数值和我们平时用 OpenCV 画图的颜色映射习惯完全反着来。
这篇文章就把我之前趟过的这些坑一次说清楚：OccupancyGrid 里 data 数组每个数字到底代表什么，RViz/map_server/OpenCV 各自默认的脸色是哪里来的，以及当你需要自己把nav_msgs/OccupancyGrid转成可视化的灰度图或彩色图时，归一化、特殊值处理、图像翻转这些细节应该怎么做。内容适合刚接触 ROS 地图数据、或者正在写建图后处理脚本的朋友参考，已经会订阅其他话题的话，上手会更快。
1. 为什么直接画 data 数组会得到一张黑图：OccupancyGrid 的数值语义
1.1 data 数组并不是亮度值，而是“占据概率索引”
很多教程一上来就让你msg.data转numpy然后reshape，却没有解释这个数组里每个数字的含义。nav_msgs/OccupancyGrid的数据结构其实非常简单，核心字段就四样：
header：时间戳和坐标系，一般就是map；info.width/info.height：栅格地图的宽和高，单位是栅格数；info.resolution：每个栅格的物理尺寸，单位是米/栅格；data[]：长度等于width * height的一维数组，每个元素是int8。
这里的data数组是整张地图按“行优先”展开的，每个值表示该栅格被占据的概率或置信度，而不是像素亮度。ROS 的标准约定是：
| 数值 | 含义 | 我自己的理解 |
|---|---|---|
| -1 | 未知区域，没有任何传感器数据覆盖 | 相当于这张地图里的“灰色地带” |
| 0 | 确定空闲，激光或者深度数据明确告诉你这里能走 | 自由的通路 |
| 1 ~ 99 | 占据概率从极低到极高，1 接近空闲，99 接近障碍物 | 中间置信度，通常是滤波或概率更新后的结果 |
| 100 | 确定占据，物理上挡路 | 障碍物本体 |
有个非常误导人的点：自由不是 255，而是 0。因为我们从小看 8 位灰度图，默认规则是 0 黑、255 白，所以很多人一看data=0就下意识觉得是“没有数据/黑色”，于是把障碍物画成了白色，自由区域画成了黑色，整张图直接负片化。
1.2 数值表示逻辑和颜色表示逻辑天生相反
再往深一层想，data的取值其实是“占据概率”的语义：0% 占据概率映射到 0，100% 占据概率映射到 100。这种设计的好处是信息紧凑，一个字节足够表达 -1 到 100 的完整状态，而且 C++ 里处理起来非常快，不用面对 NaN 这种麻烦。
但问题来了，8 位灰度图的语义是“亮度”：0 是黑色，255 是白色。你把“占据概率”直接塞进“亮度”通道，100 根本到不了 255，自由区域的 0 又恰好是纯黑。结果就是：**地图上本该空无一物的自由区域成了大片黑色，障碍物也只是深灰色，整张图看起来像一块脏抹布。**如果再把 -1 强转成uint8，负数会溢出成 255，未知区域直接变纯白，画面就变成了白底黑斑，越看越像底片。
第一次遇到这种问题时，我最推荐的检查方式不是反复换颜色，而是先打印数据统计：直接看data.min()、data.max()和np.unique(data)输出几个关键值。你很快就会发现，数组里绝大多数是 0，少量是 100，还有一部分 -1。数据本身完全正常，接下来要解决的只是“显示映射”这一步。
1.3 为什么说地图显示其实是做语义映射，而不是直接渲染
把 OccupancyGrid 画成图，本质上不是“渲染”，而是“翻译”。你需要先决定三件事：
- 未知区域显示成什么颜色；
- 自由区域显示成什么颜色；
- 占据区域显示成什么颜色。
除此之外，中间概率（1 到 99）你要不要做线性渐变，还是直接二值化？这些策略在不同工具里各不相同，所以才会出现“同一个话题，RViz 里看是一张图，自己画出来是另一张图”的现象。下面这一章就把常用的几种映射约定摆在一起对比。
2. 三套常见颜色约定：RViz、map_server 和 OpenCV 眼中的同一张地图
2.1 RViz 默认把自由刷白、占据刷黑、未知刷灰
在 RViz 里添加一个Map显示项，你会看到非常符合直觉的画面：自由区域是白色，障碍物是黑色，未知区域是中等灰色。这套配色的逻辑很朴素——白色代表“安全能走”，黑色代表“别过去”，灰色代表“还没探测过”。
RViz 的Map显示模块有自己的Color Scheme选项，默认是map方案，本质就是做了一个语义映射表：
- free (0) → 白色；
- occupied (100) → 黑色；
- unknown (-1) → 灰色（通常接近 128 或 205，具体取决于参数配置）。
要注意的是，RViz 展示的是“看起来合理”的结果，它对数据做了完整的映射处理。你以为地图本来就是白的，其实只是 RViz 替你完成了从“占据概率”到“亮度值”的翻译。
2.2 map_server 保存地图时默认遵守 PGM 的 0 黑 255 白约定
另一个容易踩坑的地方是map_server。保存地图时它会生成.pgm文件，PGM 格式本身是标准的 8 位灰度图：0 黑、255 白。但 map_server 为了保持和 RViz 一致的视觉感受，会把 OccupancyGrid 的语义做一次反转映射：
- 0（自由）→ 接近 255，接近白色；
- 100（占据）→ 0，纯黑；
- -1（未知）→ 中间灰，一般取 205 左右。
也就是说，map_server 生成的 PGM 文件，颜色方向和 data 数值方向是反的。如果你把 PGM 直接当成地图加载回程序，或者把 PGM 的像素值直接当作 OccupancyGrid 的 data 值来用，颜色大概率又会乱一次。
2.3 OpenCV / matplotlib 默认没有任何地图语义
到了 OpenCV 这里，情况更“裸”一些。cv2.imshow对一个 8 位灰度图做显示时，默认就是 0 黑、255 白，没有任何地图语义。如果你直接把 OccupancyGrid 的data数组塞进去，结果就是我开头说的黑图。matplotlib 也一样，默认 colormap 是gray，同样是 0 黑 255 白。唯一多出来的坑是，网上有些人会建议你用gray_r翻转色彩条，如果你不清楚自己数据的方向，翻转完之后正好又反过来了。
我整理了一张对比表，帮助你在不同环境之间切换时不至于晕头转向：
| 环境 / 工具 | 自由区域 (0) | 占据区域 (100) | 未知区域 (-1) | 备注 |
|---|---|---|---|---|
| RViz Map 显示 | 白色 | 黑色 | 灰色 | 默认提供了语义映射，直接可用 |
| map_server 保存的 PGM | 接近白色 (≈254) | 纯黑 (0) | 灰 (≈205) | 和 PGM 0黑255白刚好反向 |
| OpenCV 直接显示 | 黑色 | 深灰 | 溢出为白色 | 未处理时基本不可用 |
| 自己写转换脚本 | 自己设定 | 自己设定 | 自己设定 | 建议统一为 0 黑、255 白或反转 |
所以你要做的，就是选择一个“语义目标”，然后把数组数值翻译过去。常见的做法是生成一张灰度图，自由区域为 255、障碍物为 0、未知为 128 或 205；如果你偏爱彩色，也可以把自由画成绿色、障碍物画成红色，语义更直观。关键是先明确目标，再写代码，别上来就data * 255。
3. 从 OccupancyGrid 到灰度图：手写一个可靠的转换函数
3.1 向量化处理的完整代码与注释
明白了映射关系，“把 OccupancyGrid 变成图片”其实就是二十来行代码的事。下面是我在项目里一直使用的转换函数，向量化处理，性能足够应付几千乘几千的栅格地图。
import numpy as np def occupancy_grid_to_image(msg): """ 将 nav_msgs/OccupancyGrid 消息转换为 8-bit 灰度图。 输出约定： free -> 255 (白色) occupied -> 0 (黑色) unknown -> 128 (灰色) """ width = msg.info.width height = msg.info.height # data 是 int8，包含 -1，不能直接当 uint8 用 data = np.array(msg.data, dtype=np.int8).reshape(height, width) # 先复制一份，避免影响原数据 img = np.full((height, width), 128, dtype=np.uint8) # 自由空间 -> 白色 img[data == 0] = 255 # 占据区域 -> 黑色 img[data == 100] = 0 # 处理 1~99 的中间概率 # 如果你不需要渐变，直接按占据处理更简单 middle = (data > 0) & (data < 100) # 将 1~99 线性映射到 254~1（概率越高越接近黑色） img[middle] = (100 - data[middle]) * 255 // 100 return img, width, height, data这段代码有几点值得解释。
为什么用np.full先填 128 而不是直接上来给自由区域赋 255？因为未知区域必须优先兜底，如果先赋 255 再处理未知，很容易把未知区域和自由区域混在一起。反过来先填灰，后面只处理确定的状态，逻辑更清晰。
中间概率的处理不一定每张地图都有。如果你在跑 2D SLAM，大多数情况下地图数据值只有 -1、0、100 三个档位；但如果你自己接了激光+概率更新的算法，或者用了某些代价地图数据，1~99 就会频繁出现。我上面用的是线性渐变：概率越高越接近黑色。你也可以改成二值化，比如大于 60 一律当黑色，看你的下游任务怎么处理。
3.2 未知区域的颜色选择不是小事的两个原因
未知区域到底取 128 还是 205，很多人觉得随便填一个就行，但有两个坑你躲不过去。
第一，data == 0的自由区域如果和128太接近，在视觉上会分不清。我在调试某跨平台系统时确实遇到过：未知区域取205，自由区域取255，灰度差别太小，树莓派上转成低分辨率缩略图后，整个背景几乎融为一体，后端的人一眼看不出哪里是未探索区域。未知区域最好和自由区域拉开距离，128就是中等灰，和255对比足够明显。
第二，如果后续要把这张图片输入给视觉模型，颜色语义会影响标注。有些语义分割模型对黑白比较敏感，如果你把未知区域设成 205，自由区域设成 255，模型很难学。最稳的方案就是三态分明：0黑、128灰、255白，中间概率留给下一步去精细化。
3.3 方向与坐标：为什么转换后经常上下颠倒
把data数组reshape成(height, width)之后，图像的行和列与地图坐标的关系有一个隐藏的坑。
OccupancyGrid 的data是按行优先排列的，一般情况下第 0 行对应地图中 y 比较小的区域，第height-1行对应 y 比较大的区域。但 OpenCV / matplotlib 显示图像时，第 0 行在屏幕最上方，y 轴方向向下。于是整张图很可能是上下颠倒的，具体表现就是地图里北边的障碍物跑到了图片的下方。
解决方式很简单，在完成灰度图后加一句cv2.flip(img, 0)或者np.flipud(img)。为什么说“很可能”而不是“一定”？因为这取决于地图的生成工具和info.origin的定义。有些建图算法会把 origin 放在左上角，有些放在左下角。所以我不建议你盲翻，正确做法是：拿一张有明显方向特征的地图（比如 L 形走廊或非对称结构）做基准，先转一张图看一眼，如果上下反了再加 flip。我现在的习惯是写转换函数时留一个flip_ud=False参数，调试时手动切一下，看哪一版和 RViz 对得上。
还有info.origin的偏移也不要忘记。图片是纯栅格索引，而你要把机器人坐标或全局坐标画到图上时，需要先减去 origin 的位置再除以resolution。这一步和颜色无关，但会直接影响你“验证颜色对不对”的效率——我建议先把地图原点对应的栅格画成一个十字符号，这样一眼能看出方向和偏移是否同步。
4. 最容易踩的三个显示坑：偏暗、全灰、上下颠倒的排查链路
4.1 偏暗或颜色反转：先检查是不是把 data 直接当成像素了
症状：整张图偏黑，自由区域黑乎乎一片，障碍物区域也只是深灰色。排查思路很简单——看看你的代码是不是写了cv2.imshow("map", data.astype(np.uint8))或者plt.imshow(data)。
问题本质是 8 位灰度图需要 0~255 的亮度分布，而 OccupancyGrid 的 data 最大值只有 100。如果把 100 当成亮度上限，画面整体亮度就低了三分之一以上，自由区域还是 0，必黑。
还有一种变体是data * 255，看着像归一化，实际是完全错误的：自由区域的 0 乘谁都还是 0，障碍物区域的 100 乘到 255 后还会被截断或溢出，颜色直接反转。正确做法必须按语义映射，而不是线性缩放。非要线性缩放的话，别用data * 255，要先用data / 100归一化到 0~1，再考虑要不要乘 255，并且想清楚 0 自由还是 0 黑色这个问题。
4.2 整张图灰蒙蒙：大概率是 -1 和 0 的处理顺序颠倒了
症状：地图正常显示，但自由区域的白色不明显，图上到处都是灰蒙蒙的一层，连障碍物边界都看不清。
这个我排查过很久，最后发现是因为先把data == -1的未知区域设成了128，然后又把所有data <= 0的区域整体设成了255。看起来没什么问题，但代码里如果先执行img[data <= 0] = 255，后执行img[data == -1] = 128，那没问题；顺序反了，未知区域的 128 就被覆盖成 255，未知区域变成白色，当然一片亮灰。反过来，如果先执行img[data == 100] = 0，后执行中间区间的映射，也可能覆盖障碍物的黑色。
这类坑的排查链路很固定：
- 打印
np.unique(data)和各个值的计数； - 把中间 1~99 的数量单独统计一下，确认是不是渐变区间在捣乱；
- 写一个 5x5 的小型测试地图，手动构造 -1、0、100 三个值，跑完转换函数后逐像素核对颜色；
- 确认无误后再拿到真实地图上跑。
这个“先用小地图验证逻辑”的习惯帮了我大忙。很多底图颜色问题根本不需要看真实数据，小地图一眼就能暴露逻辑 bug。
4.3 上下颠倒或左右镜像：用非对称地图一次定位
症状：颜色完全正常，但图一出来方向不对，像被翻转了。常见于保存 PNG 或 PGM 之后，拿图片查看器和 RViz 里的显示做对比。
原因在 3.3 里说过：OccupancyGrid 的坐标原点和图像坐标系原点不一致。但“上下还是左右”并不是固定答案。我的排查方法是：
- 找一张有明确方向特征的地图，比如手画一个“L”形走廊，或者让机器人在某个角落站一会儿，地图上会留下明显的未探测区域；
- 转成图片后，先看未探测区域的方向和 RViz 里差多少；
- 如果上下反了，用
cv2.flip(img, 0)；左右反了，用cv2.flip(img, 1)；两个都反了，先上下再左右。
提醒一句：cv2.flip的第二个参数，0 表示绕 x 轴翻转（上下），1 表示绕 y 轴翻转（左右），负值表示两个方向同时翻转。我早期抄代码时经常把 0 和 1 搞混，结果图越翻越离谱。现在每次写完转换函数，第一件事就是造一张不对称的小图验证，再也不靠猜了。
4.4 一张表记住症状、原因和检查点
| 症状 | 可能原因 | 检查点 |
|---|---|---|
| 整图偏黑，自由区域黑 | 直接把 data 当像素显示 | 打印 data max，确认是否只有 0~100 |
| 图的颜色像负片 | data * 255或用了gray_r | 检查有没有做语义映射，而不是线性缩放 |
| 整图灰蒙蒙 | -1 和 0 的处理顺序颠倒 | 用 5x5 小地图逐值验证 |
| 地图上下颠倒/左右镜像 | 图像坐标和地图坐标不一致 | 用非对称走廊地图做 flip 测试 |
| 图片边缘少了一块 | info.origin 偏移或分辨率换算错误 | 画地图原点十字标志，核对偏移公式 |
5. 扩展到 costmap：255 可不是占据概率
5.1 costmap 的数值语义和 OccupancyGrid 不是一码事
做导航规划的同学很快会遇到 costmap，也就是代价地图。如果你以为 costmap 的 data 值可以直接复用上面的转换函数，又会踩一次坑。
costmap_2d的底层数据同样是nav_msgs/OccupancyGrid类型，但数值含义完全不同。costmap 的数值定义大致如下：
| 数值 | 含义 | 在 RViz 中常见表现 |
|---|---|---|
| 0 | 自由区域，可以通行 | 白色 |
| 1 ~ 252 | 代价梯度，数值越大代表离障碍物越近、越不适合通行 | 从浅黄到红色渐变 |
| 253 | 未知区域，没有传感器信息 | 灰色 |
| 254 | 膨胀区域，机器人在此地会有碰撞风险（inscribed radius） | 深红或橙色 |
| 255 | 致命障碍物，该栅格就是障碍物本身 | 黑色 |
很容易被混淆的是：OccupancyGrid 里100代表“占据概率 100%”，而 costmap 里255代表“这个栅格几乎必然碰撞”。这两个数字差了一个量级，语义体系也完全不同。所以当你拿到一个话题名是move_base/global_costmap/costmap的消息时，别再试图找 100 这个值，那大概率会让你误判所有障碍物。
5.2 绘制 costmap 时不能照搬 OccupancyGrid 的映射表
我自己第一次画 costmap 时直接调用了前面写的occupancy_grid_to_image，结果自由区域还是白色没错，但障碍物区域完全没东西，因为 costmap 的障碍物数值是 255，我的映射表只处理了data == 100，于是255全部落到未知区域的灰色里去了。图一出来整片灰，只有道路是白的，跟一张“只有路的地图”似的。
给 costmap 做可视化，至少要区分这几档：
img = np.full((h, w), 128, dtype=np.uint8) # 默认未知灰 img[data == 0] = 255 # 自由区域白 img[data == 255] = 0 # 致命障碍黑 img[data == 254] = 80 # 膨胀区域深灰/暗色 # 253 保持 128 灰色 # 1~252 的代价梯度自己按需求映射如果你需要直观展示“哪些区域接近膨胀但还能走”，用彩色更好：自由区域绿色，膨胀区域黄色到红色，致命障碍黑色，未知区域灰色。这比纯灰度图更容易让非技术人员看懂。
5.3 颜色不一致时的排查建议：把数据和可视化分开看
现在项目里看到“图和实际不一致”的问题，我的第一反应永远是先去查数据语义，而不是调色板。先把data.min()、data.max()打出来，再统计一下253、254、255各有多少个，基本就能判断这份数据到底是 occupancy 地图还是 costmap，是哪一种配置。颜色只是最后一层的表达方式，数据语义没弄清楚之前，调出来的颜色都不可信。
另外，costmap 在不同参数下（例如 inflate radius 大小、track unknown 是否开启）数值分布差异会很大。我在调参时，会把 costmap 转成 png 存下来，和 RViz 的显示对照着看，这样能很快发现参数变化带来的空间范围变化，比光看数字直观得多。
6. 从调试到复用：几个让我省时间的命令和小技巧
6.1 快速查看地图数据分布的命令
调试地图显示，我几乎每次都先跑这几个命令，比直接写转换脚本更快定位数据形态。
# 看一眼消息基本信息 rostopic echo -n1 /map/info # 用 python 统计 data 分布 python3 - <<'EOF' import rospy from nav_msgs.msg import OccupancyGrid import numpy as np rospy.init_node("quick_check") msg = rospy.wait_for_message("/map", OccupancyGrid, timeout=10) arr = np.array(msg.data, dtype=np.int8) print("shape:", msg.info.height, "x", msg.info.width) print("min:", arr.min(), "max:", arr.max()) vals, counts = np.unique(arr, return_counts=True) print(dict(zip(vals.tolist(), counts.tolist()))) EOF运行完你就能立刻判断：这份地图是纯三值（只有 -1、0、100），还是带中间概率；如果是 costmap 类型的数据，你还会看到 253、254、255 这样的数值。这一步是后面所有颜色映射的决策依据。
6.2 一个帮你快速验证方向的“定位十字”技巧
我调试转换函数时，习惯在地图原点坐标对应的栅格位置画一个十字标记，然后看它在最终图片里的位置。具体实现：
# 假设知道地图原点在全局坐标中的位置 origin_x, origin_y # 栅格像素坐标 px = int((origin_x - msg.info.origin.position.x) / msg.info.resolution) py = int((origin_y - msg.info.origin.position.y) / msg.info.resolution) # 在原图上画十字（img 是转换后的灰度图） img[py-2:py+3, px] = 0 img[py, px-2:px+3] = 0如果这个十字在图片中的位置和 RViz 里的原点位置对得上，说明方向和偏移都正确；如果对不上，要么是 flip 需要调整，要么是 origin 计算有误。这个方法比盯着走廊轮廓猜快得多，尤其当天花板上的特征很对称、没有明显方向感时。
6.3 小地图单元测试：颜色转换的正确打开方式
最后分享一个我强烈推荐的做法：写完转换函数后，先手工构造一个 5x5 的地图消息，把 -1、0、100、50 这几个代表值都塞进去，然后逐一核对输出图片的每个像素值。
这样做的好处是能把“数据语义判断”和“可视化实现”彻底解耦。真实地图上如果颜色不对，你可能要同时怀疑坐标、方向、数据源、映射逻辑；小地图上则只有映射逻辑一个变量，错误一眼现形。等小地图全对了，再拿真实地图跑，通常剩下的只是 flip 方向和 origin 偏移这两个问题。
我就是靠这套“先统计、再小图、后真实图”的流程，把自己从“调一晚上颜色”的泥潭里拉出来的。现在新拿到任何一张 OccupancyGrid 或 costmap 数据，流程都稳定在一个小时之内，地图显示也基本不会成为项目卡点。
