MNIST Handwritten Digit Recognition

This repository contains a simple pipeline for training a neural network on the classic MNIST dataset.
It demonstrates:

• Downloading and preprocessing the data
• Visualising the training/test images (optional)
• Building and training a neural network
• Evaluating a trained model
• Saving and reloading the trained model for interference

Table of Contents

1. Project Structure
2. Requirements
3. Installation
4. Usage
5. Examples
6. Web App
7. Contributing

Project Structure

Project Structure

    .
├── README.md
├── data
│   └── MNIST
│       └── mnist.npz
├── main.py
├── models
│   ├── __init__.py
│   ├── create_model.py
│   └── saved_models
│       ├── __init__.py
│       └── mnist_model.keras
├── requirements.txt
├── scripts
│   ├── download_data.py
│   ├── evaluate.py
│   ├── train.py
│   └── visualise.py
└── web_app
    ├── app.py
    ├── static
    │   └── styles
    │       └── style.css
    └── templates
        ├── index.html
        └── results.html

Requirements

• Python 3.7+

Packages

• TensorFlow (tested with TensorFlow 2.12+)
• NumPy
• Matplotlib
• argparse (bundled with standard Python)

All required packages are listed in requirements.txt

Installation

1. Clone the repository:

   git clone https://github.com/hub-mm/MNIST_handwritten_digit_recognition.git

2. Create Virtual Environment:

   python -m venv venv
   source venv/bin/activate # on macOS/Linux
   .\venv\Scripts\activate  # on Windows

3. Install Dependencies:

   pip install --upgrade pip
   pip install -r requirements.txt

Usage

• Run main.py script to train and evaluate the model:

  python main.py --epochs 3 --visualise

  Command Line Arguments:

  Argument	Description	Default
  --epochs	Number of epochs to train the model	3
  --visualise	If set, shows a sample image from the dataset	(flag)
  --dataset_path	Path to store/load the MNIST dataset	./data/MNIST

Examples

1. Train for 5 epochs and visualise a sample:

   python main.py --epochs 5 --visualise

2. Train for 10 epochs without visualising:

   python main.py --epochs 10

3. Specify a custom dataset path:

   python main.py --epochs 2 --dataset_path /tmp/mnist

4. Use Default:

   python main.py

When using the default parameters, this will:

1. Download the MNIST dataset to ./data/MNIST/ if not already present
2. Train a simple neural network for 3 epochs
3. Evaluate on the test set (10k images)
4. Save the model the ./models/saved_models/mnist_model.keras
5. Reload the model, compile it, predict the first test image, and display the predicted label vs. the true label

Web App

After training the model, there is the option to test out some images on a web page.

• Simple Web Page: contains a landing page and result page.

• Ability to upload Images: png, jpg, jpeg, etc. (gets converted to png).

• Output: prediction made by the trained model of what number the image is showing.

  Limitations

  • Can only guarantee accuracy for MNIST type of images.
  • Only works with single numbers.
  • Work best with black background and white number.

  Process

  Run main scripts again after training with default parameters:

  python main.py

  Click on link in terminal or access via: http://127.0.0.1:5000 if default parameters are kept.

Contributing

1. Fork the repository

2. Create a feature branch:

   git checkout -b feature/my_new_feature

3. Commit your changes:

   git commit -m 'Add some feature'

4. Push to the branch:

   git push origin feature/my_new_feature

5. Open a pull request describing what changed and why

Thank you for taking the time to check this work out!