GazeTracker

Research prototype for camera-based visual self-awareness and configurable on-screen feedback

English · Русский

---

English

Purpose

GazeTracker is an early-stage research prototype intended to explore whether real-time visual feedback can help a person notice changes in the relative position of their eyes while using a computer.

The original use-case hypothesis concerns people with exotropia (divergent strabismus). Possible usefulness for esotropia (convergent strabismus) has not been established and remains a subject for future clinical and user research.

The intended user is currently the patient, using the application for visual self-awareness. The appropriate age range, usage duration, clinical setting, contraindications, and role of a healthcare professional have not yet been defined.

What the prototype does

GazeTracker uses a conventional webcam, OpenCV, and MediaPipe Face Mesh to:

• detect and track facial and iris landmarks in real time;
• estimate the distance between the detected iris centres;
• normalize that distance against the detected face width;
• display the resulting Interocular Ratio and its recent history;
• compare the current ratio with a user-configurable threshold;
• show a visual, click-through alert when the upper threshold is exceeded;
• display either the processed camera image or a schematic eye view.

The alert and graph use the same unsmoothed measurement, so a threshold crossing is visible on the graph in the same update in which the alert is activated. Smoothing is applied only to the schematic landmarks and the large numeric value so that presentation remains stable without delaying or obscuring the alert.

Measurement quality and camera recovery

Before a value may trigger an alert, a separate quality evaluator checks only conditions that directly affect the Interocular Ratio: required eye and face-width landmarks, sufficient landmark resolution, a geometrically plausible ratio, and a lenient head-pose limit. The whole face does not have to fit into the camera frame. A rejected or stale frame cannot activate or preserve an alert and is not added to the measurement graph.

Preferred face position, distance, lighting, and sharpness produce directional or corrective guidance in the user interface, but do not suppress an otherwise usable measurement. This distinction is intentional: guidance should help the user improve the image without forcing an unnatural working distance.

This is an operational safeguard, not proof that an accepted measurement is clinically accurate. The limits in src/config.py are engineering defaults and require evaluation with representative users, cameras, lighting, eyewear, and head poses.

If camera reads repeatedly fail, the application releases and reopens the camera at a bounded interval. Alerts remain disabled while camera input is unavailable or recovery is in progress.

Understanding the measurement

The displayed Interocular Ratio is an image-derived, dimensionless proxy. It is not a clinical interpupillary-distance measurement in millimetres and it is not, by itself, a diagnosis or measurement of strabismus angle.

The value can be affected by camera position and optics, lighting, head pose, facial geometry, glasses, landmark quality, and distance from the camera. The threshold is currently user-configurable and has not been clinically validated.

Medical and research status

GazeTracker is a research prototype. It is not a certified medical device and has not been clinically validated.

The application does not diagnose, prevent, monitor, treat, or correct strabismus or any other medical condition. It must not be used as a substitute for an examination, diagnosis, treatment plan, or advice from a qualified ophthalmologist, orthoptist, optometrist, or other healthcare professional.

Personal feasibility confirmed by the developer; validation on other users has not yet been performed.

In other words, the developer's own experience supports continued development of the prototype, but this result must not be generalized to other patients or treated as clinical evidence.

No claim is currently made that responding to the visual alert improves a clinical outcome for other users. The intended purpose, clinically meaningful metric, calibration procedure, alert logic, target population, risks, and evidence requirements still need to be defined with patients and qualified specialists.

If you experience new or worsening double vision, eye pain, sudden visual changes, or other concerning symptoms, seek appropriate medical care rather than relying on this software.

Privacy

The current desktop prototype is designed to process camera frames locally. It does not intentionally upload camera images to a remote service or save a video history. Users and contributors should review this behaviour again whenever camera, telemetry, analytics, crash-reporting, or cloud functionality changes.

Installation

Requirements:

• Python 3.9–3.12;
• a supported webcam;
• the dependencies pinned in requirements.txt.

git clone https://github.com/svtv/GazeTracker.git
cd GazeTracker
python -m venv venv

Activate the environment on Windows:

venv\Scripts\Activate.ps1

Install dependencies and start the application:

pip install -r requirements.txt
python main.pyw

For development:

pip install -r requirements-dev.txt
pytest
ruff check .

Responsible evaluation and contributions

Feedback is especially welcome from people living with strabismus, caregivers, ophthalmologists, orthoptists, optometrists, vision-rehabilitation specialists, clinical engineers, accessibility researchers, and medical-device regulatory specialists.

Useful feedback includes:

• whether the proposed feedback scenario addresses a real unmet need;
• which measurement would be clinically or practically meaningful;
• whether individual calibration is necessary;
• appropriate alert conditions and acceptable false alerts;
• accessibility and comfort during prolonged use;
• risks, contraindications, and situations in which the software should not be used;
• evidence required before the application could be recommended to patients.

Please do not submit identifiable patient images, recordings, or health information through public GitHub issues. Research involving patients should be planned with appropriate clinical, ethics, consent, and data-protection review.

Acknowledgements

Inspired by Python-Gaze-Face-Tracker.

---

Русский

Назначение

GazeTracker — исследовательский прототип на ранней стадии развития. Его задача — изучить, может ли визуальная обратная связь в реальном времени помогать человеку замечать изменение относительного положения глаз во время работы за компьютером.

Изначальная гипотеза применения связана с людьми, имеющими расходящееся косоглазие (экзотропию). Возможная полезность при сходящемся косоглазии (эзотропии) пока не установлена и требует дальнейшего изучения совместно с пациентами и медицинскими специалистами.

Предполагаемый пользователь на текущем этапе — сам пациент, применяющий программу для зрительного самоконтроля. Подходящий возраст пользователей, продолжительность применения, клинический сценарий, противопоказания и роль врача пока не определены.

Что делает прототип

GazeTracker использует обычную веб-камеру, OpenCV и MediaPipe Face Mesh, чтобы:

• определять и отслеживать ориентиры лица и радужек в реальном времени;
• оценивать расстояние между обнаруженными центрами радужек;
• нормализовать это расстояние относительно обнаруженной ширины лица;
• отображать полученный Interocular Ratio и его недавнюю историю;
• сравнивать текущее значение с настраиваемым пользователем порогом;
• показывать визуальное, прозрачное для щелчков предупреждение при превышении верхнего порога;
• отображать обработанное изображение с камеры или схематическое изображение глаз.

Предупреждение и график используют одно и то же несглаженное измерение, поэтому пересечение порога появляется на графике в том же обновлении, в котором включается alert. Сглаживание применяется только к схематическим ориентирам и крупному числовому значению: отображение остаётся стабильным, но сглаживание не задерживает и не маскирует предупреждение.

Качество измерения и восстановление камеры

Прежде чем значение сможет вызвать предупреждение, отдельный оценщик качества проверяет только условия, непосредственно влияющие на Interocular Ratio: наличие необходимых ориентиров глаз и ширины лица, достаточное разрешение ориентиров, геометрически правдоподобное значение и мягкое ограничение поворота головы. Лицо не обязано целиком помещаться в кадр. Отклонённый или устаревший кадр не может включить или сохранить предупреждение и не добавляется на график.

Предпочтительные положение и расстояние до лица, освещение и резкость формируют в интерфейсе направляющие или корректирующие подсказки, но не блокируют пригодное измерение. Это разделение сделано намеренно: подсказка должна помогать улучшить изображение, не вынуждая пользователя работать на неестественном расстоянии.

Это защитное поведение программы, а не доказательство клинической точности принятого измерения. Ограничения в src/config.py являются инженерными значениями по умолчанию и требуют проверки на репрезентативных пользователях, камерах, условиях освещения, очках и положениях головы.

Если чтение кадров многократно завершается ошибкой, программа освобождает и повторно открывает камеру с ограниченной частотой попыток. Пока камера недоступна или восстанавливается, предупреждения отключены.

Как понимать измеряемую величину

Отображаемый Interocular Ratio — вычисляемый по изображению безразмерный относительный показатель. Это не клиническое измерение межзрачкового расстояния в миллиметрах и само по себе не является диагностикой или измерением угла косоглазия.

На значение могут влиять расположение и оптика камеры, освещение, поворот и наклон головы, особенности лица, очки, качество определения ориентиров и расстояние до камеры. Порог сейчас задаётся пользователем и не прошёл клиническую валидацию.

Медицинский и исследовательский статус

GazeTracker является исследовательским прототипом. Он не сертифицирован как медицинское изделие и не прошёл клиническую валидацию.

Программа не предназначена для диагностики, профилактики, мониторинга, лечения или коррекции косоглазия либо другого заболевания. Она не должна заменять обследование, диагноз, план лечения или рекомендации квалифицированного офтальмолога, ортоптиста, оптометриста либо другого медицинского специалиста.

Разработчик подтвердил персональную практическую применимость программы; валидация на других пользователях пока не проводилась. Иными словами, личный опыт разработчика является достаточным основанием для дальнейшего развития прототипа, но этот результат нельзя переносить на других пациентов или считать клиническим доказательством.

На текущем этапе не утверждается, что реакция других пользователей на визуальное предупреждение улучшает клинический результат. Предполагаемое медицинское назначение, клинически значимый показатель, процедура калибровки, логика предупреждения, целевая группа, риски и требования к доказательствам ещё должны быть определены совместно с пациентами и квалифицированными специалистами.

При появлении или усилении двоения, боли в глазах, внезапных изменений зрения или других тревожных симптомов следует обратиться за медицинской помощью, а не полагаться на эту программу.

Конфиденциальность

Текущий настольный прототип спроектирован для локальной обработки кадров камеры. Он не предназначен для отправки изображений камеры на удалённый сервис или сохранения истории видеозаписей. Это поведение необходимо проверять повторно при каждом добавлении телеметрии, аналитики, отчётов о сбоях, облачных функций или новых компонентов работы с камерой.

Установка

Требования:

• Python 3.9–3.12;
• поддерживаемая веб-камера;
• зависимости, зафиксированные в requirements.txt.

git clone https://github.com/svtv/GazeTracker.git
cd GazeTracker
python -m venv venv

Активация окружения в Windows:

venv\Scripts\Activate.ps1

Установка зависимостей и запуск:

pip install -r requirements.txt
python main.pyw

Для разработки:

pip install -r requirements-dev.txt
pytest
ruff check .

Ответственная оценка и участие в проекте

Особенно полезна обратная связь от людей с косоглазием, их близких, офтальмологов, ортоптистов, оптометристов, специалистов по зрительной реабилитации, клинических инженеров, исследователей доступности и специалистов по регулированию медицинских изделий.

Важные направления обратной связи:

• соответствует ли предложенный сценарий реальной потребности;
• какой показатель имеет клинический или практический смысл;
• требуется ли индивидуальная калибровка;
• при каких условиях нужно предупреждение и какие ложные срабатывания допустимы;
• доступность и комфорт при длительном использовании;
• риски, противопоказания и ситуации, в которых программу применять не следует;
• какие доказательства необходимы, прежде чем программу можно будет рекомендовать пациентам.

Пожалуйста, не публикуйте в открытых GitHub Issues изображения и записи пациентов, а также идентифицирующую медицинскую информацию. Исследования с участием пациентов необходимо планировать с надлежащей клинической, этической и правовой оценкой, информированным согласием и защитой данных.

Благодарности

Проект создан под влиянием Python-Gaze-Face-Tracker.