🔢 DigitVision

• About the Project
• Features
• How It Works
• Model Architecture
• Model Performance
• Tech Stack
• Getting Started
• Usage Tips
• Project Structure
• Deployment
• Limitations
• License
• Author

MNIST models usually stop at a notebook: great accuracy on clean 28×28 test images, and no idea what happens with a real photo. DigitVision closes that gap. It pairs a compact, regularized CNN with a computer-vision preprocessing pipeline that turns messy, real-world photos of handwritten digits into MNIST-style input, and wraps everything in a clean Streamlit web app.

You can try it right now: digitvision-app.streamlit.app

• Two input modes: upload an image (PNG/JPG) or take a photo directly with your camera.
• Smart digit extraction: detects red ink via HSV color masking, with an automatic Otsu-threshold fallback for dark pen on light paper.
• MNIST-style normalization: crops, scales to 20 px, pads to 28×28 and centers the digit by its center of mass, the same way MNIST was built.
• Transparent results: predicted digit, confidence level (high / medium / low), top-3 predictions and a probability chart for all ten classes.
• "How DigitVision saw your image": inspect the detection box, binary mask and the exact 28×28 model input.
• Model dashboard: test accuracy, parameter count, epochs and per-digit accuracy in the sidebar.
• Prediction history: the last 10 predictions of your session.
• Reproducible training: fixed seeds and a single script (train.py) that also writes metrics.json.

 Photo / Upload
       │
       ▼
 Resize (max 800 px)
       │
       ▼
 Enough red ink found? ── yes ──▶ HSV red-ink mask ──────┐
       │ no                                              │
       ▼                                                 │
 Grayscale → Gaussian blur → Otsu threshold ─────────────┤
 (auto-inverted if the background is dark)               │
                                                         ▼
                                       Morphological close + open
                                                         │
                                                         ▼
                                    Contour detection → bounding box
                                                         │
                                                         ▼
                           Scale to 20 px → pad to 28×28 → center of mass
                                                         │
                                                         ▼
                                       CNN → softmax (10 classes)
                                                         │
                                                         ▼
                                     Digit + confidence + charts

1. Segmentation: the image is searched for red ink first; if there isn't enough, it falls back to grayscale + Gaussian blur + Otsu thresholding (auto-inverted when the background is dark).
2. Cleanup: morphological closing and opening remove noise and fill small gaps.
3. Localization: contours with at least 10 % of the largest contour's area are merged into one bounding box.
4. Normalization: the digit is resized so its longest side is 20 px, placed on a 28×28 canvas and shifted so its center of mass sits at the center.
5. Classification: the CNN outputs a probability for each digit 0–9.

A lightweight VGG-style CNN with built-in data augmentation, 289,066 parameters in total.

Training setup

Evaluated on the official 10,000-image MNIST test set. Early stopping ended training after 15 epochs.

Per-digit accuracy

All numbers come from metrics.json, which train.py generates automatically.

• Python 3.10 or newer
• pip (and optionally venv)

# 1. Clone the repository
git clone https://github.com/MahdiKordian/DigitVision.git
cd DigitVision

# 2. (Recommended) create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

The repository already includes the trained model (mnist_model.keras), so you can start right away:

streamlit run app.py

Then open the local URL shown in your terminal (usually http://localhost:8501).

python train.py

This downloads MNIST (if needed), trains the network, and saves:

• mnist_model.keras: the trained model
• metrics.json: accuracy, loss, parameters, epochs, training time and per-digit accuracy

The app reads both files automatically.

• Write one digit, large and clear, in the frame.
• A red marker on white paper gives the most reliable detection.
• A dark pen on light paper works too.
• Avoid shadows, glare and busy backgrounds.
• If the result card turns orange or red, the model is unsure: retake the photo with better light or a bigger digit.

DigitVision/
├── app.py              # Streamlit web app (UI, preprocessing, inference)
├── train.py            # Model definition, training and evaluation
├── config.py           # App name, version, tagline and file paths
├── requirements.txt    # Python dependencies
├── mnist_model.keras   # Trained model
├── metrics.json        # Evaluation results shown in the app
├── LICENSE             # MIT License
├── .gitignore
└── README.md

The live demo is hosted on Streamlit Community Cloud: digitvision-app.streamlit.app.

To deploy your own copy:

1. Fork this repository.
2. Go to share.streamlit.io and create a new app from your fork.
3. Set the main file to app.py and deploy.

Make sure mnist_model.keras and metrics.json are committed. The app needs them at startup.

• DigitVision recognizes a single digit per image. Multi-digit numbers are not supported.
• The model is trained on MNIST only. The 99.32 % figure is measured on MNIST's own test set; accuracy on real photos depends on lighting, pen thickness and image quality, which is why the preprocessing pipeline and confidence indicator exist.
• Unusual writing styles (for example a crossed 7 or a looped 1) may reduce confidence.

Distributed under the MIT License. See LICENSE for details.

Mahdi Kordian, AI Engineer working with Machine Learning, Deep Learning, Generative AI and LLMs.

If you find this project useful, a ⭐ on the repository is much appreciated.