hysts/pytorch_mpiigaze: training MPIIGaze and MPIIFaceGaze models in PyTorch

What hysts/pytorch_mpiigaze is for

Appearance-based gaze estimation predicts where a person is looking from a cropped image of their eye or face, without infrared hardware or geometric eye models. The two papers behind this repository, MPIIGaze and MPIIFaceGaze, defined the standard benchmarks for that task. This project is an unofficial PyTorch reimplementation of their training and evaluation code.

The audience is narrow and specific. You are a researcher or engineer who wants to train a model on the MPIIGaze or MPIIFaceGaze data and report a mean angular error in degrees that can be compared against the published numbers. The README is explicit that this is not an end-user tool: if you just want to run gaze estimation on a webcam without training anything, it points you at pytorch_mpiigaze_demo instead. That split matters, because a lot of people arrive at this repository looking for the demo and leave disappointed.

The repository is not archived, and the last push was on 2026-07-25. It is a research codebase, so treat the API as stable enough to run but not as a library with compatibility guarantees.

How the training and evaluation pipeline is organised

The codebase is deliberately flat. train.py and evaluate.py sit at the top level, configuration lives in configs/, dataset preparation lives in tools/, and the model, data and training logic live under gaze_estimation/. Shell wrappers in scripts/ drive the full experiments.

Configuration uses OmegaConf. The README states that default parameters and their types are defined in gaze_estimation/config/config_schema.py, which is not meant to be edited directly. You override values with a YAML file such as configs/mpiigaze/lenet_train.yaml, or with key=value arguments on the command line, for example train.test_id=1. That schema-first approach is the most opinionated design decision here: it keeps the defaults in one typed place, but it also means an unfamiliar key will fail rather than silently do nothing, and you have to read the schema to know what is overridable.

The evaluation protocol is leave-one-person-out. The README describes the default commands as training on the data of everyone except person p00 and then evaluating on p00. The scripts scripts/run_all_mpiigaze_lenet.sh and scripts/run_all_mpiigaze_resnet_preact.sh repeat that loop over all 15 people for LeNet and ResNet-preact-8 with the default parameters. That loop is the honest unit of work: a single train and evaluate pair gives you one fold, not a benchmark result.

The README reports results for four configurations. On MPIIGaze, LeNet reaches a mean test angle error of 6.52 degrees at 3.5 s/epoch, and ResNet-preact-8 reaches 5.73 degrees at 7 s/epoch. On MPIIFaceGaze, AlexNet reaches 5.06 degrees at 135 s/epoch, and ResNet-14 reaches 4.83 degrees at 62 s/epoch. Training times were measured on a GTX 1080 Ti, so they are a rough scale reference rather than a promise about your hardware.

Installing pytorch_mpiigaze and running a first fold

The README lists three requirements: Linux, tested on Ubuntu only, Python 3.10 or newer, and uv. There is no Windows or macOS claim anywhere in the README, so treat those platforms as untested rather than supported.

Create the environment from the lockfile with uv sync:

uv sync

That resolves the dependencies declared in pyproject.toml, which include torch, torchvision, omegaconf, h5py, opencv-python, pandas, scipy, tensorboard, termcolor, fvcore and tqdm. The dev group adds mypy, pre-commit, pytest, pytest-xdist and ruff.

Next, fetch and preprocess the data. The download scripts and the preprocessing tools are separate steps, and both are needed before training. For MPIIGaze:

bash scripts/download_mpiigaze_dataset.sh
uv run python tools/preprocess_mpiigaze.py --dataset datasets/MPIIGaze -o datasets/

For MPIIFaceGaze the pattern is the same with different names:

bash scripts/download_mpiifacegaze_dataset.sh
uv run python tools/preprocess_mpiifacegaze.py --dataset datasets/MPIIFaceGaze_normalized -o datasets/

With the preprocessed data in place, the default experiment trains on everyone except p00 and evaluates on p00:

uv run python train.py --config configs/mpiigaze/lenet_train.yaml
uv run python evaluate.py --config configs/mpiigaze/lenet_eval.yaml

The README does not state what the training script prints per epoch or where checkpoints are written, so inspect the config files and the training loop before you assume a particular output layout. What you should expect from a successful run is a mean angle error in degrees comparable to the 6.52 figure reported for LeNet, though your number will differ with hardware and seeds.

Where this repository stops being the right tool

The biggest limitation is that it does not do inference for you in any packaged form. The README states plainly that the repository no longer ships its own demo program. If your goal is a running application, this codebase gives you a checkpoint and nothing else.

The bridge is a conversion step. To visualize a model trained here, the README says to convert the checkpoint to safetensors with ptgaze-convert and point gaze_estimator.checkpoint in a ptgaze config file at the converted file:

ptgaze-convert checkpoint_0040.pth model.safetensors --mode mpiigaze

That means your inference path depends on a second project with its own release cycle. A checkpoint that trains here is not directly consumable by ptgaze until it goes through that conversion, and the ptgaze README is the place the README sends you for details.

Two smaller constraints are worth naming. The dataset download scripts depend on external hosts, and the README gives no fallback if a mirror is unavailable. And the benchmark numbers are per-fold averages over 15 people; a single fold can look better or worse than the published mean, so quoting one fold as a result is a mistake the code will not stop you from making.

pytorch_mpiigaze compared with pl_gaze_estimation

The README lists pl_gaze_estimation as a newer training codebase built on PyTorch Lightning. That is the direct alternative, and the difference is architectural rather than numerical.

This repository wires up its own training loop, its own OmegaConf schema and its own checkpoint handling, with train.py and evaluate.py as the entry points and shell scripts to loop over folds. pl_gaze_estimation delegates the loop, logging, checkpointing and multi-device behaviour to Lightning. If you already standardise on Lightning for experiment management, the newer codebase removes code you would otherwise maintain. If you want the smallest possible dependency surface and a training loop you can read end to end in one sitting, the explicit loop here is easier to audit.

The MPIIGaze and MPIIFaceGaze papers themselves are the other reference point. The README links the original CVPR 2015 and CVPRW 2017 papers, plus the 2019 CHI evaluation paper whose code lives in a separate OpenGaze repository. Those are the sources for the method definitions; this repository is one implementation of them, and it labels itself unofficial.

Maintenance, upgrade cost and the MIT licence

The last push was on 2026-07-25, which is recent, and the repository is not archived. There are no releases listed in the repository, so you consume it as a source checkout pinned by uv.lock rather than as a versioned package. The lockfile is the practical upgrade boundary: bumping it is the moment your environment can change.

Dependency drift is the real cost. The declared floors are aggressive (torch>=2.12.1, torchvision>=0.27.1, numpy>=2.2.6, opencv-python>=5.0.0.93), so an environment that satisfies them today may not satisfy them after a major release in any of those libraries. Because there is no published release cadence, you should expect to test upgrades yourself rather than wait for a tagged compatibility statement.

The licence is MIT, as stated in the README badge and the LICENSE file at the repository root. That is permissive and imposes no copyleft on your own code. It says nothing about the datasets: MPIIGaze and MPIIFaceGaze have their own terms, and the download scripts fetch them from their original hosts. Check those terms for your use case; this article is not legal advice.

Editorial conclusion

Adopt it if you need to reproduce appearance-based gaze estimation baselines on MPIIGaze or MPIIFaceGaze and you are comfortable on Linux with Python 3.10 or newer. Do not adopt it if you want real-time gaze tracking from a webcam, because the README points that use case at ptgaze instead. Before committing, check that the download scripts still reach the dataset mirrors and decide whether the newer PyTorch Lightning codebase fits your workflow better.

Frequently asked questions

Official sources

1. hysts/pytorch_mpiigaze on GitHub
2. Issues
3. License: MIT
4. README