mola_input_ouster

MOLA input module for Ouster LiDAR sensors using the native Ouster C++ SDK.

Provides direct sensor connection and PCAP replay without ROS middleware.

• Links
  • Rosindex
  • Website
  • Repository
• C++ API
  • Class Hierarchy
  • File Hierarchy
  • Full C++ API

• Standard Documents
  • CHANGELOG
  • PACKAGE
  • README
  • LICENSE
• ROS Package Dependencies
  • mola_kernel
  • mola_yaml
  • mrpt_libmaps
  • mrpt_libobs

README

mola_input_ouster

Provides a MOLA RawDataSourceBase module for Ouster LiDAR sensors using the native Ouster C++ SDK, without requiring any ROS middleware.

This module can operate in three modes:

• Live sensor: Connects to an Ouster sensor on the network.

• PCAP replay: Replays a recorded .pcap capture file.

• OSF replay: Replays an Ouster .osf recording (sensor metadata is embedded in the file — no separate JSON required).

It produces mrpt::obs::CObservationPointCloud and mrpt::obs::CObservationIMU observations for downstream consumption by mola::LidarOdometry, state estimators, or any other mola::RawDataConsumer.

Distro	Build dev	Release
ROS 2 Humble (u22.04)
ROS 2 Jazzy (u24.04)
ROS 2 Kilted (u24.04)
ROS 2 Rolling (u24.04)

Usage: OSF replay (just view, no SLAM)

OUSTER_OSF=/path/to/recording.osf \
mola-cli  $(mola-dir mola_input_ouster)/mola-cli-launchs/osf_ouster_just_view.yaml

Build dependencies

• mola_kernel

• mola_yaml

• mrpt (mrpt-obs, mrpt-maps)

• Ouster SDK (ouster_client, ouster_pcap, ouster_osf) — bundled as a git submodule (see below)

Ouster SDK: bundled submodule vs. system installation

The Ouster SDK is included as a git submodule under ouster-sdk/, so the package is self-contained and requires no separate SDK installation.

Clone with submodules:

git clone --recurse-submodules https://github.com/MOLAorg/mola_input_ouster.git

Or, if you already cloned without --recurse-submodules:

git submodule update --init --recursive

If a system-wide (or user-installed) Ouster SDK is already present on your machine, CMake will prefer it automatically. To force the bundled copy regardless, pass -DUSE_BUNDLED_OUSTER_SDK=ON to CMake.

Usage: Sensor check (just view, no SLAM)

Quickly verify connectivity and inspect the raw point clouds without running any odometry:

OUSTER_HOSTNAME=os-122xxxxxxxxx.local \
mola-cli  $(mola-dir mola_input_ouster)/mola-cli-launchs/live_ouster_just_view.yaml

Same for a recorded PCAP file:

OUSTER_PCAP=/path/to/capture.pcap \
OUSTER_META=/path/to/metadata.json \
mola-cli  $(mola-dir mola_input_ouster)/mola-cli-launchs/pcap_ouster_just_view.yaml

Usage: Live LiDAR odometry

OUSTER_HOSTNAME=os-122xxxxxxxxx.local \
mola-cli  $(mola-dir mola_input_ouster)/mola-cli-launchs/lidar_odometry_ouster_live.yaml

Or using the convenience script:

mola-lo-gui-ouster-live os-122xxxxxxxxx.local

For LiDAR-Inertial Odometry (LIO) with IMU deskewing:

MOLA_DESKEW_METHOD=MotionCompensationMethod::IMU \
mola-lo-gui-ouster-live os-122xxxxxxxxx.local

Changing the lidar mode (resolution / spin rate)

The OUSTER_LIDAR_MODE environment variable sets the scan resolution and rotation frequency. The format is <columns>x<Hz>:

Value	Columns	Hz	Notes
_512x10	512	10	Fastest — lowest horizontal resolution
_512x20	512	20
_1024x10	1024	10	Default
_1024x20	1024	20	Higher rate, same horizontal density
_2048x10	2048	10	Highest horizontal resolution
_4096x5	4096	5	Select sensors only

Example — run at 2048 columns × 10 Hz:

OUSTER_HOSTNAME=os-122xxxxxxxxx.local \
OUSTER_LIDAR_MODE=_2048x10 \
mola-lo-gui-ouster-live os-122xxxxxxxxx.local

Or directly via the YAML params block:

params:
  sensor_hostname: os-122xxxxxxxxx.local
  lidar_mode: _1024x20
  timestamp_mode: TIME_FROM_PTP_1588

Usage: PCAP replay

OUSTER_PCAP=/path/to/capture.pcap \
OUSTER_META=/path/to/metadata.json \
mola-cli  $(mola-dir mola_input_ouster)/mola-cli-launchs/lidar_odometry_ouster_pcap.yaml

Or using the convenience script:

mola-lo-gui-ouster-pcap /path/to/capture.pcap /path/to/metadata.json

YAML configuration

All parameters are documented in the class doxygen: mola::OusterDirectInput.

The most important ones:

Parameter	Default	Description
sensor_hostname	(required for live)	Ouster sensor hostname or IP
pcap_file	(required for PCAP)	Path to .pcap capture file
metadata_json	(required for PCAP)	Path to Ouster metadata JSON file
osf_file	(required for OSF)	Path to .osf recording file
lidar_mode	MODE_1024x10	Ouster resolution/rate (live only)
timestamp_mode	TIME_FROM_PTP_1588	Ouster timestamp source (live only)
lidar_sensor_label	lidar	Sensor label for LiDAR observations
imu_sensor_label	imu	Sensor label for IMU observations
sensor_mounting_pose	0 0 0 0 0 0	Pose of sensor housing on vehicle (base_link → os_sensor), x y z yaw_deg pitch_deg roll_deg
lidar_sensor_pose	(auto)	Manual override: base_link → lidar frame (bypasses intrinsic composition)
imu_sensor_pose	(auto)	Manual override: base_link → IMU frame (bypasses intrinsic composition)
time_warp_scale	1.0	Replay speed multiplier (PCAP only)

Coordinate frames and sensorPose

In MRPT/MOLA, CObservation::sensorPose is the SE(3) pose of the sensor’s own coordinate frame w.r.t. the vehicle frame (base_link). Point coordinates inside CObservationPointCloud::pointcloud are expressed in the lidar frame, and IMU readings in CObservationIMU are expressed in the IMU frame. The sensorPose tells downstream consumers where each of those frames sits on the vehicle. This is consistent with how mrpt::ros2bridge and mola::BridgeROS2 handle observations.

Sensor intrinsic transforms

Ouster sensors store factory-calibrated 4×4 homogeneous transforms in their firmware metadata (queried via the sensor HTTP API, or read from the metadata JSON in PCAP replay mode):

• lidar_to_sensor_transform — Lidar frame → sensor housing frame (os_lidar → os_sensor). Typically a 180° Z-rotation plus a Z offset (lidar aperture height above the housing origin).

• imu_to_sensor_transform — IMU frame → sensor housing frame (os_imu → os_sensor). Typically a small translation (the IMU chip position inside the housing).

Both are available in the SDK’s sensor_info struct.

By default, this module automatically composes the user-provided sensor_mounting_pose (pose of the housing on the vehicle, i.e. base_link → os_sensor) with each factory intrinsic:

lidar sensorPose = sensor_mounting_pose (+) lidar_to_sensor_transform
                 = base_link → os_sensor → os_lidar

IMU   sensorPose = sensor_mounting_pose (+) imu_to_sensor_transform
                 = base_link → os_sensor → os_imu

This matches the TF tree published by the official ouster-ros driver. Point data stays in the lidar frame; IMU data stays in the IMU frame.

If lidar_sensor_pose or imu_sensor_pose are set explicitly in YAML, they override the automatic composition and are used directly as the observation’s sensorPose (still interpreted as base_link → sensor frame).

Environment variables

The mola-cli launch files support these environment variables, following the same conventions as mola_lidar_odometry:

Variable	Default	Description
OUSTER_HOSTNAME	(none)	Sensor hostname for live mode
OUSTER_PCAP	(none)	PCAP file path for replay mode
OUSTER_META	(none)	Metadata JSON file path
OUSTER_OSF	(none)	OSF file path for OSF replay mode
OUSTER_LIDAR_MODE	MODE_1024x10	LiDAR resolution/rate
OUSTER_TIMESTAMP_MODE	TIME_FROM_PTP_1588	Timestamp source
MOLA_LIDAR_NAME	lidar	Sensor label
MOLA_IMU_NAME	imu	IMU sensor label
MOLA_TIME_WARP	1.0	Replay speed
SENSOR_POSE_{X,Y,Z,YAW,PITCH,ROLL}	0	Sensor housing mounting extrinsics

Ouster SDK compatibility

The bundled submodule tracks Ouster SDK v0.16.x (currently pinned to v0.16.2). This is the same SDK version used by the official ouster-ros driver.

The module requires SDK ≥0.11.0 (the version where init_client uses std::optional for lidar/timestamp modes). See the notes at the top of OusterDirectInput.cpp for any API adaptation details.

License

GPL-3.0. See LICENSE.

Part of the MOLA project.