# tonelliluca/lane_departure_warning_carla architecture

> Architecture diagram of the GitHub repository tonelliluca/lane_departure_warning_carla, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonelliluca/lane_departure_warning_carla
- Repository: https://github.com/tonelliluca/lane_departure_warning_carla

## Overview

##### Project type and purpose
- This is an open-source, vision-based Lane Departure Warning (LDW) system built on the CARLA autonomous driving simulator. It’s not a traditional front-end/backend web app but rather a simulation-centric tool integrating real-time computer vision, messaging (MQTT), logging, and post-run analysis.

##### File structure
- Top-level directories:
- analysis: scripts and notebooks for post-run data processing and plotting.
- asciidoc: source for the system report (architecture, design, deployment).
- data: model weights (YOLOPv2).
- log: runtime performance logs organized by scenario.
- test_commands: JSON scenario definitions injected into CARLA.
- utils: core modules (YOLOP model wrapper, CARLA client, image cropper, logger).
- Key files:
- launcher.py: entry point that spins up CARLA, attaches sensors, kicks off the LDW pipeline.
- camera_lanes_analysis_sync.py / camera_lanes_analysis_async.py: two modes of running the vision pipeline.
- environment.yml / .env: environment and secret configuration (MQTT credentials).
- typings: type stubs for CARLA Python API.
- CI: .github/workflows/build-doc.yml to generate documentation.

##### README for additional insights
- Core features: real-time YOLOPv2 lane detection, warning generation, record/playback, MQTT publishing, performance logging, comparison with CARLA ground-truth.
- Tech stack: Python 3.7, PyTorch YOLOPv2, CARLA 0.9.15, HiveMQ MQTT, Conda environment.

- Camera → YOLOP → Warning → MQTT
- Performance metrics → File system → Analysis
- Blue for external systems (CARLA, HiveMQ)
- Green for core runtime modules (image processing, model inference, warning logic)
- Yellow for storage (weights, logs)
- Orange for post-run analysis and documentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        CARLA["CARLA Simulator"]:::external
        MQTT["HiveMQ MQTT Broker"]:::external
    end

    %% Configuration
    subgraph "Configuration"
        ENV[".env / environment.yml"]:::config
        SCENARIO["Scenario JSONs"]:::config
    end

    %% Runtime Pipeline
    subgraph "LDW Runtime Pipeline"
        Launch["LDW Entry Point (launcher.py)"]:::runtime
        Sync["Synchronous Pipeline"]:::runtime
        Async["Asynchronous Pipeline"]:::runtime
        Capture["Image Capture (Camera Sensor)"]:::runtime
        Preprocess["Preprocessing (Cropper)"]:::runtime
        Inference["YOLOPv2 Model Inference"]:::runtime
        Detect["Lane Detection & Warning Logic"]:::runtime
        Publish["MQTT Publisher & Detection Logger"]:::runtime
        PerfLog["Performance Logger"]:::runtime
    end

    %% Storage
    subgraph "Data Storage"
        Weights["Model Weights"]:::storage
        Logs["Performance & Event Logs"]:::storage
    end

    %% Analysis & Documentation
    subgraph "Post-Run Analysis & Docs"
        Analyze["Post-Run Data Analysis Scripts"]:::analysis
        Plots["Analysis Plots"]:::analysis
        DocsSrc["AsciiDoc Source"]:::docs
        DocsBuild["Documentation Build Workflow"]:::docs
    end

    %% Data Flows & Relationships
    ENV -->|configures| Launch
    SCENARIO -->|JSON commands| CARLA
    Launch -->|starts simulator| CARLA
    CARLA -->|RGB Frame| Capture
    Capture -->|cropped image| Preprocess
    Preprocess -->|input tensor| Inference
    Inference -->|detections| Detect
    Detect -->|warnings| Publish
    Publish -->|MQTT messages| MQTT
    Detect -->|metrics| PerfLog
    PerfLog -->|writes logs| Logs
    Weights -->|loaded by| Inference
    Logs -->|read by| Analyze
    Analyze -->|generates| Plots
    DocsSrc -->|used by| DocsBuild

    %% Click Events
    click CARLA "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/utils/carla.py"
    click Launch "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/launcher.py"
    click Sync "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/camera_lanes_analysis_sync.py"
    click Async "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/camera_lanes_analysis_async.py"
    click Preprocess "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/utils/image_cropper.py"
    click Inference "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/utils/YOLOPModel.py"
    click Detect "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/utils/utils.py"
    click Publish "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/utils/DetectionLogger.py"
    click Weights "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/data/weights/model.txt"
    click Logs "https://github.com/tonelliluca/lane_departure_warning_carla/tree/main/log/tracked/"
    click SCENARIO "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/test_commands/*.json"
    click Analyze "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/analysis/analyze_data.py"
    click Plots "https://github.com/tonelliluca/lane_departure_warning_carla/tree/main/analysis/plots/"
    click DocsSrc "https://github.com/tonelliluca/lane_departure_warning_carla/tree/main/asciidoc/src/"
    click DocsBuild "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/.github/workflows/build-doc.yml"
    click ENV "https://github.com/tonelliluca/lane_departure_warning_carla/blob/main/environment.yml"

    %% Styles
    classDef external fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef runtime fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef storage fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef analysis fill:#f8d7da,stroke:#333,stroke-width:1px;
    classDef docs fill:#ffe5cc,stroke:#333,stroke-width:1px;
    classDef config fill:#e2e3e5,stroke:#333,stroke-width:1px;
```
