Facial-Emotion-Detector

From the README

Facial Emotion Detection

A machine learning project for detecting and classifying facial emotions using OpenCV and MediaPipe for face detection and landmark extraction.

Recognition

2nd Runner-up at InfinityAI 2025, the hackathon run by Tredence Inc. and Databricks in Bengaluru, March 2025. Prize: ₹2,00,000.

Project Overview

This system detects faces in images or video streams and classifies the emotion displayed by the face. It uses:

• MediaPipe for facial landmark detection
• Machine learning algorithms for emotion classification
• OpenCV for image processing and visualization

Supported Emotions

The system is not tied to a fixed emotion set. The classes it recognises are whatever the EMOTIONS variable in .env lists at the time you collect data and train — the shipped .env configures two classes. If EMOTIONS is unset, utils.py falls back to angry,disgust,fear,happy,neutral,sad,surprise.

Installation

1. Clone the repository:

git clone https://github.com/Life-Experimentalist/Facial-Emotion-Detector.git
cd Facial-Emotion-Detector

1. Install dependencies:

pip install -r requirements.txt

1. Ensure required model files are in the correct location:
   • face_landmarker.task (MediaPipe face landmark model)
   • haarcascade_frontalface_default.xml (OpenCV face detection model)

Project Workflow

Follow these steps to train and use your own emotion detection model:

1. Collect Training Images

Run the collection script to gather training images for each emotion:

python collect_imgs.py

This will:

• Access your webcam
• Prompt you to show different emotions
• Capture and save facial images for each emotion class
• Store images in data/train/<emotion>

2. Prepare Data

Process the collected images for training:

python prepare_data.py

This script:

• Extracts facial landmarks from each image
• Processes the data into a format suitable for training
• Creates training and validation datasets

3. Train Model

Train the emotion detection model:

python train_model.py

This will:

• Train a machine learning model on your prepared data
• Evaluate model performance
• Save the trained model as model.pkl

4. Run Inference

Once trained, you can detect emotions in real-time:

python inference.py

By default, this uses your webcam. Other options include:

• Process an image: python inference.py -i path/to/image.jpg
• Process a video: python inference.py -v path/to/video.mp4
• Save results: python inference.py -o output.avi

Configuration

Settings can be modified in the .env file:

FACE_CASCADE_PATH=path/to/haarcascade_frontalface_default.xml
IMAGES_PER_CLASS=100
NUM_CLASSES=2
DATA_DIR=path/to/data
EMOTIONS=happy,neutral
DEBUG=False
CROP_FACE_ONLY=False
CONSOLE_OUTPUT=False

Required Files

Model Files

• face_landmarker.task: MediaPipe face landmark detection model for extracting facial features
• haarcascade_frontalface_default.xml: OpenCV's Haar Cascade for face detection (fallback method)
• model.pkl: Your trained emotion classification model (created after training)

Code Files

• collect_imgs.py: Script to collect training images from webcam
• prepare_data.py: Processes images and extracts features for training
• train_model.py: Trains the emotion classification model
• inference.py: Performs emotion detection on images, videos or webcam feed
• utils.py: Shared utilities and helper functions

Environment Variables

The .env file contains configuration settings:

• FACE_CASCADE_PATH: Path to the Haar cascade XML file
• IMAGES_PER_CLASS: Number of images to collect per emotion
• NUM_CLASSES: Number of emotion classes
• DATA_DIR: Directory to store training data
• EMOTIONS: List of emotions to detect (comma-separated)
• DEBUG: Enable/disable debug logging
• CROP_FACE_ONLY: Whether to crop only the face region (True) or use full frame (False)
• CONSOLE_OUTPUT: Whether to output emotion detection results to console

Troubleshooting

Model Performance Issues

Disclaimer: If the model is not working properly or consistently predicts the same emotion, this likely indicates issues with the training data. Common problems include:

1. Insufficient data: Collect more training images for each emotion
2. Poor quality images: Ensure good lighting and clear facial expressions
3. Class imbalance: Make sure you have similar numbers of images for each emotion
4. Poor facial expressions: Ensure you're clearly expressing the intended emotion

Try retraining your model with more varied and higher-quality training data.

Common Issues

1. Camera not found: Try a different camera index with -v option
2. Face not detected: Improve lighting and position your face clearly in frame
3. Model file not found: Ensure model.pkl exists in the project directory after training

Improvements & Customization

• Add more emotion classes by modifying the EMOTIONS variable in .env
• Experiment with different machine learning algorithms in train_model.py
• Adjust landmark extraction parameters for different face types

Files That Can Be Removed (Optional)

These files are not necessary for core functionality:

• check.py: Only used for development testing
• data.txt: Legacy data file if present
• results.txt and results.txt.txt: Output logs that can be removed
• __pycache__/: Compiled Python files that are generated automatically

License

Apache License 2.0

Copyright (c) 2025 VKrishna04

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.