Перейти к содержанию

Обзор#

Приложение FaceStream осуществляет несколько функций:

  • Чтение потоков

В качестве источников данных могут выступать веб-камеры, USB и IP-камеры (посредством протокола RTSP), видеофайлы и фотоизображения.

  • Обработка потоков

Выполняется поиск и сопровождение лиц или тел в потоке, пока они не покинут кадр или не будут перекрыты.

  • Проверка на Liveness

Выполняется проверка на Liveness по одному или нескольким кадрам трека.

  • Отсылка лучших снимков лиц или тел в виде HTTP-запросов во внешний сервис

В качестве внешнего сервиса выступает ПО компании VisionLabs LUNA PLATFORM 5.

Работа FaceStream зависит от пяти настроек.

  • Настройки управления потоками, задаваемые в LUNA Streams.

    Здесь задаются настройки, касающиеся источников потоков, такие как тип источника, адрес источника, настройки фильтрации и др. Настройки задаются с помощью отправки запросов с телом в формате JSON в сервис LUNA Streams. FaceStream забирает настройки из LUNA Streams для дальнейшей обработки. Подробное описание работы FaceStream с LUNA Streams приведено в разделе "Взаимодействие FaceStream с LUNA Streams".

  • Настройки FaceStream, задаваемые в LUNA Configurator.

    Здесь задаются общие настройки FaceStream, такие как логирование, настройка отправки готовых изображений из FaceStream во внешние сервисы, отладка и т.п.

  • Настройки TrackEngine, задаваемые в LUNA Configurator.

    Здесь задаются настройки, касающиеся детекции и трекинга лица или тела.

  • Настройки LUNA Streams, задаваемые в LUNA Configurator.

    Здесь задаются общие настройки сервиса LUNA Streams, такие как логирование, настройки БД, адрес сервиса LUNA Licenses и т.п.

  • Настройки FaceEngine, задаваемые в конфигурационном файле "faceengine.conf" и передаваемые во время запуска контейнера FaceStream.

    Здесь задаются параметры, касающиеся глубокой настройки распознавания лица и тела. Изменять параметры рекомендуется только по согласованию с сотрудниками VisionLabs.

При работе с FaceStream также доступны следующие возможности:

  • Динамическое создание, изменение, удаление источников потоков посредством запросов API
  • Просмотр потоков в браузере с указанными параметрами в режиме реального времени
  • Получение метрик по потоку (количество потоков, количество ошибок, количество необработанных кадров, FPS)

FaceStream можно настроить на работу:

Работа FaceStream с лицами и телами#

FaceStream может обрабатывать как лица, так и тела. Для каждого объекта предусмотрена своя схема работы и свой набор параметров, описанных ниже.

Необходимый минимум параметров для работы с обоими объектами можно найти в разделе "Перечень приоритетных настроек".

Работа с лицами#

Схема работы FaceStream с лицами представлена на рисунке ниже.

Схема работы FaceStream с лицами
Схема работы FaceStream с лицами

  1. В FaceStream отправляется видео с камеры видеонаблюдения, веб-камеры, видеофайл или фотоизображения. FaceStream может работать сразу с несколькими источниками потока (количество задается лицензией). Источники и дополнительные настройки обработки потока указываются в теле HTTP-запроса к сервису LUNA Streams. Затем данные настройки извлекаются приложением FaceStream.

  2. FaceStream выполняет декодирование кадров видео.

  3. Из кадра вырезается зона ROI, если задан параметр "roi" (настройки управления потоками).

  4. Полученное изображение масштабируется до размера "scale-result-size" (настройки TrackEngine) если задан параметр "detector-scaling" (настройки TrackEngine).

  5. Выполняется детекция лиц на кадре.

  6. Вместо детекции может выполняться редетекция лица в кадре, если задан параметр "detector-step" (настройки TrackEngine).

  7. Для каждого нового лица в потоке создается трек, который подкрепляется новыми детекциями данного лица с последующих кадров. Трек прерывается, если лицо исчезает из кадра. Можно задать параметр "skip-frames" (настройки TrackEngine), чтобы трек не прерывался сразу. Система будет ждать появления лица в области указанное количество кадров. http://git.visionlabs.ru/facestream/fs-extras/-/jobs/3952748/artifacts/browse

  8. FaceStream отсекает кадры плохого качества и выбирает лучшие снимки. Существует несколько алгоритмов выбора лучшей детекции/детекций в треке. См. описание группы параметров в разделе "Фильтрация кадров" (настройки управления потоками).

  9. Если кадр является лучшим снимком, он добавляется в коллекцию лучших снимков. В зависимости от настройки "face_bestshots_to_send" (настройки управления потоками) для каждого трека выбирается лучшая детекция в треке или несколько детекций.

  10. Опционально. Если в настройке "portrait_type" (настройки управления потоками) указан параметр "warp", то лучшие снимки приводятся к формату LUNA PLATFORM и создаются биометрические образцы. Биометрический образец лучше подходит для обработки с помощью LUNA PLATFORM.

  11. Лучшие снимки, исходные изображения (опционально) и дополнительная информация из настроек управления потоком отправляется в LUNA PLATFORM в виде HTTP-запроса к ресурсу "/6/handlers/{handler_id}/stream_events" для генерации события.

    Основные параметры видеопотока (протокол передачи данных, путь к источнику, область интереса на кадре и др.) задается в разделе "data" (настройки управления потоками).

    Адрес LUNA PLATFORM задается в разделе "lunaplatform" (настройки FaceStream).

    Частота отправки кадров задаётся в секции "sending" (настройки управления потоками).

Работа с телами#

Схема работы FaceStream с телами представлена на рисунке ниже.

Схема работы FaceStream с телами
Схема работы FaceStream с телами

  1. В FaceStream отправляется видео с камеры видеонаблюдения, веб-камеры, видеофайл или фотоизображения. FaceStream может работать сразу с несколькими источниками потока (количество задается лицензией). Источники и дополнительные настройки обработки потока задаются с помощью отправки HTTP-запроса в сервис LUNA Streams, которые в дальнейшем извлекаются приложением FaceStream.

  2. FaceStream выполняет декодирование кадров видео.

  3. Полученное изображение масштабируется до размера "scale-result-size" (настройки TrackEngine) если задан параметр "detector-scaling" (настройки TrackEngine).

  4. Выполняется детекция тел на кадре.

  5. Вместо детекции может выполняться редетекция тела в кадре, если задан параметр "detector-step" (настройки TrackEngine).

  6. Для каждого нового тела в потоке создается трек, который подкрепляется новыми детекциями данного тела с последующих кадров. Трек прерывается, если тело исчезает из кадра. Можно задать параметр "skip-frames" (настройки TrackEngine), чтобы трек не прерывался сразу. Система будет ждать появления тела в области указанное количество кадров.

  7. FaceStream отсекает кадры плохого качества и выбирает лучшие снимки. См. описание параметра "min_score_body" (настройки управления потоками).

  8. Если кадр является лучшим снимком, он добавляется в коллекцию лучших снимков. В зависимости от параметра "body_bestshots_to_send" (настройки управления потоками) для каждого трека выбирается лучшая детекция в треке или несколько детекций.

  9. Лучшие снимки приводятся к формату LUNA PLATFORM и создаются биометрические образцы.

  10. Лучшие снимки, исходные изображения (опционально) и дополнительная информация из настроек управления потоком отправляется в LUNA PLATFORM в виде HTTP-запроса к ресурсу "/6/handlers/{handler_id}/stream_events" для генерации события. Вместе с лучшими снимками отправляются детекции с координатами тела человека. Количество отправляемых детекций задается в параметре "minimal_body_track_length_to_send" (настройки управления потоками).

    Основные параметры видеопотока (протокол передачи данных, путь к источнику, область интереса на кадре и др.) задается в разделе "data" (настройки управления потоками).

    Адрес LUNA PLATFORM задается в разделе "lunaplatform" (настройки FaceStream).

    Частота отправки кадров задаётся в секции "sending" (настройки управления потоками).

Взаимодействие FaceStream с LUNA Streams#

Для работы FaceStream необходимо предварительно запускать дополнительный сервис — LUNA Streams (порт по умолчанию — 5160). В теле запроса "create stream" к сервису LUNA Streams задаются настройки для управления потоками. После отправки запроса создается поток, чьи настройки забирает FaceStream для дальнейшей обработки. Примеры запросов можно найти в спецификации OpenAPI LUNA Streams.

LUNA Streams имеет собственный пользовательский интерфейс, предназначенный для работы с потоками. См. подробную информацию в разделе "Пользовательский интерфейс сервиса LUNA Streams".

Для использования сервиса LUNA Streams необходимо использовать сервисы LUNA PLATFORM 5 — LUNA Licenses и LUNA Configurator, а также базы данных PostgreSQL или Oracle и Influx.

База данных Influx нужна для целей мониторинга состояния сервисов LUNA PLATFORM. При необходимости мониторинг может быть отключен.

В документации FaceStream не описывается использование базы данных Oracle.

При необходимости можно запустить LUNA Streams без LUNA Configurator. Данный способ не описывается в документации.

FaceStream лицензируется с помощью ключа LUNA PLATFORM 5, в котором содержится информация о максимальном количестве потоков, которые может обработать LUNA Streams. Лицензия регулируется сервисом LUNA Licenses.

См. подробную информацию по активации лицензии LUNA Streams в руководстве по установке FaceStream.

В базе данных PostgreSQL/Oracle хранятся все данные потоков LUNA Streams.

Версии API сервиса LUNA Streams#

LUNA Streams имеет две версии API.

Для переключения между версиями API необходимо обновить соответствующее значение в параметре "api_version" группы "lunastreams" в настройках FaceStream.

По умолчанию используется первая версия API. В данной документации описывается вторая версия API. См. описание первой версии API в документации FaceStream v.5.1.49 и ниже.

Важно! Попытки выполнить запросы к API второй версии при значении "api_version" = "1" и наоборот приведут к ошибкам, т.к. для первой версии API адрес LUNA PLATFORM задается в теле запроса на создание потока, а для второй версии адрес задается в группе параметров "lunaplatform" в настройках FaceStream.

Диаграмма последовательности создания и обработки потока#

Диаграмма последовательности создания и обработки потока приведена ниже:

Диаграмма последовательности создания и обработки потока
Диаграмма последовательности создания и обработки потока

1․ Пользователь задает настройки FaceStream, TrackEngine и настройки сервиса LUNA Streams в сервисе LUNA Configurator.

Настройки сервиса LUNA Streams содержат только настройки сервиса (адрес БД LUNA Streams, адрес InfluxDB и пр.) и не содержат настроек управления видеопотоком (параметры отправки лучших снимков, адрес LP, идентификаторы обработчиков и др.). Такие настройки задаются с помощью отдельного HTTP-запроса после запуска FaceStream (см. п.4).

При необходимости пользователь может задать настройки FaceEngine в отдельном конфигурационном файле.

2․ При запуске FaceStream, приложение считывает настройки из сервиса LUNA Configurator.

3․ FaceStream переходит в режим ожидания появления потока.

4․ Пользователь отправляет HTTP-запрос "create stream" к сервису LUNA Streams, содержащий настройки управления потоком в теле запроса.

5․ Сервис LUNA Streams проверяет наличие лицензируемой функции, регулирующей количество потоков для работы LUNA Streams, в сервисе LUNA Licenses. Если на данный момент уже обрабатываются какие-либо потоки, то дополнительно проверяется количество уже обрабатываемых потоков на момент запроса с помощью отчета FaceStream (не отражено на диаграмме, см. п. 17).

6․ Сервис LUNA Licenses возвращает ответ.

7․ Если лицензируемая функция отсутствует или на момент создания потока обрабатывается максимальное количество доступных потоков, то пользователю возвращается соответствующая ошибка.

8․ Если лицензируемая функция присутствует и на момент создания потока еще не обрабатывается максимальное количество доступных потоков то сервис LUNA Streams создает поток и записывает настройки управления потоком в БД LUNA Streams.

9․ Сервис LUNA Streams получает идентификатор "stream_id".

10․ Сервис LUNA Streams возвращает пользователю уникальный идентификатор "stream_id".

11․ Сервис LUNA Streams добавляет поток во внутреннюю очередь.

Очередь реализована в самом сервисе LUNA Streams и не является внешней.

12․ Сервис LUNA Streams обновляет статус потока на "pending".

13․ Сервис LUNA Streams обновляет статус потока в БД LUNA Streams.

14․ Сервис LUNA Streams получает ответ.

Если на момент создания потока FaceStream отключен, то может быть создано только то количество потоков со статусом "pending", которое оговорено лицензией. После запуска FaceStream будут приняты в обработку потоки, созданные в порядке очереди.

Посмотреть потоки в очереди, отфильтровав их определенным образом, можно с помощью GET-запроса к ресурсу "streams/processing/queue".

Потоки можно создавать со статусом "pause". В таком случае они будут добавлены в базу данных и будут ожидать ручного обновления статуса до "pending".

15․ FaceStream извлекает поток(и) из очереди со статусом "pending".

16․ FaceStream начинает оправлять данные в основные сервисы LUNA PLATFORM 5 для дальнейшей обработки кадров по заданному обработчику и генерации событий.

17․ FaceStream начинает отправку отчетов об обработке потоков в LUNA Streams.

Время отправки отчетов является фиксированным и не может быть изменено.

18․ Сервис LUNA Streams обновляет статус обрабатываемых потоков на "in_progress".

19․ Сервис LUNA Streams удаляет обрабатываемый поток из очереди.

20․ Сервис LUNA Streams обновляет статус потока в БД LUNA Streams.

21․ Сервис LUNA Streams получает ответ.

Завершение обработки для набора изображений, видеофайла или конечного видеопотока:

22․ FaceStream прекращает отправлять данные в LUNA PLATFORM.

Если необходимо, чтобы видеопоток воспринимался как конечный, то необходимо включить параметр "endless".

23․ FaceStream отправляет последний отчет в сервис LUNA Streams.

Если в отчёте сказано, что какой-то поток был обработан, то FaceStream забирает следующие параметры потока со статусом "pending" из очереди LUNA Streams, и сервис меняет статус потока с "pending" на "in_progress", удаляя из очереди. Если по неизвестным причинам отчет не был передан, то потоки заново помещаются в очередь.

24․ Сервис LUNA Streams обновляет статус потока на "done" в БД Streams.

25․ Сервис LUNA Streams обновляет статус потока в БД LUNA Streams.

26․ Сервис LUNA Streams получает ответ.

Бесконечный видеопоток:

27․ FaceStream будет отправлять данные в LUNA PLATFORM и отчеты в LUNA Streams до тех пор, пока видеопоток не будет прерван.

Более подробное описание обработки потока LUNA Streams см. в разделе "Процесс обработки потоков в LUNA Streams".

Запросы к сервису LUNA Streams#

Доступны следующие запросы к сервису LUNA Streams для работы с потоками:

  • задание настроек для управления потоком (запрос "create stream")
  • получение существующих потоков по их "stream_id" с описанием данных каждого потока (запрос "get streams")
  • получение всей информации по потоку по его "stream_id" (запрос "get stream")
  • удаление существующих потоков по их "stream_id" (запрос "delete streams")
  • удаление потока по его "stream_id" (запрос "remove stream")
  • получение числа созданных потоков (запрос "count streams")
  • обновление полей "description" и "status" потока по его "stream_id" (запрос "update stream")
  • замена всех данных потока на новые по его "stream_id" (запрос "put stream")
  • получение ссылки на последний кадр (запрос "get last frame preview")
  • получение ссылки на поток, запущенный в реальном времени (запрос "get live preview")
  • получение логов потока (запрос "get streams logs")
  • удаление логов потока (запрос "delete streams logs")

Подробное описание запросов и примеры запросов можно найти в спецификации OpenAPI LUNA Streams.

Распределение потоков в LUNA Streams#

Как было сказано ранее, доступна возможность обработки нескольких потоков одновременно.

Для каждого потока предполагается его текущий статус:

  • pending — поток взят в работу, но пока не найдено ни одного "рабочего процесса"
  • in_progress — поток обрабатывается
  • done — поток полностью обработан (актуально для типов передачи потока "videofile"/"images" или ["tcp/udp"] с параметром "endless" равным "false")
  • pause — пользователь остановил обработку потока (не применимо для типов передачи потока "videofile" или "images")
  • restart — сервер перезапустил обработку потока
  • cancel — пользователь отменил обработку потока
  • failure — при обработке потока произошла ошибка
  • handler_lost — "рабочий процесс" FaceStream потерян, следует передать другому (не применимо для типов передачи потока "videofile" или "images")
  • not_found — поток был в обработке, но в процессе выполнения был удалён
  • deleted — намеренное удаление потока

Статусы "pause" и "cancel" можно указать при обновлении потока с помощью запроса "update stream".

Статусы "restart", "handler_lost" являются временными. При данных статусах невозможно получить поток, однако переход через эти статусы регистрируется в обычном режиме. Статус "restart" может появиться только при использовании группы настроек "autorestart" (см. раздел "Автоматический перезапуск потоков" ниже).

Статус "not_found" является внутренним и будет отправлен для обратной связи, если поток был удален во время обработки. При данном статусе невозможно получить поток.

Статус "deleted" является виртуальным. Поток с таким статусом не может существовать, но этот статус можно увидеть в логах потоков.

Таблица переходов от статуса к статусу#

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

Символ «+» означает, что статус, указанный в первой строке, может стоять после статуса в первом столбце. Пустое поле означает, что нет случаев, когда может возникнуть данный статус.

Символ «-» означает, что в системе нет потока (он не создан или уже удален).

Нет pending in_progress done restart pause cancel failure handler_lost
Нет + +
pending + + + + +
in_progress + + + + +* + + +
done + + + +
restart + +
pause + + + +
cancel + + + +
failure + + + +
handler_lost +

* не поддерживается для типов передачи потока "videofile" или "images"

Процесс обработки потоков в LUNA Streams#

По умолчанию новый поток создается со статусом "pending" и сразу же попадает в очередь обработки. Обработку потока можно отложить, указав статус "pause" при создании.

Как только появляется "рабочий процесс" свободного потока с запросом на пул из очереди, поток принимается к обработке и ему присваивается статус "in_progress".

После того, как поток был обработан "рабочим процессом" FaceStream, ему присваивается статус "done" в случае успеха (актуально для типов передачи потока "videofile"/"images" или "tcp/udp" с параметром "endless" равным "false") или "failure", если произошли какие-либо ошибки. Однако статус обработки потока может быть понижен с "in_progress" по следующим причинам:

  • отсутствие обратной связи от "рабочего процесса" потока: сервер понизит рейтинг процесса, а запись со статусом "handler_lost" будет добавлена в логи потока

  • замена потока: запись со статусом "restart" будет добавлена в логи потока

Для типов передачи потока "tcp" или "udp" с параметром "endless" равным "true", статус не может измениться на "done".

Во время процедуры обработки любое изменение статуса потока регистрируется. Таким образом, можно восстановить процесс обработки потоков из логов.

Количество одновременных обработок потоков (статусы "pending" и "in_progress") регулируется лицензией, однако в БД LUNA Streams может храниться бесконечное множество потоков, имеющих иной статус, например, "pause".

Потоки со статусом "failure" могут быть автоматически перезапущены.

Автоматический перезапуск потоков#

Возможность автоматического перезапуска потоков актуальна только для потоков со статусом "failure". Параметры автоматического перезапуска (возможность перезапуска, максимальное количество попыток перезапуска, задержка между попытками) задаются пользователем для каждого потока в разделе "autorestart" настроек управления потоками. Параметры и статус автоматического перезапуска можно получить с помощью запроса "get stream".

Ниже перечислены статусы автоматического перезапуска:

  • "disabled" — автоматический перезапуск отключен пользователем (отключен параметр "restart")
  • "enabled" — автоматический перезапуск включен, но в данный момент не активен поскольку поток не находится в статуса "failure"
  • "in_progress" — автоматический перезапуск в процессе
  • "failed" — превышено допустимое количество попыток автоматического перезапуска и ни одна попытка не увенчалась успехом
  • "denied" — автоматический перезапуск разрешен пользователем, но не разрешен из-за критической ошибки*, полученной в отчете FaceStream.

* критической ошибкой считается ошибка Failed to authorize in Luna Platform. В будущих версиях список критических ошибок может пополняться.

Ниже описан процесс обработки потоков с включенным автоматическим перезапуском.

Когда происходит попытка автоматической перезагрузки потока данных, происходят следующие изменения:

  • статус потока изменяется сначала на "restart", а затем на "pending";
  • счетчик попыток автоматической перезагрузки "current_attempt" увеличивается на 1;
  • запись времени последней попытки "last_attempt_time" обновляется, чтобы отразить актуальное время.

Для того чтобы произошла перезагрузка, должны соблюдаться следующие условия:

  • статус потока должен находиться в состоянии "failure";
  • должен быть включен автоматический перезапуск потока (параметр "restart");
  • значение текущей попытки автоматической перезагрузки "current_attempt" должно быть равно "null" или меньше, чем максимальное число попыток "attempt_count";
  • время последней попытки автоматической перезагрузки "last_attempt_time" должно быть равно "null" или разница между текущим временем и временем последней попытки должна быть больше или равна задержке "delay".

Если соблюдаются условия ниже, то произойдет сбой автоматического перезапуска потока (прекращение попыток перезапуска):

  • статус потока находится в состоянии "failure";
  • статус автоматического перезапуска потока находится в состоянии "in_progress";
  • значение текущей попытки автоматической перезагрузки "current_attempt" равно значению максимального числа попыток "attempt_count".

Если соблюдаются условия ниже, то произойдет завершение работы автоматического перезапуска потока:

  • статус потока не равен статусу "failure";
  • статус автоматической перезагрузки потока находится в состоянии "in_progress";
  • время последней попытки автоматической перезагрузки "last_attempt_time" равно "null" или разница между текущим временем и временем последней попытки больше или равна задержке "delay".

Завершение работы автоматического перезапуска потока означает смену статуса автоматической перезагрузки потока на "enabled" и сброс значений текущей попытки автоматической перезагрузки "current_attempt" и времени последней попытки автоматической перезагрузки "last_attempt_time".

Автоматическое удаление логов потоков#

При необходимости можно запустить автоматическое удаление логов потоков. Автоматическое удаление логов помогает очистить таблицу "log" базы данных LUNA Streams от большого количества ненужных логов.

Самая последняя запись для каждого потока удалена не будет.

Автоматическое удаление логов потоков настраивается с помощью нижеописанных параметров из группы параметров "LUNA_STREAMS_LOGS_CLEAR_INTERVAL":

  • "interval". Задает интервал удаления логов. Логи, старше чем данный интервал, будут удалены.
  • "interval_type". Задает тип интервала (недели, дни, часы, минуты, секунды).
  • "check_interval". Задает частоту проверки логов на удаление (секунды).
  • "active". Включает/выключает автоматическое удаление логов потоков.

По умолчанию автоматическое удаление логов выключено ("active" = false).

Значения настроек по умолчанию включают автоматическое удаление логов ("active" = true) с проверкой потоков логов в базе данных каждые 180 секунд ("check_interval" = 180) и удаляют логи старше 7 дней ("interval" = 7 и "interval_type" = days).

Пример проверки логов на удаление каждые 5 минут и удаления логов старше 4 недель:

{
    "interval": 4,
    "interval_type": "weeks",
    "check_interval": 300,
    "active": true
}

Группировка потоков#

Потоки можно группировать. Группировка призвана объединять потоки с множеством камер в логические группы. Например, можно группировать потоки по территориальному признаку.

Поток может привязан к нескольким группам.

Группа создается с помощью запроса "create group". Для создания группы нужно указать обязательные параметры "account_id" и "group_name". При необходимости можно указать описание группы.

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

  • с помощью параметров "group_name" или "group_id" во время создания потока (запрос "create stream").
  • с помощью запроса "linker". В запросе необходимо указать идентификаторы потоков и группу, к которой их необходимо привязать.

С помощью запроса "linker" также можно отвязать потоки от группы.

Если поток был привязан к группе, то при запросе "get stream" или "get streams" группа будет отражена в поле "groups".

Описание базы данных LUNA Streams#

Общая схема базы данных LUNA Streams приведена ниже.

База данных сервиса LUNA Streams
База данных сервиса LUNA Streams

Описание данных приведено в разделе "Настройки управления потоками".

Рекомендации по настройке FaceStream#

Данный раздел содержит общие рекомендации по настройке FaceStream.

В разделе указаны названия настроек, в которых настраиваются описываемые параметры.

Рекомендации перед началом настройки#

Настройку FaceStream следует выполнять для каждой используемой камеры отдельно. FaceStream должен работать с потоком камеры, находящейся в стандартных рабочих условиях. Данные требования обусловлены следующими причинами:

  • Кадры с разных видеокамер могут отличаться по:
  • уровню шума,
  • размеру кадра,
  • освещённости,
  • размытости и т. п.
  • Настройки FaceStream зависят от условий освещения, поэтому будут отличаться для камер, расположенных в тёмном и светлом помещении;
  • Производительность FaceStream зависит от количества лиц или тел, одновременно находящихся в кадре. Поэтому настройки для камеры, которая детектирует одно лицо в 10 секунд, будут отличаться от настроек для камеры, которая детектирует 10 лиц в секунду;
  • Количество детекций лиц или тел и качество этих детекций зависят от правильного расположения камеры. Если камера расположена под неправильным углом, то объекты не будут детектироваться на кадрах или не могут быть использованы для дальнейшей обработки, например, из-за слишком больших углов поворота головы на кадрах;
  • Лица или тела в зоне видимости камеры могут быть частично или полностью перекрыты посторонними предметами или на фоне могут располагаться объекты, мешающие алгоритмам распознавания.

Камера может быть расположена так, что освещение или условия съёмок изменяются в течение дня. Рекомендуется протестировать работу FaceStream при разных условиях и выбрать оптимальный режим, обеспечивающий надёжную работу FaceStream при любых условиях.

Скорость обработки кадров для видео можно задать с помощью параметра "real_time_mode_fps".

Настройка производительности FaceStream#

Описанные ниже настройки оказывают наибольшее влияние на производительность FaceStream.

Уменьшение области поиска лиц#

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

Параметр "roi" (настройки управления потоками, группа параметров "data"), позволяет задать прямоугольную область, в которой будет выполняться поиск лиц.

Исходный кадр с зоной ROI
Исходный кадр с зоной ROI

Указанная прямоугольная область вырезается из кадра и именно это изображение в дальнейшем обрабатывает FaceStream.

Вырезанная область кадра, используемая для обработки в FaceStream
Вырезанная область кадра, используемая для обработки в FaceStream

Чем меньше зона поиска, тем меньше ресурсов потребляется на обработку каждого кадра.

Правильное использование параметра "roi" существенно повышает производительность работы FaceStream.

Параметр необходимо использовать только при работе с лицами.

Масштабирование кадра#

Масштабирование кадра перед началом обработки позволяет значительно увеличить производительность FaceStream. Масштабирование кадра можно включается в следующих настройках:

Режим работы Название параметра Значение по умолчанию Состояние по умолчанию
Только с детектором лиц "minFaceSize" настроек FaceEngine 50 (уменьшить в 2.5 раза) Включено
Только с детектором тел "imageSize" настроек FaceEngine 640 (уменьшить до 640 пикс. по наибольшей стороне) Включено
С детектором лиц и с детектором тел "detector-scaling" и "scale-result-size" настроек TrackEngine 640 (уменьшить до 640 пикс. по наибольшей стороне) Включено

Определение области с движением#

За определение области с движением отвечают три параметра, задаваемые в настройках TrackEngine:

  • frg-subtractor — включение режима учёта перемещений в кадре;
  • frg-regions-alignment — задание выравнивания для областей с движением;
  • frg-regions-square-alignment — установка равных ширины и высоты области с движением.

Ниже приведены рекомендуемые значения для данных параметров при использовании CPU и GPU:

frg-subtractor frg-regions-alignment frg-regions-square-alignment
Рекомендованное значение при использовании CPU 1 0 0
Рекомендованное значение при использовании GPU 1 360 0

Обработка пакетов кадров#

За пакетную обработку кадров отвечают три параметра, задаваемые в настройках TrackEngine:

  • batched-processing — включение пакетной обработки кадров;
  • min-frames-batch-size — минимальное количество кадров, которое следует накопить со всех камер перед обработкой;
  • max-frames-batch-gather-timeout — время между обработкой пакетов кадров.

Общая информация о настройке#

Работа с треком#

Для каждого найденного лица или тела создаётся новый трек. В рамках этого трека определяются и отправляются лучшие кадры.

В общем случае трек прерывается, когда объект больше не может быть найден на кадре.

Если трек был прерван, а человек вновь появился в кадре, то для него будет создан новый трек.

Возможна ситуация, когда два лица или тела пересекаются в кадре (один человек проходит за спиной другого). В этом случае треки для обоих людей обрываются и создаются новые треки.

Возможна ситуация, когда человек отворачивается или его лицо или тело временно перекрывается. В этом случае трек можно не обрывать сразу, а указать параметр "skip-frames" в настройках TrackEngine. Он задаёт количество кадров, в течение которых система будет ожидать повторного появления объекта в области, где он исчез.

При работе с треком также полезно использовать параметр "detector-step", позволяющий указать количество кадров, на которых будет выполняться редетекция лица или тела в заданной области до выполнения детекции лица или тела.

Отправка лучшего кадра#

Группа параметров "sending" (настройки управления потоками) позволяет задать параметры для отправки лучшего кадра. FaceStream отправляет полученные лучшие снимки в LUNA PLATFORM (см. "Перечень приоритетных настроек").

Для увеличения точности распознавания можно отправлять для одного лица или тела не один, а сразу несколько лучших снимков. Для этого нужно включить параметр "face_bestshots_to_send" или "body_bestshots_to_send" (настройки управления потоками).

LUNA PLATFORM позволяет агрегировать данные лучшие снимки и создавать на их основе биометрический шаблон более высокого качества.

Если за указанный период или до окончания трека не набралось необходимое количество лучших снимков, то отправляются только те лучшие снимки, которые были собраны.

Значения параметров "time_period_of_searching" (настройки управления потоками) и "silent_period" (настройки управления потоками) могут быть заданы в секундах или кадрах. Для выбора единиц измерения используется параметр "type".

Примечание. Параметр "silent_period" работает только при включенном режиме работы с лицами. При работе с телами или в совместном режиме параметр не будет работать.

Далее перечислены основные варианты настроек параметров "time_period_of_searching" и "silent_period" группы "sending" из настроек управления потоками при работе с лицами.

  • Лучший снимок отправляется только после того, как трек закончился и человек вышел из зоны видимости камеры.

    Таким образом анализируются все кадры с лицом или телом человека и выбирается лучший кадр.

    time_period_of_searching = -1 silent_period = 0

  • Требуется получить лучший кадр как можно быстрее и отправлять лучшие снимки с указанной периодичностью.

    Например, если злоумышленник зашёл в супермаркет, требуется сразу отправить лучший кадр для сравнения с чёрным списком.

    Данный режим так же используется для демонстрации работы FaceStream в реальном времени.

    В конце трека лучший кадр будет отправлен, даже если заданный период не закончился.

    time_period_of_searching = 3 silent_period = 0

  • Требуется быстро отправить лучший кадр, а потом отправить заново, только если человек долго находится в кадре.

    time_period_of_searching = 3 silent_period = 20

  • Требуется быстро отправить лучший кадр и больше никогда не отправлять с этого трека лучший кадр.

    time_period_of_searching = 3 silent_period = -1

Фильтрация кадров#

Фильтрация кадров лиц выполняется по трём основным критериям (задаются в настройках для управления потоками"):

Для угла поворота (yaw) задаются два дополнительных параметра "yaw_number" и "yaw_collection_mode", которые позволяют уменьшить вероятность возникновения ошибки, когда вместо большого угла наклона возвращается угол "0";

Если кадр не прошёл фильтрацию хотя бы по одному из указанных фильтров, то он не может быть выбран в качестве лучшего кадра.

Если задан параметр "face_bestshots_to_send", то кадр, прошедший фильтрацию, добавляется в массив лучших снимков для отправки. Если уже набрано необходимое количество лучших снимков для отправки, то один из этих снимков, имеющий худшее качество кадра (score), будет заменён новым лучшим кадром, если его качество выше.

Фильтрация кадров тел выполняется только по одному критерию - "min_score_body".

Работа со СКУД#

Работа со СКУД ведется только с лицами.

При работе со СКУД используются настройки "primary_track_policy" из настроек управления потоками. Они позволяют включить режим работы только с одним лицом, размер которого является самым большим. Предполагается, что интересующее лицо находится близко к камере.

Трек самого большого лица в кадре становится главным треком. Все остальные лица в кадре детектируются, но не обрабатываются. Лучшие снимки для них не отправляются.

Как только другое лицо достигнет большего размера, чем лицо главного трека, трек этого лица станет новым главным треком и обработка будет выполняться для него.

Включение режима выполняется настройкой "use_primary_track_policy".

Определение лучшего кадра начинается только когда лицо достигает размера (по вертикали), заданного в параметре "best_shot_min_size". Кадры с лицами меньшего размера не могут стать лучшими снимками.

Когда размер детекции лица по вертикали достигает значения установленного в "best_shot_proper_size", сразу же выполняется отправка лучшего кадра.

Значения "best_shot_min_size" и "best_shot_proper_size" задаются в зависимости от используемой видеокамеры и её расположения.

Далее приведены примеры настройки параметров группы "sending" из настроек управления потоками для работы со СКУД.

  • Турникет откроется только один раз. Для повторного открытия турникета потребуется оборвать трек (отойти из зоны видимости видеокамер).
time_period_of_searching = -1
silent_period  = 0
  • Турникет будет открываться с некоторой периодичностью (в данном случае каждые три секунды), если человек встал прямо перед ним.
time_period_of_searching = 3    
silent_period  = 0

При включённом параметре "use_primary_track_policy" лучший кадр никогда не отправляется при окончании трека.

Форматы, стандарты сжатия видео и протоколы#

FaceStream использует библиотеку FFMPEG для конвертации видео и получения потока с использованием различных протоколов. Далее перечислены все основные форматы, стандарты сжатия видео и протоколы, которые были протестированы при работе с FaceStream.

FFMPEG поддерживает большее количество форматов и стандартов сжатия видео. Они не перечислены в данном разделе, т. к. крайне редко используются при работе с FaceStream.

Форматы видео#

Основные форматы видео, обрабатываемые FaceStream:

  • AVI,
  • MP4,
  • MOV,
  • MKV,
  • FLV.

Стандарты сжатия видео (кодеки)#

Основные стандарты сжатия видео, с которыми работает FaceStream:

  • MPEG1, MPEG2, MPEG3, MPEG4,
  • MS MPEG4,
  • MS MPEG4v2,
  • MJPEG,
  • H.264,
  • H.265,
  • VC1,
  • HEVC,
  • VP8,
  • VP9,
  • AV1,
  • другие.

Протоколы#

Основные протоколы транспортного уровня, используемые FaceStream для получения данных:

  • TCP,
  • UDP.

Основные протоколы прикладного уровня, используемые FaceStream для получения данных:

  • HTTP (основывается на протоколе транспортного уровня TCP)
  • HTTS (основывается на протоколе транспортного уровня TCP)
  • RTP (основывается на протоколе транспортного уровня UDP)
  • RTSP (основывается на протоколах транспортного уровня TCP или UDP)
  • RTMP (основывается на протоколе транспортного уровня TCP)
  • HLS (основывается на протоколе транспортного уровня TCP)

Для использования протоколов прикладного уровня, необходимо указать соответствующий протокол транспортного уровня в параметре "type" настроек управления потоками.

Потребление памяти при работе FaceStream#

В данном разделе перечислены причины увеличения потребления оперативной памяти при работе FaceStream.

  1. Каждый подключенный поток даёт прирост потребления памяти. Количество потребляемой памяти зависит от настроек, заданных для FaceStream:

  2. числа Ffmpeg потоков в параметре "ffmpeg_threads_number" (настройки управления потоками),

  3. размера кэша изображений в параметре "stream_images_buffer_max_size" (настройки FaceStream),

  4. размеров буферов в параметре "frames-buffer-size" (настройки TrackEngine).

  5. Если количество потоков, заданных в параметре "ffmpeg_threads_number", больше "1", то значительно увеличивается потребляемая память. При этом прирост потребления происходит крайне медленно и заметен лишь через несколько часов работы.

Для RTSP потоков можно выставить значение параметра "ffmpeg_threads_number" равным "0" или "1". В этом случае рост памяти не выявлен.

  1. Потребление памяти растет после запуска FaceStream. Рост происходит в течение 1-2 часов. Это связано с наполнением кэшей (см. пункт 1). Если новые потоки не создаются и не выполняется пункт 2, то потребление памяти перестаёт расти.

  2. Потребление памяти растёт при включённых настройках в секции Debug (настройки FaceStream и TrackEngine).

Интерфейс воспроизведения потока#

В FaceStream доступна возможность просмотра потока в режиме реального времени. Для просмотра потока необходимо ввести следующий адрес в браузерную строку после начала обработки потока приложением FaceStream:

http://127.0.0.1:34569/api/1/streams/preview/<stream_id>.

При появлении объектов в поле видимости камеры, FaceStream отображает их определенным образом.

Ограничивающий прямоугольник желтого цвета возникает если для детекции не пройден хотя бы один порог из "detection_yaw_threshold", "detection_pitch_threshold" или "detection_roll_threshold".

Ограничивающий прямоугольник красного цвета возникает если оценка приемлемости детекции ниже, чем значения, заданные в параметрах "min_score_face" или "min_score_body".

Ограничивающий прямоугольник синего цвета возникает при детекции (редетекции) или трекинге объекта.

Ограничивающий прямоугольник зеленого цвета возникает во всех остальных случаях при соблюдении всех условий.

Ограничивающий прямоугольник оранжевого цвета возникает при использовании ROI.

Совместный режим детектирования лиц и тел#

В FaceStream доступен режим одновременного детектирования лиц и тел.

Важно! Функционал находится в состоянии бета-тестирования. Часть функций может не работать.

Совместный режим включается с помощью одновременного включения настроек "use-face-detector" и "use-body-detector". Использование совместного режима регулируется настройкой "data" > "analytics" > "mode" в настройках создания потока.

При включении совместного режима, FaceStream отправляет следующие данные к ресурсу handlers/{handler_id}/stream_events LUNA PLATFORM:

  • Лучшие снимки лиц и тел
  • Время детекции
  • Время относительно начала видеофайла
  • Координаты лиц и тел
  • Исходные изображения

В совместном режиме используется порог "min_score_body".

Периодическая отправка лучших снимков в совместном режиме работает аналогично работе с телами. Это значит, что параметр "silent_period" не будет работать.

Неподдерживаемый функционал#

В настоящее время в совместном режиме не поддерживается следующий функционал:

  • Политика Главного трека.
  • Параметр "data" > "analytics" > "sending" > "full_frame_settings", определяющий какие исходные кадры будут отправлены (лица, тела или лица и тела). В настоящий момент отправляются только исходные кадры лиц и тел.
  • Периодическая отправка лиц. В настоящий момент работает по сценарию периодической отправки тел.
  • Параметр "data" > "analytics" > "sending" > "bestshot_settings" > "type", определяющий какие лучшие снимки будут отправлены (лица, тела или лица и тела). В настоящий момент будут отправляться только лучшие снимки лиц и тел.