Трекинг объектов

Трекинг присваивает каждой детекции устойчивый идентификатор от кадра к кадру. В LibreYOLO это не отдельная задача со своими весами, а режим предсказания — model.track(), который прогоняет выбранный трекер по покадровому выходу модели детекции, сегментации или оценки позы.

Определение

Трекинг не входит в число ключей задач LibreYOLO, и скачивать отдельный чекпойнт для трекинга не нужно. Это метод модели, model.track(source), который запускает детекцию на каждом кадре и связывает результаты во времени. Метод — генератор: он отдаёт по одному Results на каждый обработанный кадр, а в result.track_id лежит целочисленный тензор (N,), выровненный с result.boxes. Те же идентификаторы доступны и в result.boxes.id.

Отдаются только подтверждённые объекты, которые отслеживаются в текущий момент. Трек, потерянный при ассоциации, живёт ещё заданное число кадров, прежде чем его удаляют, — track_buffer для ByteTrack и BoT-SORT и max_age для двух вариантов OC-SORT, — так что объект, найденный заново внутри этого окна, сохраняет исходный ID.

Ассоциация выполняется после детекции, поэтому остальные данные кадра её переживают: Results с треками — это Results детекции, суженный до сопоставленных строк, так что маски и ключевые точки приходят вместе с рамками.

Модели

Запуск трекинга определяют два независимых выбора: модель, которая выдаёт рамки на каждом кадре, и трекер, который их связывает.

Любая нативная модель LibreYOLO, у которой задача — детекция, сегментация или оценка позы, имеет метод track(), так что детектор выбирается как обычно. Полный список — в индексе моделей; можно начать с YOLO9, RF-DETR, D-FINE или RTMDet. Задачи, в результатах которых нечего ассоциировать, отклоняют вызов, а не возвращают бессмысленные ID: классификация, повёрнутые рамки, точки, глубина, нормали поверхности, границы, семантическая и паноптическая сегментация, восстановление изображений, OCR и меш тела — все они бросают исключение из track().

Два класса моделей LibreYOLO тоже его не поддерживают. Модели, загруженные через LibreSAM, — это сегментаторы изображений, а модели, загруженные через LibreOpenVocab, — покадровые детекторы; и те, и другие бросают исключение из track(), а вместо него используется predict() на каждом кадре.

Трекинг работает на нативных моделях PyTorch. Экспортированный артефакт, загруженный через LibreYOLO("model.onnx"), возвращает объект бэкенда среды выполнения, у которого есть predict(), но нет track().

В составе библиотеки идут четыре трекера, они выбираются аргументом tracker:

"bytetrack" — трекер по умолчанию. Он опирается только на движение: фильтр Калмана и трёхэтапная ассоциация — сначала детекции с высокой уверенностью, затем второй проход, который даёт детекциям с низкой уверенностью шанс сопоставиться с существующим треком, прежде чем их отбросят, затем неподтверждённые треки. Настраивается через TrackConfig.

"botsort" сохраняет трёхэтапный жизненный цикл ByteTrack, но использует состояние Калмана в координатах центра, ширины и высоты и перед сопоставлением компенсирует движение камеры для предсказанных треков. Это вариант BoT-SORT только по движению: модель внешнего вида в нём не запускается. Настраивается через BoTSortConfig, где добавляются enable_cmc, cmc_method и cmc_downscale.

"ocsort" тоже опирается только на движение и добавляет в стоимость ассоциации член, учитывающий направление скорости, второй проход ассоциации по последнему реальному наблюдению каждого трека и сглаживание состояния Калмана вдоль виртуальной траектории, когда трек находится заново. Настраивается через OCSortConfig.

"deepocsort" расширяет OC-SORT внешним видом. Каждый трек хранит взвешенное по уверенности скользящее среднее эмбеддингов реидентификации, а в стоимость ассоциации добавляется член с косинусной близостью, так что идентификаторы переживают долгие перекрытия и пересечения объектов. Обходится это в один прямой проход небольшой сети эмбеддингов на кадр, а веса OSNet скачиваются при первом использовании. Настраивается через DeepOCSortConfig.

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

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # track() — генератор: один Results на каждый обработанный кадр.for result in model.track("video.mp4"):    print(result.track_id)        # целочисленный тензор (N,), выровнен с boxes    print(result.boxes.xyxy)

Выбор трекера

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # "bytetrack" (по умолчанию), "botsort", "ocsort" или "deepocsort".for result in model.track("video.mp4", tracker="botsort"):    print(result.track_id)

Сохранение видео с разметкой

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Без output_path файл попадёт в runs/track/<video_stem>.mp4.for result in model.track("video.mp4", save=True, vid_stride=2):    pass

Настройка трекера

from libreyolo import BoTSortConfig, LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Тип конфига выбирает трекер, поэтому tracker= здесь лишний.config = BoTSortConfig(track_buffer=60, frame_rate=25, enable_cmc=False)for result in model.track("video.mp4", tracker_config=config):    print(result.track_id) # Или передайте те же поля именованными аргументами — track() соберёт конфиг сам.for result in model.track("video.mp4", tracker="botsort", track_buffer=60):    print(result.track_id)

track_conf задаёт порог для первого этапа ассоциации: track_high_thresh для ByteTrack и BoT-SORT, det_thresh для OC-SORT и Deep OC-SORT. Это не conf из predict(), и для ByteTrack, BoT-SORT и OC-SORT детектор внутри работает с более низким порогом, чтобы слабые детекции остались доступны на проходе восстановления. Deep OC-SORT запускает детектор прямо с det_thresh. Для ByteTrack и BoT-SORT значение track_conf должно быть не ниже track_low_thresh, который по умолчанию равен 0.1.

Настройки трекера передаются одним из двух способов. Либо экземпляром конфига в tracker_config= — его тип и выбирает трекер, так что tracker= становится лишним. Либо теми же полями в виде именованных аргументов, и тогда track() сам соберёт конфиг для названного трекера; неизвестные ключи не применяются молча, а вызывают предупреждение. В обоих случаях track_conf игнорируется, как только соответствующий ключ задан явно.

Остальные аргументы повторяют предсказание: iou, imgsz, classes, max_det, vid_stride, show и save вместе с output_path. Источник — путь к видеофайлу. О работе с результатами — в разделе предсказания.

Обучение

Трекеры не обучают. Три из четырёх опираются только на движение и вообще не имеют обучаемых параметров, а сеть внешнего вида в Deep OC-SORT — это опубликованный чекпойнт для реидентификации, который скачивается при первом использовании. Улучшить качество трекинга — значит улучшить детектор или подстроить пороги ассоциации, описанные выше.