Facial Expression Classification

A PyTorch-based deep learning model for classifying facial expressions into 5 emotion categories: Angry, Fear, Happy, Sad, and Surprise.

🚀 Quick Start

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

# 2. Train the model (if not already trained)
python train_model.py

# 3. Test predictions
python test_samples.py

# 4. Try the interactive demo
python demo_app.py

Features

• GPU-Optimized Training: Automatically uses CUDA if available
• Data Augmentation: Random flips, rotations, and translations for better generalization
• Early Stopping: Prevents overfitting by stopping when validation performance plateaus
• Learning Rate Scheduling: Automatically reduces learning rate when training stalls
• Comprehensive Evaluation: Generates accuracy plots, confusion matrices, and per-class metrics

Architecture

The CNN model consists of:

• 4 convolutional blocks with progressive filter increases (32 → 64 → 128 → 256)
• Batch normalization and dropout for regularization
• 3 fully connected layers for classification
• ~2.5M trainable parameters

Requirements

Install dependencies:

pip install -r requirements.txt

Usage

Training

Simply run the training script:

python train_model.py

The script will:

1. Load images from the data/ directory
2. Split into train/validation/test sets (70%/15%/15%)
3. Train the CNN model with GPU acceleration
4. Save the best model based on validation accuracy
5. Generate evaluation plots and metrics

Prediction Demo

After training, you can use the model to predict emotions in new images:

Option 1: Command-Line Interface

Predict on a single image:

python predict.py --image path/to/your/image.jpg

Predict on all images in a directory:

python predict.py --dir path/to/images/ --output predictions/

Use a custom model:

python predict.py --image test.jpg --model best_model.pth

Option 2: Interactive Web Demo

Launch a user-friendly web interface:

python demo_app.py

This will start a Gradio web server where you can:

• Upload images through your browser
• See real-time predictions with confidence scores
• Get a visual breakdown of emotion probabilities
• Access the demo from any device on your network

The web interface will be available at http://localhost:7860 and will also provide a public URL for sharing (valid for 72 hours).

Output Files

After training completes, you'll find:

• facial_expression_model.pth - Final trained model with metadata
• best_model.pth - Best checkpoint during training
• class_names.txt - Emotion class labels
• training_history.png - Training and validation curves
• confusion_matrix.png - Classification performance heatmap

Demo Scripts

The project includes two demo scripts for inference:

1. predict.py - Command-line prediction tool

   • Process single images or entire directories
   • Generates visualization images with predictions
   • Outputs detailed probability scores

2. demo_app.py - Interactive web interface (Gradio)

   • User-friendly browser-based UI
   • Real-time predictions with visual feedback
   • Shareable public URL for remote access
   • Perfect for demonstrations and testing

Data Structure

Organize your data as follows:

data/
├── Angry/
│   ├── image1.png
│   ├── image2.jpg
│   └── ...
├── Fear/
│   └── ...
├── Happy/
│   └── ...
├── Sad/
│   └── ...
└── Suprise/
    └── ...

Configuration

Key parameters can be adjusted in the script:

• DEFAULT_IMG_SIZE: Image dimensions (default: 48x48)
• DEFAULT_BATCH_SIZE: Batch size for training (default: 32)
• DEFAULT_EPOCHS: Maximum training epochs (default: 50)
• DEFAULT_LEARNING_RATE: Initial learning rate (default: 0.001)

Model Performance

The model achieves:

• Fast training with GPU support (~100-300 it/s)
• Automatic best model selection
• Detailed per-class metrics (precision, recall, F1-score)
• Visual confusion matrix for error analysis

Code Structure

The codebase follows Python best practices:

• Type hints for function signatures
• Comprehensive docstrings
• Modular class-based design
• Clear comments explaining key operations
• Constants for easy configuration

License

This project is provided as-is for educational purposes.