Оценка направления взгляда

Оценка взгляда возвращает направление взгляда для каждого лица на изображении. В LibreYOLO это двухэтапная задача: сначала работает детектор лиц, а затем голова взгляда считывает pitch и yaw с каждого кропа лица, который вернул детектор.

Определение

Оценка взгляда возвращает два угла на каждое лицо. result.gaze — это объект Gaze формы (N, 2), в столбце 0 pitch, в столбце 1 yaw, в радианах, строка в строку с result.boxes, найденными рамками лиц. Соглашение то же, что в L2CS-Net: положительный yaw поворачивает взгляд влево с точки зрения самого человека, положительный pitch — вниз.

Тот же объект отдаёт pitch_deg и yaw_deg в градусах и direction_3d — единичный вектор (N, 3) в системе координат камеры со столбцами (x, y, z).

Задача двухэтапная, поэтому предсказание зависит от двух моделей. Для лиц, которые детектор пропустил, строки взгляда не будет, а плохо поставленные рамки дают углы, посчитанные по плохо обрезанному лицу. Каноническое имя задачи — gaze; gaze-estimation приводится к нему.

Модели

L2CS-Net — единственное семейство для этой задачи. Он совмещает ствол ResNet с двумя параллельными головами классификации по угловым бинам, одна для pitch и одна для yaw, на кропах лиц 448x448. Архитектурно поддерживаются пять глубин бэкбона, и у одной, ResNet-50, есть опубликованный чекпойнт.

На веса наложено лицензионное ограничение. Они обучены на Gaze360, лицензия которого разрешает только исследовательское и некоммерческое использование и запрещает распространение, поэтому LibreYOLO не размещает зеркал для этого семейства. Единственный чекпойнт, который библиотека может скачать автоматически, скачивается через gdown прямо с Google Drive самих авторов — после того как библиотека напечатает условия лицензии. Прочитайте L2CS-Net, прежде чем разворачивать модель.

Для такого скачивания нужен extra gaze:

bash

pip install "libreyolo[gaze]"

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

Предсказание

Python

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Если face_detector не задан, предсказание откатывается к встроенному# детектору OpenCV, поэтому кроме чекпойнта ничего не скачивается.model = LibreYOLO("LibreL2CSr50.pt")result = model(SAMPLE_IMAGE) gaze = result.gazeprint(gaze.pitch, gaze.yaw)              # радианы, по одной строке на лицоprint(gaze.pitch_deg, gaze.yaw_deg)      # те же углы в градусахprint(gaze.direction_3d)                 # единичные векторы (N, 3)

CLI

# В отличие от Python, у CLI нет автоматического отката: моделям# взгляда нужен явный детектор лиц, и это должен быть детектор# LibreYOLO, рамки которого — лица.libreyolo predict model=LibreL2CSr50.pt source=photo.jpg face_detector=face-detector.pt save=True

Выбор источника лиц

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreL2CSr50.pt") # Передайте голове взгляда рамки от детектора, который вы уже запустили.result = model(SAMPLE_IMAGE, face_boxes=[[34, 12, 90, 80]]) # Или назовите один из встроенных детекторов.result = model(SAMPLE_IMAGE, face_detector="yunet")

Источник лиц задаётся одним из трёх способов. face_boxes передаёт уже посчитанные рамки и пропускает детекцию. face_detector принимает "auto", "haar", "yunet", модель детекции LibreYOLO или обычный вызываемый объект, и его можно задать в конструкторе или при каждом вызове. Если в Python его не задать, предсказание откатывается к встроенному детектору OpenCV, так что простой вызов работает без какой-либо настройки. На OpenCV 4 это каскад Хаара, который поставляется внутри wheel-пакета, и скачивать вообще ничего не нужно; на OpenCV 5, где API Хаара удалили, это YuNet, который один раз скачивает небольшой файл модели из OpenCV zoo.

У CLI такого отката нет. libreyolo predict отвергает модель взгляда без face_detector=, и значение этого аргумента — имя детектора LibreYOLO или путь к чекпойнту. Источники, стриминг и работа с результатом описаны в разделе предсказание.

Обучение

Ни одно семейство этой задачи не обучается внутри LibreYOLO. LibreL2CS.train() бросает исключение: обучайте в исходном проекте L2CS-Net и загружайте полученный state dict сюда.

Валидация

Валидация на датасетах с эталонной разметкой (ground truth) взгляда выходит за рамки библиотеки, и val() бросает исключение, а не возвращает метрики, которых не считал. Словаря metrics/ для этой задачи нет. Оценивайте в исходном проекте, на том датасете, под который обучали чекпойнт.

Экспорт

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreL2CSr50.pt")model.export(format="onnx")

CLI

libreyolo export model=LibreL2CSr50.pt format=onnx

Контракт экспорта для взгляда покрывает ONNX, TorchScript, ExecuTorch, TensorRT и OpenVINO. Наружу уходят только ствол ResNet и две головы по угловым бинам: граф принимает предобработанный кроп лица 448x448 и возвращает сырые логиты yaw и pitch. Детекция лиц, кадрирование, softmax, математическое ожидание по бинам и перевод в углы остаются в Python, в libreyolo.models.l2cs.utils. Форматы и их аргументы описаны в разделе экспорт.