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 注意事项

  1. save_map 和 load_map 的 path 参数为主机本地路径,请确保该路径可写 / 可读。
  2. 空路径返回 error_code=2(kInvalidArgument);设备未连接或算法会话未就绪返回 error_code=1(kNotInitialized)。
  3. save_map 应在 SLAM(mode: 3)或 ReMap(mode: 5)模式下调用;load_map 应在 Relocation(mode: 4)或 ReMap(mode: 5)模式下调用。
  4. mode 超出 0~5 范围时返回 kInvalidArgument。
  5. 典型流程:
    • 建图: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
  6. 服务调用成功后会更新驱动的期望模式,用于设备重连后的状态恢复。

← 上一章:数据输出 | 下一章:Odin1 Lite 快速启动(Ubuntu)→


中文 | EN
This site uses Just the Docs, a documentation theme for Jekyll.