OpenEmotion

Open-source facial emotion recognition using Deep Learning, PyTorch, OpenCV, and FER-2013.

OpenEmotion is a deep-learning project that detects faces from images or a live webcam and predicts one of seven facial-expression classes.

Status: 🚧 Active development

Demo

OpenEmotion can process a live camera feed using OpenCV:

Webcam
   ↓
OpenCV
   ↓
Face Detection
   ↓
Face Preprocessing
   ↓
EfficientNet-B0
   ↓
Emotion + Confidence

Supported Emotions

Emotion	Class
😠	Angry
🤢	Disgust
😨	Fear
😀	Happy
😐	Neutral
😢	Sad
😲	Surprise

Features

• 🧠 PyTorch deep-learning model
• 👤 Face detection using OpenCV
• 🎭 7-class facial-expression classification
• 📷 Real-time webcam detection
• 🖼️ Image-based inference
• ⚡ GPU support with CUDA
• 💻 CPU support
• 📊 Classification report
• 📈 Confusion matrix
• 📓 Kaggle/Jupyter training notebook
• 🔧 Modular Python source code
• 🧪 Basic automated tests

---

Tech Stack

• Python
• PyTorch
• TorchVision
• OpenCV
• EfficientNet-B0
• FER-2013
• NumPy
• Pandas
• Scikit-learn
• Matplotlib
• Seaborn

---

Project Structure

OpenEmotion/
│
├── README.md
├── LICENSE
├── requirements.txt
├── pyproject.toml
├── .gitignore
│
├── notebooks/
│   └── emotion_detection.ipynb
│
├── src/
│   └── openemotion/
│       ├── __init__.py
│       ├── config.py
│       ├── model.py
│       ├── preprocessing.py
│       ├── inference.py
│       └── face_detector.py
│
├── scripts/
│   ├── train.py
│   ├── evaluate.py
│   └── webcam.py
│
├── tests/
│   └── test_inference.py
│
├── models/
│   └── .gitkeep
│
└── docs/
    └── architecture.md

---

Requirements

Recommended:

• Python 3.10+
• Git
• 8 GB+ RAM
• NVIDIA GPU + CUDA for faster training — optional
• Webcam for real-time detection — optional

OpenEmotion can run on CPU, but training will be considerably slower.

---

Installation

1. Clone the Repository

git clone https://github.com/sharmaB01/OpenEmotion.git

Enter the project directory:

cd OpenEmotion

---

2. Create a Virtual Environment

macOS / Linux

python3 -m venv .venv

Activate it:

source .venv/bin/activate

Windows

python -m venv .venv

Activate:

.venv\Scripts\activate

---

3. Install Dependencies

Upgrade pip:

python -m pip install --upgrade pip

Install dependencies:

pip install -r requirements.txt

---

Dataset

OpenEmotion uses the FER-2013 dataset.

The dataset is not included in this GitHub repository.

https://www.kaggle.com/datasets/msambare/fer2013 Download the FER-2013 dataset from a legitimate source and arrange it in the following structure:

fer2013/
│
├── train/
│   ├── angry/
│   ├── disgust/
│   ├── fear/
│   ├── happy/
│   ├── neutral/
│   ├── sad/
│   └── surprise/
│
└── test/
    ├── angry/
    ├── disgust/
    ├── fear/
    ├── happy/
    ├── neutral/
    ├── sad/
    └── surprise/

Each directory should contain the corresponding facial-expression images.

For example:

fer2013/train/happy/
├── image1.jpg
├── image2.jpg
├── image3.jpg
└── ...

---

Training

OpenEmotion currently uses EfficientNet-B0 as its baseline model.

To train:

python scripts/train.py \
    --data /path/to/fer2013 \
    --epochs 10

Example:

python scripts/train.py \
    --data ~/datasets/fer2013 \
    --epochs 10

You can change the batch size:

python scripts/train.py \
    --data ~/datasets/fer2013 \
    --epochs 10 \
    --batch-size 64

After training, the model is saved to:

models/openemotion_efficientnet_b0.pth

---

Training on Kaggle

If you don't have a local GPU, you can train OpenEmotion using Kaggle.

The repository contains the training notebook:

notebooks/emotion_detection.ipynb

Upload the notebook to Kaggle and attach a FER-2013 dataset.

Kaggle GPU can then be used for training.

After training, download the generated model:

openemotion_efficientnet_b0.pth

Place it in:

models/

Resulting structure:

OpenEmotion/
└── models/
    └── openemotion_efficientnet_b0.pth

You can then use the trained model with the local webcam application.

---

Evaluate the Model

After training:

python scripts/evaluate.py \
    --data /path/to/fer2013 \
    --model models/openemotion_efficientnet_b0.pth

Example:

python scripts/evaluate.py \
    --data ~/datasets/fer2013 \
    --model models/openemotion_efficientnet_b0.pth

The evaluation provides:

• Precision
• Recall
• F1-score
• Classification report
• Confusion matrix

---

Real-Time Webcam Detection

Once you have a trained model, start the webcam application:

python scripts/webcam.py \
    --model models/openemotion_efficientnet_b0.pth

OpenEmotion will:

Webcam
   ↓
OpenCV Frame
   ↓
Face Detection
   ↓
Face Crop
   ↓
Image Preprocessing
   ↓
EfficientNet-B0
   ↓
Emotion Prediction
   ↓
Confidence Score

The webcam window will display something similar to:

┌─────────────────────────────┐
│                             │
│      ┌───────────────┐      │
│      │               │      │
│      │     FACE      │      │
│      │               │      │
│      └───────────────┘      │
│                             │
│      Happy 87.4%            │
│                             │
└─────────────────────────────┘

Press Q to close the application.

---

Multiple Cameras

The default camera is:

0

To use another camera:

python scripts/webcam.py \
    --model models/openemotion_efficientnet_b0.pth \
    --camera 1

---

GPU Support

OpenEmotion automatically checks whether CUDA is available.

You can check your PyTorch installation:

python -c "import torch; print(torch.cuda.is_available())"

If you get:

True

PyTorch can use your NVIDIA GPU.

If you get:

False

the project will run on CPU.

---

Jupyter Notebook

The complete experimentation notebook is available at:

notebooks/emotion_detection.ipynb

Start Jupyter:

jupyter notebook

or:

jupyter lab

The notebook can be used for:

• Dataset exploration
• Data visualization
• Model training
• Model evaluation
• Classification reports
• Confusion matrices
• Experimentation

For normal usage, the Python scripts are recommended.

---

Python API

OpenEmotion can also be used directly from Python.

Example:

import torch

from openemotion.model import load_model
from openemotion.inference import predict_emotion

device = torch.device(
    "cuda" if torch.cuda.is_available() else "cpu"
)

model = load_model(
    "models/openemotion_efficientnet_b0.pth",
    device,
    7
)

emotion, confidence = predict_emotion(
    model,
    face_image,
    device
)

print("Emotion:", emotion)
print("Confidence:", confidence)

---

Run Tests

Install pytest if required:

pip install pytest

Run:

pytest

---

Model Details

Component	Value
Model	EfficientNet-B0
Framework	PyTorch
Input	224 × 224 RGB
Output	7 classes
Dataset	FER-2013
Face Detection	OpenCV Haar Cascade
GPU	CUDA supported
CPU	Supported

---

Limitations

Facial-expression recognition is an estimation problem and is not perfectly reliable.

Performance can be affected by:

• Lighting
• Camera quality
• Face angle
• Occlusion
• Multiple faces
• Image quality
• Facial appearance
• Dataset bias
• Differences between training and real-world images

The predicted class should be considered a model prediction, not a definitive measurement of a person's actual emotional state.

---

Roadmap

• FER-2013 dataset support
• PyTorch training
• EfficientNet-B0 baseline
• Model evaluation
• Classification report
• Confusion matrix
• OpenCV face detection
• Real-time webcam prototype
• Improve model accuracy
• Better face detection
• Multi-face tracking
• FPS optimization
• Image inference CLI
• Video inference
• ONNX export
• FastAPI inference API
• React web application
• Docker support
• CI/CD
• Model benchmarking
• Improved automated tests

---

Contributing

Contributions are welcome!

Fork the repository

git clone https://github.com/sharmaB01/OpenEmotion.git
cd OpenEmotion

Create a feature branch:

git checkout -b feature/my-feature

Make your changes and run the tests:

pytest

Commit your changes:

git add .
git commit -m "Add my feature"

Push the branch:

git push origin feature/my-feature

Then open a Pull Request.

---

License

OpenEmotion is released under the MIT License.

See LICENSE for details.

---

Acknowledgements

OpenEmotion is built using:

• PyTorch
• TorchVision
• OpenCV
• Scikit-learn
• FER-2013

---

Disclaimer

OpenEmotion is an open-source research and educational project.

Facial-expression classification is an estimation task and should not be interpreted as a reliable measurement of a person's internal emotional state.

Do not use the model as the sole basis for decisions involving employment, education, healthcare, law enforcement, financial services, or other high-impact decisions.

---

Quick Start

For experienced users:

git clone https://github.com/sharmaB01/OpenEmotion.git

cd OpenEmotion

python3 -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

Prepare FER-2013:

fer2013/
├── train/
└── test/

Train:

python scripts/train.py \
    --data /path/to/fer2013 \
    --epochs 10

Evaluate:

python scripts/evaluate.py \
    --data /path/to/fer2013 \
    --model models/openemotion_efficientnet_b0.pth

Run webcam:

python scripts/webcam.py \
    --model models/openemotion_efficientnet_b0.pth

Press Q to exit.

---

OpenEmotion

PyTorch + OpenCV + EfficientNet-B0 + FER-2013

⭐ If you find this project useful, consider giving the repository a star.