6. 建图与重定位建议调用流程

6.1 文档说明

本文档介绍典型场景下建议的建图 & 重定位功能调用流程。

6.2 概念说明

设备：Odin1 设备
主机：连接 Odin1 并运行上位机调用 API 的设备
设备运行模式：Odin1 提供【算法】和【传感器】两种主要运行模式
传感器运行模式：设备仅上传所有传感器原始数据
算法运行模式：Odin1 设备内部算法的运行模式，分别是里程计模式、SLAM 模式、和重定位模式
地图文件：Odin1 内部算法在 SLAM 模式下生成的特殊格式地图文件

6.3 整体流程

建议将设备初始化开流后保持与设备连接，通过特定 API 对设备工作模式（raw / slam）、算法工作模式（odom / 建图 / 重定位）、以及特定数据流的开关进行控制，确保设备响应速度，避免与设备反复重连及设备内部反复重新初始化。

6.4 具体流程

6.4.1 设备连接 & 初始化

// 初始化 sdk，准备与设备连接
lidar_system_init(lidar_device_callback_t cb);

// lidar_device_callback 内处理设备连接：
lidar_create_device(lidar_device_info_t *dev_info, device_handle *device);

// 获取设备版本
lidar_get_version(device_handle device);

// 获取标定文件
lidar_get_calib_file(device_handle device, const char* path);

// 注册数据回调
lidar_register_stream_callback(odinDevice, data_callback_info);

// 初始化设备
lidar_open_device(device_handle device);

6.4.2 （可选）设备连接 & 初始化状态下，开启加密设备日志保存

// 在收到设备回调（device_cb）后、调用 lidar_open_device 之前调用
// 设备运行期间产生的加密日志会持续写入 dest_dir 指定的目录
// dest_dir 必须是已存在的目录，建议每次连接使用独立子目录便于归档

const char* dest_dir = "/home/user/odin_logs/Conn_20260610_101530";
int ret = lidar_enable_encrypted_device_log(odinDevice, dest_dir);
// 返回 0 表示开启成功，-1 表示失败

// 不需要"关闭日志"接口；不调用本 API 即不启用日志
// 排障时将 dest_dir 整目录打包发回厂商支持即可

说明：

该接口必须在 lidar_open_device 之前调用，否则会丢失启动期日志；
dest_dir 不会被 SDK 自动创建，需要客户自行 mkdir -p（或 std::filesystem::create_directories）；
与 6.4.4 保存地图不同，本接口无需轮询，也无需再用单独的 API 把日志从设备拉到主机——日志会由 SDK 在主机端持续写入 dest_dir；
对应到 ROS 驱动里 control_command.yaml 的 save_log: 1，纯 SDK 客户不需要这个 yaml，直接调用本 API 即可。

参考实现见 host_sdk_sample.cpp（device_cb 内 g_save_log 分支），头文件声明见 lidar_api.h。

6.4.3 建图：设备连接 & 初始化状态下，开始建图

// 使能内部算法
int type = LIDAR_MODE_SLAM;
lidar_set_mode(odinDevice, type);

// 配置算法运行模式至 SLAM 模式: 将 "map_mode" 参数设置为 1
// "map_mode" 设置不同的值对应分别为
// 0: 正常里程计模式
// 1: 建图 SLAM 模式
// 2: 重定位模式
lidar_set_custom_parameter(device_handle device, const char* param_name, const void* value_data, size_t value_length);

// 将保存地图标志位 "save_map" 参数初始化为 0
lidar_set_custom_parameter(device_handle device, const char* param_name, const void* value_data, size_t value_length);

// 设备开流，算法开始运行，可以开始移动设备正常建图
lidar_start_stream(device_handle device, int type, uint32_t &dtof_subframe_odr);

6.4.4 建图：设备连接 & 初始化 & 建图状态下，保存 & 获取地图

// 设备内部保存当前建图文件：将 "save_map" 参数设置为 1
lidar_set_custom_parameter(device_handle device, const char* param_name, const void* value_data, size_t value_length);

// 查询建图文件是否保存完成：读取到 "save_map" 参数由 1 变 0
int value = 0;
int result = lidar_get_custom_parameter(odinDevice, "save_map", &value);

// 当设备内部地图保存完成后，获取设备中的地图文件至主机
lidar_get_mapping_result(device_handle device, const char* dest_dir, const char* file_name);

// 保存地图并不会停止建图，可选择继续运行并再次保存 & 获取地图

6.4.5 建图：设备连接 & 初始化 & 建图状态下，取消建图

// 将设备切换到传感器模式，保留原始传感器输出，关闭内部算法
int type = LIDAR_MODE_RAW;
lidar_set_mode(odinDevice, type);

// 如需完全停止内部算法和数据输出，调用以下 api
// lidar_stop_stream(device_handle device, int type);

// 重新执行 6.4.3 即可重新开始建图

6.4.6 重定位说明

该模式要求 Odin1 在 SLAM 模式生成并上传的地图文件，用于传入设备运行重定位。

6.4.7 重定位：设备连接 & 初始化状态下，开始重定位

// 配置算法运行模式至重定位模式: 将 "map_mode" 参数设置为 2
// "map_mode" 设置不同的值对应分别为
// 0: 里程计模式
// 1: SLAM 模式
// 2: 重定位模式
lidar_set_custom_parameter(device_handle device, const char* param_name, const void* value_data, size_t value_length);

// 指定和传入重定位使用的地图文件，不传入则无法正常运行
lidar_set_relocalization_map(device_handle device, const char* abs_path);

// 设备开流，算法开始运行
lidar_start_stream(device_handle device, int type, uint32_t &dtof_subframe_odr);

6.4.8 重定位：设备连接 & 初始化 & 建图状态下，停止重定位

// 将设备切换到传感器模式，保留原始传感器输出，关闭内部算法
int type = LIDAR_MODE_RAW;
lidar_set_mode(odinDevice, type);

// 如需完全停止内部算法和数据输出，调用以下 api
// lidar_stop_stream(device_handle device, int type);

// 重新执行 6.4.7 即可重新开始重定位

6.5 流程图总结

流程图总结