How gbennnn/realtime-digit-recognition works
Purpose and execution modes
This repository serves realtime MNIST handwritten-digit recognition. It has two primary entry points:
• Training: train_mnist.py downloads MNIST, trains a TensorFlow/Keras CNN, and writes a reusable model artifact.
• Serving: app.py runs a Flask application that loads the trained artifact and exposes browser-driven inference.
Model lifecycle
The training pipeline in train_mnist.py defines and fits the CNN: two convolution/pooling stages followed by dense classification layers for digits 0–9. TensorFlow is the material ML runtime and MNIST is obtained externally through its dataset loader. The resulting deployable artifact is models/mnist_cnn.h5.
Flask inference boundary
app.py is the server-side integration point between HTTP clients and TensorFlow inference. It renders the application UI and owns the /predict endpoint. The endpoint accepts the drawing representation, applies MNIST-oriented image preparation—cropping, scaling, and padding—and returns prediction data to the client. The model file boundary is models/mnist_cnn.h5.
Browser drawing and realtime request flow
The UI is composed of templates/index.html, static/script.js, and static/style.css. The HTML hosts the canvas and prediction display; browser JavaScript captures drawing input, serializes the canvas image, and issues repeated requests to Flask while the user draws. Response data updates the displayed predicted digit, creating the realtime interaction loop.
Input normalization contract
The key compatibility boundary is between canvas output and the model’s expected MNIST-like tensor. Client-produced drawings are not directly equivalent to MNIST samples, so server preprocessing in app.py normalizes geometry via foreground cropping, resizing, and padding before model invocation. Training input conventions established in train_mnist.py must remain aligned with this inference preprocessing.
Runtime and deployment shape
The app is a local Python 3.10+ process using Flask 3.1 and TensorFlow 2.19, with dependencies defined in requirements.txt. It has no separate database, queue, or cloud service dependency. Runtime availability depends on the trained H5 artifact being present at models/mnist_cnn.h5; retraining/regeneration is handled by train_mnist.py.
Main entry points: train_mnist.py CNN training · app.py /predict endpoint · index.html Canvas page · script.js Drawing client
Components 11
Training pipeline
- MNIST dataset
- CNN training · Defines and fits the digit classifier.
train_mnist.py
Flask serving
- Flask inference app · Renders the UI and owns /predict preprocessing and inference.
app.py - MNIST image preparation · Crops, rescales, and pads canvas drawings into model input.
app.py - /predict endpoint
app.py
Browser UI
- Canvas page · Hosts the drawing canvas and prediction display.
templates/index.html - Drawing client · Captures strokes, serializes canvas data, and updates predictions.
static/script.js - UI styles
static/style.css
Other components
- TensorFlow/Keras
- Trained CNN artifact · Reusable digit classifier required by serving.
models/mnist_cnn.h5 - Python dependencies · Pins Flask and TensorFlow runtime dependencies.
requirements.txt
Connections 15
- MNIST dataset → CNN training: loaded for training
- TensorFlow/Keras → CNN training: trains CNN
- CNN training → Trained CNN artifact: writes artifact
- Python dependencies → Flask inference app: provides Flask runtime
- Python dependencies → TensorFlow/Keras: provides ML runtime
- Trained CNN artifact → Flask inference app: loaded at startup
- Canvas page → Flask inference app: rendered by
- UI styles → Canvas page: styles
- Canvas page → Drawing client: loads
- Drawing client → /predict endpoint: repeated canvas requests
- /predict endpoint → MNIST image preparation: drawing payload
- MNIST image preparation → TensorFlow/Keras: MNIST-like tensor
- TensorFlow/Keras → /predict endpoint: prediction result
- /predict endpoint → Drawing client: prediction data
- CNN training → MNIST image preparation: shares input convention