mozihe/z-localization

Z-Localization is a ROS 2 LiDAR-inertial localization stack for mobile robots, released by Northeastern University's T-DT lab as part of its RoboMaster sentry work. It bundles a front-end odometry module (ZLIO), a localization back-end, a unified launch entry, and map-processing and extrinsics-calibration tools. The robot gets pose, velocity, covariance and a localization state, and the same entry point works for live runs and rosbag replay project overview.

What changes in a workflow

The stack covers the whole path from raw sensor data to a reusable prior map. You can run ZLIO alone as odometry, or feed an existing LIO front-end through the back-end's standalone odometry and point-cloud interfaces. Relocalization, loop closure and optional UWB position aiding are handled by the back-end project overview.

A documented mapping workflow goes: replay a bag in mapping mode, stop input, call the save-map service, then automatically clean the saved bundle to reduce dynamic ghost points. The author reports that the automatic step greatly cuts manual effort, but the result still needs CloudCompare cleanup and leveling; for a horizontally mounted LiDAR the author recommends regenerating the map bundle and descriptors on a grid after refinement, because descriptors usually come out better than those saved directly during mapping bag-to-prior-map workflow.

Requirements

• Platform: Ubuntu 22.04 and ROS 2 Humble, C++17, CMake ≥ 3.16, colcon. The listed libraries include Eigen, GTSAM 4.2.x, PCL, yaml-cpp and nanoflann, with OpenMP, oneTBB and Threads for parallelism environment and dependencies.
• Sensor path: the documented live setup uses a Livox Mid-360 via Livox ROS Driver 2 and Livox-SDK2, with Livox CustomMsg output. The driver launch flag defaults to off, so it should stay off when replaying bags or when the driver is started separately prior-map localization steps.
• No prior map: real-time global pose requires mapping mode with UWB enabled, and the robot must move several metres (3 m horizontal displacement by default) until the state reaches NORMAL prior-map-free real-time localization.

Constraints to plan for

The configs ship with the author's own install extrinsics, field paths and UWB settings; they are not general calibration results, and sensor, extrinsics and time-related parameters need careful review configuration example. Replaying a bag from the beginning requires restarting the localization program bag-to-prior-map workflow. The project is GPL-2.0-only, which matters if you plan to redistribute or integrate it into closed-source work license. The author describes the code quality as weak, says AI was used for cleanup under human review, and states updates are unlikely except for major bugs project overview.