How byu-frost-lab/lio_hawaii works
Project Type and Purpose
• This repository is a CLI‐driven, Docker‐based orchestration layer for running two ROS 2‐based SLAM packages—LiORF and LIO-SAM—against WAMV data (bag files) collected in Hawaii.
• It is not a traditional web full-stack app, but rather a command-line tool that builds/pulls a Docker image, injects configuration and data volumes, launches a ROS 2 environment inside a container, and runs the appropriate SLAM launch files.
File Structure Analysis
• Top-level scripts and configs:
• run_lio.sh – Bash entrypoint/CLI wrapper
• liorf – submodule containing the LiORF code
• LIO-SAM – git submodule for LIO-SAM
• config_liorf/ – parameter YAMLs for LiORF variants
• config_liosam/ – parameter YAMLs, ROS 2 entry‐point, RViz config for LIO-SAM
• launch/ – Python launch files to invoke ROS 2 with specific configs
• docker/ – Dockerfile and build script for constructing the container image
• CI / build / deployment files:
• .dockerignore, docker/build_docker.sh, docker/dockerfile
• .gitmodules to bring in the two SLAM submodules
Key Insights from README
• The CLI (‘lio’) abstracts:
• docker build vs. pull
• tag selection
• dynamic mounting of one or more rosbag directories
• forwarding X11 for GUI tools (RViz2)
• Inside the container:
• config files are mounted to fixed paths
• ROS 2 launch commands invoke either run_liorf_derek_*.launch.py or LIO-SAM’s run.launch.py
• Bags are played with ros2 bag play
• The container is ephemeral and removed on exit.
Main Components
a. Host Environment
• User’s Terminal & CLI script (run_lio.sh)
• Local filesystem with bag files, SSH key (optional)
• X11 server for GUI forwarding
b. Docker Engine
• frostlab/lio_hawaii:<tag> Image
• Container instance (lio_hawaii)
c. Inside Container
• Mounted Volumes:
– /root/ros2_ws/src/liorf (LiORF code + config_liorf)
– /root/ros2_ws/src/LIO-SAM (LIO-SAM code + config_liosam)
– /root/ros2_ws/bags (rosbag directories)
• ROS 2 Launch System:
– LiORF launch or LIO-SAM launch
• ROS 2 Nodes / SLAM Pipeline:
– Sensor inputs replayed via ros2 bag play
– SLAM algorithm nodes (IMU, lidar, state estimation…)
• RViz2 (GUI visualization)
Relationships & Data Flow
1) User runs ./run_lio.sh
2) CLI builds/pulls image or prints debug command
3) docker run is invoked with:
• -v flags for code, configs, bag files
• -e and entrypoint for ROS 2
• --rm to auto-remove container
4) Inside container:
a) Entry‐point script sets up ROS 2 workspace
b) Launch file starts SLAM pipelines
c) ros2 bag play streams data into topics
d) SLAM nodes subscribe, compute odometry & mapping
e) RViz2 connects to ROS 2 master for display
5) When SLAM is done or user exits, container stops
Architectural Patterns & Design Principles
• Containerization for environment consistency
• CLI wrapper abstracts complexity and standardizes usage
• Volume‐mounting pattern to decouple code/config/data
• Submodule use for maintainable, versioned SLAM packages
• ROS 2 launch framework for modular node orchestration