Z-Localization

Z-Localization 是一套面向移动机器人的 ROS 2 激光惯性定位栈，支持里程计、点云建图、先验地图定位、 回环与重定位，也可接入 UWB 提供位置辅助。实机运行与 rosbag 回放使用同一套入口，输出位姿、速度、协方差和定位状态。

项目包含 ZLIO 前端、定位后端、统一启动入口，以及地图处理和车体外参标定工具。 ZLIO 可以单独作为里程计使用，后端也提供独立里程计与点云接口，方便适配已有的 LIO 前端及奥丁之眼等定位模块。

地图制作也在项目范围内：保存实测地图、清理动态残影、配合 CloudCompare 精修，再生成用于定位的先验地图包。

前后端的设计思路、尝试和取舍，整理在设计说明中。

由于作者的代码质量实在有点拉胯，项目借助 AI 做过整理与优化，并经过人工审查。建议配合 AI 食用，发现问题欢迎提 Issue 或 PR。

如果这个项目对你有帮助，欢迎点个 Star ⭐，给作者一点更新动力（虽然大概率不会再更新了，除非有重大 bug，相信后人的智慧 (￣▽￣)ゞ）。

环境与依赖 · 配置示例 · 无先验地图的实时定位 · 从 bag 建图到先验定位 · 更多文档 · 联系作者

完整 ROS 包与测试依赖见前端说明和后端说明。

配置入口为 config/lio.yaml 和 config/backend.yaml。 仓库中的安装外参、场地路径和 UWB 设置来自作者的设备，不是通用标定结果。

参数确实不少，作者对此负全责 (；´д｀)ゞ。请务必认真看前端调参指南和后端调参指南，尤其是传感器、外参与时间相关的部分。

bag 建图流程以 Mid-360 + Livox CustomMsg、关闭 UWB、使用 Scan Context 为例。 场地配置 pcd/site.yaml：

extends: ../config/backend.yaml
uwb:
  enabled: false
trajectory:
  save_directory: pcd/site_raw
  save_global_pcd: true
  save_on_shutdown: false

没有先验地图、又需要实时全局位姿时，使用 mode:=mapping，将场地配置中的 uwb.enabled 设为 true 并接入 UWB。 实机运行使用 use_sim_time:=false，需要一并启动 Mid-360 驱动时追加 driver:=true。

正式使用定位前，先启动程序并让机器人移动几米（默认需要至少 3 m 的水平位移跨度）， 待定位状态进入 NORMAL 后再使用全局位姿。UWB 配置见调参指南。

回放建图 → 保存地图 → 自动清理 → CloudCompare 精修 → 网格生成地图包与描述子 → 先验定位。

以下命令在项目根目录执行，使用上面的 pcd/site.yaml。

ros2 launch bringup bringup.launch.py \
  frontend_config:="$PWD/config/lio.yaml" \
  backend_config:="$PWD/pcd/site.yaml" \
  mode:=mapping use_sim_time:=true rviz:=true

另一个终端播放 bag：

ros2 bag play /absolute/path/to/bag --clock

从头重播前，重新启动定位程序。

回放结束后停止输入，待末尾观测和地图更新完成再保存：

ros2 service call /stop std_srvs/srv/Trigger "{}"

# 地图更新完成后执行
ros2 service call /backend_node/save_map std_srvs/srv/Trigger "{}"

返回 success: true 后再退出节点，结果在 pcd/site_raw/。 保留完整地图包，后续清理需要其中的关键帧和局部点云；同一目录再次保存会更新原有结果。

ros2 run backend clean_map_bundle \
  --in "$PWD/pcd/site_raw" \
  --out "$PWD/pcd/site_auto_clean" \
  --lidar-origin -0.011 -0.02329 0.04412

这里的雷达光心位置对应默认 Mid-360 外参，在 IMU 系中表达。 清理及后续生成工具的输出目录须不存在或为空。

过滤思路参考 FreeDOM。按作者的实测体验，这一步非常有效， 能大幅减少手工清理的工作量，但结果仍不足以直接使用（尤其是在适应性训练阶段如此恶劣的环境下）。

用 CloudCompare 打开 pcd/site_auto_clean/map.pcd，去掉剩余动态残影和噪点， 调平地图并调整世界系原点，另存为 pcd/site_refined.pcd。

雷达水平安装时，作者建议精修后重新按网格生成。 按作者的使用经验，这样生成的描述子通常比建图时直接保存的质量更好。

下面以 X：0–28 m、Y：0–15 m、采样 Z 坐标 0 m、雷达离地高度 0.35 m 为例，范围和高度按调整后的地图填写。

ros2 run backend build_pcd_map_bundle \
  --input "$PWD/pcd/site_refined.pcd" \
  --out-bundle "$PWD/pcd/site_prior" \
  --x-min 0 --x-max 28 --y-min 0 --y-max 15 \
  --sensor-z 0.0 --bundle-step 1.5 \
  --map-voxel 0.15 --scan-voxel 0.4 \
  --descriptor-type scan_context --sc-lidar-height 0.35

--sensor-z 是地图中的采样高度坐标，--sc-lidar-height 是离地高度，两者不一定相等。 本例按水平姿态、固定高度生成；描述子配置须与定位时一致，其余选项见工具参数。

ros2 launch bringup bringup.launch.py \
  frontend_config:="$PWD/config/lio.yaml" \
  backend_config:="$PWD/pcd/site.yaml" \
  mode:=localization prior_map:="$PWD/pcd/site_prior" \
  use_sim_time:=true rviz:=true

另一个终端回放验证：

ros2 bag play /absolute/path/to/bag --clock

实机运行时使用 use_sim_time:=false，追加 driver:=true 可一并启动 Livox Mid-360 驱动。 driver 默认 false，回放 bag 或已单独启动驱动时保持关闭；驱动使用 MID360_config.json 中的网络配置，输出 Livox CustomMsg。

作者：mozihe

• 邮箱：zhujunheng2005@gmail.com
• QQ：820288431

本项目采用 GPL-2.0-only。第三方组件保留各自许可证。