# karthikrao117/adaptive-traffic-controller-with-yolo-object-detection architecture

> Architecture diagram of the GitHub repository karthikrao117/adaptive-traffic-controller-with-yolo-object-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection
- Repository: https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection

## Overview

##### Project type and purpose
- This is a specialized computer-vision pipeline application (an open-source tool) that processes one or more video streams in real time.
- It detects and tracks vehicles in four lanes using YOLOv7, counts them per lane, and then runs an Adaptive Traffic Control System (ATCS) algorithm to decide which lane gets the next green signal.

##### File structure
- Top-level scripts:
- yolo_video.py – orchestrates the pipeline: reads input, runs detection, tracking, counting, visualization, ATCS.
- atcs.py – encapsulates the ATCS optimization logic (round-robin + starvation avoidance + congestion prioritization).
- runDetections.py – wraps YOLOv7 inference on a frame batch.
- input_retrieval.py – handles threaded video capture using imutils’ FileVideoStream.
- input_videos/ – sample MP4 inputs.
- yolo-coco/ holds model assets: coco.names, yolov7-tiny.cfg, yolov7-tiny.weights.
- No separate frontend/backend – the entire pipeline lives in Python scripts.

##### README insights
- Highlights performance optimizations: threaded frame reading (imutils), skip-frame technique, CPU-only compatibility.
- Describes the detection→tracking→counting→ATCS decision loop in detail.

##### Main components and interactions
a. Video Ingestion Module
- Component: input_retrieval.py (imutils FileVideoStream)
- Role: spawn thread(s), read frames into a buffer/queue.
b. Pre-Processing Module
c. YOLO Inference Engine
- runDetections.py + yolo-coco assets
d. Tracking & Counting Module
- In yolo_video.py: use frame-to-frame center-point distance over last 10 frames to track IDs; count new vehicles per lane.
e. ATCS Optimization Module
- atcs.py: ingest counts + starvation metrics; apply round-robin with congestion weighting; output next green-signal decision and duration.
f. Output & Visualization Module

##### Architectural patterns & design principles
- Pipeline pattern: discrete stages (Ingest → Pre-process → Inference → Post-process → Decision → Output) connected by in-memory queues.
- Threading for I/O decoupling (frame reader thread vs. main processing loop).
- Modular scripts: each responsibility isolated (configuration, inference, ATCS logic).
- No persistent storage required; counts and states live in memory each cycle.

7. ATCS outputs “Next Green Lane & Duration.”
8. Loop back to Pre-Processing for the next decision cycle.

##### Detail and clarity
- Skip-frame optimization: annotate the Pre-Processing step with “skip N frames before inference.”
- Configurable parameters: confidence threshold, NMS threshold, skip-frame count, max cycle time.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes
    VideoSources["Video Sources<br/>(4 lanes or URL)"]:::io
    Videos["Sample Input Videos<br/>(input_videos/)"]:::data
    Example["Example Diagrams/Screenshots<br/>(example_gif/)"]:::data

    Ingestion["Video Ingestion Module<br/>(input_retrieval.py)<br/>Threaded Reader"]:::io
    FrameQueue[/Frame Buffer Queue/]:::data

    PreProc["Pre-Processing Module<br/>(yolo_video.py)<br/>Resize, Color Convert,<br/>Skip N Frames"]:::compute
    Inference["YOLO Inference Engine<br/>(runDetections.py)"]:::compute
    ModelAssets[(Model Assets<br/>yolov7-tiny.cfg,<br/>.weights, coco.names)]:::data

    Tracking["Tracking & Counting Module<br/>(yolo_video.py)"]:::compute
    ATCS["ATCS Optimization Module<br/>(atcs.py)"]:::compute

    Output["Output & Visualization Module<br/>(yolo_video.py)<br/>Draw & Write/Display"]:::io

    %% Flows
    VideoSources -->|raw frame| Ingestion
    Videos --> VideoSources
    VideoSources --> Example
    Ingestion -->|frame| FrameQueue
    FrameQueue -->|frame| PreProc
    PreProc -->|blob| Inference
    Inference -->|bbox + confidences| Tracking
    Inference -->|uses| ModelAssets
    Tracking -->|vehicle counts| ATCS
    ATCS -->|signal decision| PreProc
    ATCS -->|signal decision| Output
    PreProc -->|next cycle| FrameQueue

    %% Click Events
    click Ingestion "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/input_retrieval.py"
    click PreProc "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/yolo_video.py"
    click Inference "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/runDetections.py"
    click ModelAssets "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/tree/main/yolo-coco/"
    click Tracking "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/yolo_video.py"
    click ATCS "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/atcs.py"
    click Output "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/blob/main/yolo_video.py"
    click Videos "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/tree/main/input_videos/"
    click Example "https://github.com/karthikrao117/adaptive-traffic-controller-with-yolo-object-detection/tree/main/example_gif/"

    %% Styles
    classDef io fill:#B3CDE0,stroke:#6497B1,color:#000;
    classDef compute fill:#C7E9B4,stroke:#7FB77E,color:#000;
    classDef data fill:#FDD0A2,stroke:#FC8D59,color:#000;
```
