# mwasifanwar/neurodrive-vision architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/neurodrive-vision
- Repository: https://github.com/mwasifanwar/neurodrive-vision

## Overview

##### Project type and purpose
- Project Type: A modular computer‐vision pipeline for lane detection and road perception research.
- Purpose: Ingest video or image input (file, camera), process frames through a series of vision algorithms (edge detection, ROI extraction, Hough transform, smoothing, tracking), and expose results via a CLI or interactive Gradio UI.

##### File structure
- app/
- cli.py           ← Command‐line interface entry point
- gradio_app.py    ← Interactive web demo built with Gradio
- src/
- io.py            ← Input/output helpers (video capture, frame loading, result saving)
- pipeline.py      ← Orchestrates the sequence of vision steps
- tracker.py       ← EMA‐based lane tracking logic
- utils.py         ← Shared utilities (logging, drawing helpers)
- vision/          ← Core algorithms as modular plugins
– edges.py       ← Edge detection routines (Canny, Sobel)
– hough.py       ← Probabilistic Hough transform for line detection
– lines.py       ← Line grouping and filtering
– roi.py         ← Adaptive region‐of‐interest mapping
– smoothing.py   ← Exponential moving average smoothing
- assets/figures/    ← Static assets for documentation or sample outputs
- tests/             ← Unit tests for individual vision modules
- requirements.txt   ← Python dependencies (OpenCV, NumPy, Gradio, etc.)

##### Extract architectural insights from the README
- Real‐time pipeline for autonomous driving research
- Key features: adaptive ROI, probabilistic Hough, EMA smoothing, Gradio UI
- Technology stack: OpenCV & NumPy for CV, Gradio for UI

##### Main components & their interactions
a. Frontend Layer
- CLI Interface (app/cli.py)
- Gradio Web Demo (app/gradio_app.py)
b. Processing Core
- Pipeline Orchestrator (src/pipeline.py)
- Vision Modules (src/vision/*.py)
- Tracker (src/tracker.py)
- I/O & Config (src/io.py, src/config.py)
- Utils (src/utils.py)
c. Assets & Tests
- assets/figures (static output)
- tests/test_edges.py (validation)
d. External Dependencies
- OpenCV, NumPy (CV & matrix ops)
- Gradio (UI)

##### Relationships & data flow
- Input source → io.py → pipeline.py
- pipeline.py invokes in order:
1) roi.py → 2) edges.py → 3) hough.py → 4) lines.py → 5) smoothing.py → 6) tracker.py
- CLI or Gradio UI calls pipeline, receives final annotated frames & metrics

##### Architectural patterns & design principles
- Modular Pipeline Pattern: each vision step is a separate module
- Dependency Injection: config parameters passed into modules at runtime
- Separation of Concerns: UI (app/) vs. core processing (src/) vs. tests/assets

##### Essential elements
- Clear component names (file or module names)
- Callouts for key technologies (OpenCV/NumPy, Gradio) at component boundaries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        CLI["CLI Interface"]:::frontend
        Gradio["Gradio Web Demo"]:::frontend
    end

    %% Core Processing
    subgraph "Core Processing"
        Config["Configuration Parameters"]:::support
        IO["Input/Output Helpers"]:::support
        Pipeline["Pipeline Orchestrator"]:::core

        subgraph "Vision Modules"
            ROI["Region-of-Interest Extraction"]:::core
            Edges["Edge Detection"]:::core
            Hough["Probabilistic Hough Transform"]:::core
            Lines["Line Grouping & Filtering"]:::core
            Smoothing["Exponential Smoothing"]:::core
        end

        Tracker["Lane Tracker (EMA)"]:::core
        Utils["Shared Utilities"]:::support
    end

    %% Assets & Tests
    subgraph "Support Assets & Tests"
        Figures["Static Figures & Sample Outputs"]:::support
        TestEdges["Unit Tests for Edge Detection"]:::support
    end

    %% External Dependencies
    OpenCV["OpenCV & NumPy"]:::external
    GradioExt["Gradio"]:::external

    %% Data & Control Flows
    CLI -->|"invoke pipeline"| Pipeline
    Gradio -->|"invoke pipeline"| Pipeline

    OpenCV -->|"(cv operations)"| ROI
    OpenCV -->|"(cv operations)"| Edges
    OpenCV -->|"(cv operations)"| Hough
    OpenCV -->|"(cv operations)"| Lines
    OpenCV -->|"(cv operations)"| Smoothing
    GradioExt -->|"UI support"| Gradio

    %% Pipeline orchestration
    IO -->|"raw frame"| Pipeline
    Config -->|"parameters"| Pipeline

    Pipeline -->|"ROI mask"| ROI
    ROI -->|"masked frame"| Edges
    Edges -->|"edges"| Hough
    Hough -->|"lines candidates"| Lines
    Lines -->|"filtered lines"| Smoothing
    Smoothing -->|"smoothed lines"| Tracker
    Tracker -->|"lane coordinates"| Utils
    Utils -->|"annotated frame"| CLI
    Utils -->|"annotated frame"| Gradio
    Utils -->|"saved outputs"| Figures

    %% Test linkage
    Edges -->|"validate edges"| TestEdges

    %% Click Events
    click CLI "https://github.com/mwasifanwar/neurodrive-vision/blob/main/app/cli.py"
    click Gradio "https://github.com/mwasifanwar/neurodrive-vision/blob/main/app/gradio_app.py"
    click Pipeline "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/pipeline.py"
    click Config "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/config.py"
    click IO "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/io.py"
    click Tracker "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/tracker.py"
    click Utils "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/utils.py"
    click Edges "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/vision/edges.py"
    click ROI "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/vision/roi.py"
    click Hough "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/vision/hough.py"
    click Lines "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/vision/lines.py"
    click Smoothing "https://github.com/mwasifanwar/neurodrive-vision/blob/main/src/vision/smoothing.py"
    click Figures "https://github.com/mwasifanwar/neurodrive-vision/tree/main/assets/figures"
    click TestEdges "https://github.com/mwasifanwar/neurodrive-vision/blob/main/tests/test_edges.py"

    %% Styling
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E6FFE6,stroke:#28A745,color:#28A745;
    classDef support fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef external fill:#FFF5E6,stroke:#D97706,color:#D97706;
```
