# byu-frost-lab/lio_hawaii architecture

> Architecture diagram of the GitHub repository byu-frost-lab/lio_hawaii, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/byu-frost-lab/lio_hawaii
- Repository: https://github.com/byu-frost-lab/lio_hawaii

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Environment"
        CLI["run_lio.sh"]:::host
        Gitsub[".gitmodules"]:::host
        Dockerignore[".dockerignore"]:::host
        Readme["README.md"]:::host
        FS["Host FS (bags, SSH key, code)"]:::host
        X11["X11 Server"]:::host
    end

    DockerEngine["Docker Engine"]:::engine
    Image["frostlab/lio_hawaii:<tag>"]:::image

    subgraph "Container: lio_hawaii"
        Vol1["LiORF Code & Config<br/>(/root/ros2_ws/src/liorf)"]:::volume
        Vol2["LIO-SAM Code & Config<br/>(/root/ros2_ws/src/LIO-SAM)"]:::volume
        Vol3["rosbag Data<br/>(/root/ros2_ws/bags)"]:::volume
        EP["ros_entrypoint.sh"]:::script
        Launch["ROS 2 Launch System"]:::system
        NodePlay["ros2 bag play"]:::node
        SLAM["SLAM Nodes<br/>(IMU, LiDAR, Estimation)"]:::node
        RViz["RViz2 GUI"]:::gui
    end

    BuildScript["build_docker.sh"]:::script
    Dockerfile["dockerfile"]:::script

    CLI -->|"invokes"| DockerEngine
    CLI -->|"reads"| Gitsub
    CLI -->|"reads"| Dockerignore
    CLI -->|"reads"| Readme
    CLI -->|"accesses"| FS
    CLI -->|"forwards X11"| X11
    DockerEngine -->|"builds or pulls image"| Image
    DockerEngine -->|"uses build script"| BuildScript
    DockerEngine -->|"uses Dockerfile"| Dockerfile
    Image -->|"docker run --> container"| EP
    FS -->|"mounts code/config"| Vol1
    FS -->|"mounts code/config"| Vol2
    FS -->|"mounts bags"| Vol3
    EP -->|"launches"| Launch
    Launch -->|"plays bags"| NodePlay
    NodePlay -->|"publishes topics to"| SLAM
    SLAM -->|"publishes data to"| RViz
    X11 -->|"displays GUI"| RViz

    click CLI "https://github.com/byu-frost-lab/lio_hawaii/blob/main/run_lio.sh"
    click Gitsub "https://github.com/byu-frost-lab/lio_hawaii/blob/main/.gitmodules"
    click Dockerignore "https://github.com/byu-frost-lab/lio_hawaii/blob/main/.dockerignore"
    click Readme "https://github.com/byu-frost-lab/lio_hawaii/blob/main/README.md"
    click Vol1 "https://github.com/byu-frost-lab/lio_hawaii/tree/main/liorf/"
    click Vol2 "https://github.com/byu-frost-lab/lio_hawaii/tree/main/LIO-SAM/"
    click BuildScript "https://github.com/byu-frost-lab/lio_hawaii/blob/main/docker/build_docker.sh"
    click Dockerfile "https://github.com/byu-frost-lab/lio_hawaii/tree/main/docker/dockerfile"
    click EP "https://github.com/byu-frost-lab/lio_hawaii/blob/main/docker/ros_entrypoint.sh"

    classDef host fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef engine fill:#ABEBC6,stroke:#1D8348,color:#0B5345;
    classDef image fill:#82E0AA,stroke:#1D8348,color:#0B5345,shape:cylinder;
    classDef container fill:#F5CBA7,stroke:#B9770E,color:#873600;
    classDef volume fill:#D7BDE2,stroke:#7D3C98,color:#4A235A,shape:cylinder;
    classDef script fill:#FADBD8,stroke:#C0392B,color:#78281F;
    classDef system fill:#D5DBDB,stroke:#616A6B,color:#1C2833;
    classDef node fill:#D6EAF8,stroke:#2E86C1,color:#154360;
    classDef gui fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    class CLI,Gitsub,Dockerignore,Readme,FS,X11 host
    class DockerEngine engine
    class Image image
    class Vol1,Vol2,Vol3 volume
    class EP,BuildScript,Dockerfile script
    class Launch system
    class NodePlay,SLAM node
    class RViz gui
```
