RKO-LIO

Robust LiDAR-Inertial Odometry Without Sensor-Specific Modelling

Four different platforms, four different environments, one odometry system

Quick Start

Following is for the python version, see ROS for that.

Assuming you have a rosbag (ros1/ros2) which contains a TF tree, you can run RKO-LIO through

pip install "rko_lio[all]"
# or
pip install rko_lio rosbags "rerun-sdk>=0.31"
# data path should be a directory with *.bag files (ROS1) or a metadata.yaml (ROS2)
rko_lio -v /path/to/data

Why pip install those three packages?

• rko_lio -> the odometry package
• rosbags -> required for the rosbag dataloader. Both ros1 and ros2 bags are supported!
• rerun-sdk -> required for the optional visualizer (-v flag)

pip install "rko_lio[all]" fetches the other optional dependencies as well.

Check further options for the CLI through rko_lio --help.

To dump a default config you can edit and pass with --config, run rko_lio --dump_config.

More details are available in the Python docs.

Extrinsics and convention

Please note that the system needs the extrinsic to be specified between IMU and LiDAR. Either your data includes this in some format, and then the dataloaders try to automatically read it, or otherwise you can specify it in a config file (required if it’s missing in the data). Pass the config file with

rko_lio --config config_file.yaml

This file needs two keys: extrinsic_imu2base_quat_xyzw_xyz and extrinsic_lidar2base_quat_xyzw_xyz, which must each be a list. For example: [0,0,0,1,0,0,0] for identity. Both keys are required.

Throughout this package, I refer to transformations using transform_<from-frame>2<to-frame>. By this, I mean a transformation that converts a vector expressed in the <from-frame> coordinate system to the <to-frame> coordinate system. Mathematically, this translates to:

The superscript on the vector indicates the frame in which the vector is expressed, and $^{ \mathrm{to} }\mathbf{T}_{\mathrm{from}}$ corresponds to transform_<from-frame>_to_<to-frame>.

ROS

Supported distros: Humble, Jazzy, Kilted, Lyrical, Rolling.

sudo apt install ros-$ROS_DISTRO-rko-lio

Or if you’d like to build from source, clone the repo into your colcon workspace and

rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select rko_lio  # --symlink-install --event-handlers console_direct+

In case you cannot system install the necessary dependencies through rosdep, you can also build the dependencies while building RKO-LIO

colcon build --packages-select rko_lio --cmake-args -DRKO_LIO_FETCH_CONTENT_DEPS=ON

A launch file is provided:

ros2 launch rko_lio odometry.launch.py imu_topic:=<topic> lidar_topic:=<topic> base_frame:=base_link

The three parameters imu_topic, lidar_topic, and base_frame are the minimum you need to specify for the launch file. You can specify them and other options all at once in a config file passed with config_file:=file.yaml.

Check further launch configuration options through ros2 launch rko_lio odometry.launch.py -s

More details are available in the ROS docs.

File truncated at 100 lines see the full file

Changelog for package rko_lio

0.3.0 (2026-06-16)

• misc: adds testing for lyrical, fixes the current ci fails (#142)
  • adds testing for lyrical, fixes the current ci fails, and switches to leaner images for ci
• use VoxelHash struct to avoid ODR violations (#140) Co-authored-by: Meher Malladi <<rm.meher97@gmail.com>>
• core: revert voxel down sample sorted (#141) not a 1-1 improvement over previous behavior
• core: Fix tbb threading using max_num_threads (#137)
  • core: return the thread limit which was lost in #93
• core: improved voxel down sampling, use robin set, explicit hash sorting (#136)
  • tests: add test cases for voxel_down_sample_sorted
• core, python, ros: a series of simplifications (#133)
  • core: clean up preprocessing result for double deskewing on/off
  • ros: frame parsing simplifications
  • ros: imu rate publishing simplify
  • ros: unify publishers to use lio->state
  • core: simplify point to voxel usage
  • api: fix my embarrassing spelling mistake on correspondences
  • ros: clean up bag progress publish in offline mode
• core: Reject empty input vectors instead of dereferencing end() (#135)
• ros (bug): fix shared library components not installing properly
• core: time in nanoseconds, everywhere (#132)
  • switch doubles to nanoseconds end-to-end
  • ros: improve the utils slightly
• ros (+ core): Installable and therefore reusable libs (#131)
  • make core/ros/ros::utils libs ament-installable + exportable
  • install only on no fetch content. and prevent install on humble
• core: drop Bonxai for tsl::robin_map (#130)
  • switch to tsl robin map instead of bonxai
  • change method names to snake case for the hash map
• chore: bump FetchContent dependencies (#128)
• ros: offline node exits once lidar buffer has been emptied (#127)
  • fix a potential bug that i thought i fixed on imu msgs being leftover
  • catch the potential race with the node dying before reg exits
• docs: overhaul (#126)
• ros, feat: odometry at imu rate (#125)
  • feat: publish odometry at imu freq, when running sequentially
  • add a part for the imu rate odom to the docs
• core: simplifications and clean up to core (#124)
• Add Catch2 tests for core functionalities and related updates (#123)
  • add catch2 based tests to cover important core functionalities.
  • then related file updates
  • consolidate workflows
• core: error out if keypoints is too small as thats likely a data error (#110)
• ros: add deskewed scan topic as a config, change default topic names to relative (#108)
• core: orientation linear system simplifications. move util classes to util (#94)
• Some code refactoring and execution time improvement. (#93) Co-authored-by: Meher Malladi <<rm.meher97@gmail.com>>
• Contributors: Aleksandr Kovalko, Luca Lobefaro, Meher Malladi, Saurabh Gupta, dependabot[bot], muvahhid kılıç

0.2.0 (2025-12-02)

• Fix (core): log proper pose for the first frame if init. phase is on (#89)
• chore: bump FetchContent Eigen to 5.0.1 (#88) Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
• core: minimize TimestampProcessingConfig (#87)
  • remove the configs for start and end time thresholds that can be satisfied much simpler by just forcing relative or absolute overrides
• python: remove unnecessary scan viz (#85)
• remove pytest as optional dep, added toml based config (#83)
• Rename published_deskewed_cloud to publish_deskewed_scan (#81)
• Fix: core - proper second frame pose if initialization off (#77)
  • move preproc to its own file and fix the non intialization behaviour

File truncated at 100 lines see the full file