Autoware.Universe 样例运行：高精地图部署到 ~/autoware-map 与排错指南

简介：本资源面向正在搭建 Autoware.Universe 自动驾驶开发环境的开发者与学习者，提供一份可直接用于验证安装是否成功的高精地图样例数据。资源包共 4 个文件，包含 2 个 yaml 配置文件、1 个 pcd 点云地图、1 个 osm 矢量地图，压缩包约 15.15MB，体积轻量便于快速部署到 ~/autoware_map 目录。其中 yaml 用于地图投影与配置参数，pcd 承载三维点云环境信息，osm 提供车道级矢量路网，三者配合可支撑路径规划与定位模块的基本运行。目前已有 1146 人学习下载，适合刚完成 Autoware.Universe 安装、需要跑通官方样例来确认环境可用性的初学者，也可作为后续仿真实验与算法调试的基础地图素材，帮助读者省去自行寻找与整理地图数据的时间。

1. 把高精地图塞进 ~/autoware-map：Autoware.Universe 样例跑通的第一道坎

很多人第一次在 Autoware.Universe 里点开样例仿真，车是能动的，但地图区域一片灰，RViz 里看不到车道线，Planning 模块直接报找不到 map。问题往往不在算法，而在高精地图根本没被放到正确的位置。Autoware.Universe 默认约定地图根目录是~/autoware-map，里面按map_path、lanelet2_map.osm、pointcloud_map这套结构组织。标题里说的「运行样例 高精地图到 ~/autoware-map」，本质就是让样例仿真能读到一份合规的 Lanelet2 矢量地图加一份点云地图。这件事适合两类人：一类是刚装完 Autoware.Universe、想先跑通官方样例的新手；另一类是手里有自己采集的地图、想替换进样例验证感知和规划链路的工程师。下面按「目录结构 → 地图来源 → 启动验证 → 排错」的顺序拆开讲，每一步都能直接抄。

2. 先搞清 ~/autoware-map 的目录约定与地图格式

2.1 为什么是 ~/autoware-map 而不是随便一个路径

Autoware.Universe 的 launch 文件里，地图加载节点默认会去读一个叫map_path的参数，而这个参数在样例 launch 中通常被写成~/autoware-map。这里的~是当前用户的家目录，不是 shell 里随便展开的变量。也就是说，如果你用root跑，它找的是/root/autoware-map；用普通用户跑，找的是/home/你的用户名/autoware-map。很多人把地图放在/tmp或者工程目录下，然后手动改 launch 参数，结果一升级代码参数又被覆盖，这就是典型的「玄学找不到地图」。最稳的做法是尊重默认约定，把地图放到~/autoware-map，让样例 launch 零修改就能跑。

这个目录不是随便放几个文件就行，它有一套固定结构。常见做法是：

~/autoware-map/ ├── map_path/ │ ├── lanelet2_map.osm │ ├── pointcloud_map/ │ │ ├── pointcloud_map_0.pcd │ │ ├── pointcloud_map_1.pcd │ │ └── ... │ └── map_projector_info.yaml

lanelet2_map.osm是矢量地图，描述车道、路口、停止线、信号灯关联；pointcloud_map目录里是切好的 PCD 点云瓦片；map_projector_info.yaml记录地图原点的投影信息。少任何一个，地图加载节点都可能只加载一半，表现就是 RViz 里只有点云没有车道线，或者只有车道线没有地面。

2.2 Lanelet2 与 PCD 各自负责什么

Lanelet2 是 Autoware 里描述道路拓扑的标准格式，基于 OpenStreetMap 的 XML 结构扩展而来。它把道路拆成 lanelet（车道段），每个 lanelet 有左右边界线、中心线，以及和前后 lanelet 的连接关系。Planning 模块靠它算路由，Control 模块靠它算参考线。PCD 点云则是给感知和定位用的，NDT 或 EKF 定位会把实时激光和这份点云做匹配，得到车辆在地图里的位姿。两者缺一不可：只有 Lanelet2，定位飘；只有 PCD，规划不知道往哪走。

map_projector_info.yaml容易被忽略，但它决定了地图坐标和经纬度之间的换算。样例里常见内容是：

projector_type: Local map_origin: latitude: 35.0 longitude: 139.0

如果你用的是自己采集的地图，这个原点必须和采集时记录的一致，否则定位会整体偏移几十米，看起来像「车在路外跑」。

2.3 样例地图从哪来，能不能自己换

Autoware.Universe 官方样例通常自带一份小范围地图，放在某个 sample 包里。你可以直接把它拷到~/autoware-map下先用起来：

# 假设样例地图在某个已安装的 share 目录下 mkdir -p ~/autoware-map cp -r /path/to/sample_map/* ~/autoware-map/

注意这里的/path/to/sample_map要换成你环境里实际存在的样例地图路径，不同安装方式位置不一样，用ros2 pkg prefix配合包名去找更稳。拷完之后检查map_path下是否有lanelet2_map.osm和pointcloud_map目录。

想换成自己采集的地图，流程是：先用建图工具生成 PCD 和 Lanelet2，再按上面结构放好。Lanelet2 的生成可以用 Vector Map Builder 之类的工具，也可以从其他格式转换。转换时最容易翻车的是坐标系：Lanelet2 默认用地图局部坐标，单位是米，如果你从经纬度直接转，必须经过投影，否则车道线会扭曲。

3. 把地图放对位置并让样例真正读进去

3.1 拷贝与目录校验的最小命令集

放地图这件事本身不复杂，复杂的是放完之后怎么确认它真的被读到了。我一般会按下面这套命令走一遍：

# 1. 建目录 mkdir -p ~/autoware-map/map_path/pointcloud_map # 2. 拷贝矢量地图 cp lanelet2_map.osm ~/autoware-map/map_path/ # 3. 拷贝点云瓦片 cp pointcloud_map/*.pcd ~/autoware-map/map_path/pointcloud_map/ # 4. 拷贝投影信息 cp map_projector_info.yaml ~/autoware-map/map_path/ # 5. 校验文件是否齐全 ls -lh ~/autoware-map/map_path/ ls -lh ~/autoware-map/map_path/pointcloud_map/ | head

第 5 步的ls不是走形式。如果pointcloud_map目录是空的，或者 PCD 文件大小为 0，后面启动时地图加载节点会报「no pointcloud map found」，但错误信息不一定直接指向目录为空，容易误判成定位问题。

3.2 启动样例并确认地图加载

Autoware.Universe 的样例启动方式通常是跑一个 launch 文件，具体名字随版本变化，常见的是sample_vehicle_launch或planning_simulator相关。启动前先 source 环境：

source /opt/ros/humble/setup.bash source ~/autoware/install/setup.bash

然后启动样例：

ros2 launch autoware_launch planning_simulator.launch.xml \ map_path:=$HOME/autoware-map \ vehicle_model:=sample_vehicle \ sensor_model:=sample_sensor_kit

这里显式把map_path传进去，是为了避免默认值和你实际目录不一致。启动后重点看两个地方：一是终端里地图加载节点有没有报错；二是 RViz 里有没有出现车道线和点云。如果 RViz 里地图区域是空的，先别怀疑 RViz 配置，去终端里搜lanelet2_map和pointcloud_map相关的日志。

3.3 用 ros2 topic 验证地图话题是否发布

地图加载成功后，会发布若干话题。可以用下面命令确认：

# 查看地图相关话题 ros2 topic list | grep -E "map|lanelet" # 查看矢量地图话题是否有数据 ros2 topic echo /map/vector_map --once # 查看点云地图话题 ros2 topic echo /map/pointcloud_map --once

如果/map/vector_map一直没有输出，说明 Lanelet2 没加载成功，常见原因是 osm 文件格式不对或者路径没传对。如果/map/pointcloud_map有输出但 RViz 里看不到，检查 RViz 的 Fixed Frame 是不是设成了map，以及点云显示插件的 Topic 有没有选对。

提示：样例启动时如果同时开了多个终端，注意每个终端都要 source 环境，否则ros2 topic list可能看不到地图话题。

4. 地图加载失败的排查：从日志到参数逐层定位

4.1 先看日志里地图加载节点说了什么

地图加载失败时，终端里通常会有类似Failed to load lanelet2 map或pointcloud map path does not exist的日志。不要只看最后一行，往上翻几行，找到第一个报错的位置。常见日志模式：

• cannot find file：路径不对，检查map_path参数和实际目录。
• failed to parse：osm 文件格式有问题，可能是 XML 不完整或标签不合法。
• projector info not found：缺map_projector_info.yaml，或者文件内容格式不对。

如果日志被刷屏了，可以用grep过滤：

ros2 launch ... 2>&1 | grep -i -E "map|lanelet|pointcloud"

4.2 路径、权限、坐标系三类高频问题

路径问题最常见。~在 launch 参数里不一定被展开，显式写成$HOME/autoware-map更稳。权限问题次之，如果地图文件是 root 创建的，普通用户跑样例时读不了，表现也是加载失败。用ls -l看文件属主，必要时chmod或chown。

坐标系问题更隐蔽。Lanelet2 地图和点云地图必须在同一个坐标系下，否则 RViz 里两者会错位。检查map_projector_info.yaml里的projector_type和map_origin，确保和地图生成时一致。如果点云看起来正常但车道线整体偏移，大概率是投影原点不一致。

4.3 用 rviz 配置和 tf 树交叉验证

RViz 里看不到地图，不一定是地图没加载。先确认 TF 树里有没有map到base_link的变换：

ros2 run tf2_tools view_frames

生成的frames.pdf里如果map和base_link之间断开了，RViz 就无法把地图显示到正确位置。这时候要检查定位模块有没有正常输出，样例里通常需要手动给一个初始位姿。在 RViz 里用2D Pose Estimate点一下车辆大概位置，地图往往就出来了。

5. 避坑：地图替换与样例复现中的五个血泪教训

5.1 现象：RViz 里只有点云没有车道线

原因：Lanelet2 地图没加载成功，但点云加载成功了。两者是独立加载的，一个失败不影响另一个。常见原因是lanelet2_map.osm文件名不对，或者 osm 内容里缺少relation标签，导致解析器认为没有有效 lanelet。

解决：先确认文件名严格是lanelet2_map.osm，再检查 osm 文件里有没有<relation>节点。可以用grep -c "relation" lanelet2_map.osm快速看数量，如果是 0，说明地图本身有问题，需要重新生成。

5.2 现象：地图加载成功但车辆定位飘到地图外

原因：map_projector_info.yaml里的原点和你采集地图时的原点不一致，或者点云地图和矢量地图用的不是同一套坐标。定位模块拿实时激光去匹配点云，匹配结果再投影到地图坐标，原点不一致就会整体偏移。

解决：核对map_origin的经纬度，确保和建图时记录的一致。如果点云和矢量地图来自不同批次，最好重新用同一套流程生成，避免混用。

5.3 现象：启动时报map_path参数找不到

原因：launch 文件里参数名和你传的不一致，或者你用的 launch 文件根本不接受map_path参数。不同版本的 Autoware.Universe 参数名可能有差异。

解决：用ros2 launch <pkg> <launch_file> --show-args查看支持的参数列表，确认参数名。如果确实不支持，就按默认路径放地图，不改参数。

5.4 现象：点云地图加载后 RViz 卡顿严重

原因：PCD 瓦片太大或者数量太多，RViz 一次性渲染压力大。样例地图通常已经切好，但自己采集的地图可能是一个巨大的 PCD。

解决：用点云切分工具把大 PCD 切成小瓦片，放到pointcloud_map目录下。切分时注意瓦片之间要有重叠，避免边界处出现空洞。同时可以在 RViz 里降低点云显示的点大小和密度。

5.5 现象：换了地图后 Planning 模块报找不到路由

原因：Lanelet2 地图里的 lanelet 连接关系不完整，比如路口处缺少regulatory_element或relation，导致路由搜索失败。

解决：用 Lanelet2 的可视化工具检查地图拓扑，重点看路口和车道变化处。如果只是跑样例验证，建议先用官方样例地图跑通，再逐步替换成自己的地图，这样能快速区分是环境问题还是地图问题。

6. 进阶：用脚本一键校验地图目录并生成启动命令

跑通一次之后，我习惯把校验逻辑写成脚本，避免每次换地图都手动ls。下面这个脚本检查目录结构、文件存在性和基本内容，最后打印出启动命令：

#!/usr/bin/env bash # check_autoware_map.sh # 校验 ~/autoware-map 目录是否符合 Autoware.Universe 样例要求 MAP_ROOT="$HOME/autoware-map" MAP_PATH="$MAP_ROOT/map_path" PCD_DIR="$MAP_PATH/pointcloud_map" OSM_FILE="$MAP_PATH/lanelet2_map.osm" PROJ_FILE="$MAP_PATH/map_projector_info.yaml" fail=0 # 检查根目录 if [ ! -d "$MAP_ROOT" ]; then echo "[FAIL] 缺少目录: $MAP_ROOT" fail=1 fi # 检查矢量地图 if [ ! -f "$OSM_FILE" ]; then echo "[FAIL] 缺少 lanelet2_map.osm" fail=1 else rel_count=$(grep -c "<relation" "$OSM_FILE" 2>/dev/null || echo 0) if [ "$rel_count" -eq 0 ]; then echo "[WARN] lanelet2_map.osm 里没有 relation，可能不是有效 Lanelet2 地图" else echo "[OK] lanelet2_map.osm 包含 $rel_count 个 relation" fi fi # 检查点云目录 if [ ! -d "$PCD_DIR" ]; then echo "[FAIL] 缺少 pointcloud_map 目录" fail=1 else pcd_count=$(find "$PCD_DIR" -name "*.pcd" | wc -l) if [ "$pcd_count" -eq 0 ]; then echo "[FAIL] pointcloud_map 目录下没有 pcd 文件" fail=1 else echo "[OK] 找到 $pcd_count 个 pcd 文件" fi fi # 检查投影信息 if [ ! -f "$PROJ_FILE" ]; then echo "[WARN] 缺少 map_projector_info.yaml，定位可能异常" else echo "[OK] 找到 map_projector_info.yaml" fi if [ "$fail" -eq 0 ]; then echo "" echo "校验通过，可用以下命令启动样例：" echo "ros2 launch autoware_launch planning_simulator.launch.xml \\" echo " map_path:=$MAP_ROOT \\" echo " vehicle_model:=sample_vehicle \\" echo " sensor_model:=sample_sensor_kit" else echo "" echo "校验未通过，请先修复上述问题。" exit 1 fi

脚本里几个关键点：grep -c "<relation"用来粗略判断 osm 是否是 Lanelet2 结构，虽然不是严格解析，但能挡住大部分空文件或错误格式；find ... -name "*.pcd" | wc -l统计点云瓦片数量，避免目录存在但为空；最后打印的启动命令显式带上map_path，减少路径歧义。这个脚本我一般放在~/autoware-map/同级，换地图后先跑一遍，比直接启动再翻日志快得多。

还有一个习惯：每次替换地图后，先在 RViz 里用2D Pose Estimate给一个初始位姿，看地图和点云是否对齐。对齐了再跑规划，不对齐就先查投影信息。这个顺序能省掉很多「以为是算法问题、其实是地图问题」的排查时间。希望帮到你。

本文还有配套的精品资源，点击获取