livox_custom_to_pc2

ROS2 package for Livox MID360 data processing. Converts livox_ros_driver2/msg/CustomMsg to sensor_msgs/msg/PointCloud2 and corrects IMU units from g to m/s².

Background

The Livox ROS2 driver (livox_ros_driver2) publishes two non-standard outputs:

• /livox/lidar — uses a proprietary CustomMsg type instead of PointCloud2
• /livox/imu — transmits linear acceleration in g instead of m/s² (driver issue #157)

This package fixes both so downstream tools (GLIM, DLIO, etc.) receive standard-compliant messages.

Point cloud format

The PointCloud2 output mirrors the official Livox driver format (lddc.cpp, xfer_format=0):

Field	Type	Description
x, y, z	float32	Position (m)
intensity	float32	Reflectivity
tag	uint8	Livox point tag
line	uint8	Laser line ID
timestamp	float64	Absolute nanoseconds since epoch

Point step: 26 bytes. The timestamp field satisfies DLIO's Livox detection check (value > 1e14).

---

Tools

livox_custom_to_pc2_node — live converter node

Subscribes to the raw Livox topics and republishes converted messages in real time.

ros2 run livox_custom_to_pc2 livox_custom_to_pc2_node

Topics:

Direction	Topic	Type
Subscribe	/livox/lidar	livox_ros_driver2/msg/CustomMsg
Subscribe	/livox/imu	sensor_msgs/msg/Imu (g)
Publish	/livox/points	sensor_msgs/msg/PointCloud2
Publish	/livox/imu_si	sensor_msgs/msg/Imu (m/s²)

Topic names are configurable via ROS2 parameters:

ros2 run livox_custom_to_pc2 livox_custom_to_pc2_node \
  --ros-args \
  -p sub_lidar_topic:=/livox/lidar \
  -p pub_lidar_topic:=/livox/points \
  -p sub_imu_topic:=/livox/imu \
  -p pub_imu_topic:=/livox/imu_si

---

convert_bag — offline bag converter

Converts a single recorded bag from CustomMsg + raw IMU to PointCloud2 + SI IMU. Reads at disk speed — no real-time playback required.

ros2 run livox_custom_to_pc2 convert_bag <input_bag_dir> <output_bag_dir>

Example:

ros2 run livox_custom_to_pc2 convert_bag \
  /data/bags/2026-05-27_genf/rosbag2_2026-05-27_12-33-24_genf \
  /data/bags_converted/rosbag2_2026-05-27_12-33-24_genf

Output topics: /livox/points (PointCloud2) and /livox/imu_si (Imu)

Prints progress in 5% increments and a dropout analysis on completion. Exit codes: 0 = success, 2 = success with dropouts detected, 1 = error.

---

convert_session.sh — batch bag converter

Converts all rosbag2_* bags in a session folder. Skips bags already present in the output.

/home/ros/atn_ws/src/livox_custom_to_pc2/scripts/convert_session.sh <session_dir>

# from inside the session folder:
/home/ros/atn_ws/src/livox_custom_to_pc2/scripts/convert_session.sh .

All output bags go to /data/bags_converted/ keeping the original bag directory name.

---

check_bag — dropout analyser

Checks LiDAR and IMU streams for timestamp gaps. Works on both original and converted bags. Does not deserialise messages — uses bag recording timestamps only, so it is very fast.

# single bag
ros2 run livox_custom_to_pc2 check_bag <bag_dir>

# whole session folder (finds all rosbag2_* subdirs automatically)
ros2 run livox_custom_to_pc2 check_bag <session_dir>

# multiple paths at once
ros2 run livox_custom_to_pc2 check_bag <bag1> <bag2> ...

Thresholds:

Topic	Expected interval	Dropout threshold
LiDAR (10 Hz)	~100 ms	> 200 ms
IMU (200 Hz)	~5 ms	> 15 ms

Exit codes: 0 = no dropouts, 2 = dropouts found, 1 = error.

---

index_bags — bag index generator

Scans a directory of bags and writes INDEX.md with a full summary table.

ros2 run livox_custom_to_pc2 index_bags /data/bags_converted

INDEX.md contains:

• Duration, LiDAR frame count, IMU message count, IMU/LiDAR ratio
• Dropout counts per bag with ✅ / ⚠️ status indicator
• Detailed dropout timestamps for any bag with dropouts

The file is written into the scanned directory and is immediately visible on the host via the bind mount at ~/atn_development/bags_converted/INDEX.md.

---

Typical workflow

One-time setup (docker-compose.yml)

volumes:
  - /Volumes/atn_drive01:/data/bags:ro
  - /Users/timonmathis/atn_development/bags_converted:/data/bags_converted

In the container — source setup once per shell

source /opt/ros/humble/setup.bash
source /home/ros/atn_ws/install/setup.bash

Convert a session

/home/ros/atn_ws/src/livox_custom_to_pc2/scripts/convert_session.sh \
  /data/bags/2026-05-27_genf

Build the index

ros2 run livox_custom_to_pc2 index_bags /data/bags_converted
# → ~/atn_development/bags_converted/INDEX.md on host

Check a single bag

ros2 run livox_custom_to_pc2 check_bag /data/bags_converted/<bag_name>