RKO-LIO

Robust LiDAR-Inertial Odometry Without Sensor-Specific Modelling

Four different platforms, four different environments, one odometry system

Quick Start

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

pip install rko_lio rosbags rerun-sdk
# 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)

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

More details are available in the Python usage 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, 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 usage docs.

The same note above about extrinsics applies here as well. Though you probably have a well defined TF tree and need not concern yourself with this (I hope).

Citation

If you found this work useful, please consider leaving a star :star: on this repository and citing our paper:

```bib @article{malladi2025arxiv,

File truncated at 100 lines see the full file

Changelog for package rko_lio

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
  • better (but not cross platform-worthy) identity registration testing
• Update accelerometer data expectation in docs. Clarified accelerometer assumptions
• core: Configurable lidar timestamp processing (#74)
  • thresholds and timestamp processing behaviour is configurable
  • config modifications to the python side
  • ros side launch config modified to have more params
  • docs additions and cleanup
  • fix the py tests since the api changed
• update installation instructions and badge formatting. Updated README.md to improve formatting and clarity of installation instructions and dependencies.
• More CLI options, profiles stats has variance, dumping deskewed scans (#73)
  • add the modifications needed to dump the plys when running
  • add variance to profile stats
  • python: pybind interval stats, and imu logging in rerun
  • more cli options, viz improvements a bit
  • update the cli for dumping deskewed
  • update the rbl
• Update README.md. Add ros source build details
• Folder reorganisation and docs update (#69)
  • flatten the directories. massive renaming across the board
  • docs rework
  • docs updates
  • rename the config file so its explicit
  • fix workflows
• Core/move logging to wrappers (#68)
  • remove logging from core. improve docs
  • python side now does its own config and traj dumping
  • nlohmann json is no longer a core requirement. ros only
  • result dumping on ros side now
  • make result logging on ros optional. and add launch config for that
  • use a shutdown callback for ros to dump results
• Contributors: Anthony Bisulco, Meher Malladi, dependabot[bot]

0.1.7 (2025-10-21)

• python: Update rosbags requirement from to allow 0.11 (#63)

  • Update rosbags requirement from <0.11,>=0.10 to >=0.10,<0.12 in /python

  * Changes to rosbag reader to support older versions and 0.11 Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Meher Malladi <<rm.meher97@gmail.com>>

• actions: Bump pypa/cibuildwheel from 3.2.0 to 3.2.1 (#61) Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

• python: Update typer requirement from <0.20,>=0.19 to >=0.19,<0.21(#62) Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

• python: Update rerun-sdk version (#64) Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

• python: pin versions for compatibility (#60)

  • add python to dependabot checks
  • specify upper bounds for pip dependencies
  • add optional dataloader tests, and add a workflow to install and

File truncated at 100 lines see the full file