👁️ Eye Lab: Gaze Tracker API

June 12, 2026 · View on GitHub

Eye Lab is an open-source tool to create eye-tracking usability tests. It started as a final undergraduate work for the Computer Engineering student Karine Pistili who made the prototype. The idea is to evolve it into a more complete and useful tool with the community's help.

The current version of the software allows users to create their usability sessions of a website, recording the webcam, screen, and mouse movements and use this information to find out where the user has been looking into the screen by using heatmaps.

👩‍💻 Setting up project locally

The project consists of two parts, this repository contains the backend of the application, and the frontend can be found here. Install it as well to have the full application running.

Prerequisites

Python 3x

Setting Up a Virtual Environment

Linux & macOS

Step 1: Create a virtual environment

python3 -m venv venv

Step 2: Activate the virtual environment

source venv/bin/activate

Step 3: Install dependencies

pip install -r requirements.txt

Step 4: Run Flask

flask run

Windows

Step 1: Create a virtual environment

python -m venv venv

Step 2: Activate the virtual environment

venv\Scripts\activate

Step 3: Install dependencies

pip install -r requirements.txt

Step 4: Run Flask

flask run

2. Using Conda (Works on Linux, macOS, and Windows)

Step 1: Create a Conda virtual environment

conda create --name flask_env python=3.10

Step 2: Activate the environment

conda activate flask_env

Step 3: Install dependencies

pip install -r requirements.txt

Step 4: Run Flask

flask run

Deployment

Files: use the environment files to configure deployments: .env and .env.production (keep secrets out of the repo). Script: deploy with ./deploy_cloud_run.sh (supports -e dev or -e prod, CLI flags override env files).

Quick examples:

# Deploy using development defaults in .env
./deploy_cloud_run.sh -e dev

# Deploy to production using .env.production (or override values with flags)
./deploy_cloud_run.sh -e prod -p my-prod-project -s my-service-name -r europe-west6 -i my-image -a

Configuration variables (place in .env for local/dev or .env.production for prod):

PROJECT_ID — GCP project id
REGION — Cloud Run region (example: europe-west6)
SERVICE_NAME — Cloud Run service name
IMAGE_NAME — container image name (default is same as service)
ALLOW_UNAUTH — true or false (whether to allow unauthenticated access)

If no -e value is provided, deploy_cloud_run.sh uses dev and loads .env by default.

Files added by this project:

deploy_cloud_run.sh — helper script that builds with Cloud Build and deploys to Cloud Run.
.env — development defaults.
.env.production — production template (do not commit secrets; see .gitignore).

Run locally with .env or .env.production:

# Run using development env file
./run_local.sh -e dev --port 3000

# Run using production env file (if you have it configured locally)
./run_local.sh -e prod --port 3000

This script sources the selected env file and runs the app via python wsgi.py. Security note: never commit production credentials or service account keys. Keep .env.production and any secret files out of source control.

Additional Notes

If you face issues running flask run, try:
```
python -m flask run
```
If Flask is not installed, install it manually:
```
pip install flask
```
On Windows, if venv\Scripts\activate doesn't work, run PowerShell as Administrator and enable scripts:
```
Set-ExecutionPolicy Unrestricted -Scope Process
```

🧑‍🤝‍🧑 Contributing

Anyone is free to contribute to this project. Just do a pull request with your code and if it is all good we will accept it. You can also help us look for bugs if you find anything that creates an issue. To see the full list of contributions, check out the ahead commits of the "develop" branch concerning the "main" branch. Full logs of the project development can be found in the Daily Work Progress file. Hoping to see your name in the list of contributors soon! 🚀

📃 License

This software is under the MIT License.