# bahrombekk/train-number architecture

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

- Interactive diagram: https://gitdiagram.com/bahrombekk/train-number
- Repository: https://github.com/bahrombekk/train-number

## Overview

##### Project type and purpose
- This is a specialized video-processing pipeline (not a full-stack web app) for batch processing trains-of-interest. It uses computer vision and machine learning to detect train wagons and read their numbers.
- Purpose: Ingest multiple video files, detect wagons in frames via YOLO, recognize digits within each detection, validate them, and write annotated video + text/image outputs.

##### File structure
Top-level files and directories:
- main.py             – Orchestrates processing of multiple videos in parallel
- video_processor.py  – Implements the VideoProcessor class and the multi-threaded pipeline
- data.json           – Configuration listing videos and model paths
- demo/               – Sample/demo scripts, data and outputs to illustrate functionality
- output/             – Default output directory structure for processed frames, images, text
- requirements.txt    – Dependencies (OpenCV, PyTorch, etc.)
- number.txt / video files (not in repo)
Patterns:
- Pipeline / producer-consumer pattern with two message queues
- Multi-threading for CPU/GPU utilization
- File-system used as persistence (no database)

##### README for additional insights
- Main Class: VideoProcessor with methods setup_directories, frame_producer, frame_processor, frame_writer
- Main script loads data.json, spawns a thread per video to call process_video()
- Two models: YOLO object detection model + digit recognition model (PyTorch)
- Outputs:
– Annotated video file
– Text files of detected numbers
– Image snapshots of valid detections

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration and Controller
    Config["Configuration Loader\ndata.json"]:::config
    Main["Main Controller\nmain.py"]:::core
    Config --> Main

    %% VideoProcessor Module
    subgraph "VideoProcessor" 
        direction TB
        VP["VideoProcessor\n(video_processor.py)"]:::core
        Setup["setup_directories()"]:::core
        Producer(("Frame Producer Thread")):::thread
        FrameQ[/FrameQueue/]:::storage
        Processor(("Frame Processor Thread")):::thread
        ProcQ[/ProcessedQueue/]:::storage
        Writer(("Frame Writer Thread")):::thread

        VP --> Setup
        Setup --> Producer
        Producer --> FrameQ
        FrameQ --> Processor
        Processor --> ProcQ
        ProcQ --> Writer
    end
    Main --> VP

    %% Models and Libraries
    YOLO["YOLO Model Service"]:::model
    Digit["Digit Recognition Model Service"]:::model
    Libs["External Libraries\nOpenCV, PyTorch, threading"]:::deps

    Processor --> YOLO
    Processor --> Digit
    Producer --> Libs
    Processor --> Libs

    %% File System Storage
    FS[/File System\nInput Videos & Outputs/]:::fs
    Producer --> FS
    Processor --> FS
    Writer --> FS

    %% Demo Scripts and Data
    subgraph "Demo" 
        direction TB
        DemoMain["demo/main.py"]:::demo
        DemoModel["demo/model.py"]:::demo
        DemoNumber["demo/number.py"]:::demo
        DemoData["demo/data.json"]:::demo
        DemoOutput[/demo/output/]:::demo

        DemoData --> DemoMain
        DemoMain --> DemoModel
        DemoMain --> DemoNumber
        DemoMain --> DemoOutput
    end

    %% Click Events
    click Config "https://github.com/bahrombekk/train-number/blob/main/data.json"
    click Main "https://github.com/bahrombekk/train-number/blob/main/main.py"
    click VP "https://github.com/bahrombekk/train-number/blob/main/video_processor.py"
    click YOLO "https://github.com/bahrombekk/train-number/blob/main/video_processor.py"
    click Digit "https://github.com/bahrombekk/train-number/blob/main/video_processor.py"
    click FS "https://github.com/bahrombekk/train-number/tree/main/output/"
    click DemoMain "https://github.com/bahrombekk/train-number/blob/main/demo/main.py"
    click DemoModel "https://github.com/bahrombekk/train-number/blob/main/demo/model.py"
    click DemoNumber "https://github.com/bahrombekk/train-number/blob/main/demo/number.py"
    click DemoData "https://github.com/bahrombekk/train-number/blob/main/demo/data.json"
    click DemoOutput "https://github.com/bahrombekk/train-number/tree/main/demo/output/"
    click Libs "https://github.com/bahrombekk/train-number/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef config fill:#D7BDE2,stroke:#512E5F,color:#1B2631;
    classDef thread fill:#D5DBDB,stroke:#717D7E,color:#1B2631;
    classDef storage fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef model fill:#F5CBA7,stroke:#7E5109,color:#1B2631;
    classDef fs fill:#A9DFBF,stroke:#145A32,color:#1B2631;
    classDef deps fill:#F1948A,stroke:#641E16,color:#1B2631;
    classDef demo fill:#EBDEF0,stroke:#6C3483,color:#1B2631;
```
