# gunterwinter/license-plate-recognition architecture

> Architecture diagram of the GitHub repository gunterwinter/license-plate-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gunterwinter/license-plate-recognition
- Repository: https://github.com/gunterwinter/license-plate-recognition

## Overview

##### Project Type and Purpose
- This is a full-stack computer vision application focused on real-time vehicle and license plate detection and recognition.
- The README confirms the use of YOLOv8 for object detection (both vehicle and plate), SORT/DeepSORT for tracking, and PaddleOCR (via ONNX for inference) in the recognition stage.

##### File Structure
- Top-Level Components:
- "main.py": The central entry point which likely integrates detection, tracking, and OCR modules.
- "detectors" folder: Contains the YOLOv8 models for detection along with related Jupyter notebooks and scripts (e.g., exporting to ONNX, training models). This indicates modular detectors for vehicles, plates, etc.
- "ppocr_onnx" folder: Implements the plate recognition pipeline using ONNX models (with separate modules for detection, preprocessing, prediction, and postprocessing).
- "tracking" folder: Hosts two parallel tracking algorithms:
▪ "deep_sort": Contains the implementation for DeepSORT (including model training, evaluation, and ONNX export).
▪ "sort": Contains the simpler SORT tracking algorithm.
- "weights" folder: Holds the pre-trained weights and engine files (for vehicles, plates, OCR, re-ID models) needed during inference.
- "utils": Contains helper utilities that support various functional areas (data processing, logging, drawing).

##### Key Components and Their Interactions
a. Input / Data Acquisition:
– A video stream (or video file) is provided as input.
– main.py accepts command-line arguments to determine if the video stream is for real-time monitoring or saved video inference.

b. Detection Module:
– YOLOv8-based detectors for both vehicle detection and plate detection reside in the “detectors” directory.
– The vehicle detector and plate detector may be run on different portions of the image; their outputs then serve different downstream modules.

c. Tracking Module:
– Two tracking algorithms (SORT and DeepSORT) are available in the “tracking” folder.
– These modules manage object tracking across frames, maintaining identity of vehicles across time.
– DeepSORT, in particular, uses additional appearance features (via re-ID models) and has its own dedicated configurations and weights.

d. OCR/Plate Recognition Module:
– The “ppocr_onnx” directory contains the pipeline for plate recognition.
– Preprocessing of images, prediction (using PaddleOCR ONNX models), and postprocessing steps are implemented as separate modules.

e. Integration and Flow:
– main.py ties all these components together. Typically, it will:
- Load the video input.
- Run the detections using YOLOv8 detectors.
- When plates are detected, the images are passed to the OCR pipeline (ppocr_onnx) for character recognition.
– The outputs (videos, logs, or processed frames with annotations) are then saved in a designated directory.

##### Architectural Patterns and Design Principles
- Modular Architecture – Each main functionality (detection, tracking, OCR) is encapsulated in its own module/library, making it easier to manage and update.
- Pipeline Processing – Data flows sequentially from input to detection, then tracking and finally recognition.
- Separation of Concerns – The responsibilities are distributed: one set of modules handles detection (with YOLOv8), another set focuses on tracking (SORT/DeepSORT), and another on OCR (PaddleOCR via ONNX).

##### Relevant Technologies, Frameworks, and Libraries
- YOLOv8 from Ultralytics for object detection.
- SORT and DeepSORT algorithms for tracking.
- PaddleOCR (and its ONNX models) for OCR.
- ONNX for model interoperability and possibly TensorRT for acceleration (as seen in the notebooks).
- Python (versions 3.7 to 3.13) as the primary programming language.
- Configuration and utilities aiding in modular design (e.g., YAML configuration for DeepSORT).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Video Input"]:::input
    B["Main Integration (main.py)"]:::integration
    C["Detection Module (YOLOv8)"]:::detection
    subgraph "Tracking Module"
        D1["SORT Tracker"]:::tracking
        D2["DeepSORT Tracker"]:::tracking
    end
    E["OCR/Plate Recognition (ppocr_onnx)"]:::ocr
    F["License Plate Data"]:::ocr
    G["Pre-Trained Weights"]:::weights
    H["General Utilities"]:::utils
    I["Tracking Utilities"]:::utils

    A -->|"video_stream"| B
    B -->|"load_video_and_invoke_modules"| C
    B -->|"coordinate_processing"| H
    B -->|"coordinate_tracking"| I
    C -->|"vehicle&plate_detection"| D1
    C -->|"vehicle&plate_detection"| D2
    C -->|"extract_plate_regions"| E
    D1 -->|"tracking_info"| F
    D2 -->|"tracking_info"| F
    E -->|"ocr_results"| F
    C -->|"uses_weights"| G
    D2 -->|"requires_reID_weights"| G
    E -->|"uses_ocr_weights"| G

    click B "https://github.com/gunterwinter/license-plate-recognition/blob/main/main.py"
    click C "https://github.com/gunterwinter/license-plate-recognition/tree/main/detectors/yolov8"
    click E "https://github.com/gunterwinter/license-plate-recognition/tree/main/ppocr_onnx"
    click D2 "https://github.com/gunterwinter/license-plate-recognition/tree/main/tracking/deep_sort"
    click D1 "https://github.com/gunterwinter/license-plate-recognition/blob/main/tracking/sort.py"
    click G "https://github.com/gunterwinter/license-plate-recognition/tree/main/weights"
    click H "https://github.com/gunterwinter/license-plate-recognition/blob/main/utils/utils.py"
    click I "https://github.com/gunterwinter/license-plate-recognition/tree/main/tracking/utils"

    classDef input fill:#577590,stroke:#293241,stroke-width:2px,color:#ffffff;
    classDef integration fill:#277da1,stroke:#43aa8b,stroke-width:2px,color:#ffffff;
    classDef detection fill:#f9c74f,stroke:#f9844a,stroke-width:2px,color:#000000;
    classDef tracking fill:#90be6d,stroke:#43aa8b,stroke-width:2px,color:#000000;
    classDef ocr fill:#f94144,stroke:#f3722c,stroke-width:2px,color:#ffffff;
    classDef weights fill:#6a4c93,stroke:#8338ec,stroke-width:2px,color:#ffffff;
    classDef utils fill:#ffafcc,stroke:#ff7b6c,stroke-width:2px,color:#000000;
```
