Skip to content

About

A modular implementation of a **Convolutional Neural Network (CNN)** from scratch in Python using only **NumPy** for computation (no PyTorch, TensorFlow, or Keras). It includes training pipelines for the classic MNIST handwritten digits dataset and a custom real-time webcam face recognizer using OpenCV.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

CNN From Scratch in Python & NumPy

A modular implementation of a Convolutional Neural Network (CNN) from scratch in Python using only NumPy for computation (no PyTorch, TensorFlow, or Keras). It includes training pipelines for the classic MNIST handwritten digits dataset and a custom real-time webcam face recognizer using OpenCV.


Features

  • Modular Layer Design: Follows a standard forward/backward API design similar to PyTorch.
  • Custom Spatial Layers: Built-in 2D cross-correlation (Conv2D) and spatial downsampling (MaxPool2D) with full backpropagation.
  • Custom Core Layers: Fully-connected linear transformations (Dense), activations (ReLU and Softmax), and reshaping (Flatten).
  • Mathematical Integrity: Custom loss functions (Mean Squared Error and Categorical Cross-Entropy) and analytical gradients computed using calculus and the chain rule.
  • Real-Time Webcam Face Recognition: Merges the custom CNN model with OpenCV's Haar Cascades and CLAHE contrast enhancement for robust, real-time face recognition via camera feeds.

Directory Structure

File Description
losses.py Loss functions (MSE and Categorical Cross-Entropy) and their analytical derivatives.
layers.py Base Layer interface, Dense, ReLU, Softmax, and Flatten layers.
cnn_layers.py Spatial convolutional neural network layers (Conv2D and MaxPool2D).
dataset.py Downloader and parsing scripts for the raw binary MNIST dataset.
train.py Main entry point to train and validate the custom CNN on MNIST handwritten digits.
prepare_faces.py Image pre-processing script (grayscale conversion, resizing to 28x28, and normalization) for custom datasets.
train_faces.py Custom training script to train the model on face folders and save weights to disk.
predict_face.py Script to perform single-image face classification.
realtime_predict.py OpenCV camera application running real-time face detection and custom CNN predictions.

Getting Started

1. Installation

Clone the repository and install the dependencies listed in requirements.txt:

pip install -r requirements.txt

2. Train on MNIST Digits

Run the standard digits classifier training loop. It will automatically download the MNIST dataset to the data/ directory:

python3 train.py

After training, a training curve plot will be saved as training_plot.png.


Real-Time Custom Face Recognizer

You can adapt this CNN to recognize you and your friends by following these steps:

Step 1: Collect Face Images

Create a folder named Faces/ in the project root directory. Inside it, create a folder for each person containing photos of them (e.g., JPEG/PNG formats):

Faces/
  ├── Face1/
  │     ├── photo1.jpg
  │     └── photo2.jpg
  └── Face2/
        ├── photo1.jpg
        └── photo2.jpg

Step 2: Preprocess the Dataset

Convert raw photos into normalized 28x28 grayscale matrices:

python3 prepare_faces.py

This saves the processed dataset to faces_dataset.npz.

Step 3: Train the Network

Train the CNN on the custom dataset and export the learned model parameters:

python3 train_faces.py

This will train the network, plot performance curves to faces_training_plot.png, and save the weights to faces_model_weights.npz.

Step 4: Run Real-Time Webcam Inference

Start the live camera application. It will detect faces in the feed using OpenCV, pass the cropped face regions to your scratch-built CNN, and display the predicted name and confidence:

python3 realtime_predict.py

(Press q in the video feed window to close it safely.)


Under the Hood: Mathematical Overview

Forward Passes:

  • Convolution: Output[d, i, j] = Sum(Input[c, i+p, j+q] * Kernel[d, c, p, q]) + Bias[d] (summed over channels c)
  • Dense: Y = X * W + B
  • Softmax: y_i = e^(z_i) / Sum(e^(z_j)) (with stability shift: z_i - max(z))

Loss Functions:

  • Categorical Cross-Entropy: CCE = - (1 / B) * Sum(y_true * log(y_pred))

About

A modular implementation of a **Convolutional Neural Network (CNN)** from scratch in Python using only **NumPy** for computation (no PyTorch, TensorFlow, or Keras). It includes training pipelines for the classic MNIST handwritten digits dataset and a custom real-time webcam face recognizer using OpenCV.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages