🧠 MNIST Handwritten Digit Recognition

A deep learning project that identifies handwritten digits (0–9) using a custom Convolutional Neural Network (CNN) built with PyTorch, trained on the MNIST dataset, with interactive prediction interfaces powered by OpenCV and Gradio.

(A placeholder for a demo GIF or screenshot showing the Gradio or OpenCV app in action)

📑 Table of Contents

• Project Overview
• Results
• Project Structure
• Getting Started
• CNN Architecture
• Technologies Used
• Notebooks Guide
• Contributing
• License

---

🎯 Project Overview

This project demonstrates the complete deep learning pipeline:

1. Data Exploration — Understanding the MNIST dataset structure and distribution
2. Model Training — Training a CNN from scratch using PyTorch (with Apple Silicon MPS acceleration)
3. FastAI Baseline — Training a transfer learning baseline with FastAI for comparison
4. Interactive Prediction — Drawing digits and getting real-time predictions via:
   • An OpenCV desktop canvas application
   • A Gradio browser-based web UI
5. Model Evaluation — Confusion matrices, misclassification analysis, and per-class metrics

---

📊 Results

Metric	Value
Training Accuracy	98.27%
Validation Accuracy	99.14%
Architecture	2-layer CNN with Dropout
Training Device	Apple Silicon M5 (MPS)
Training Time	~5 epochs

---

🏗️ Project Structure

CV_ML_Project/
├── README.md                         # This file
├── requirements.txt                  # Python dependencies
├── notebooks/
│   ├── 01_mnist_exploration.ipynb    # Data exploration & visualization
│   ├── 02_fastai_training.ipynb      # FastAI transfer learning baseline
│   ├── 03_pytorch_from_scratch.ipynb # Custom CNN training notebook
│   └── 04_evaluation.ipynb           # Model evaluation & metrics
├── src/
│   ├── __init__.py
│   ├── model.py                      # CNN architecture (DigitCNN)
│   ├── train.py                      # Standalone training script
│   ├── predict.py                    # Single-image prediction utility
│   └── preprocess.py                 # Image preprocessing pipeline
├── app/
│   ├── canvas.py                     # OpenCV interactive drawing canvas
│   └── web_ui.py                     # Gradio web-based drawing UI
├── models/
│   └── digit_cnn.pth                 # Trained model weights
├── data/
│   └── MNIST/                        # Auto-downloaded MNIST dataset
└── tests/
    └── test_predict.py               # Unit tests for pipeline

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• macOS with Apple Silicon (M1/M2/M3/M4/M5) recommended for MPS GPU acceleration

Installation

# Clone the repository
git clone git@github.com:shard-c6/cv-ml-project.git
cd cv-ml-project

# Install dependencies
pip install -r requirements.txt

Train the Model

The trained weights are already included (models/digit_cnn.pth), but you can retrain:

python3 src/train.py

Run the OpenCV Canvas App

python3 app/canvas.py

• Draw a digit with your mouse
• Press p to predict
• Press c to clear
• Press q to quit

Run the Gradio Web UI

python3 app/web_ui.py

Open http://127.0.0.1:7860 in your browser, draw a digit, and click Identify Digit.

Run Tests

python3 tests/test_predict.py

---

🧠 CNN Architecture

Input (1 × 28 × 28)
  ↓
Conv2d(1 → 32, 3×3, padding=1) → ReLU → MaxPool2d(2×2) → Dropout2d(0.15)
  ↓
Conv2d(32 → 64, 3×3, padding=1) → ReLU → MaxPool2d(2×2) → Dropout2d(0.25)
  ↓
Flatten → Linear(64×7×7 → 128) → ReLU → Dropout(0.5)
  ↓
Linear(128 → 10) → Output (digit 0–9)

---

🔧 Technologies Used

Technology	Purpose
PyTorch	Deep learning framework, CNN implementation
FastAI	High-level training API, transfer learning
OpenCV	Image preprocessing, interactive drawing canvas
Gradio	Browser-based web UI for predictions
torchvision	MNIST dataset loading and transforms
Matplotlib	Data visualization and evaluation plots
NumPy	Numerical computing and array operations

---

📓 Notebooks Guide

Notebook	Description
01_mnist_exploration.ipynb	Load MNIST, visualize samples, check class distribution
02_fastai_training.ipynb	Train a ResNet18 baseline with FastAI, confusion matrix
03_pytorch_from_scratch.ipynb	Build and train a CNN from scratch in PyTorch
04_evaluation.ipynb	Full evaluation: confusion matrix, misclassified examples

---

🤝 Contributing

Contributions are welcome! Please check out the CONTRIBUTING.md guide to see how you can help, whether by reporting bugs, suggesting features, or opening pull requests.

---

🙏 Acknowledgments

• The MNIST Database by Yann LeCun, Corinna Cortes, and Christopher J.C. Burges
• PyTorch & FastAI for making deep learning accessible
• Gradio for the intuitive web UI framework

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⬆️ Back to Top