LIO-Localization

A ROS2 workspace for LiDAR-Inertial Odometry (LIO) based pointcloud map creation and localization within a fixed pointcloud map. Two LIO backends are supported: FAST-LIO2 and SPARK Fast-LIO2. Works with Livox, Velodyne, and Ouster LiDARs.

Prerequisites

• ROS2 Humble (full desktop install)
• Livox SDK2 — Installation guide
• Livox ROS2 Driver — Installation guide

Installation

Clone with submodules:

git clone --recursive https://github.com/wdc3iii/LIO-Localization.git
cd LIO-Localization

Install ROS2 dependencies via rosdep:

cd ws_lio_loc
rosdep install --from-paths src --ignore-src -r -y

This handles libpcl-dev, pcl_conversions, yaml-cpp, and all other ROS2 dependencies automatically.

Source the Livox ROS2 Driver workspace, then build:

source /path/to/livox_ros_driver2/install/setup.bash
cd ws_lio_loc
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/setup.bash

Note: spark_fast_lio already forces Release mode with -O3 in its CMakeLists, but passing --cmake-args -DCMAKE_BUILD_TYPE=Release ensures the other packages (e.g. relocalization_bringup) also build optimized — important for PCL-heavy operations.

Usage

Per-workflow docs (recording, mapping, relocalization, map consolidation, GLIM mapping, PLY→PCD conversion) live in the package README: ws_lio_loc/src/relocalization_bringup/README.md.

Packages

Package	Description
fast_lio	FAST-LIO2 mapping engine (LiDAR-inertial odometry)
spark_fast_lio	SPARK Fast-LIO2 mapping engine (LiDAR-inertial odometry)
scan_lock	ICP-based localization within a prior pointcloud map
relocalization_bringup	Launch files, sensor configs, and map consolidation tools

Docker

A Docker-based development environment is provided with two variants: GPU (NVIDIA runtime) and No-GPU. The container includes ROS2 Humble, Livox SDK2, the Livox ROS2 driver, and all PCL dependencies pre-installed.

Prerequisites

• Docker Engine and Docker Compose
• For GPU support: NVIDIA Container Toolkit
• For GUI forwarding (RViz, pcl_viewer): X11 display server on the host

Environment Setup

The compose files read variables from docker/.env, which is not tracked in git (per-machine settings differ). Bootstrap it from the tracked template:

cp docker/.env_example docker/.env

Then edit docker/.env for your machine:

Variable	Purpose	Default in .env_example
USER	Container username (matches host so file ownership lines up)	$(id -un)
UID / GID	Container user IDs (set to match id -u / id -g on your host)	1001 / 1000
LIO_ROOT	Absolute path to this repo on the host (bind-mounted into the container)	/home/${USER}/repos/LIO-Localization
WITH_GLIM	Build with GLIM (CPU global mapping; ~5-10 min added build time)	unset
WITH_GLIM_CUDA	Build with GLIM + CUDA 12.6 GPU acceleration (implies WITH_GLIM; ~15-25 min added build time). GPU-compose variant only.	true
CUDA_ARCH	Target compute capability for the GPU build (89 = RTX 40-series, 86 = 30-series, 75 = 20-series, "75;86;89" = fat binary)	89 (Dockerfile default)

UID/GID mismatch between the host and container is the most common new-machine pitfall — files created inside the container will be owned by the wrong UID on the host. Run id to check.

GLIM build notes. WITH_GLIM_CUDA=true pulls in the NVIDIA CUDA 12.6 apt repo, GTSAM/Iridescence from the koide3 PPAs, builds gtsam_points with CUDA enabled, and clones+builds glim + glim_ros2 into ~/glim_ws/install (auto-sourced via .bashrc). The build uses gcc-12 to dodge a known gcc-11 internal compiler error on deep nanoflann template recursion, and caps parallelism at -j8 to avoid memory-pressure ICEs. CUDA 12.6 requires host driver ≥ 560.28.03 — check with nvidia-smi. See the GLIM Mapping section in the bringup README for usage.

Option 1: VS Code Dev Container (Recommended)

1. Install the Dev Containers extension in VS Code.
2. Open this repository in VS Code.
3. Press Ctrl+Shift+P → Dev Containers: Reopen in Container.
4. Select one of the available configurations:
   • LIO GPU Dev Container — uses docker-compose.yml with NVIDIA runtime
   • LIO No-GPU Dev Container — uses docker-compose-no-gpu.yml
5. VS Code will build the image (first time only), start the container, and attach with recommended extensions pre-installed.

Option 2: Terminal

Build the image:

cd docker
docker compose build                  # GPU
docker compose -f docker-compose-no-gpu.yml build  # No-GPU

Start the container:

# Allow X11 forwarding for GUI apps
xhost +local:docker

# GPU
cd docker
docker compose up -d
docker compose exec lio_localization bash

# No-GPU
cd docker
docker compose -f docker-compose-no-gpu.yml up -d
docker compose -f docker-compose-no-gpu.yml exec lio_localization bash

Stop the container:

cd docker
docker compose down                   # GPU
docker compose -f docker-compose-no-gpu.yml down   # No-GPU

Building the Workspace Inside the Container

Once inside the container, build the ROS2 workspace as usual:

cd $LIO_ROOT/ws_lio_loc
source /opt/ros/humble/setup.bash
source ~/livox_driver_ws/install/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/setup.bash

tmux

A quick reference for common tmux operations. All commands start with the prefix: Ctrl+b

Starting and Stopping

tmux                           # Create new session (unnamed)
tmux new-session -s name       # Create named session
tmux kill-session -t name      # Kill a session
tmux kill-server               # Kill all sessions

Attaching and Detaching

tmux list-sessions             # List all sessions
tmux attach-session -t name    # Attach to session

Once inside tmux:

• Prefix d — detach from session (session keeps running)
• Prefix :kill-session — kill current session

Splitting Panes

• Prefix " — split horizontally (top/bottom)
• Prefix % — split vertically (left/right)
• Prefix x — close current pane (will prompt y/n)
• Prefix arrow key — navigate between panes
• Prefix z — toggle zoom (fullscreen) on current pane

Other Basics

• Prefix c — create new window
• Prefix n / Prefix p — next/previous window
• Prefix [ — enter scroll/copy mode (exit with q)
• Prefix : — enter command mode