GazeTracking

Gaze Tracking

This is a Python library (3.10+) that provides a webcam-based eye tracking system. It gives you the exact position of the pupils and the gaze direction, in real time.

Installation

Clone the project:

git clone https://github.com/antoinelame/GazeTracking.git
cd GazeTracking

Requires Python 3.10+. Pick one of the four options below.

Option 1 — pip

The standard way. Works everywhere.

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Option 2 — uv

A faster alternative to pip. Install uv first.

uv venv
uv pip install -e .

Option 3 — Anaconda

If you already use conda.

conda env create --file environment.yml
conda activate GazeTracking

Option 4 — Docker

Runs in an isolated container. Linux only (uses your webcam and display).

./build_and_run.sh

Trouble installing dlib? The wheel usually installs fine. If pip tries to compile it from source, install CMake first: brew install cmake (macOS) or sudo apt install cmake build-essential (Ubuntu).

Run the demo

python example.py

Simple Demo

import cv2
from gaze_tracking import GazeTracking

gaze = GazeTracking()
webcam = cv2.VideoCapture(0)

while True:
    _, frame = webcam.read()
    gaze.refresh(frame)

    new_frame = gaze.annotated_frame()
    text = ""

    if gaze.is_right():
        text = "Looking right"
    elif gaze.is_left():
        text = "Looking left"
    elif gaze.is_center():
        text = "Looking center"

    cv2.putText(new_frame, text, (60, 60), cv2.FONT_HERSHEY_DUPLEX, 2, (255, 0, 0), 2)
    cv2.imshow("Demo", new_frame)

    if cv2.waitKey(1) == 27:
        break

Documentation

In the following examples, gaze refers to an instance of the GazeTracking class.

Refresh the frame

gaze.refresh(frame)

Pass the frame to analyze (numpy.ndarray). If you want to work with a video stream, you need to put this instruction in a loop, like the example above.

Position of the left pupil

gaze.pupil_left_coords()

Returns the coordinates (x,y) of the left pupil.

Position of the right pupil

gaze.pupil_right_coords()

Returns the coordinates (x,y) of the right pupil.

Looking to the left

gaze.is_left()

Returns True if the user is looking to the left.

Looking to the right

gaze.is_right()

Returns True if the user is looking to the right.

Looking at the center

gaze.is_center()

Returns True if the user is looking at the center.

Horizontal direction of the gaze

ratio = gaze.horizontal_ratio()

Returns a number between 0.0 and 1.0 that indicates the horizontal direction of the gaze. The extreme right is 0.0, the center is 0.5 and the extreme left is 1.0.

Vertical direction of the gaze

ratio = gaze.vertical_ratio()

Returns a number between 0.0 and 1.0 that indicates the vertical direction of the gaze. The extreme top is 0.0, the center is 0.5 and the extreme bottom is 1.0.

Blinking

gaze.is_blinking()

Returns True if the user's eyes are closed.

Webcam frame

frame = gaze.annotated_frame()

Returns the main frame with pupils highlighted.

You want to help?

Your suggestions, bugs reports and pull requests are welcome and appreciated. You can also starring ⭐️ the project!

If the detection of your pupils is not completely optimal, you can send me a video sample of you looking in different directions. I would use it to improve the algorithm.

Licensing

This project is released by Antoine Lamé under the terms of the MIT Open Source License. View LICENSE for more information.