6. 建图与重定位 API
6.1 文档说明
本文档介绍 Odin1 Lite 建图(SLAM)与重定位(Relocalization)功能的 ROS Service 调用方式及典型工作流程。
重定位由与固件版本匹配的 ROS Driver 和
manifold-lc-sdk算法 deb 包共同提供。仅部署 ROS Driver 时可获取传感器数据,无法运行建图和重定位算法;算法 deb 的安装方式参见 9. 重定位功能使用说明。
6.2 概念说明
| 术语 | 说明 |
|---|---|
| 设备 | Odin1 Lite 模组 |
| 主机 | 连接 Odin1 Lite 并运行 ROS 驱动的 PC / 机器人 |
| Device Mode | 设备工作模式,通过 device_mode 服务切换 |
| Normal(1) | 正常里程计模式,设备输出 odom / 点云等数据 |
| SLAM(3) | 建图模式,算法边运行边构建回环地图 |
| Relocation(4) | 重定位模式,加载已保存地图进行位置重定位 |
| ReMap(5) | 重定位 + 增量建图模式,在已载入地图基础上扩展地图 |
| 地图文件 | SLAM / ReMap 模式下由算法生成的二进制地图文件(.bin) |
6.3 相关 ROS Service
所有服务前缀为
/{topic_prefix}/device{N}/(默认/manifold/device0/)。ℹ️ 设备型号不再出现在话题/服务路径中;型号与 SN 由
/{topic_prefix}/driver/device_online的 JSON 字段发布。
| 服务 | 类型 | 说明 |
|---|---|---|
device_mode | DeviceMode | 切换工作模式:0=Standby / 1=Normal / 2=Upgrade / 3=SLAM / 4=Relocation / 5=ReMap |
save_map | SaveMap | 保存当前回环地图到指定路径 |
load_map | LoadMap | 加载已保存的地图文件用于重定位或 ReMap |
exploy_map | ExployMap | 将当前闭环地图导出到主机文件(具体格式由插件实现) |
服务定义
DeviceMode.srv
uint8 mode # 0=Standby 1=Normal 2=Upgrade 3=SLAM 4=Relocation 5=ReMap
---
bool success
int32 error_code # 0=OK, 其它为 SDK OdinResult 枚举
string message
SaveMap.srv
string path # 输出地图文件路径(主机本地路径)
---
bool success
int32 error_code
string message
LoadMap.srv
string path # 输入地图文件路径(主机本地路径)
---
bool success
int32 error_code
string message
6.4 典型流程
6.4.1 建图流程
步骤 1:启动驱动
# ROS2
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py
# ROS1
roslaunch odin_ros_driver_rev1 odin1Lite.launch
步骤 2:切换到 SLAM 模式(开始建图)
执行前请先进入 ROS 工作目录并 source 环境:
cd ~/catkin_ws source install/setup.bash # ROS2 # source devel/setup.bash # ROS1
# ROS2
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 3}"
# ROS1
rosservice call /manifold/device0/device_mode "{mode: 3}"
此时设备进入 SLAM 建图模式,可移动设备开始建图。
步骤 3:保存地图
建图完成后,调用 save_map 将地图保存到主机本地文件:
# ROS2
ros2 service call /manifold/device0/save_map \
odin_ros_driver_rev1/srv/SaveMap "{path: '/tmp/odin_map.bin'}"
# ROS1
rosservice call /manifold/device0/save_map "path: '/tmp/odin_map.bin'"
保存地图不会停止建图,可继续运行并再次保存。
步骤 4:停止建图(可选)
切回 Normal 模式:
# ROS2
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"
# ROS1
rosservice call /manifold/device0/device_mode "{mode: 1}"
6.4.2 重定位流程
前提:已通过上述建图流程保存了地图文件。
步骤 1:切换到 Relocation 模式
执行前请先进入 ROS 工作目录并 source 环境:
cd ~/catkin_ws source install/setup.bash # ROS2 # source devel/setup.bash # ROS1
# ROS2
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 4}"
# ROS1
rosservice call /manifold/device0/device_mode "{mode: 4}"
步骤 2:加载地图
# ROS2
ros2 service call /manifold/device0/load_map \
odin_ros_driver_rev1/srv/LoadMap "{path: '/tmp/odin_map.bin'}"
# ROS1
rosservice call /manifold/device0/load_map "path: '/tmp/odin_map.bin'"
加载成功后,设备开始运行重定位算法。请根据应用侧的定位状态与位姿输出确认重定位结果。
步骤 3:停止重定位
# ROS2
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"
# ROS1
rosservice call /manifold/device0/device_mode "{mode: 1}"
6.4.3 ReMap 流程(增量建图)
ReMap(mode: 5)在已保存地图的基础上进行重定位,同时扩展地图。适用于需要在已有地图中追加新区域的场景。
步骤 1:切换到 ReMap 模式并加载已有地图
# ROS2
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 5}"
ros2 service call /manifold/device0/load_map \
odin_ros_driver_rev1/srv/LoadMap "{path: '/tmp/odin_map.bin'}"
在 RViz 中将 Fixed Frame 设为 device0/map 即可查看已载入地图。
步骤 2:移动设备采集新区域
算法会在旧地图基础上进行定位,并增量构建新的地图内容。
步骤 3:保存扩展后的地图
ros2 service call /manifold/device0/save_map \
odin_ros_driver_rev1/srv/SaveMap "{path: '/tmp/odin_map_extended.bin'}"
增量保存后的地图通常比原始地图更大。
步骤 4:停止 ReMap
ros2 service call /manifold/device0/device_mode \
odin_ros_driver_rev1/srv/DeviceMode "{mode: 1}"
6.4.4 loop-closure 可视化话题
在 SLAM / Relocation / ReMap 模式下,算法会发布以下 loop-closure 可视化话题:
| 话题后缀 | 类型 | 说明 |
|---|---|---|
loop_closure/optimization_busy | std_msgs/Bool | 优化器是否正在运行 |
loop_closure/optimization_status_marker | visualization_msgs/Marker | 文本标记显示 IDLE / OPTIMIZATION |
loop_closure/optimized_path | nav_msgs/Path | local_map 坐标系下优化后的轨迹 |
loop_closure/optimized_cloud | sensor_msgs/PointCloud2 | local_map 坐标系下优化后的全局点云 |
loop_closure/map_cloud | sensor_msgs/PointCloud2 | map 坐标系下加载的地图点云 |
这些话题由
manifold-lc-sdk算法包产生;仅当算法 deb 包装好且设备处于 SLAM / Relocation / ReMap 模式时才会出现。
6.5 流程图总结
┌─────────────────────────────────────────────────────────┐
│ 启动 ROS 驱动 │
└───────────────────────┬─────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 建图 (SLAM) │ │重定位(Reloc)│ │ReMap(增量建图)│
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
▼ ▼ ▼
device_mode device_mode device_mode
mode: 3 mode: 4 mode: 5
│ │ │
▼ ▼ ▼
移动设备建图 load_map 加载 load_map 加载
│ 已有地图 已有地图
▼ │ │
save_map 保存 ▼ ▼
│ 应用侧确认 移动设备扩展地图
▼ │ │
device_mode ▼ ▼
mode: 1 device_mode save_map 保存
(回到 Normal) mode: 1 device_mode mode: 1
(回到 Normal) (回到 Normal)
└─────────────────────────────────────────────────────────┘
6.6 注意事项
save_map和load_map的path参数为主机本地路径,请确保该路径可写 / 可读。- 空路径返回
error_code=2(kInvalidArgument);设备未连接或算法会话未就绪返回error_code=1(kNotInitialized)。 save_map应在 SLAM(mode: 3)或 ReMap(mode: 5)模式下调用;load_map应在 Relocation(mode: 4)或 ReMap(mode: 5)模式下调用。mode超出0~5范围时返回kInvalidArgument。- 典型流程:
- 建图:
device_mode mode: 3→save_map→device_mode mode: 1 - 重定位:
device_mode mode: 4→load_map→device_mode mode: 1 - ReMap:
device_mode mode: 5→load_map→save_map→device_mode mode: 1
- 建图:
- 服务调用成功后会更新驱动的期望模式,用于设备重连后的状态恢复。