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

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

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

Поддерживаются несколько типов источников:

tcp, udp – источники видеосигнала реального времени. Это могут быть как usb-камеры, так и IP-камеры (посредством протокола RTSP);
videofile – видеофайлы;
images – набор кадров в виде отдельных файлов изображений.

Обратите внимание, что настройки управления потоками не хранятся в сервисе LUNA Configurator и могут быть заданы только с помощью HTTP запросов к сервису LUNA Streams. Подробное описание запросов и примеры запросов можно найти в спецификации Open API LUNA Streams. Настройки LUNA Streams, задаваемые в LUNA Configurator, описаны в разделе "Настройки LUNA Streams".

account_id#

Параметр задаёт значение обязательного поля “account_id”, которое передаётся в заголовке запроса в LUNA PLATFORM 5 в сервис API.

Account ID задаётся в формате UUID4. Требования в Account ID можно найти в документации LUNA PLATFORM 5.

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

name#

Имя потока. Служит для идентификации источника отправляемых кадров.

Записывается в поле "source" генерируемого события LP.

description#

Пользовательское описание потока.

Данный параметр не записывается в генерируемое событие LP.

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 в процентах:

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.

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

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

rotation#

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

preferred_program_stream_frame_width#

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

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

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

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

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

endless#

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

Параметр доступен только для типов источника сигнала "udp" и "tcp".

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

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

mask#

Параметр 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"

event_handler#

Данная группа параметров определяет параметры обработчика, создаваемого в LUNA PLATFORM, с помощью которого будут обрабатываться потоки. Для лиц и тел следует использовать различные обработчики. Обработчик должен быть создан в LP 5 заранее.

Подробную информацию об обработчиках см. в руководстве администратора LUNA PLATFORM.

origin#

Полный сетевой путь к сервису API развернутой LUNA PLATFORM, включающую сервисы LUNA Handlers и LUNA Events, необходимые для генерации события по обработчику.

"origin": "http://luna_address:port/"

luna_address - адрес сервиса LUNA API,

port - порт, используемый сервисом API. По умолчанию - 5000.

api_version#

Версия API для генерации события в LUNA PLATFORM. На настоящий момент поддерживается 6 версия API.

bestshot_handler > handler_id#

Параметр позволяет использовать внешний статический "handler_id" LUNA PLATFORM для обработки биометрических образцов лиц или тел по заданным правилам. При использовании данного обработчика, LUNA PLATFORM генерирует событие, которое содержит всю информацию, полученную из FaceStream и обрабатывает её в соответствии с правилами обработки.

Обработчик должен быть создан в LP 5 заранее.

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.

policies#

sending#

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

"sending": {
    "time_period_of_searching": -1,
    "silent_period" : 0,
    "type" : "sec",
    "number_of_bestshots_to_send": 1
    "send_only_full_set": true
    "delete_track_after_sending" false
},

time_period_of_searching#

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

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

silent_period#

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

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

type#

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

number_of_bestshots_to_send#

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

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

send_only_full_set#

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

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

delete_track_after_sending#

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

Позволяет удалять лучшие кадры и детекции с координатами тела человека после отправки данных. Если значение равно "false" (по умолчанию), то данные останутся в памяти.

primary_track_policy#

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

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

Часто вместе с политикой Главного Трека используется 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.

liveness#

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

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

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

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

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

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

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

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

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

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

Лицо не должно выходить за пределы кадра. При этом расстояние от левого и правого краёв кадра должно быть больше или равно ширине найденного лица, а расстояние от верхнего и нижнего краёв кадра должно быть больше или равно высоте найденного лица;
Кадр должен включать не только лицо, но и область груди;
Камера должна быть расположена на уровне пояса и направлена на человека снизу вверх;
Желательно, чтобы в кадр не попадали прямоугольные объекты (такие как оконные и дверные проёмы), обрамляющие область лица с четырёх сторон.

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

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

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

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

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

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

Неправильное расположение камеры для использования 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" задано неправильно.

При завышенном параметре "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_shoulders_liveness_filtration (Deprecated. Любое значение будет считаться 0.0),
Use_mask_liveness_filtration,
Use_flying_faces_liveness_filtration.

Величины указываются в долях единицы. В приведенном ниже примере (являющимся настройкой по умолчанию) цифра 0.0 ни на что не указывает, т.к. проверка Use_shoulders_liveness_filtration объявлена как Deprecated, 0.25 - 25% на mask_liveness и 0.75 - 75% на flying_faces_liveness. Соотношение всегда масштабируется исходя из данных цифр вне зависимости от того составляют ли они единицу и какие из методов liveness включены.

"livenesses_weights": [0.0, 0.25, 0.75]

mask_backgrounds_count#

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

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

filtering#

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

"filtering": {
    "min_score": 0.5187,
    "detection_yaw_threshold": 40,
    "detection_pitch_threshold": 40,
    "detection_roll_threshold": 30,
    "yaw_number": 1,
    "yaw_collection_mode": false,
    "mouth_occlusion_threshold" : 0.0
},

min_score#

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

Значение данного параметра зависит от сценария работы FaceStream - с лицами или с телами.

Режим работы с лицами

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

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

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

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

Режим работы с телами

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

Детекции, у которых общее качество меньше, чем значение, указанное в пороге "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", то фильтрация детекции тела по размеру выполняться не будет.

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 и выше).

health_check#

Данная группа параметров используется только при работе с потоками ("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#

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

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

location#

Данная группа параметров включает информацию о расположении источника видеосигнала.

"city" - город
"area" - область
"district" - район
"street" - улица
"house_number" - номер дома
"geo_position" - географическое положение, включает в себя параметры "latitude" (широта) и "longitude" (долгота)

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

Параметр send_location_data регулирует отправку расположения источника видеосигнала.

"location": {
    "send_location_data" : false,
    "city": "Moscow",
    "area": "CAO",
    "district": "Arbat",
    "street": "Arbat",
    "house_number": "37",
    "geo_position": {
    "longitude": 36.616,
    "latitude": 55.752
    }
}

autorestart#

Данная группа параметров позволяет настроить автоматический перезапуск потока. Доступно три параметра:

restart - следует ли использовать автоматический перезапуск потока
attempt_count - количество попыток автоматического перезапуска потока (по умолчанию 10)
delay - задержка автоматического перезапуска потока, в секундах (по умолчанию 60 секунд)

См. подробную информацию о работе автоматического перезапуска потока в разделе "Автоматический перезапуск потоков".

status#

Состояние на момент начала обработки. Доступно два состояния - "pending" (ожидание) "pause" (пауза).

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

group_name и group_id#

Параметры привязки потока к группе. Можно указать либо "group_id", либо "group_name".