# GazeTracking's horizontal ratio counts from the right, and its models ship inside the wheel > antoinelame/GazeTracking is a small Python library that reports pupil positions and gaze direction from a webcam, with four installation routes, a compiled dependency that needs a build tool, model files shipped as package data, and no tagged releases at all. Its own documentation asks users whose detection is imperfect to send a video of themselves looking in different directions. **antoinelame/GazeTracking** — 👀 Eye Tracking library easily implementable to your projects - Repository: https://github.com/antoinelame/GazeTracking - Stars: 2,634 · Forks: 621 - Language: Python - License: MIT - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/antoinelame-gazetracking ## The horizontal ratio counts from the right The two ratio methods are the part of the interface most likely to be misused, because they do not run in the direction people expect. The horizontal one returns a number between zero and one where the extreme right is zero, the centre is one half, and the extreme left is one. So a gaze that has moved to your right produces a smaller number, and the vertical one runs the other way, with the top at zero and the bottom at one. Neither is wrong, and both are consistent inside the library, but a threshold written as greater than half meaning right of centre will be exactly backwards. Nothing on the page flags the convention, and the demo does not use the ratios at all, it uses the three direction methods instead, so the first time most people meet the numbers is when they read these sections. ## Four install routes and two names for the environment The installation section offers four routes and they are not variations on one theme. The first is the conventional one: create a virtual environment, activate it, install the project in editable mode. The second is the same two steps with a different tool, which is faster and creates its own environment directory. The third is a conda route that creates an environment from a file shipped in the repository, and here the name of the environment is fixed by the file and appears in the activation command. The fourth is a container build, described as isolated, and marked as working only on Linux with the reason given: it uses your webcam and your display. The first route in full: ```shell python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e . ``` So the two environment based routes end up with environments whose names differ and whose names only one of them documents. ## The container installs a compiler and runs as a person The image is a slim interpreter base with a build tool and a compiler installed into it, which is unusual for a project whose dependencies are three Python wheels and is there because one of them falls back to compiling from source. Two graphics libraries are installed alongside, which the computer vision dependency needs for its windowing support. Then the image creates an unprivileged user, switches to it, copies the source with ownership set to that user, and installs the project into the user's own site directory before adding that directory to the path. It is a careful image by the standards of a project this size. The interpreter version it is based on is one patch of Python 3.12, while the manifest claims support from 3.10 through 3.13, so the container verifies one of those four. ## The models ship inside the package and the project asks for your face Two facts about data sit next to each other in this repository and belong together. The packaging configuration lists the trained model files as package data, which means the weights are distributed inside the wheel rather than downloaded at run time, so accuracy is fixed by whatever version of the package you installed. And the help section asks anyone whose pupil detection is not ideal to send the maintainer a video of themselves looking in different directions, which would be used to improve the algorithm. That is how an early gaze tracker gets better, and the request is made in good faith, but the page says nothing about consent, about what happens to the footage, or about whether it is deleted. Anyone feeding this into anything involving other people should decide that question themselves first. ## The demo loop has one exit key and no frame cap The demo is about thirty lines and it is the fastest way to see whether the library works on a given machine. It constructs the tracker, opens the webcam, and then loops forever: read a frame, hand it to the tracker, ask for an annotated copy, decide which direction message to draw, draw it, show the window, and check the keyboard. The only exit is the escape key, and there is no frame rate limit and no cleanup call when the loop ends. That is fine for a demo and it is the shape most people will copy when they write their first application, so the two omissions propagate. It also means the demo never touches the ratio methods, which is why the inverted convention goes unnoticed until someone reads the reference. ## A line length is configured and then the check is switched off The lint configuration is five settings long and two of them contradict each other. A line length of one hundred and twenty characters is declared, and the rule that reports long lines is then listed among the ignored rules. So the formatter will still wrap code at that width, since the formatter reads the same setting, while the linter will never complain about a line that exceeds it. That combination is common in projects that prefer the formatter's opinion and do not want the linter arguing with it, and it is usually left over from adding the ignore after a noisy pull request rather than chosen as policy. The rest of the configuration is unremarkable: a target version matching the minimum interpreter, a rule set covering errors, imports, modernisation and a few bug patterns. ## The container needs a camera and a screen and says neither The page tells you the container uses your webcam and your display and marks the route as Linux only, which is honest about the constraint and thin on the mechanics. Reaching a webcam from inside a container needs the video device passed in, and reaching a window needs a display made available, and the one line the page gives for the container route is a shell script whose contents are not shown. So a reader who expects the container to behave like the local demo has to discover the device and display handling themselves. The alternative is not hiding anything: the local routes are documented in full, the demo is a single file, and the four routes exist precisely so that someone can pick the one their machine supports. It is a documentation gap in one route rather than a problem with the others. ## Conclusion Use this library if you are prototyping anything that reacts to where someone is looking, and accept that accuracy depends on lighting, glasses and how still the camera is. Three things to know before you build on it. The horizontal ratio is inverted relative to what most people expect, so any threshold you write has to be tested against a person actually looking right. The detection model is a data file inside the package rather than something you can retrain from the documentation, so an improvement arrives when the package is updated. And there is no tagged release at all, which means installing from a checkout gives you whatever the last commit was, with the manifest still claiming an early version number. ## FAQ ### What is GazeTracking? A Python library that reports pupil positions and gaze direction from a webcam in real time, exposing the left and right pupil coordinates, left, right and centre detection, horizontal and vertical ratios, a blinking check, and an annotated frame. ### How do I install GazeTracking? Four documented routes: a virtual environment with an editable install, the same with a faster installer, a conda environment created from the file in the repository, and a container build the page marks as Linux only because it uses your webcam and display. ### Why does installing GazeTracking need CMake? One dependency compiles from source on some platforms instead of using a wheel, and the page tells you to install a build tool and compiler first if that happens. The container image installs both for the same reason. ### What does GazeTracking's horizontal_ratio return? A number between zero and one where the extreme right is zero, the centre is one half and the extreme left is one. Looking right therefore gives the smaller number, and the vertical ratio runs the opposite way. ### How accurate is GazeTracking? The page gives no figure. It says accuracy depends on pupil detection, asks users whose detection is imperfect to send a video of themselves looking in different directions, and ships trained model files inside the package. ### Which Python versions does GazeTracking support? Python 3.10 and newer, with classifiers covering 3.10 through 3.13. The container image is built on 3.12, and there are no tagged releases, so the manifest's version number is the only version on offer. ## Sources - [antoinelame/GazeTracking on GitHub](https://github.com/antoinelame/GazeTracking) - [Issues](https://github.com/antoinelame/GazeTracking/issues) - [License: MIT](https://github.com/antoinelame/GazeTracking/blob/master/LICENSE) - [README](https://github.com/antoinelame/GazeTracking/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/antoinelame-gazetracking