Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status

Facial Expression Analysis Toolbox (FEAT)

FEAT is a suite for facial expressions (FEX) research written in Python. This package includes tools to extract emotional facial expressions (e.g., happiness, sadness, anger), facial muscle movements (e.g., action units), and facial landmarks, from videos and images of faces, as well as methods to preprocess, analyze, and visualize FEX data.


Option 1 Clone the repository
git clone
Run setup
python install

Option 2
pip install git+

Verify models have been downloaded python

Usage examples

1. Feature extraction

Extract emotion predictions from a face video.

python -i input.mp4 -o output.csv

or detect in notebok.

from feat.detector import Detector
detector = Detector() 
out = detector.detect_image("input.png")
out = detector.detect_video("input.mp4")

2. Preprocessing FEX data

Loading a facial expression file and preprocess.

# Code goes here

You can also preprocess facial expression data extracted using other software (e.g., iMotions, FACET, Affectiva, OpenFace)

# Code goes here

3. Analyze FEX data

Analyze FEX.

# Code goes here

4. Visualize FEX data

Visualize FEX.

# Code goes here

Methods (to use when writing up paper)

Emotion prediction model A deep convolutional neural network was trained on the Facial Expression Recognition database by Carrier et al 2013.

AU prediction model Joint Facial Action Unit Detection and Face Alignment via Adaptive AttentionShao, Liu, Cai, and Ma, 2020


  1. Fork the repository on GitHub.
  2. Run the tests with pytest tests/ to make confirm that all tests pass on your system. If some tests fail, try to find out why they are failing. Common issues may be not having downloaded model files or missing dependencies.
  3. Create your feature AND add tests to make sure they are working.
  4. Run the tests again with pytest tests/ to make sure everything still passes, including your new feature. If you broke something, edit your feature so that it doesn't break existing code.
  5. Create a pull request to the main repository's master branch.

Google DOCS for development


Short examples for how to use the toolbox are currently on dropbox papers. This will eventually be moved to readthedocs.


This package was created with Cookiecutter with the following template.