Начало работы с PersonAnalysis: распознавание лиц и ReID по телу
Установите InsightFace 2.1, выберите Cheetah, зарегистрируйте эталонные фотографии и сопоставляйте людей на изображениях и в локальном видео через Python API.
Что вы настроите
PersonAnalysis объединяет обнаружение людей, распознавание лиц и повторную идентификацию по телу (ReID). Люди в текущем изображении сравниваются с эталонами, которым вы назначили имена или идентификаторы.
В этом руководстве используется CPU. Извлечение признаков, сопоставление и необязательное обновление эталонов тела выполняются отдельно. Для видео сохраняйте один экземпляр, чтобы эталоны оставались доступными между кадрами.
Перед началом
- Python 3.10 или новее, желательно в виртуальном окружении.
- reference.jpg ровно с одним чётким лицом, scene.jpg и короткое видео clip.mp4 с постоянной частотой кадров, которое вы вправе обрабатывать.
- Доступ к Интернету для первой загрузки моделей либо полный пакет Cheetah, установленный локально.
1. Установите InsightFace 2.1
Выполните команды в выбранном окружении Python. Базовый пакет включает NumPy, OpenCV и ONNX Runtime для CPU. Для PersonAnalysis не нужны дополнения GUI или PrivateFrame.
Для NVIDIA CUDA сначала установите InsightFace, затем замените onnxruntime на onnxruntime-gpu и явно выберите CUDAExecutionProvider. См. руководство по среде выполнения. PersonAnalysis поддерживает CPU и CUDA; Cheetah не использует CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Выберите Cheetah и подготовьте модели
Начните с cheetah_s: детектор тела получает изображение 320×320, а модели лица совпадают с Buffalo S. В cheetah_l используются детектор тела 640×640 и модели лица Buffalo L. Модель ReID общая; вход для детекции лиц по умолчанию составляет 640×640 в обоих пакетах.
Недостающий официальный пакет Cheetah загружается при первой подготовке. Для автономной работы скачайте полный архив со страницы моделей и распакуйте в ~/.insightface/models/cheetah_s/ или cheetah_l/. manifest.json, MODEL.LICENSE и четыре файла ONNX должны находиться на одном уровне без лишней вложенной папки.
- В руководстве явно указано name="cheetah_s"; конструктор Python по умолчанию использует cheetah_l.
- Существующий некорректный пакет вызывает ошибку и автоматически не заменяется. Восстановите его из полного архива.
3. Зарегистрируйте эталон, извлеките признаки и сопоставьте
Сохраните пример для изображения как person_image.py рядом с reference.jpg и scene.jpg и выполните python person_image.py. На эталонном фото должно быть ровно одно пригодное лицо. Проверьте accepted и rejected. person_001 — назначенный вами идентификатор.
get() принимает декодированное изображение OpenCV BGR uint8 и возвращает текущие наблюдения. match() сравнивает их с эталонами: сначала принимает подходящее совпадение по лицу, иначе пробует эталоны тела. Ни один вызов не меняет библиотеку эталонов.
В примере auto_update отключён. При его включении update() может добавить эталон тела после надёжного совпадения по лицу и однозначной связи лица с телом. Совпадение только по телу не расширяет библиотеку и не создаёт новые идентификаторы. Сначала сопоставьте весь кадр, затем обновляйте эталоны.
import cv2
from insightface.app import PersonAnalysis
image = cv2.imread("scene.jpg")
if image is None:
raise FileNotFoundError("scene.jpg")
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
observations = app.get(image)
matches = app.match(observations)
for result in matches:
print(result.person_id, result.matched_by, result.similarity)
auto_update = False
if auto_update:
changes = app.update(matches)
print(changes.added, changes.replaced, changes.skipped)4. Повторно используйте экземпляр для видео
Сохраните следующий пример как person_video.py рядом с reference.jpg и clip.mp4 и выполните python person_video.py. Необязательное обновление эталонов тела включено; задайте auto_update=False, чтобы отключить его.
При постоянных 30 FPS значение analysis_fps=2 выбирает каждый пятнадцатый кадр. Декодируются все кадры, но модели обрабатывают только выбранные. Это ограничение по времени видео, а не гарантия скорости или ожидание воспроизведения. Для переменной частоты нужны реальные временные метки.
Пример читает кадры последовательно. Для веб-камер и RTSP настольный режим сохраняет последний ожидающий кадр и ограничивает частоту анализа по прошедшему времени.
import math
import cv2
from insightface.app import PersonAnalysis
analysis_fps = 2
auto_update = True
capture = cv2.VideoCapture("clip.mp4")
try:
if not capture.isOpened():
raise OSError("clip.mp4")
source_fps = capture.get(cv2.CAP_PROP_FPS)
if not math.isfinite(source_fps) or source_fps <= 0:
raise ValueError("CAP_PROP_FPS")
frame_step = max(1, math.ceil(source_fps / analysis_fps))
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
frame_index = -1
while True:
ok, frame = capture.read()
if not ok:
if frame_index < 0:
raise OSError("clip.mp4")
break
frame_index += 1
if frame_index % frame_step:
continue
matches = app.match(app.get(frame))
if auto_update:
app.update(matches)
for result in matches:
print(frame_index / source_fps, result.to_dict())
finally:
capture.release()5. Читайте результаты и настраивайте сопоставление
person_id содержит зарегистрированный ID либо None. matched_by равен face, body или None; similarity — принятая косинусная близость, а не вероятность правильного ответа. Читайте body_bbox, reid_feature и face из result.observation, предварительно проверяя наличие значений.
Фото лица не описывает одежду. Зарегистрируйте известный фрагмент тела через body_images или разрешите добавлять эталоны тела после подходящих совпадений по лицу. На сопоставление тела влияют одежда, поза, перекрытия и качество изображения.
По умолчанию используются face_similarity_threshold=0.45, reid_similarity_threshold=0.85 и max_body_samples=4. Изменяйте их через PersonConfig при создании нового экземпляра и проверяйте на характерном видео. См. справочник параметров: исходные значения не гарантируют откалиброванную точность.
- Эталоны находятся только в памяти экземпляра и удаляются при закрытии. Автоматического экспорта, базы данных и восстановления после перезапуска нет.
- Результаты описывают текущий кадр. SDK не сохраняет траектории, анонимные идентификаторы, длительность присутствия или историю событий.
- to_dict() помогает приложению сохранять текущие результаты, но не является копией библиотеки эталонов и не подходит для передачи в update().
6. Попробуйте настольный интерфейс
Многоязычный Evaluation Studio поддерживает локальное видео, веб-камеры и RTSP, эталонные фотографии и ограничение частоты анализа. Установите дополнение GUI, выберите Cheetah S или L и следуйте руководству по интерфейсу.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Оцените сценарий и проверьте лицензию моделей
Проверьте чёткие лица, вид со спины, похожую одежду, перекрытия и незарегистрированных людей. Перед выбором порогов изучите ложные и пропущенные совпадения. Измеряйте скорость на планируемом оборудовании и данных.
Код SDK распространяется по лицензии MIT. Публичные предобученные пакеты Cheetah разрешены для некоммерческого использования; коммерческая лицензия на код не предоставляет таких прав на модели.
Изучите полное руководство API и условия моделей. По вопросам внедрения и разрешений свяжитесь с InsightFace. Возможности и выбор моделей описаны в обзоре Person Analysis.
Оцените Person Analysis для своего приложения
Расскажите об источниках данных, среде развёртывания и коммерческих требованиях, чтобы обсудить лицензирование моделей и интеграцию.
Связаться с нами