Оцінювання напрямку погляду

Визначення

Оцінювання напрямку погляду повертає два кути для кожного обличчя. result.gaze, це корисне навантаження Gaze форми (N, 2), де стовпець 0 містить нахил, а стовпець 1 поворот у радіанах. Рядки узгоджені з result.boxes, рамками виявлених облич. Використовується угода L2CS-Net: додатний поворот спрямовує погляд уліво відносно людини, а додатний нахил спрямовує його вниз.

Те саме корисне навантаження надає pitch_deg і yaw_deg у градусах, а також direction_3d, одиничний вектор (N, 3) у системі координат камери зі стовпцями (x, y, z).

Оскільки задача двоетапна, передбачення залежить від двох моделей. Для облич, які детектор пропустив, рядка погляду немає, а неточно розміщені рамки дають кути з неправильно обрізаного обличчя. Канонічний ключ задачі, gaze; gaze-estimation нормалізується до нього.

Моделі

L2CS-Net, єдине сімейство для цієї задачі. Воно поєднує стовбур ResNet із двома паралельними класифікаційними головами для інтервалів кутів, однією для нахилу та однією для повороту, на фрагментах обличчя 448x448. Архітектура підтримує п'ять глибин бекбона, а опубліковану контрольну точку має одна з них, ResNet-50.

На ваги поширюється ліцензійне обмеження. Їх навчено на Gaze360, ліцензія якого дозволяє лише дослідницьке та некомерційне використання й забороняє повторне розповсюдження, тому LibreYOLO не створює дзеркал для цього сімейства. Єдина контрольна точка, яку бібліотека може отримати автоматично, надходить безпосередньо з Google Drive авторів через gdown після показу умов ліцензії. Перед розгортанням прочитайте розділ L2CS-Net.

Для цього шляху завантаження потрібна додаткова залежність gaze:

pip install "libreyolo[gaze]"

Без неї бібліотека показує інструкції з ручного завантаження замість спроби передавання. Для передбачення та експорту контрольної точки, яка вже є у вас, додаткові залежності не потрібні.

Передбачення

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)

# На відміну від шляху 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 це каскад Haar із пакета wheel, для якого завантаження не потрібне. В OpenCV 5, де API Haar вилучено, це YuNet, який один раз отримує невеликий файл моделі зі сховища OpenCV zoo.

CLI не використовує цей резервний варіант. libreyolo predict відхиляє модель погляду без face_detector=, а значенням має бути ім'я детектора LibreYOLO або шлях до контрольної точки. Джерела, потокову обробку й роботу з результатами описано в розділі передбачення.

Навчання

Жодне сімейство цієї задачі не навчається в LibreYOLO. LibreL2CS.train() спричиняє помилку: навчайте в upstream-проєкті L2CS-Net і завантажуйте сюди отриманий словник стану.

Валідація

Валідація за датасетами з еталонним напрямком погляду не підтримується, тому val() спричиняє помилку, а не повертає метрики, яких не обчислював. Для цієї задачі немає словника metrics/. Оцінюйте в upstream на датасеті, на якому навчали контрольну точку.

Експорт

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

libreyolo export model=LibreL2CSr50.pt format=onnx

Контракт експорту погляду охоплює ONNX, TorchScript, ExecuTorch, TensorRT і OpenVINO. З бібліотеки виходять лише стовбур ResNet і дві голови інтервалів кутів: граф приймає попередньо оброблений фрагмент обличчя 448x448 і повертає необроблені логіти повороту та нахилу. Виявлення обличчя, обрізання, softmax, математичне сподівання інтервалу та перетворення на кути залишаються в Python, у libreyolo.models.l2cs.utils. Формати та їхні аргументи описано в розділі експорт.