ОПИСАНИЕ ФАЙЛОВ ПРОЕКТА GAZE TRACKER V3
=======================================

Этот документ подробно объясняет, за что отвечает каждый файл проекта и как файлы связаны между собой.


1) КОРЕНЬ ПРОЕКТА
-----------------

1.1) main.py
------------
Назначение:
- Главная точка входа для локального запуска приложения.

Что делает:
- Импортирует `run_app` из пакета `gaze_tracker`.
- При запуске файла как скрипта (`python main.py`) вызывает `run_app()`.

Зачем нужен:
- Удобный и понятный старт проекта без необходимости знать внутреннюю структуру.


1.2) requirements.txt
---------------------
Назначение:
- Список зависимостей Python, необходимых для работы проекта.

Текущие ключевые библиотеки:
- `mediapipe` — обнаружение лица/landmarks и радужки.
- `opencv-python` — работа с камерой и окнами визуализации.
- `numpy` — математика и массивы.
- `scikit-learn` — регрессия для калибровки и предсказания точки взгляда.
- `Pillow` — корректный вывод кириллицы в окнах OpenCV.

Зачем нужен:
- Быстрая установка окружения командой `pip install -r requirements.txt`.


1.3) README.md
--------------
Назначение:
- Пользовательская документация проекта.

Что содержит:
- Краткое описание проекта.
- Сценарий использования.
- Требования к окружению.
- Актуальные варианты запуска (`python main.py`, `python -m gaze_tracker`, API-вызов).
- Инструкцию по установке зависимостей через `requirements.txt`.


1.4) .gitignore
---------------
Назначение:
- Исключает служебные и временные файлы из git.

Что игнорируется:
- `__pycache__/`, `*.pyc`
- старый лог-файл `gaze_debug.log`
- артефакты сборки `build/`, `dist/`, `*.egg-info/`


1.5) pyproject.toml (отсутствует)
---------------------------------
Назначение:
- В этом репозитории файл отсутствует, поэтому локальная установка как пакета
  (`pip install .`) не является основным сценарием.

Что это означает:
- Для запуска проекта используются `requirements.txt` + `python main.py`.
- Код при этом остается модульным и может запускаться как `python -m gaze_tracker`.


2) ПАКЕТ gaze_tracker
---------------------

2.1) gaze_tracker/__init__.py
-----------------------------
Назначение:
- Публичный API пакета.

Что делает:
- Экспортирует `run_app()` как основной программный запуск GUI.
- Содержит `main()` как алиас обратной совместимости.
- Хранит строку версии `__version__`.

Зачем нужен:
- Позволяет запускать приложение через импорт:
  `from gaze_tracker import run_app`.


2.2) gaze_tracker/__main__.py
-----------------------------
Назначение:
- Точка входа при запуске модуля командой `python -m gaze_tracker`.

Что делает:
- Импортирует `main` из пакета и вызывает его.

Зачем нужен:
- Альтернативный способ запуска без `main.py`.


2.3) gaze_tracker/config.py
---------------------------
Назначение:
- Центральное хранилище параметров приложения.

Основные группы параметров:
- Камера: индекс, разрешение, FPS, буфер.
- Параметры камеры для head pose: фокус, центр, дисторсия.
- Калибровка: сетка точек, дополнительные крайние точки, время удержания, минимум сэмплов.
- Runtime: число прогревочных кадров.
- Фильтры: коэффициенты OneEuro и окно медианы.
- Модель: степень полинома, коэффициенты Ridge/RANSAC.

Зачем нужен:
- Позволяет менять поведение системы без правок в логике.


2.4) gaze_tracker/landmarks.py
------------------------------
Назначение:
- Константы индексов landmarks для глаз и head pose.

Что содержит:
- Словари `RIGHT_EYE` и `LEFT_EYE` с индексами ключевых точек.
- `FACE_3D_MODEL` — базовая 3D-модель лица для `solvePnP`.
- `HEAD_POSE_LANDMARKS` — индексы точек, используемых для позы головы.

Зачем нужен:
- Единая "карта" landmarks, чтобы вся геометрия была согласована.


2.5) gaze_tracker/gaze_estimation.py
------------------------------------
Назначение:
- Извлечение признаков взгляда из landmarks лица и глаз.

Ключевые функции:
- `get_point_2d`, `get_point_3d` — преобразование landmarks в координаты.
- `get_iris_center_2d` — центр радужки (fitEllipse с fallback на minEnclosingCircle).
- `get_eye_bbox_2d` — bounding box глаза.
- `get_iris_position_2d` — нормализованная позиция радужки внутри глаза.
- `compute_gaze_vector_3d` — 3D-компоненты взгляда по геометрии глаза.
- `_eye_quality` + `_weighted_mean` — оценка качества глаза и взвешивание.
- `extract_gaze_features` — итоговый набор признаков (2D/3D/eye_aspect).

Что возвращает:
- Словарь признаков вида:
  `gaze_x_2d`, `gaze_y_2d`, `gaze_x_3d`, `gaze_y_3d`, `eye_aspect`.

Зачем нужен:
- Формирует основу для калибровки и последующего предсказания экранной точки.


2.6) gaze_tracker/head_pose.py
------------------------------
Назначение:
- Оценка поворота головы (yaw/pitch/roll).

Как работает:
- Берет 2D координаты опорных точек лица из кадра.
- Использует 3D-модель из `landmarks.py`.
- Применяет `cv2.solvePnP` для вычисления ориентации.
- Переводит rotation matrix в углы Эйлера.
- Нормализует углы к стабильному диапазону.

Зачем нужен:
- Компенсирует влияние положения головы на оценку взгляда.


2.7) gaze_tracker/calibration.py
--------------------------------
Назначение:
- Регрессионная калибровка: отображение признаков взгляда в координаты экрана.

Основные сущности:
- `CalibrationResult` — обученные модели + трансформеры.
- `RegressionCalibrator` — хранит сэмплы, обучает и предсказывает.

Как работает:
- Из калибровочных точек собирается `X` (признаки) и `y` (x/y на экране).
- Признаки расширяются `PolynomialFeatures`.
- Признаки нормализуются `StandardScaler`.
- Для `x` и `y` обучаются отдельные модели Ridge.
- При включенном флаге применяется RANSAC для устойчивости к выбросам.

Зачем нужен:
- Именно этот модуль превращает "сырые" признаки глаз в реальные экранные координаты.


2.8) gaze_tracker/filters.py
----------------------------
Назначение:
- Сглаживание траектории предсказанной точки.

Что содержит:
- `OneEuroFilter` — адаптивное сглаживание (меньше шум, умеренная задержка).
- `MedianFilter` — подавление резких выбросов по окну.

Зачем нужен:
- Убирает дрожание точки и повышает стабильность визуально.


2.9) gaze_tracker/tracker.py
----------------------------
Назначение:
- Центральный "оркестратор" математики трекинга между UI и моделями.

Что делает:
- Создает и хранит калибратор + фильтры.
- `build_feature_vector` — собирает единый вектор признаков для модели.
- `add_calibration_sample` / `finalize_calibration` — жизненный цикл калибровки.
- `predict_screen` — предсказание координат экрана с ограничением диапазона.
- `smooth` — последовательное сглаживание через медиану + OneEuro.

Зачем нужен:
- Инкапсулирует всю "бизнес-логику" трекинга вне UI.


2.10) gaze_tracker/ui/app.py
----------------------------
Назначение:
- GUI-приложение и основной runtime-цикл трекера.

Ключевые зоны ответственности:
- Построение интерфейса Tkinter (кнопки, статусы, сообщения).
- Инициализация камеры и MediaPipe FaceMesh.
- Цикл обработки кадров:
  - чтение кадра,
  - распознавание лица,
  - извлечение признаков взгляда,
  - оценка позы головы,
  - калибровка или предсказание,
  - сглаживание и отрисовка точки.
- Управление состояниями:
  - калибровка в процессе / завершена,
  - трекинг активен / остановлен.
- Отрисовка русскоязычного текста в OpenCV через Pillow (`_draw_text`).

Как связан с остальными модулями:
- Читает настройки из `config.py`.
- Получает признаки из `gaze_estimation.py`.
- Получает head pose из `head_pose.py`.
- Хранит и использует модель через `tracker.py`.


3) КАК ВСЕ ФАЙЛЫ РАБОТАЮТ ВМЕСТЕ (КРАТКИЙ ПОТОК)
------------------------------------------------
1. `main.py` вызывает `gaze_tracker.run_app()`.
2. `gaze_tracker/ui/app.py` открывает UI и камеру.
3. На каждом кадре:
   - FaceMesh -> landmarks,
   - `gaze_estimation.py` -> признаки глаз,
   - `head_pose.py` -> углы головы,
   - `tracker.py` -> вектор признаков.
4. При калибровке:
   - пары (признаки, точка экрана) копятся,
   - `calibration.py` обучает регрессию.
5. В рабочем режиме:
   - `calibration.py` предсказывает точку,
   - `filters.py` сглаживает,
   - `ui/app.py` рисует результат.


4) ЧТО СЧИТАЕТСЯ LEGACY/УДАЛЕННЫМ
--------------------------------
- Старый монолитный файл `gaze_app.py` удален.
- Актуальная реализация находится в `gaze_tracker/*`.
- `gaze_tracker/ui/__init__.py` удален (в текущей структуре не требуется).


5) ИМПОРТЫ ПО ФАЙЛАМ И ЗАЧЕМ ОНИ НУЖНЫ
--------------------------------------

5.1) main.py
------------
- `from gaze_tracker import run_app`
  - Импортирует публичную функцию запуска приложения из пакета.


5.2) gaze_tracker/__init__.py
-----------------------------
- `from .ui.app import main as _ui_main`
  - Импортирует `main` из UI-слоя и переиспользует его в `run_app()/main()`.


5.3) gaze_tracker/__main__.py
-----------------------------
- `from . import main`
  - Импортирует главный запуск из пакета для сценария `python -m gaze_tracker`.


5.4) gaze_tracker/config.py
---------------------------
- Импортов нет.
  - Это файл чистых констант конфигурации.


5.5) gaze_tracker/landmarks.py
------------------------------
- `import numpy as np`
  - Нужен для объявления `FACE_3D_MODEL` как `np.array` и работы с числовыми константами.


5.6) gaze_tracker/gaze_estimation.py
------------------------------------
- `from typing import Optional, Tuple, Dict`
  - Аннотации типов для функций и возвращаемых значений.
- `import cv2`
  - Работа с геометрией радужки (`fitEllipse`, `minEnclosingCircle`).
- `import numpy as np`
  - Математика и операции с векторами/матрицами.
- `from .landmarks import RIGHT_EYE, LEFT_EYE`
  - Константы индексов landmark-точек для правого и левого глаза.


5.7) gaze_tracker/head_pose.py
------------------------------
- `from typing import Tuple`
  - Типизация возвращаемых углов (`yaw/pitch/roll`).
- `import cv2`
  - `solvePnP` и `Rodrigues` для вычисления позы головы.
- `import numpy as np`
  - Математика поворотов, проверка валидности чисел, преобразования.
- `from .config import CAMERA_FOCAL_LENGTH, CAMERA_CENTER, CAMERA_DIST_COEFFS`
  - Параметры камеры для точной оценки head pose.
- `from .landmarks import FACE_3D_MODEL, HEAD_POSE_LANDMARKS`
  - 3D-модель лица и индексы соответствующих 2D landmark-точек.


5.8) gaze_tracker/calibration.py
--------------------------------
- `from dataclasses import dataclass`
  - Удобный контейнер `CalibrationResult` для моделей и трансформеров.
- `from typing import List, Optional, Tuple`
  - Аннотации типов.
- `import numpy as np`
  - Формирование матриц `X/y`, преобразования для обучения и предсказания.
- `from sklearn.linear_model import Ridge, RANSACRegressor`
  - Регрессоры для калибровки (`Ridge`) и устойчивости к выбросам (`RANSAC`).
- `from sklearn.preprocessing import PolynomialFeatures, StandardScaler`
  - Нелинейное расширение признаков и нормализация.
- `from .config import POLY_DEGREE, RIDGE_ALPHA, USE_RANSAC, RANSAC_MIN_SAMPLES, RANSAC_RESIDUAL_THRESHOLD, RANSAC_MAX_TRIALS`
  - Параметры обучения регрессии.


5.9) gaze_tracker/filters.py
----------------------------
- `from collections import deque`
  - История значений для оконного медианного фильтра.
- `from typing import Deque, Tuple`
  - Аннотации типов.
- `import numpy as np`
  - Математика для OneEuro и медианы.


5.10) gaze_tracker/tracker.py
-----------------------------
- `from typing import Optional, Tuple, Dict`
  - Типизация интерфейса трекера.
- `from collections import deque`
  - Внутренняя история признаков.
- `import time`
  - Временные метки для OneEuro фильтра.
- `import numpy as np`
  - Ограничение диапазонов и векторные операции.
- `from .calibration import RegressionCalibrator`
  - Калибратор, обучающий отображение признаков в экранные координаты.
- `from .filters import OneEuroFilter, MedianFilter`
  - Сглаживание траектории точки.
- `from .config import ONE_EURO_MIN_CUTOFF, ONE_EURO_BETA, ONE_EURO_D_CUTOFF, MEDIAN_WINDOW`
  - Параметры фильтрации.


5.11) gaze_tracker/ui/app.py
----------------------------
- `import ctypes`
  - Получение фактического размера экрана в пикселях (DPI-aware режим на Windows).
- `import os`
  - Проверка наличия шрифта для Pillow.
- `import time`
  - Тайминги в калибровке и анимации.
- `from typing import List, Tuple`
  - Аннотации типов.
- `import cv2`
  - Захват камеры, окна, отрисовка графики.
- `import numpy as np`
  - Создание canvas и численные операции.
- `import tkinter as tk`
  - Основной GUI интерфейс (кнопки, окно, статус).
- `from tkinter import messagebox`
  - Диалоги ошибок/инфо.
- `from PIL import Image, ImageDraw, ImageFont` (условный импорт в `try`)
  - Корректная отрисовка кириллицы поверх кадров OpenCV.
- `import mediapipe as mp` (условный импорт в `try`)
  - FaceMesh и landmarks лица/радужки.
- `from ..config import CAMERA_INDEX, CAMERA_WIDTH, CAMERA_HEIGHT, CAMERA_FPS, CAMERA_BUFFERSIZE, CALIBRATION_GRID, CALIBRATION_EXTRA_POINTS, CALIBRATION_HOLD_TIME, CALIBRATION_MIN_SAMPLES, CALIBRATION_WARMUP_RATIO, WARMUP_FRAMES`
  - Настройки камеры и калибровки.
- `from ..gaze_estimation import extract_gaze_features, get_point_2d, get_iris_center_2d`
  - Извлечение признаков взгляда и точек для визуализации.
- `from ..head_pose import estimate_head_pose`
  - Оценка углов поворота головы.
- `from ..landmarks import RIGHT_EYE, LEFT_EYE`
  - Индексы точек правого и левого глаза.
- `from ..tracker import GazeTracker`
  - Высокоуровневый объект трекинга (калибровка, предсказание, сглаживание).
