eyeblink-detection

Welcome to eyeblink-detection, a small Python project that uses facial landmarks and mathematical calculations to detect eyeblinks. The project provides two options for running it: locally with Python or with Docker. It also includes a peak-finding algorithm to locate specific peaks and parameters to filter out noise and longer eyeblinks.

How to Run

There are two options for running the eyeblink detection program: with or without Docker.

Option 1: Without Docker

Install the required packages by running the following commands:

apt-get update

apt-get install build-essential cmake \
libopenblas-dev liblapack-dev \
libx11-dev libgtk-3-dev \
python python-dev python-pip \
python3 python3-dev python3-pip

pip3 install --upgrade pip

Clone the repository and navigate to the directory:

git clone https://github.com/sobir-git/eyeblink-detection
cd eyeblink-detection/

Create a virtual environment and install the required Python packages:

python3 -m venv env
. env/bin/activate
python -m pip install -r requirements.txt

Run the program:

python detect_blinks.py

You can add the -g flag to display the graph of metrics:

python -g detect_blinks.py

Option 2: With Docker

Clone the repository and navigate to the directory:

git clone https://github.com/sobir-git/eyeblink-detection
cd eyeblink-detection/

Build the Docker image:

docker build -t eyeblink-detection:latest .

Run the Docker container with specific access to webcam and X11 desktop:

xhost +

docker run -it \
    --env="DISPLAY" \
    --env="QT_X11_NO_MITSHM=1" \
    --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
    --device=/dev/video0:/dev/video0 \
    eyeblink-detection:latest

How It Works

The eyeblink detection program takes facial landmarks using the dlib library and computes the eye-area-over-distance metric.

Mathematically, it is computed as:

ADR = (sqrt(S1) + sqrt(S2)) / (2*d)

where S1 and S2 are the areas of the left and right eyes, and d is the distance between the centers of the two eyes.

The program applies some preprocessing to this ADR metric, including SG smoothing using the Savitzky–Golay filter, and baseline correction by running a median filter and then subtracting it from the signal.

The program then runs a peak-finding algorithm to locate specific peaks using Scipy's scipy.signal.find_peaks function. The peak-finding algorithm is controlled by parameters such as prominence and peak_width. The peak_width parameter is used to filter out super-fast eyeblinks which occur in <100ms duration as a result of noise in the data, as well as filter out super-long eyeblinks that can happen when one is drowsy and closes their eyes for a longer time (>500ms). Here is snapshot of the metrics and peak detection in action (show if run with -g flag):

Acknowledgments

This project is based on this tutorial by Adrian Rosebrock. We also thank the developers of the dlib and OpenCV libraries for providing excellent computer vision tools.