Komplexní end-to-end machine learning projekt, který překonává propast mezi pouhým trénováním konvoluční sítě (CNN) a jejím reálným nasazením do moderní desktopové aplikace pro klasifikaci v reálném čase. An end-to-end machine learning project. It bridges the gap between training a Convolutional Neural Network (CNN) and deploying it into a modern, borderless desktop app for real-time classification.

Proč tento projekt vyčníváWhy this project stands out

Zatímco trénování modelu na datasetu MNIST je běžný začátek, tento repozitář se zaměřuje na inženýrské aspekty a nasazení, které z něj dělají skutečnou aplikaci: While training a model on the MNIST dataset is a common starting point, this repository focuses on the engineering and deployment aspects that make an application ready:

• Domain-Specific Augmentation:
  Kreslení myší přináší odchylky, které v perfektně vycentrovaném MNIST datasetu nejsou. Trénovací pipeline využívá RandomAffine (posun, škálování a rotace) namísto běžného šumu, což nutí model lépe zobecňovat na různě velké a nevycentrované tahy. Human mouse-drawing introduces variations not present in the perfectly centered MNIST dataset. The training pipeline utilizes RandomAffine (translation, scaling, and rotation) forcing the model to generalize to off-center and differently sized strokes.
• Modern GUI:
  Žádné výchozí okraje oken. Aplikace nabízí moderní rozhraní postavené na CustomTkinter s vlastní logikou tažení a real-time inferencí (model predikuje nepřetržitě během kreslení). No default window borders. The app features a custom-built, rounded, borderless UI using CustomTkinter with smooth custom drag logic and real-time inference (the model predicts continuously as you draw).
• Professional Training Pipeline:
  Zahrnuje automatické ukládání checkpointů, dynamické plánování rychlosti učení (ReduceLROnPlateau) a robustní logování experimentů pomocí TensorBoard i Weights & Biases (W&B). Includes automated checkpointing, dynamic learning rate scheduling (ReduceLROnPlateau), and robust experiment tracking with both TensorBoard and Weights & Biases (W&B).

Klíčové funkceFeatures

• Klasifikace v reálném čase:Real-time Classification:
  Predikce s nulovým zpožděním aktualizované při každém pohybu myši. Zero-lag predictions updated on every mouse motion event.
• Sledování jistoty sítě:Confidence Tracking:
  Dynamické UI prvky (barvy a progress bary), které reagují na distribuci Softmax pravděpodobností. Dynamic UI elements (colors and progress bars) that react to the model's Softmax confidence distribution.
• Čistá OOP architektura:Clean OOP Architecture:
  Vysoce modulární kód striktně oddělující architekturu modelu, trénovací cyklus, spouštěcí skripty a UI. Highly modular codebase separated into model architecture, training lifecycle, execution scripts, and UI.
• Integrace Tqdm:Tqdm Integrations:
  Čisté, synchronizované výpisy v konzoli během trénování bez překrývání bufferu. Clean, synchronized console outputs during training without buffer overlap.

Struktura projektuProject Structure

digit_classification/
├── data/                  # Auto-generated (datasets, models, logs)
├── src/
│   ├── app.py             # GUI and real-time classification
│   ├── model.py           # CNN architecture definition
│   ├── train.py           # Configuration and training script entry point
│   └── trainer.py         # PyTorchTrainer class (training loop, W&B, checkpoints)
├── requirements.txt
└── README.md

Rychlý startQuick Start

Příprava prostředí, natrénování modelu a spuštění samotné aplikace zabere jen pár příkazů (doporučeno Python 3.12+). Setting up the environment, training the model, and launching the application takes just a few commands (Python 3.12+ recommended).

1. Instalace závislostí1. Install Dependencies

pip install -r requirements.txt

2. Trénování modelu2. Train the Model

Automaticky stáhne dataset, inicializuje W&B a uloží nejlepší váhy. Automatically downloads the dataset, initializes W&B, and saves the best weights.

python src/train.py

3. Spuštění aplikace3. Run the Application

Zapne interaktivní dashboard pro kreslení. Launches the interactive drawing dashboard.

python src/app.py

Architektura modeluModel Architecture

Síť je lehká PyTorch CNN navržená pro rychlou inferenci na CPU/GPU. Skládá se ze dvou konvolučních bloků (extrakce příznaků na 32 kanálů) a plně propojené klasifikační vrstvy (128 skrytých neuronů na 10 výstupních logitů). The network is a lightweight PyTorch CNN designed for fast CPU/GPU inference. It consists of a Feature Extractor (2x Conv Blocks mapping to 32 channels) and a Classifier (128 hidden neurons outputting 10 class logits).

import torch.nn as nn

class DigitClassifierCNN(nn.Module):
    def __init__(self):
        super().__init__()
        
        # Feature Extractor: 1 channel -> 32 channels
        self.features = nn.Sequential(
            nn.Conv2d(1, 16, kernel_size=3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2),
            nn.Conv2d(16, 32, kernel_size=3, padding=1),
            nn.ReLU(),
            nn.MaxPool2d(2)
        )
        
        # Classifier: Flatten -> 128 hidden neurons -> 10 output logits
        self.classifier = nn.Sequential(
            nn.Flatten(),
            nn.Linear(32 * 7 * 7, 128),
            nn.ReLU(),
            nn.Linear(128, 10)
        )

    def forward(self, x):
        return self.classifier(self.features(x))

Logování a sledováníExperiment Tracking

Všechny trénovací běhy jsou automaticky logovány. Křivky ztrátové funkce a metrik můžete sledovat lokálně pomocí TensorBoardu: All training runs are automatically logged. You can view the loss curves and accuracy metrics locally using TensorBoard:

tensorboard --logdir data/runs

Případně si je můžete zobrazit v cloudových dashboardech vašeho účtu Weights & Biases. Or view your rich dashboards in the cloud via your Weights & Biases account.