---
title: FER2013 Facial Expression Recognition
emoji: 🤗
color: "#0077ff"
SDK: gradio
sdk_version: 5.29.1 # Replace with the version in your requirements.txt
app_file: app.py
---

# FER2013 Facial Expression Recognition Demo

This is an interactive web demo built with **Gradio** and **PyTorch**, showcasing a **ResNet-18** model trained on the **FER2013 dataset** for facial expression recognition.

Upload an image containing a face, and the model will classify its expression into one of the 7 categories:

* Angry
* Disgust
* Fear
* Happy
* Sad
* Surprise
* Neutral

## Try the Demo!

Click the badge below or the "App" tab above to interact with the live demo hosted on Hugging Face Spaces:

[![Gradio](https://img.shields.io/badge/-Gradio%20Demo-000?style=for-the-badge&logo=Gradio&logoColor=white)](https://huggingface.co/spaces/your_username/your_space_name)
## Model Details

* **Architecture:** ResNet-18 (from `torchvision.models`)
* **Framework:** PyTorch
* **Dataset:** FER2013 (used for training/fine-tuning)
* **Task:** 7-class Image Classification (Facial Expression Recognition)

The model architecture is based on the standard ResNet-18, with the final fully connected layer replaced and trained on the FER2013 dataset.

## How it Works

1.  The user uploads an image through the Gradio interface.
2.  The `app.py` script receives the image as a NumPy array.
3.  Standard image preprocessing (resizing to 224x224, converting to a PyTorch tensor, normalizing with standard ImageNet means and standard deviations) is applied using `torchvision.transforms`.
4.  The preprocessed image tensor is passed through the loaded PyTorch ResNet-18 model.
5.  The model outputs raw logits for the 7 classes.
6.  Softmax is applied to the logits to obtain probability scores for each expression.
7.  The predicted expression (highest probability) and the confidence scores for all 7 expressions are displayed using Gradio's `gr.Label` component.

## Dataset

The model was trained on the [FER2013 dataset](https://www.kaggle.com/datasets/deadskull7/fer2013). This dataset consists of 48x48 grayscale images of faces, each labeled with one of the 7 emotional categories.

## Limitations

* Performance may vary significantly depending on the quality of the input image, lighting conditions, face angle, and presence of occlusions (e.g., masks, hands, hair).
* The model is trained specifically on the FER2013 dataset, which has known limitations and biases in data distribution and annotation.
* Best results are typically achieved with frontal or near-frontal face images.
* The model can only classify into the 7 expressions present in the FER2013 dataset.

## Running Locally

If you wish to run this demo on your local machine:

1.  **Clone the repository:**
    ```bash
    git clone [https://huggingface.co/spaces/your_username/your_space_name](https://huggingface.co/spaces/your_username/your_space_name)
    cd your_space_name
    ```
    *(Replace `your_username/your_space_name` with your actual Space ID)*

2.  **Ensure model weights are present:**
    Make sure your trained model weights file (`fer2013_resnet18_weights.pth` or whatever you named it) is in the correct location as referenced in the `app.py` file.

3.  **Install dependencies:**
    Install the required Python packages listed in `requirements.txt`:
    ```bash
    pip install -r requirements.txt
    ```

4.  **Run the app:**
    ```bash
    python app.py
    ```
    The Gradio interface will launch locally. Open the provided URL (usually `http://127.0.0.1:7860`) in your web browser.

## Files in this Repository

* `app.py`: Contains the Python code for loading the model, defining the prediction function, and setting up the Gradio interface.
* `requirements.txt`: Lists the necessary Python libraries.
* `fer2013_resnet18_weights.pth`: The trained PyTorch model state dictionary file. *(Update filename if different)*
* `README.md`: This file.
* `examples/`: (Optional) Directory containing example images used in the demo interface.

## Attribution

* **ResNet Architecture:** Based on the paper "Deep Residual Learning for Image Recognition" by Kaiming He et al. ([arXiv:1512.03385](https://arxiv.org/abs/1512.03385)).
* **FER2013 Dataset:** Created and distributed as part of a Kaggle competition.
* **Libraries:** Built using [PyTorch](https://pytorch.org/), [TorchVision](https://pytorch.org/vision/stable/index.html), [Gradio](https://gradio.app/), [NumPy](https://numpy.org/), and [Pillow](https://python-pillow.org/).
* **Hosting:** Deployed on [Hugging Face Spaces](https://huggingface.co/spaces).
* **(Optional) Model Training/Demo Creator:** Created by [Your Name or Handle].

## License

This project is licensed under the [Specify Your License, e.g., MIT License]. You can find the license text [here](LINK_TO_LICENSE_FILE_IF_APPLICABLE, or state it's in the repo).

## Feedback and Issues

If you find any issues or have suggestions, please open an issue on the Space's repository on the Hugging Face Hub.