# tkvmaster/anpr-system architecture

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

- Interactive diagram: https://gitdiagram.com/tkvmaster/anpr-system
- Repository: https://github.com/tkvmaster/anpr-system

## Overview

##### Project type and purpose
- This is a specialized Computer Vision / Deep Learning pipeline for Automatic Number-Plate Recognition (ANPR).

##### File structure
- Top‐level scripts and notebooks:
- anpr-system.py – the main inference CLI
- *.ipynb – exploratory and training notebooks (data scraping, YOLOv5 training, post‐processing)
- runs/train/exp – stores training artifacts for YOLOv5: best.pt, last.pt, events, results.csv
- utility_files – logos, demo GIF, and any static assets
- requirements.txt – external dependencies
- README.md – project overview, usage, tech stack
- The absence of a “frontend” folder confirms this is a back-end/CLI pipeline rather than a web app.

##### Key insights from the README
- Two‐step inference: (1) YOLOv5 detection → (2) PaddleOCR recognition + Norfair tracking
- Data flow: video input → frame extraction → ROI crop → preprocessing → OCR → tracking → outputs
- Training uses PyTorch/YOLOv5; inference uses OpenCV for video I/O, PaddleOCR for text, Norfair for tracking
- Outputs: annotated video and CSV file

##### Main components and their interactions
1. Data Collection & Preprocessing
– image_scrapping.ipynb → raw images
– License_Plate_Detection.ipynb → labeling/augmentation
2. YOLOv5 Training
– yolov5 repo + custom dataset → runs/train/exp/weights/best.pt
B. Real‐Time Inference Pipeline (core)
1. Video Input
– OpenCV VideoCapture (input MP4 or camera feed)
2. Frame Extraction
– loop each frame
3. License‐Plate Detection
4. ROI Cropping & Preprocessing
– crop plate region → grayscale/threshold ng preprocessing
5. OCR Recognition
– PaddleOCR → produces candidate plate strings
6. Tracking & Aggregation
– Norfair Tracker → associates plate detections across frames → selects best OCR result per track
7. Output Modules
– Annotated Video Writer (OpenCV VideoWriter)
– CSV Logger → append <track_id, timestamp, plate_string>

##### Architectural patterns and design principles
- Pipeline pattern: sequential modules chained via in-memory objects (numpy arrays / OpenCV mats)
- Modular design: each stage (detection, OCR, tracking) is a self‐contained component
- CLI parameterization: anpr-system.py accepts weights/input/output/csv flags for flexibility
- Offline vs. Online separation: training and inference are clearly decoupled

##### Detail without overthinking
- Every major script or notebook as an optional “Developer Tools” section if desired

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Offline Model Training
    subgraph "Offline Model Training"
        direction TB
        Scraping["image_scrapping.ipynb"]:::notebook
        Labeling["License_Plate_Detection.ipynb"]:::notebook
        TrainingNB["yolov5_training.ipynb"]:::notebook
        ArtifactsDir["runs/train/exp"]:::storage
        BestWeights["best.pt"]:::storage
        ResultsCSV["results.csv"]:::storage
        HypConfig["hyp.yaml"]:::storage
        OptConfig["opt.yaml"]:::storage
        EventsLog["events.out.tfevents*"]:::storage

        Scraping -->|"raw images"| Labeling
        Labeling -->|"labeled dataset"| TrainingNB
        TrainingNB -->|"training artifacts"| ArtifactsDir
        ArtifactsDir --> BestWeights
        ArtifactsDir --> ResultsCSV
        ArtifactsDir --> HypConfig
        ArtifactsDir --> OptConfig
        ArtifactsDir --> EventsLog
    end

    %% Real-Time Inference Pipeline
    subgraph "Real-Time Inference"
        direction TB
        CLI["anpr-system.py"]:::cli
        VideoSource["Video Source (MP4/Camera)"]:::io
        FrameExtract["Frame Extractor\n(OpenCV VideoCapture)"]:::process
        Detector["YOLOv5 Detector\n(PyTorch)"]:::process
        CropPreproc["ROI Crop & Preprocess"]:::process
        OCR["PaddleOCR Reader"]:::process
        Tracker["Norfair Tracker"]:::process
        VideoOut["Annotated Video Writer\n(OpenCV VideoWriter)"]:::io
        CSVLog["CSV Logger"]:::io

        CLI --> VideoSource
        VideoSource -->|"video frames"| FrameExtract
        FrameExtract -->|"frames"| Detector
        BestWeights -.-> Detector
        Detector -->|"bounding boxes"| CropPreproc
        CropPreproc -->|"cropped ROIs"| OCR
        OCR -->|"text strings"| Tracker
        Tracker -->|"tracked results"| VideoOut
        Tracker -->|"tracked results"| CSVLog
    end

    %% Developer Tools & Docs
    subgraph "Developer Tools & Documentation"
        direction TB
        DemoNotebook["ANPR_with_Tracking.ipynb"]:::notebook
        Utility["utility_files/"]:::storage
        Requirements["requirements.txt"]:::io
        Readme["README.md"]:::io
        LicenseFile["LICENSE"]:::io

        DemoNotebook
        Utility
        Requirements
        Readme
        LicenseFile
    end

    %% Styles
    classDef process fill:#D0E8FF,stroke:#004085;
    classDef io fill:#E2E3E5,stroke:#6C757D;
    classDef storage fill:#D4EDDA,stroke:#155724;
    classDef notebook fill:#FFF3CD,stroke:#856404;
    classDef cli fill:#F8D7DA,stroke:#721C24;

    %% Click Events
    click CLI "https://github.com/tkvmaster/anpr-system/blob/main/anpr-system.py"
    click Scraping "https://github.com/tkvmaster/anpr-system/blob/main/image_scrapping.ipynb"
    click Labeling "https://github.com/tkvmaster/anpr-system/blob/main/License_Plate_Detection.ipynb"
    click TrainingNB "https://github.com/tkvmaster/anpr-system/blob/main/yolov5_training.ipynb"
    click DemoNotebook "https://github.com/tkvmaster/anpr-system/blob/main/ANPR_with_Tracking.ipynb"
    click ArtifactsDir "https://github.com/tkvmaster/anpr-system/tree/main/runs/train/exp"
    click BestWeights "https://github.com/tkvmaster/anpr-system/blob/main/runs/train/exp/weights/best.pt"
    click ResultsCSV "https://github.com/tkvmaster/anpr-system/blob/main/runs/train/exp/results.csv"
    click HypConfig "https://github.com/tkvmaster/anpr-system/blob/main/runs/train/exp/hyp.yaml"
    click OptConfig "https://github.com/tkvmaster/anpr-system/blob/main/runs/train/exp/opt.yaml"
    click EventsLog "https://github.com/tkvmaster/anpr-system/blob/main/runs/train/exp/events.out.tfevents.1670929509.004fd0c0c5af.3206.0"
    click Utility "https://github.com/tkvmaster/anpr-system/tree/main/utility_files/"
    click Requirements "https://github.com/tkvmaster/anpr-system/blob/main/requirements.txt"
    click Readme "https://github.com/tkvmaster/anpr-system/blob/main/README.md"
    click LicenseFile "https://github.com/tkvmaster/anpr-system/tree/main/LICENSE"
```
