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

Настройки управления потоками#

Параметры для управления потоками задаются сервисе LUNA Streams. Сервис позволяет создавать и хранить потоки в базе данных LUNA Streams.

Важно! LUNA Streams имеет две версии API. В данной документации описывается вторая версия API. См. описание первой версии API в документации FaceStream v.5.1.49 и ниже.

Важно! Настройки управления потоками не хранятся в сервисе LUNA Configurator и могут быть заданы только с помощью HTTP запросов к сервису LUNA Streams. Настройки сервиса LUNA Streams, задаваемые в LUNA Configurator, описаны в разделе "Настройки LUNA Streams".

Базовое описание параметров приведено в спецификации OpenAPI сервиса LUNA Streams. В данном разделе приводится расширенное описание для некоторых параметров.

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

Общие настройки потока#

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

Общие настройки потока:

  • "account_id" — задает значение обязательного поля "account_id", которое передаётся в заголовке запроса в LUNA PLATFORM 5 в сервис LUNA API. Параметр используется для привязки получаемых данных к конкретному пользователю.
  • "name" — имя потока. Служит для идентификации источника отправляемых кадров.
  • "description" — пользовательское описание потока
  • "location" — задает информацию о расположении источника видеосигнала (город, область, район и т.д.)
  • "autorestart" — настойка автоматического перезапуска потока. См. раздел "Автоматический перезапуск потоков" для более подробной информации.
  • "status" — статус потока на момент начала обработки
  • "group_name" и "group_id" — параметры привязки потока к группе

Также доступна группа параметров "data", задающая основные настройки для обработки потока. См. раздел "Настройки обработки потока" для более подробной информации.

Настройки обработки потока#

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

Основные настройки в группе параметров "data":

  • "type" — тип передачи потока:
    • сетевой протокол TCP
    • сетевой протокол UDP
    • набор изображений
    • видеофайл
  • "reference" — источник потока (ссылка, путь к видеофайлу или набору изображений и др.)
  • "roi" — область интереса в которой происходит детекция и сопровождение лица на кадре
  • "ffmpeg_threads_number" — количество потоков для декодирования видео с помощью FFMPEG
  • "real_time_mode_fps" — количество FPS, с которым будет обработан видеофайл
  • "frame_processing_mode" — параметр, определяющий будет ли обрабатываться полный или масштабированный кадр
  • "rotation" — угол поворота изображения с источника. Используется в случае, если входящий поток повернут, например, если камера установлена на потолке. Поворот выполняется по часовой стрелке.
  • "preferred_program_stream_frame_width" — позволяет автоматически выбирать оптимальный канал из нескольких в потоке
  • "endless" — управление перезагрузкой потока при получении ошибки сети
  • "mask" — маска имён файлов в директории с изображениями

Также в группе параметров "data" задаются настройки аналитики. См. раздел "Настройки аналитики" для более подробной информации.

type#

Тип передачи потока. После выбора типа передачи потока, необходимо указать путь к источнику/изображениям/USB-устройству и тд. в настройке "reference".

Приложение может использовать один из следующих типов передачи потока:

  • tcp — сетевой протокол транспортного уровня для приема видеоданных
  • udp — сетевой протокол транспортного уровня для приема видеоданных
  • images — набор кадров в виде отдельных файлов изображений
  • videofile — видеофайл

В FaceStream указываются только протоколы транспортного уровня (TCP или UDP). Необходимо понимать на каком протоколе транспортного уровня базируется протокол прикладного уровня (HTTP, RTSP, HLS и др.). См. подробную информацию в разделе "Протоколы".

Протокол TCP реализует механизм контроля ошибок, позволяющий минимизировать потерю информации и пропуски опорных кадров ценой увеличения сетевой задержки. Опорные кадры являются основой различных алгоритмов сжатия, используемых в видеокодеках (например, h264). Только опорные кадры содержат достаточное количество информации для полного восстановления (декодирования) изображения, в то время как промежуточные кадры содержат лишь отличия между соседними опорными кадрами.

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

Протокол UDP не реализует механизма контроля ошибок, поэтому поток не защищен от повреждения. Использование данного протокола рекомендуется только при наличии высококачественной сетевой инфраструктуры.

При большом количестве потоков (10 и более) настоятельно рекомендуется использовать протокол UDP. При использовании протокола TCP могут возникнуть проблемы с чтением потоков.

FaceStream обрабатывает данные из типов images и videofile только один раз. После обработки всех изображений или видеофайла в логи FaceStream будет выведено сообщение о завершении обработки. Если набор изображений или видеофайлы были изменены, то необходимо перезапустить обработку потока, после чего FaceStream снова единоразово выполнит обработку всех изображений или видеофайла.

reference#

Полный путь к источнику (для типа "tcp"/"udp"):

"reference": "rtsp://some_stream_address"

Номер USB устройства (для типа "tcp"/"udp"):

"reference": "/dev/video0"

Для использования USB устройства, необходимо указать флаг --device с адресом USB устройства при запуске Docker-контейнера FaceStream. См. раздел "Ключи запуска" в руководстве по установке FaceStream.

Полный путь к видеофайлу (для типа "videofile"):

"reference": "/example/path/to/video/video.mp4"

Полный путь к директории с изображениями (для типа "images"):

"reference": "/example/path/to/images/"

Для использования видеофайлов и изображений необходимо их предварительно перенести в Docker-контейнер.

roi#

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

ROI задаёт область интереса в которой происходит детекция и сопровождение лица на кадре.

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

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

Область интереса ROI на исходном кадре задается параметрами "x", "y", "width", "height" и "mode", где:

  • "x" и "y" – координаты верхней левой точки области интереса ROI;
  • "width" и "height" – ширина и высота обрабатываемой области кадра;
  • "mode" – режим указания "x", "y", "width" и "height". Доступно два режима:
  • "abs" – параметры "x", "y", "width" и "height" задаются в пикселях;
  • "percent" – параметры "x", "y", "width" и "height" задаются в процентах от текущего размера кадра.

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

При значениях ширины и высоты, равных "0", областью интереса считается весь кадр.

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

Система координат ROI
Система координат ROI

Ниже приведен пример расчета ROI в процентах:

Пример расчета ROI в процентах
Пример расчета ROI в процентах

frame_processing_mode#

Данный параметр используется для типов "tcp", "udp" и "videofile".

Параметр аналогичен convert_full_frame, но задаётся для конкретного экземпляра FaceStream.

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

При значении "scale" масштабирование изображения выполняется в зависимости от настроек TrackEngine (стандартное поведение для релизов 3.2.4 и ниже).

По умолчанию задано значение "auto". В этом случае один из двух режимов выбирается автоматически.

real_time_mode_fps#

Данный параметр используется только для типа "videofile".

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

Если у видео высокое значение FPS и FaceStream не может работать с заданным количеством кадров в секунду, то кадры будут пропускаться.

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

Параметр не используется, если выставлено значение "0".

ffmpeg_threads_number#

Параметр позволяет задать количество потоков для декодирования видео с помощью FFMPEG.

При увеличении числа потоков увеличивается число ядер процессора, задействованных в декодировании. Увеличение числа потоков рекомендуется при обработке видео высокого разрешения (4K и выше).

preferred_program_stream_frame_width#

Данный параметр используется для типов "tcp", "udp".

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

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

Например, имеется 4 канала, ширины кадров которых равны 100, 500, 1000 и 1400. Если параметр "preferred_program_stream_frame_width" равен "800", то будет выбран канал, ширина кадра которого равняется 1000.

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

В логах FaceStream (тег "ffmpeg") выбранное значение будет указываться в виде сообщения:

Url: [url] selected preferred stream #[res], [width]x[height] preferred width: [preferredProgramStreamFrameWidth]

Значение по умолчанию равно 800.

endless#

Данный параметр используется для типов "tcp", "udp".

Данный параметр позволяет управлять перезагрузкой потока при получении ошибки сети (ошибка определяется системой как маркер конца файла eof).

Если параметр endless принимает значение true, то в случае получения eof и успешного переподключения, обработка потока будет продолжена. Если все попытки переподключения не удались (см. группу параметров "healthcheck"), то поток примет статус "failure". Если же параметр принимает значение false, то обработка потока не будет продолжена и поток примет статус "done".

При трансляции видеофайла предполагается использование значения false. Это позволит избежать повторной обработки уже обработанного фрагмента видеофайла при получении eof. Если же при трансляции видеофайла значение параметра endless будет true, то после окончания обработки видеофайл начнет обрабатываться с начала.

mask#

Данный параметр используется для типа "images".

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

Если задать маску “Img_%02d.jpg”, то FaceStream будет обрабатывать файлы, имена которых состоят из: Префикс (Img_) + двузначное число (%02d) + формат (.jpg)

Изображения, подходящие под маску, будут обрабатываться по очереди изображения:

  • Img_00.jpg
  • Img_01.jpg
  • Img_02.jpg
  • Img_03.jpg

Другой пример маски – Photo-%09d.jpg. Подходящие под маску файлы:

  • Photo-000000000.jpg
  • Photo-000000001.jpg
  • Photo-000000002.jpg
  • Photo-000000003.jpg

FaceStream обрабатывает файлы по порядку нумерации и не пропускает несуществующие файлы. Если следующий по нумерации файл отсутствует, FaceStream прекращает обработку.

Указанная в примере маска “example1_%04d.jpg” приведёт к обработке изображений, название которых состоит из префикса example1_ и порядкового номера кадра размером в 4 символа (например: example1_0001.jpg, example1_0002.jpg и т. д.).

"mask": "example1_%04d.jpg"

Настройки аналитики#

Под аналитикой понимается анализ содержимого видеопотока для извлечения ключевых данных и характеристик. Задание настроек аналитики также предоставляет возможность настройки фильтрации данных и их отправки во внешнюю систему. Соответствующие параметры задаются в группе параметров "analytics".

Основные настройки в группе параметров "analytics":

  • "enabled" — включение аналитики
  • "mode" — режим аналитики (1 — только лица, 2 — только тела, 3 — тела и лица)
  • "droi" — область выбора исходного кадра
  • "filtering" — объекты фильтрации изображений и отправки результирующих лучших кадров
  • "sending" — настройка параметров, связанных с составлением коллекции лучших кадров, а также периода, в течении которого будет проводиться анализ кадров для выбора лучшего кадра
  • "event_handler" — настройка параметров, связанных с интеграцией с внешней системой для последующей обработки кадров
  • "healthcheck" — настройка параметров, отвечающих за повторное подключение к потоку при возникновении ошибок во время потоковой передачи видео

Также в группе параметров "analytics" задаются настройки проверки Liveness и политики Главного трека. Как правило, данные параметры редко используются в кооперативном режиме. См. разделы "Настройка Liveness" и "Настройка политики Главного трека" для более подробной информации

Область выбора лучшего кадра#

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

Область интереса внутри исходного кадра или ROI задается с помощью параметра "droi". Если используется область ROI, то детектирование лиц выполняется в области ROI, но лучший кадр выбирается только в области DROI. Детекция лица должна полностью находиться внутри области DROI, чтобы кадр рассматривался в качестве лучшего. Ни одна сторона детекции не должна выступать из области DROI даже на миллиметр.

DROI рекомендуется использовать при работе со СКУД и при включённом режиме "use_mask_liveness_filtration".

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

Область интереса DROI на исходном кадре задается параметрами "x", "y", "width", "height" и "mode", где:

  • "x" и "y" – координаты верхней левой точки области интереса DROI;
  • "width" и "height" – ширина и высота обрабатываемой области кадра;
  • "mode" – режим указания "x", "y", "width" и "height". Доступно два режима:
  • "abs" – параметры "x", "y", "width" и "height" задаются в пикселях;
  • "percent" – параметры "x", "y", "width" и "height" задаются в процентах от текущего размера кадра.

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

При расчете DROI нужно учитывать то, что данная область интереса рассчитывается относительно исходного кадра, а не относительно ROI.

Система координат DROI
Система координат DROI

Если размер ROI изменяется, а размер DROI остаётся в значении по умолчанию (0, 0, 0, 0), то DROI не учитывается. Если изменить размер DROI, то он будет учитываться при выборе лучшего кадра.

Ниже приведен пример расчета DROI в процентах:

Пример расчета DROI в процентах
Пример расчета DROI в процентах

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

Группа параметров "filtering" описывает объекты фильтрации изображений и отправки результирующих лучших кадров.

min_score_face#

Параметр задает порог для фильтрации отправляемых детекций лиц.

Для каждой детекции вычисляется AGS (Approximate Garbage Score) и общее качество.

Детекции, у которых значение AGS меньше, чем значение, указанное в пороге "min_score_face" не будут считаться приемлимыми для дальнейшей работы. Далее по отфильтрованным детекциям будут выбраны лучшие снимки в соответствии с общим качеством детекции.

Если в параметре "min_score_face" задано значение "0", то лучшие снимки будут определены по общему качеству детекций.

Значение по умолчанию – 0.5187.

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

min_score_body#

Параметр задает порог для фильтрации отправляемых детекций тел.

Для каждой детекции вычисляется общее качество.

Детекции, у которых общее качество меньше, чем значение, указанное в пороге "min_score" не будут считаться приемлимыми для дальнейшей работы. Далее по отфильтрованным детекциям будут выбраны лучшие снимки.

Если в параметре "min_score" задано значение "0", то лучшие снимки будут определены по качеству детекций.

Значение по умолчанию – 0.5.

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

detection_yaw_threshold#

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

Параметр задаёт максимальное значение угла поворота головы вправо и влево относительно камеры.

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

Для отключения фильтрации необходимо задать значение "180".

detection_pitch_threshold#

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

Параметр задаёт максимальное значение угла наклона головы вниз и вверх относительно камеры.

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

Для отключения фильтрации необходимо задать значение "180".

detection_roll_threshold#

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

Параметр задаёт максимальное значение угла наклона головы влево и вправо относительно камеры.

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

Иллюстрация положения головы
Иллюстрация положения головы

Для отключения фильтрации необходимо задать значение "180".

yaw_number#

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

Параметр определяет количество кадров, используемых для фильтрации фотоизображений по углу поворота (yaw angle) головы. Фильтрация отсекает изображения с сильно повернутыми от камеры лицами.

Как это работает:

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

Пример: Установим значение параметра "7", то есть будут рассмотрены 7 кадров. Представим, что на шести кадрах из семи посчитали, что угол поворота головы относительно камеры находится в диапазоне 50 — 60 градусов, а на седьмом кадре значение угла равно 0. Такое резкое изменение угла поворота головы за такой короткий промежуток времени невозможно, и, скорее всего, угол на седьмом кадре определен неверно. Седьмой кадр будет отсечен и не будет отправлен на внешний сервис в качестве лучшего кадра.

По умолчанию параметр выключен, значение равно "1". Рекомендуемое значение – "7".

yaw_collection_mode#

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

Параметр указывает системе, что необходимо собрать заданное в параметре "yaw_number" количество кадров для анализа угла поворота (yaw angle) головы.

Если параметр "yaw_collection_mode" отключен, то система будет последовательно проводить анализ поступающих кадров, т. е. сначала проводится анализ двух кадров, затем трех и т. д. Максимальное количество кадров этой последовательности задано в "yaw_number".

По умолчанию параметр отключён.

Цель работы параметров "yaw_number" и "yaw_collection_mode" — увеличить точность определения лучшего кадра из всего трека.

mouth_occlusion_threshold#

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

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

Например, при значении параметра равном "0.5" допускается перекрытие 50% области рта.

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

Фильтрация проводится при значении параметра "0.3" и выше. При значении ниже фильтрация отключена.

min_body_size_threshold#

Параметр задает размер детекции тела, меньше которого она не будет рассматриваться как лучший снимок. Размер высчитывается как квадратный корень из произведения ширины (в пикселях) на высоту (в пикселях) детекции.

Пример: min_body_size_threshold = sqrt (64*128) = 90.5

Если значение равно "0", то фильтрация детекции тела по размеру выполняться не будет.

Отправка во внешнюю систему#

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

Лучшие кадры
Лучшие кадры

Настройки отправки данных тел#

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

Доступно два параметра:

  • "delete_track_after_sending" — включить удаление лучших кадров и детекций после отправки данных. Если значение равно "false" (по умолчанию), то данные останутся в памяти.
  • "send_only_full_set" — включить отправку данных во внешнюю систему только если набрано определенное количество лучших снимков (параметр "body_bestshots_to_send") и только если набрано определенное количество детекций с координатами тела человека (параметр "minimal_body_track_length_to_send" настроек FaceStream).

Настройки отправки лучших снимков#

Настройки отправки лучших снимков регулируются в группе параметров "bestshot_settings".

Доступны следующие параметры:

  • "type" — режим отправки лучших снимков:
    • только лучшие снимки лиц
    • только лучшие снимки тел
    • лучшие снимки лиц и тел в одном запросе
    • лучшие снимки лиц и тел в разных запросах

  • "face_bestshots_to_send" и "body_bestshots_to_send" — количество лучших снимков, которое пользователь хочет получить с трека или с какого-то промежутка времени на этом треке.

    Использование данного параметра предполагает создание коллекции из лучших снимков трека или временного отрезка трека, заданном в параметре "time_period_of_searching". Эта коллекция будет отправлена во внешнюю систему.

    Увеличение значения повышает вероятность правильного распознавания объекта, но сказывается на загруженности сети.

full_frame_settings#

Важно! В настоящий момент в совместном режиме детектирования лиц и тел отправляются только исходные кадры лиц и тел.

Данный параметр задает режим отправки исходных кадров:

  • только исходные кадры лиц
  • только исходные кадры тел
  • исходные кадры лиц и тел в одном запросе
  • исходные кадры лиц и тел в разных запросах

Важно! Отправка исходных кадров должна быть включена в параметре "send_source_frame" в настройках FaceStream.

time_period_of_searching#

Период анализа кадров, по истечении которого будет отправлен лучший кадр (период начинается с момента появления человека в кадре - первой детекции). Уменьшение этого параметра позволяет быстрее определять личность, но с большей погрешностью.

Период оправки
Период оправки

Тип измерения задается в параметре "type" (см. ниже). Если значение равно "-1" (по умолчанию), то анализ кадров проводится по всем кадрам до конца трека. По окончании трека (когда объект покидает пределы кадра) лучший кадр будет отправлен во внешний сервис.

silent_period#

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

Период ожидания, когда предыдущий анализ кадров завершился, а новый ещё не начался.

Период ожидания
Период ожидания

Тип измерения задается в параметре "type" (см. ниже). Если значение равно "-1", то период ожидания будет длиться бесконечно.

Бесконечный период ожидания
Бесконечный период ожидания

type#

Параметр задаёт тип измерения для параметров "silent_period" и "time_period_of_searching". Может принимать два значения - "frames" (кадры) или "sec" (секунды).

Настройки интеграции с внешней системой#

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

frame_store#

В данном параметре задаётся URL для сохранения исходных кадров лиц или тел в LUNA PLATFORM 5.

В качестве URL можно указать либо адрес до бакета сервиса LUNA Image Store, либо адрес к ресурсу "/images" сервиса LUNA API. При указании адреса к ресурсу "/images", исходный кадр будет сохранен под идентификатором "image_id".

Для отправки кадра следует включить опцию send_source_frame.

Пример адреса до бакета сервиса LUNA Image Store:

"frame_store": "http://127.0.0.1:5020/1/buckets/<frames>/images"

Здесь:

  • 127.0.0.1 — IP адрес, где развернут сервис LUNA Image Store;
  • 5020 — порт сервиса LUNA Image Store по умолчанию;
  • 1 — версия API сервиса LUNA Image Store;
  • <frames> — имя бакета сервиса LUNA Image Store, в котором нужно сохранить изображение лица или тела. Бакет должен быть создан пользователем предварительно.

Пример команды создания бакета с именем "source-images":

curl -X POST http://127.0.0.1:5020/1/buckets?bucket=source-images

Пример адреса к ресурсу "/images" сервиса LUNA API:

"frame_store": "http://127.0.0.1:5000/6/images"

Здесь:

  • 127.0.0.1 — IP адрес, где развернут сервис LUNA API;
  • 6 — версия API сервиса LUNA API;
  • 5000 — порт сервиса API по умолчанию.

См. дополнительную информацию о бакетах и ресурсе "/images" в руководстве администратора LUNA PLATFORM 5.

authorization#

В данной группе параметров задаются либо token, либо account_id для выполнения запросов к сервису LUNA API.

Параметр event_handler > authorization > account_id должен совпадать с параметром account_id, задаваемом в запросе. Если поле авторизации не заполнено, то будет использован идентификатор account_id, задаваемый при создании потока (см. account_id).

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

Настройки healthcheck#

Данная группа параметров используется только при работе с потоками ("tcp", "udp") и видеофайлами ("videofile").

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

max_error_count#

Максимальное количество ошибок при воспроизведении потока.

Параметр работает совместно с параметрами "period" и "retry_delay". После получения первой ошибки, выполняется ожидание, заданное в параметре "retry_delay", а затем выполняется повторная попытка подключения к потоку. Если за время, указанное в параметре "period", было накоплено количество ошибок большее или равное количеству, указанному в "max_error_count, то обработка потока будет прекращена и его статус изменится на "failure".

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

period#

Задаёт время в секундах, за которое ведётся подсчёт ошибок.

Параметр работает совместно с параметрами "retry_delay и "max_error_count. См. описание работы с данным параметром в разделе "max_error_count".

retry_delay#

Задаёт время в секундах, по истечении которого выполняется повторная попытка подключения к потоку.

Параметр работает совместно с параметрами "period и "max_error_count. См. описание работы с данным параметром в разделе "max_error_count".

timeout#

Задаёт таймаут в миллисекундах на чтение закодированного пакета.

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

Настройки Liveness#

Liveness не используется для типа "images".

Liveness используется только при работе с лицами.

Liveness используется для проверки наличия живого человека в кадре и предотвращает использование распечатанного фото или фото с телефона для прохождения проверки.

Настройки Liveness задаются в группе параметров "data" > "analytics" > "liveness".

Данную группу параметров рекомендуется использовать только по согласованию с сотрудниками VisionLabs.

Общие рекомендации по использованию Liveness#

Liveness предназначен для применения только на автоматических контрольно-пропускных пунктах. Это сценарий, когда человек не задерживается перед камерой дольше десяти секунд.

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

В процессе работы Liveness возвращает значение, которое определяет степень уверенности системы в том, что в кадре живой человек. Значение находится в интервале от 0 до 1.

Требования к установке камеры#

Для стабильной работы Liveness при установке камеры должны быть выполнены следующие условия:

  • Лицо не должно выходить за пределы кадра. При этом расстояние от левого и правого краёв кадра должно быть больше или равно ширине найденного лица, а расстояние от верхнего и нижнего краёв кадра должно быть больше или равно высоте найденного лица;

  • Кадр должен включать не только лицо, но и область груди;

  • Камера должна быть расположена на уровне пояса и направлена на человека снизу вверх;

  • Желательно, чтобы в кадр не попадали прямоугольные объекты (такие как оконные и дверные проёмы), обрамляющие область лица с четырёх сторон.

Пример правильного расположения камеры приведён на изображении ниже.

Правильное расположение камеры для использования Liveness
Правильное расположение камеры для использования Liveness

При правильном расположении камеры уже на расстоянии в 3-4 метра FS начнёт собирать кадры и выбирать лучший снимок.

Посторонние объекты и люди, не проходящие через турникет, не попадают в зону видимости камеры.

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

Ниже приведён пример неправильного расположения камеры.

Неправильное расположение камеры для использования Liveness
Неправильное расположение камеры для использования Liveness

При неправильно настроенной камере:

  • Человек попадает в кадр слишком поздно. FS не успевает получить необходимое количество кадров для обработки;
  • Человек смотрит в камеру сверху вниз. Это ухудшает качество кадра для последующей обработки;
  • В зону видимости камеры попадает пространство за пределами зоны интереса. В этом пространстве могут находиться люди или объекты, мешающие корректной работе FS.

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

Рекомендуемые значения параметров секции "Liveness" приведены ниже.

"use_mask_liveness_filtration": true,
"use_flying_faces_liveness_filtration": true,
"liveness_mode": 1,
"number_of_liveness_checks": 10,
"liveness_threshold": 0.8,
"livenesses_weights": [0.0, 0.25, 0.75],
"mask_backgrounds_count": 300

Данные настройки не рекомендуется изменять.

Параметр "best_shot_min_size" следует устанавливать из расчета, что человек находится на расстоянии 3-4 метра до турникета.

Параметр "best_shot_proper_size" следует устанавливать из расчета, что человек находится на расстоянии 1 метр до турникета.

Для контроля выбора нужного человека используется параметр "droi". Прямоугольник выбирается так, чтобы люди, имеющие намерение подойти к данному турникету, попали в прямоугольник как можно раньше. Это актуально для турникетов, расположенных близко к друг другу. Люди из соседних очередей могут попадать в зону видимости камер таких турникетов.

FAQ Liveness#

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

При разрешении камеры 1920х1080 и выше Mask Liveness работает медленно.

Для решения проблемы следует вручную уменьшить разрешение в камере до 720p. Это не скажется на качестве распознавания и работе Liveness, т.к. они работают без потери качества с лицами, размер которых примерно равен 100 пикселям.

Люди не могут пройти проверку Liveness при настройках FS по умолчанию

Возможные причины:

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

Не следует изменять настройки в секции Liveness, кроме настройки "liveness_threshold".

Значение параметра "liveness_threshold" можно уменьшить, но оно не должно быть ниже "0.6".

  • Liveness применяется не для целевого случая.

FS Liveness не предназначен для процессов авторизации и случаев долгого нахождения перед камерой.

  • В зону видимости камеры попадают недопустимые объекты.

Например, если на заднем фоне находится экран, транслирующий видео, Liveness работать не будет.

  • Для камеры задано неподходящее разрешение.

Проверьте разрешение камеры. См. "При использовании Liveness обработка потока работает медленно".

  • Происходит задержка передачи кадров.

Если камера не передаёт кадры в реальном времени, то кадры могут поступать с задержкой.

При завышенном параметре "best_shot_min_size" Liveness не успевает накопить нужное число разнообразных кадров.

Часто вместе с Liveness используется политика Главного Трека. См. диаграмму активности FaceStream при использовании Liveness и Primary Track Policy.

use_mask_liveness_filtration#

Параметр включает режим проверки наличия человека в кадре, основанный на работе с фоном.

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

use_flying_faces_liveness_filtration#

Параметр включает режим проверки наличия человека в кадре, основанный на работе с окружением лица.

liveness_mode#

Параметр позволяет задать, для каких кадров трека будет проводиться проверка Liveness. Есть три варианта выбора кадров:

  • 0 — Первые N кадров;
  • 1 — Последние N кадров перед отправкой лучшего кадра (рекомендуемое значение);
  • 2 — Все кадры трека.

Значение N задаётся в параметре number_of_liveness_checks.

number_of_liveness_checks#

Параметр позволяет задать количество кадров в треке для проверки Liveness при использовании параметра "liveness_mode".

Не рекомендуется выставлять значение меньше 10.

liveness_threshold#

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

Рекомендуемое значение - "0.8". Не рекомендуется задавать значение ниже "0.6".

livenesses_weights#

Параметр определяет коэффициент влияния проверки каждого типа (mask и flying_faces) на итоговую оценку наличия живого человека в кадре.

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

  • "use_mask_liveness_filtration"
  • "use_flying_faces_liveness_filtration"

Величины указываются в долях единицы. В приведенном ниже примере 0.25 - 25% на "mask_liveness" и 0.75 - 75% на "flying_faces_liveness". Соотношение всегда масштабируется исходя из данных цифр вне зависимости от того составляют ли они единицу и какие из методов liveness включены. 

"livenesses_weights": [0.25, 0.75]

mask_backgrounds_count#

Количество кадров фона, которые используются для соответствующей проверки.

Изменение данного параметра запрещено.

Настройки политики Главного трека#

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

Политика Главного трека не используется для типа "images".

Важно! В настоящий момент политика Главного трека не работает для совместного режима детектирования лиц и тел.

Политика Главного трека предназначена для работы с Системами Контроля Управления Доступом (СКУД, турникеты на входах в банки/ офисные здания) для упрощения контроля и внедрения технологии распознавания лиц при входе на охраняемую территорию.

Настройки политики Главного трека задаются в группе параметров "data" > "analytics" > "primary_track_policy".

Часто вместе с политикой Главного Трека используется Liveness. См. диаграмму активности FaceStream при использовании Liveness и Primary Track Policy.

use_primary_track_policy#

Если значение этого параметра "true", то включается режим реализации Главного Трека (Primary Track). Логика работы заключается в следующем:

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

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

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

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

best_shot_min_size#

Параметр используется при включенном параметре "use_primary_track_policy".

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

best_shot_proper_size#

Параметр используется при включенном параметре "use_primary_track_policy".

Задаёт высоту детекции в пикселях для Главного Трека. Когда размер детекции достигает указанного значения, FaceStream определяет лучшие снимки до окончания трека, а затем отправляет их в LP.