Глоссарий#

Термин	Определение
Лучший кадр, Bestshot	Кадр видеопотока, на котором лицо зафиксировано в оптимальном ракурсе для дальнейшего использования в системе распознавания лиц
Bbox	Прямоугольник, ограничивающий пространство изображения с обнаруженным лицом
Interaction over Union (IOU)	Пересечение над объединением. Данный параметр определяет коэффициент пересечения двух детекций
JSON	Текстовый формат обмена данными, основанный на JavaScript.
Liveness	Программный способ подтверждения витальности (живучести, жизненности) человека по одному или нескольким изображениям с целью предотвращения спуфинг-атак
MessagePack (MsgPack)	Быстрый и компактный формат двоичной сериализации для обмена данными
Атрибуты	Пол и возраст человека, определяемые системой автоматически
Детекция	Действия по нахождению областей изображения, содержащих лица
Спуфинг-атака	Тип атаки, основанной на фальсификации передаваемых данных, в частности подмена живого человека на поддельное изображение (например, фотографию) с целью обмана системы

Введение#

Данный документ содержит сведения о VisionLabs LUNA KIOSK и описывает принципы работы компонентов.

VisionLabs LUNA KIOSK (далее – Система) представляет собой набор библиотек, обеспечивающих возможность реализации работы в режиме реального времени для выполнения детекции лица в кадре, проверки витальности человека и передачи данных во внешнюю систему.

Система предназначена для:

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

Системные требования#

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

Минимальные системные требования для архитектуры x64#

Необходимый ресурс	Рекомендовано
Процессор	Intel(R) Core(TM) i3-10110U
Оперативная память	4Гб и выше
Жесткий диск	HDD или SSD не менее 1,4 ГБ
Операционная система	Windows 10 (64 bit) Ubuntu 24.04 x64 Debian 10 x64 Astra Linux 1.7.7
Поддержка инструкций	Advanced Vector Extensions 2 (AVX2)

Для запуска приложения под Windows установите пакет Visual C++ Redistributable.

Минимальные системные требования для архитектуры ARM#

Необходимый ресурс	Рекомендовано
Процессор	Rockchip RK3588S
Оперативная память	4Гб и выше
Жесткий диск	HDD или SSD не менее 128 ГБ
Операционная система	Armbian 23 (aarch64)

Поддерживаемые камеры#

Система оптимизирована и протестирована для надежной работы со следующими 3D- и ИК-камерами:

Intel® RealSense™ Depth Cameras:
- D415
- D435
- D435j
- D455
VLS LUNA CAMERA:
- VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D Embedded
- VLS LUNA CAMERA 2D
Orbbec:
- Gemini E
- Gemini 335
- Gemini UW

Важные примечания:

Для получения информации о камерах VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D обратитесь к представителю VisionLabs.
Перед использованием камер Orbbec с LUNA KIOSK убедитесь, что на целевой системе установлен официальный драйвер Orbbec. Без драйвера камера может не распознаваться операционной системой или SDK. Для получения последних пакетов драйверов и инструкций по установке обратитесь к Порталу разработчиков Orbbec.
Минимальное рабочее расстояние для камер Orbbec Gemini UW составляет 200 мм.

Требования к расстоянию Gemini UW

Требования к подключению#

Для стабильной работы подключайте все поддерживаемые камеры через USB 3.0.

Если есть дополнительное оборудование, например, камера подключена через хаб, то нужно использовать более свежие стандарты: USB 3.1, 3.2.

Совместимость SDK Orbbec и Intel RealSense#

В этом разделе приведена информация о совместимости SDK Orbbec и Intel RealSense с соответствующим оборудованием и операционными системами.

Orbbec SDK v.1.10.27#

Совместимость с оборудованием:
- Gemini E
- Gemini 335
Требования к прошивке:
- Минимальная версия прошивки: 1.6.00
Поддерживаемые операционные системы:
- Windows:
  - Windows 10 или новее
  - Архитектура: x86 и x64
- Linux:
  - Архитектура: только x64
  - Рекомендуемые дистрибутивы:
    - Ubuntu 20.04 LTS
    - Ubuntu 22.04 LTS
    - Ubuntu 24.04 LTS

Orbbec SDK v.2.5.5#

Совместимость с оборудованием:
- Gemini E
- Gemini 335
Требования к прошивке:
- Минимальная версия прошивки: 1.6.00
Поддерживаемые операционные системы:
- Windows:
  - Windows 10 или новее
  - Архитектура: только x64
- Linux:
  - Архитектура: только x64
  - Рекомендуемые дистрибутивы:
    - Ubuntu 20.04 LTS
    - Ubuntu 22.04 LTS
    - Ubuntu 24.04 LTS

Intel RealSense SDK v.2.56.5#

Совместимость с оборудованием:
- Камеры:
  - Intel RealSense D415
  - Intel RealSense D435i
  - Intel RealSense D435
Требования к прошивке:
- Минимальная версия прошивки: 5.17.0.10
Поддерживаемые операционные системы:
- Windows:
  - Поддерживаемые версии:
    - Windows 11
    - Windows 10 (сборка 15063 или новее)
  - Рекомендуемые конфигурации:
    - Windows 10 RS5 (Redstone 5)
    - Windows 11 KB5030219 (сборка ОС 22621.2283 или новее)
    - Для всех установок рекомендуется сборка 17763 и выше
Linux:
- Поддерживаемые дистрибутивы:
  - Ubuntu 20.04 LTS
  - Ubuntu 22.04 LTS
  - Ubuntu 24.04 LTS
  - Дистрибутивы, не входящие в серию LTS, не поддерживаются
- Версии ядра:
  - 6.[2, 5, 8]
  - 5.[0, 3, 4, 8, 13, 15, 19]

Ограничения по оборудованию#

Следующие чипсеты Intel не поддерживаются:

Серия чипсетов Intel	ID чипа PCH	Совместимые процессоры
300 Series/C240	9DED, A36D	Мобильные и настольные процессоры Intel Core 8-го и 9-го поколений
600 Series	51ED	Мобильные процессоры Intel Core 12-го поколения

Архитектура Системы#

Высокоуровневая схема архитектуры Системы представлена ниже (Рисунок 1).

Система состоит из следующих компонентов:

RSEngine – компонент, который включает в себя:
библиотеку SDK VisionLabs из набора средств разработки VisionLabs, предназначенную для обработки изображений;
библиотеки:
- RealSense2 SDK – для работы с камерой Intel RealSense;
- VLS LUNA CAMERA 3D SDK – для работы с камерой VLS LUNA CAMERA 3D;
- VLS LUNA CAMERA 2D SDK – для работы с камерой VLS LUNA CAMERA 2D;
Мониторинг камеры, предназначенный для проверки состояния камеры;
RSE Server – WebSocket сервер для взаимодействия с внешней системой WebSocket Client.

Алгоритм работы#

Выбор лучшего кадра#

Взаимодействие компонентов при выборе лучшего кадра отражено ниже (Рисунок 2).

Диаграмма взаимодействия компонентов Системы при выборе лучшего кадра

Ниже представлено пояснение к рисунку (Таблица 3).

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

Шаг	Описание
(1)	В RSE Server поступает запрос на соединение по WebSocket от клиента. Пример запроса: `GET ws://127.0.0.1:4444/` – установка соединения по WebSocket. `0` - содержимое сообщения для старта сессии
(2)	RSE Server передает запрос RSEngine на запуск камеры (в библиотеку камеры). В зависимости от того, какая камера подключена,`IntelRealSense`, `VLS LUNA CAMERA 3D` или `VLS LUNA CAMERA 2D`, RSE Server передает запрос в соответствующую библиотеку RSEngine: `RealSense2 SDK`, `VLS LUNA CAMERA 3D SDK`, `VLS LUNA CAMERA 2D SDK`.
(3)	Библиотека камеры запускает камеру
(4)	Библиотека камеры получает RGB, IR, Depth видеопотоки с камеры, разбивает на кадры и анализирует
(5)	Библиотека камеры передает набор кадров в RSE Server. В зависимости от параметра `cs_communication` будут передаваться разные данные: `- cs_communication = msg-pack`: передаются все три кадра (RGB, IR, Depth) `- cs_communication = json`: передается только RGB-кадр
(6)	RSE Server отправляет запрос на обработку кадра (производится по каждому кадру) в SDK VisionLabs
(7)	SDK VisionLabs выполняет: выбор каждого третьего кадра из поступающего видеопотока (данное количество кадров не регулируется в настройках); детекцию лиц на каждом кадре; определение атрибутов и параметров обнаруженных лиц; проверку пороговых значений полученных параметров (положение головы, качества изображений и др.). В случае, если все проверки пройдены, то процесс продолжается (переход к шагу 8). Если хотя бы одна проверка не пройдена, SDK VisionLabs отправляет запрос к камере на получение новых кадров для проведения повторной проверки до тех пор, пока есть детекция (возврат к шагу 4)
(8)	SDK VisionLabs выполняет оценку Liveness и сравнивает полученное значение оценки Liveness с пороговым значением. В случае, если полученное значение Liveness выше порогового значения, то текущий кадр становится лучшим кадром. Если полученное значение Liveness ниже порогового значения, то SDK VisionLabs отправляет запрос к камере на получение новых кадров для проведения повторной проверки до тех пор, пока есть детекция (возврат к шагу 4)
(9)	В случае, если проверка Liveness пройдена успешно, то полученный лучший кадр и атрибуты лица направляются в RSE Server
(10)	RSE Server преобразует выбранный лучший кадр и метаинформацию в формат MessagePack и отправляет клиенту во внешнюю систему

Мониторинг состояния камеры#

Взаимодействие компонентов при мониторинге состояния камеры отражено ниже (Рисунок 3).

Диаграмма взаимодействия компонентов при мониторинге состояния камеры

Ниже представлено пояснение к рисунку (Таблица 3).

Мониторинг запускается по умолчанию раз в 300 секунд, длительность можно изменить в параметрах camera-monitoring и camera-monitoring-delay в файле rsengine.conf.

Таблица 4. Описание диаграммы взаимодействия компонентов Системы при мониторинге состояния камеры

Шаг	Описание
(1)	RSE Server передает запрос RSEngine на запуск мониторинга камеры
(2)	Мониторинг камеры передает запрос на получение информации о статусе камеры в библиотеку камеры — RealSense2 SDK, VLS LUNA CAMERA 3D SDK или VLS LUNA CAMERA 2D SDK в зависимости от того, какая камера подключена — IntelRealSense, VLS LUNA CAMERA 3D или VLS LUNA CAMERA 2D SDK
(3)	Библиотека камеры передает запрос на получение информации о статусе камеры
(4)	Библиотека камеры получает статус камеры
(5)	Библиотека камеры передает информацию о статусе камеры в мониторинг камеры
(6)	RSEngine передает информацию о статусе камеры в RSE Server
(7)	RSE Server записывает данные о статусе камеры в реестр (на ОС Windows) или в рабочую папку ./logs (на ОС Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23)

Описание компонентов#

Компонент RSEngine#

RSEngine обеспечивает взаимодействие следующих библиотек в системе:

VisionLabs LUNA SDK
RealSense2 SDK
VLS LUNA CAMERA 3D SDK
VLS LUNA CAMERA 2D SDK

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

Компонент VisionLabs LUNA SDK#

VisionLabs LUNA SDK представляет собой набор средств разработки (Software Development Kit), включающий специализированные библиотеки и нейронные сети, предназначенные для расширенного анализа изображений. Его ключевые возможности включают:

Распознавание лиц: распознавание лиц на изображениях и определение ключевых точек (ориентиров) лица.
Выбор лучшего кадра: автоматический выбор кадра с наивысшим качеством из видеопотока для дальнейшей обработки.
Оценка атрибутов изображения: анализ атрибутов изображения для дальнейшей проверки Liveness.
Проверка Liveness: оценка лиц на изображениях с использованием алгоритмов Liveness для предотвращения спуфинг-атак.

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

Компонент RealSense2 SDK#

RealSense2 SDK — это компонент, предоставляющий следующие функции:

Получение изображений: получает входящие изображения с камер Intel RealSense.
Настройка параметров: позволяет настраивать параметры детекции в соответствии с конкретными требованиями.
Управление камерой: позволяет включать и выключать камеру и настраивать различные параметры, такие как:
яркость подсветки лазера;
автоэкспозицию;
яркость.
Автоматическое управление подключением:
автоматически обновляет подключение к камере;
в случае потери соединения система пытается повторно подключиться к камере;
в случае сбоя повторного подключения выполняется программный сброс кабеля подключения;
если все операции восстановления не увенчались успехом, проблема будет зарегистрирована в отчёте о состоянии камеры в системных журналах.

Компонент VLS LUNA CAMERA 3D SDK#

VLS LUNA CAMERA 3D SDK — это компонент, предоставляющий следующие функции:

Получение изображений: получает входящие изображения с устройств VLS LUNA CAMERA 3D или VLS LUNA CAMERA 3D Embedded.
Настройка параметров: позволяет настраивать параметры детекции в соответствии с конкретными требованиями.
Управление камерой: позволяет включать и выключать камеру и настраивать различные параметры, такие как:
яркость подсветки лазера;
автоэкспозицию;
яркость.

Компонент VLS LUNA CAMERA 2D SDK#

VLS LUNA CAMERA 2D SDK — это компонент, предоставляющий следующие функции:

Получение изображений: получает входящие изображения с инфракрасных камер VLS LUNA CAMERA 2D.
Настройка параметров: позволяет настраивать параметры детекции в соответствии с конкретными требованиями.
Управление камерой: предоставляет возможность включать и выключать камеру по мере необходимости.
Регулировка поворота кадра: позволяет изменять угол поворота видеокадра камеры.

Функции камер#

Детектирование лиц#

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

Распознавание лиц: идентификация лиц на изображении.
Локализация ключевых точек: определение пяти ключевых ориентиров лица: двух для глаз, одного для кончика носа и двух для уголков рта.
Оценка качества обнаружения: оценка вероятности того, что обнаруженный объект действительно является лицом, что обеспечивает высокую точность и надежность.

Проверка качества изображения#

Качество изображения оценивается по следующим параметрам:

изображение размыто;
изображение недоэкспонировано, то есть слишком темное;
изображение переэкспонировано, то есть слишком светлое.

Проверка статуса рта#

Оценка состояния рта оценивает следующие параметры:

Open: показывает, открыт ли рот.
Occluded: определяет, закрыт ли рот посторонним предметом.
Smiling: определяет наличие улыбки.

Оценка статуса глаз#

Оценка состояния глаз проводится по следующим параметрам:

Закрыты: Глаза закрыты.
Открыты: Глаза открыты.
Перекрыты Глаза закрыты, например, солнцезащитными очками или другими предметами.

Оценка положения головы#

Оценка положения головы определяет углы поворота головы человека в трёхмерном пространстве, а именно по осям:

Roll: Этот угол измеряет вертикальный наклон головы. Он ограничивает поворот головы по оси X.
Yaw: Этот угол измеряет горизонтальный поворот головы. Он ограничивает поворот головы по оси Y.
Pitch: Этот угол измеряет боковой наклон головы. Он ограничивает поворот головы по оси Z.

Проверка Depth Liveness#

Проверка Depth Liveness определяет витальность человека на изображении с помощью карты глубины.

Этот процесс включает анализ 16-битной матрицы глубины. Она содержит подробную информацию о расстояниях до объектов сцены (например, лиц) относительно точки обзора камеры. Этот анализ помогает определить, является ли объект живым человеком или имитацией, например, фотографией или маской.

Проверка IR Liveness#

Проверка IR Liveness определяет витальность человека на изображении с помощью инфракрасного (ИК) анализа изображения. Этот процесс гарантирует, что объект — живой человек, а не имитация, например, распечатанная фотография или маска.

Примечание: Для эффективной проверки камера должна быть оснащена инфракрасной подсветкой.

Проверка LivenessOneShotRGB#

Оценка LivenessOneShotRGB определяет, является ли лицо человека настоящим или поддельным, выявляя и нейтрализуя различные типы спуфинг-атак. К таким атакам относятся:

Атака с использованием распечатанного фото: применяется одна или несколько распечатанных фотографий другого человека для обмана системы.
Атака с использованием видеоповтора: злоумышленник демонстрирует заранее записанное видео другого человека, чтобы обмануть камеру.
Атака с использованием распечатанной маски: злоумышленник вырезает изображение лица из фотографии и использует его, чтобы скрыть своё собственное лицо.
Атака с использованием 3D-маски: злоумышленник надевает 3D-маску, имитирующую лицо другого человека.

Настройки проверки#

Независимо от платформы, вы можете настроить параметры LivenessOneShotRGB в файле faceengine.conf в разделе LivenessOneShotRGBEstimator::Settings:

Параметр	Описание
`version`	Указывает версию алгоритма (`10` или `11`).
`deny2XLmode`	Включает или отключает режим `2XL` или `XL`.

Для Linux в файле rsengine.conf можно настроить следующие параметры:

Параметр	Описание
`liveness-length-osl`	Включает или отключает проверку LivenessOneShotRGB. Значение по умолчанию — `1` (включено).
`liveness-length-osl-threshold`	Задаёт пороговое значение LivenessOneShotRGB. Значение по умолчанию — `0.7`.

Для Windows в разделе реестра HKLM\Software\VisionLabs\RSEServer можно настроить следующие параметры:

Параметр	Описание
`LivenessDepthOSL`	Включает или отключает оценку LivenessOneShotRGB. Значение по умолчанию — `1` (включено).
`LivenessDepthOSLThreshold`	Задаёт пороговое значение LivenessOneShotRGB. Значение по умолчанию — `0.7`.

Проверка DepthLivenessEstimator#

DepthLivenessEstimator выполняет проверку «витальности» человека изображении. Проверка предоставляет различные пороговые параметры, позволяющие настроить ее для вашего конкретного случая использования.

Конфигурация проверки#

Независимо от платформы, вы можете настроить параметры DepthLivenessEstimator через файл faceengine.conf в разделе DepthLivenessEstimator::Settings:

Параметр	Описание	Значение по умолчанию
`maxDepthThreshold`	Максимальное расстояние по глубине (в мм) в диапазоне [0..inf].	3000
`minDepthThreshold`	Минимальное расстояние по глубине (в мм) в диапазоне [0..maxDepthThreshold].	100
`zeroDepthThreshold`	Процент нулевых пикселей в диапазоне [0..1].	0.66
`confidenceThreshold`	Пороговое значение в диапазоне [0..1], выше которого человек считается живым.	0.5

Логика фильтрации пикселей#

Пиксели со значениями глубины больше maxDepthThreshold обнуляются и исключаются из оценки.
Пиксели со значениями глубины меньше minDepthThreshold обнуляются и исключаются из оценки.
Если процент нулевых пикселей во входном изображении превышает zeroDepthThreshold, всё изображение отклоняется. В этом случае все пиксели обнуляются независимо от наличия каких-либо допустимых данных. Оценщик возвращает оценку, близкую к 0.

Компонент Мониторинг камеры#

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

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

данных о прошивке;
статуса работы инфракрасных камер – включена/выключена;
статуса работы RGB-камеры - включена/выключена;
серийного номера камеры;
статуса работы всей камеры - включена/выключена;
температуры камеры;
дата последнего обновления.

Пример содержимого реестра в разделе мониторинга представлен ниже (Рисунок 4).

Компонент RSE Server#

RSE Server представляет собой WebSocket сервер, обрабатывающий команды от внешних систем.

RSE Server принимает запросы и отправляет ответы посредством WebSocket.

Формат запроса:

Код запроса операции (1 байт)
Дополнительная полезная нагрузка (MessagePack или строка)

Пример запроса:

GET ws://127.0.0.1:4444/ – установка соединения по WebSocket.

0 - содержимое сообщения для старта сессии.

Формат ответа:

Код ответа операции (1 байт)
Дополнительная полезная нагрузка (MessagePack или строка)

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

В зависимости от необходимого типа интеграции (выбирается на усмотрение разработчика внешней системы) можно настроить RSE Server следующими способами:

RSE Server ожидает запросы на подключение к камере (представлены в Таблице 5) от внешней системы – необходимо выставить параметр cs_communication = msg-pack;
RSE Server запускает процесс получения видеопотока и процесс детекции лиц, как только установится WebSocket соединение – необходимо выставить параметр cs_communication = json.

Таблица 5. Описание запросов к RSE Server

Название запроса

Код запроса

Описание

Полезная нагрузка

Возможные ответы на запрос

RSE_START_CAPTURE

0

Запускает процесс получения видеопотока и процесс детекции лиц

Нет

RSE_CAPTURE_OK (54),

RSE_CAPTURE_META (55)

RSE_STOP

1

Останавливает все запущенные процессы

Нет

RSE_STOP_OK (50)

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

если разработчик внешней системы установил параметр cs_communication = msg-pack, то каждый ответ будет поступать в формате msg-pack и будет содержать поле messageType с кодом ответа и некоторые дополнительные поля с данными (полезные нагрузки), описанными в Таблице 6;
если разработчик внешней системы установил параметр cs_communication = json, то каждый ответ будет поступать в формате json и подразделяться на типы сообщений, описанные в Таблице 7.

Таблица 6. Ответы на запросы к RSE Server при формате ответа MessagePack

Название ответа	Код	Описание	Полезная нагрузка
RSE_CAPTURE_OK	54	Захваченный набор видеокадров	— rgbFrame – RGB кадр в формате uint8 array; — rgbFrameWidth – ширина RGB кадра в пикселях в формате int; — rgbFrameHeight – высота RGB кадра в пикселях в формате int; — irFrame – IR кадр в формате uint8 array; — depthFrame – Depth кадр в формате uint8 array
RSE_CAPTURE_META	55	Метаданные обнаруженных лиц	— gotBestshot – индикатор был ли получен bestshot, в формате bool, возвращает: true – если bestshot был получен; false – если bestshot не получен; failureReason – код статуса или ошибки liveness проверок в формате int (см. описание ошибок в "Приложении 2. Коды статусов и описание ошибок;) — bestshot – cropped bestshot, RGB-кадр в формате uint8 array: если gotBestshot=True, то в ответе приходит cropped bestshot, который прошел все проверки; если gotBestshot=False, то поле пустое; — bestshotFullFrame – полный RGB-кадр, соответствующий bestshot, в формате uint8 array: если gotBestshot = true и включен send_full_bs_on_ws, в ответе приходит полный кадр; если gotBestshot = false или отключен send_full_bs_on_ws, поле отсутствует или пустое; — detection – координаты обнаруженного лица: width – ширина рамки; height – высота рамки; x – координата левого верхнего угла рамки; y – координата левого верхнего угла рамки.
RSE_STOP_OK	50	Вся обработка остановлена. RSE Server готов к новым запросам	Полезной нагрузки нет
RSE_UNKNOWN	51	Запрос не был распознан	Полезной нагрузки нет
RSE_INTERNAL_ERROR	52	Возникла ошибка при обработке запроса	Полезной нагрузки нет
RSE_BUSY	53	Запрос отклонен, т.к. сервер занят	Полезной нагрузки нет

Таблица 7. Ответы на запросы к RSE Server при формате ответа JSON

Тип сообщения

Описание

Полезная нагрузка

visual

Тип ответа, который используется для трансляции видеопотока пользователю

— msg_type – тип возвращаемого сообщения (visual);

— img_b64 – кадр с камеры в формате base64;

— metadata – параметры возвращаемого изображения:

frame_size – размеры изображения:
h – высота изображения в пикселях;
w – ширина изображения в пикселях;
detections – координаты обнаруженного лица:
h – высота рамки обнаруженного лица;
w – ширина рамки обнаруженного лица;
x – координаты левого верхнего угла рамки обнаруженного лица;
y – координаты левого верхнего угла рамки обнаруженного лица;
progress – отображает этапы прохождения Liveness проверок обнаруженного лица (в процентах);
track_id – идентификатор трека

bestshot

Тип ответа, когда лицо успешно найдено.

Этот кадр может использоваться для последующей обработки (например, во внешней системе распознавания лиц)

— msg_type – тип возвращаемого сообщения (bestshot);

— img_b64 – cropped bestshot, лицо с кадра камеры в формате base64;

— full_frame_img_b64 – полный кадр, соответствующий bestshot, в формате base64;

— metadata – параметры возвращаемого изображения:

frame_size – размеры изображения:
h – высота изображения в пикселях;
w – ширина изображения в пикселях;
detections – координаты обнаруженного лица:
h – высота рамки обнаруженного лица;
w – ширина рамки обнаруженного лица;
x – координаты левого верхнего угла рамки обнаруженного лица;
y – координаты левого верхнего угла рамки обнаруженного лица;
progress – отображает этапы прохождения Liveness проверок обнаруженного лица (в процентах);
track_id – идентификатор трека;
full_frame_size – размеры полного кадра:
h – высота полного кадра в пикселях;
w – ширина полного кадра в пикселях;

Примечания:

Поле full_frame_img_b64 передаётся только при включённом параметре send-full-bestshot-on-ws (или аналогичном для WebSocket).
Если полный кадр недоступен, full_frame_img_b64 пуст, а full_frame_size = { "h": 0, "w": 0 }.

Компонент WebSocket Client#

WebSocket Client является внешним компонентом для взаимодействия с RSE Server.

WebSocket Client – это JavaScript-библиотека для связи с RSE Server посредством WebSocket. Используется минимизированный формат двоичной сериализации MessagePack в качестве библиотеки протоколов для кодирования и декодирования сообщений, если сервер возвращает ответы в формате MessagePack.

rs-diag-app#

rs-diag-app — это диагностическая утилита, разработанная для камер Intel RealSense, созданная на основе SDK librealsense2 и фреймворка OpenCV. Этот инструмент предоставляет комплексные возможности диагностики и проверки систем камер RealSense, позволяя быстро выявлять и устранять проблемы с конфигурацией оборудования и программного обеспечения.

Утилита предназначена для:

проверки доступных устройств и стрим-профилей;
запуска потоков RGB/IR/Depth;
автоматического выбора наиболее подходящих профилей;
логирования работы SDK и приложения;
визуальной проверки потоков.

Настройка Системы#

Данный раздел содержит общие сведения в части настройки Системы и логирования.

Система позволяет настраивать следующие параметры:

Общие параметры (подробнее см. "Приложение 1. Общие параметры конфигурации").
Параметры захвата изображений (изменяются в файле rsengine.conf);
Параметры детекции лиц (изменяются в файле rsengine.conf);
Параметры выполнения проверки IOU — проверка пересечения BBox лица на ИК- и RGB-изображении (изменяются в файле rsengine.conf).

Параметры захвата изображений, параметры детекции лиц, параметры выполнения проверки IOU являются зафиксированными по умолчанию и не предполагают изменений со стороны пользователя (администратора). Настройка данных параметров производится только правообладателем (ООО «ВижнЛабс»).

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

Настройка Системы на ОС Windows#

Система настраивается через реестр Windows.

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

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


\*\* HKEY\_LOCAL\_MACHINE \ SOFTWARE \ VisionLabs \ RSEServer \*\*

Параметры конфигурации описаны в Таблице 8 и Таблице 9.

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

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

Настройка Системы на ОС Ubuntu 24.04 x64 и Debian 10 x64#

Система настраивается посредством изменения данных в клиентских файлах конфигурации в поставке (server.conf и rsengine.conf).

Для применения настроек клиентской конфигурации необходимо внести изменения в файлах server.conf и rsengine.conf (Таблица 8, Таблица 9) и перезапустить RSE Server.

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

Логирование#

RSE Server включает в себя надежный механизм журналирования, который собирает рабочие и диагностические данные для мониторинга, отладки и обслуживания. Журналы хранятся как в консоли, так и в файлах журналов.

Доступны следующие файлы журналов:

Файл	Описание
server.log	Хранит журналы RSE Server в Windows.
stdout.log	Содержит все сообщения, кроме сообщений об ошибках, включая информационные, отладочные и другие некритические журналы.
stderr.log	Содержит только сообщения об ошибках.

Комбинация stdout.log и stderr.log отражает содержимое файла server.log, но разделяет стандартные сообщения и сообщения об ошибках для упрощения анализа и устранения неполадок.

Файлы stdout.log и stderr.log становятся доступны, если параметр log-level установлен в 3.

Примечание: До версии 2.2.0 параметр verboseLogging в файле faceengine.conf регулировал уровень детализации журнала. Начиная с версии 2.2.0, параметр verboseLogging устарел. Вместо этого можно настроить уровни ведения журнала с помощью параметра log-level. См. Приложение 1. Общие параметры конфигурации.

Переключение типа камеры#

Тип камеры настраивается с помощью параметра ProcessorStrategy, который записывается в реестр Windows следующим образом:


ProcessorStrategy (REG_SZ) = IntelRealSense | VLSLunaCamera3D | VLSLunaCamera2D

Быстрый старт: команда запуска#

Чтобы настроить и запустить службу с определенным типом камеры, выполните одну из следующих команд из каталога скрипта:


:: Intel RealSense (по умолчанию)
installService.bat ProcessorStrategy=IntelRealSense

:: VL SLuna 3D
installService.bat ProcessorStrategy=VLSLunaCamera3D

:: VL SLuna 2D
installService.bat ProcessorStrategy=VLSLunaCamera2D

Вы также можете запустить скрипт без параметров — он будет использовать стратегию по умолчанию:


installService.bat

В таком случае будет использован параметр по умолчанию: ProcessorStrategy=IntelRealSense.

Изменение камеры по умолчанию#

Чтобы изменить тип камеры по умолчанию:

Откройте в текстовом редакторе скрипт installService.bat.
Найдите строчку вида set ProcessorStrategy=IntelRealSense.
Замените IntelRealSense на предпочитаемую камеру по умолчанию:
- IntelRealSense
- VLSLunaCamera3D
- VLSLunaCamera2D

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


installService.bat ProcessorStrategy=VLSLunaCamera2D quietReg=false

По умолчанию quietReg имеет значение true. Если это поведение необходимо изменить, то нужно внести правки в строчку под номером 10 (set quietReg=true).

Различия в конфигурации#

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

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

Эти ключи записываются независимо от типа камеры, если включена функция ROI (область интереса):

Всегда (общие ROI, если включены по стратегии):


RoiEnable (REG_DWORD) 1
RoiX (REG_DWORD) 160
RoiY (REG_DWORD) 0
RoiWidth (REG_DWORD) 320
RoiHeight (REG_DWORD) 480

Настройки, специфичные для IntelRealSense#

Дополнительные ключи для камер Intel RealSense:


IRStreamDarknessCheck (REG_DWORD) 0
LivenessDepthOSL (REG_DWORD) 1
LivenessDepthOSLThreshold (REG_DWORD) 70
RgbIrMatch (REG_DWORD) 0
RgbIRMatchThreshold (REG_DWORD) 120
RGBCoordinatesTransfer (REG_DWORD) 1
IOULivenessThreshold (REG_DWORD) 50

Настройки, специфичные для VLSLunaCamera3D#

Применяются только общие настройки ROI; дополнительные ключи не прописываются.

Настройки, специфичные для VLSLunaCamera2D#

Один дополнительный ключ:


FrameRotation (REG_DWORD) 0

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

В LUNA KIOSK вы можете отправлять лучшие кадры во внешнюю систему с помощью HTTP POST-запросов.

Важно: Включение HTTP-отправки не заменяет отправку через WebSocket. При активации лучшие кадры отправляются одновременно по обоим каналам.

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

Каждый лучший кадр отправляется отдельным HTTP POST запросом.

Параметры конфигурации#

server.conf#

Следующие параметры файла server.conf отвечают за отправку лучшего кадра по протоколу HTTP:

Parameter	Default	Description
`send-bestshot-on-http`	0	Включает или выключает отправку лучшего кадра по HTTP. Возможные значения: 0 - Отключено 1 - Включено
`http-bestshot-path`	http://localhost:8080	Указывает HTTP-эндпоинт, на который следует отправить лучший кадр.

Windows Registry#

Для Windows, следующие параметры отвечают за отправку лучшего кадра по протоколу HTTP:

Parameter	Type	Default	Description
`SendBestShotOnHttp`	DWORD	0	Включает или выключает отправку лучшего кадра по HTTP. Возможные значения: 0 - Отключено 1 - Включено
`HttpBestShotPath`	DWORD	http://localhost:8080	Указывает HTTP-эндпоинт, на который следует отправить лучший кадр.

Формат изображения#

Формат отправляемого изображения задаётся параметром BestshotFormat или bestshot-format. Возможные значения:

jpg (по умолчанию);
png

Перед сериализацией изображение приводится к формату R8G8B8 (24 bpp), после чего кодируется в выбранный формат (JPEG или PNG).

HTTP POST запрос#

Заголовки запроса#

Content-Type: image/jpeg
Content-Type: image/png

Тип заголовка определяется параметром BestshotFormat.

Тело запроса#

Тело HTTP запроса содержит сырые бинарные данные изображения.

То есть POST запрос имеет следующий вид:


POST /endpoint HTTP/1.1
Content-Type: image/jpeg
Content-Length: <size>

<binary image data>

HTTP ответ#

Запрос считается успешным, если код состояния HTTP-ответа находится в диапазоне 200-299.
Если сервер возвращает другой код, отправка считается неуспешной и в лог выводится предупреждение. Ответ сервера может быть выведен в лог при включённом уровне debug.

Валидация URL#

Перед отправкой выполняется проверка корректности URL по следующим критериям:

структура URL корректна;
URL содержит схему;
URL использует схему http.

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

Таймауты#

Для HTTP запроса установлен таймаут 30 секунд. Также включена автоматическая обработка HTTP redirect.

Пример сервера для тестирования#

Ниже приведён пример простого HTTP сервера на Python, который принимает POST запросы с изображением и сохраняет их в файл.


from http.server import BaseHTTPRequestHandler, HTTPServer
import sys


class Handler(BaseHTTPRequestHandler):

def do_POST(self):
length = int(self.headers['Content-Length'])
body = self.rfile.read(length)

recvFile = "received.png" if self.headers["Content-Type"] == "image/png" else "received.jpg"

with open(recvFile, "wb") as f:
f.write(body)

self.send_response(200)
self.end_headers()
self.wfile.write(b"OK")


port = int(sys.argv[1]) if len(sys.argv) > 1 else 8080

server = HTTPServer(("0.0.0.0", port), Handler)

print(f"Listening on {port}")
server.serve_forever()

Запуск:


python http_receiver.py 8080

После запуска сервер будет принимать лучшие кадры и сохранять их в файлы received.jpg или received.png.

Проверка работы#

Start the test HTTP server.
Enable HTTP best shot delivery. Set send-bestshot-on-http = 1 and http-bestshot-path = http://localhost:8080.
After generating the best shot, the server will send the image via a POST request.
Check the server’s directory – a file named received.jpg or received.png should appear.
Запустите тестовый HTTP сервер.
Включите отправку лучшего кадра по HTTP. Установите send-bestshot-on-http = 1 и http-bestshot-path = http://localhost:8080.
После формирования лучшего кадра сервер отправит изображение POST запросом.
Проверьте каталог сервера. Должен появиться файл received.jpg или received.png.

Отправка обрезанных и полных лучших кадров#

Когда для обоих типов лучших кадров включена отправка по HTTP, LUNA KIOSK автоматически отправляет два отдельных POST-запроса на один и тот же URL.

Порядок запросов:

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

В первый запрос добавляется заголовок X-Bestshot-Type со значением crop, а во второй – full.

Пересчет параметров ROI при повороте кадра#

В конфигурациях, где активирована функция ROI (область интереса) и одновременно может выполняться поворот входного кадра, необходимо корректно пересчитывать координаты и размеры ROI в соответствии с углом поворота. Игнорирование этого правила приведёт к тому, что область интереса «съедет» с нужной части изображения и алгоритмы обработки будут работать не с тем фрагментом сцены.

Пример для базового кадра размером 640×480:

Угол поворота	Параметры ROI
0	x=160 y=0 w=320 h=480
90	x=0 y=160 w=480 h=320
180	x=160 y=0 w=320 h=480
270	x=0 y=160 w=480 h=320

Примечание: Если вы задаете собственную произвольную ROI-зону, ее параметры также подлежат обязательному пересчёту при каждом изменении угла поворота кадра.

Приложение 1. Общие параметры конфигурации#

Общие параметры изменяются в реестре (для Windows) файлах server.conf и rsengine.conf. Параметры конфигурации реестра Windows представлены ниже.

server.conf#

Файл server.conf содержит общие параметры конфигурации:

Наименование параметра	Тип данных	Знач. по умолч.	Описание
`data-path`	`string`	`./data.`	Путь к каталогу данных RSE Server. Не рекомендуется изменять значение параметра.
`rsengine-conf-path`	`string`	`./client/rsengine.conf`	Путь к config-файлу библиотеки RSEngine. Актуален для настройки Системы на ОС Ubuntu 24.04 x64, Debian 10 x64, Armbian 23 и ОС Windows, использующей файлы конфигурации
`cs-communication`	`string`	`msg-pack`	Тип взаимодействия сервера с клиентом. Зависит от выбранной конфигурации Системы. Может принимать следующие значения: `json`: возвращаемый сервером тип данных – JSON; `msg-pack`: возвращаемый сервером тип данных – MessagePack
`bestshot-format`	`string`	`jpg`	Возвращаемый формат изображения лучших кадров. Выбирается исходя из требований внешнего ПО. Может принимать следующие значения: `jpg`: Формат JPEG; `png`: Формат PNG
`save-bestshot-ondisk`	`int`	`0`	Сохранение лучших кадров на диск в директорию `save-bestshot-path/SaveBestshotPath`. `0` – не сохранять; `1` – сохранять.
`save-bestshot-path`	`string`	`./bestshots`	Директория сохранения лучших кадров при активации переменной `save-bestshot-ondisk/SaveBestshotonDisk`.
`encrypt-bestshot`	`int`	`0`	Шифрование лучших кадров при их сохранении. Не используется в этой версии Системы. `0` – не шифровать; `1` – шифровать.
`server-host`	`string`	`127.0.0.1`	IP адрес сервера на котором следует запуститься чтобы принимать вебсокет соединения. При использовании одной копии необходимо указывать localhost, при использовании нескольких запущенных копий – указывать главный сервер.
`server-port`	`int`	`4444`	Порт, на котором RSE Server принимает соединения
`log-level`	`int, [0, 3]`	`1`	Уровень логирования фильтрует сообщения журнала и имеет следующие уровни от 0 до 3: `0` – отключение логирования; `1` – логирование информации о работе; `2` – логирование предупреждений и информации о работе; `3` – логирование ошибок, предупреждений и информации о работе.
`log-path`	`string`	`./logs`	Путь к доступному для записи каталогу для хранения журналов сервера
`log-file-rotation`	`int`	`0`	Посуточная ротация логов `0` – отключено; `1` – включено.
`save-full-bestshot-on-disk`	`int`	`0`	Сохранение полных лучших кадров на диск в директорию `save-bestshot-path/SaveBestshotPath`. `0` – не сохранять; `1` – сохранять. Примечание: Параметр работает независимо от `save-bestshot-ondisk`.
`send-full-bestshot-on-http`	`int`	`0`	Отправляет полный лучший кадр на указанный HTTP URL. `0` – не отправлять; `1` – отправлять. Примечание: Параметр работает независимо от `save-bestshot-ondisk`.
`send-full-bestshot-on-ws`	`int`	`0`	Опциональный. Отправляет полный лучший кадр через WebSocket. `0` – не отправлять; `1` – отправлять. Примечание: Обрезанный лучший кадр отправляется всегда.

rsengine.conf#

В файле rsengine.conf уникальные настройки для каждой камеры разнесены по блокам.

Раздел common#

Наименование параметра	Тип данных	Знач. по умолч.	Описание
`processor-strategy`	`string`	`IntelRealSense`	Режим работы Системы с камерами. `IntelRealSense` – работа с камерами Intel RealSense; `VLSLunaCamera3D` – работа с камерами VLS LUNA CAMERA 3D; `VLSLunaCamera2D` – работа с камерами VLS LUNA CAMERA 2D.
`camera-monitoring`	`int`	`1`	Параметр включает/выключает мониторинг состояния камеры. `0` – выключает мониторинг; `1` – включает мониторинг
`camera-monitoring-delay`	`int`	`300`	Параметр устанавливает в секундах частоту опроса состояния камеры у службы мониторинга
`camera-reset-onfail`	`int`	`0`	Параметр позволяет выполнить сброс камеры при неудачном запуске сессии. `0`– отключено; `1`– включено.
`camera-poll-frames-timeout`	`int`	`4000`	Таймаут (в миллисекундах) для получения кадров камерой.
`continuous-bestshots`	`int`	`0`	Продолжать получать лучшие кадры в сессии, даже если лучший кадр уже был получен. `0` – отключено; `1` – включено.
`autoexp-rgb`	`int`	`1`	Включение режима авто экспозиции для RGB изображения. Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`autoexp-ir`	`int`	`1`	Включение режима авто экспозиции для IR изображения.Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`rgb-face-detection-threshold`	`float`	`0.8`	Минимальный порог оценки качества изображения перед проверкой Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`suspicious-threshold`	`float`	`0.6`	Минимальный порог оценки качества изображения, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`margin`	`int`	`10`	Минимальный отступ между Bbox лица и границами кадра в пикселях. Лицо должно находиться в минимум 10 пикселях от границы кадра при проведении проверки Liveness, чтобы не была потеряна информация о лице. 10…100 пикселей.
`check-eyes`	`int`	`1`	Использование информации о положении и статусе глаз при проверке Liveness. `0` – отключено; `1` – включено.
`check-mouth`	`int`	`0`	Использование информации о статусе рта при проверке Liveness. `0` – отключено; `1` – включено.
`liveness-depth`	`int`	`1`	Использование информации об объемности лица на изображении при проверке Liveness. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`light-threshold`	`float`	`0.9`	Минимальный порог оценки качества освещенности лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`dark-threshold`	`float`	`0.93`	Минимальный порог оценки качества затемненности лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`blur-threshold`	`float`	`0.94`	Минимальный порог оценки качества размытости лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`yaw-threshold`	`int`	`15`	Максимальный угол наклона головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`pitch-threshold`	`int`	`15`	Максимальный угол вращения головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`roll-threshold`	`int`	`10`	Максимальный угол поворота головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`roi-enable`	`int`	`1`	Обрезка исходного кадра для уменьшения зоны интереса для повышения качества распознавания. Преднастроенные ниже параметры ограничивают центральную часть кадра, где лицо искажено меньше всего. Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`roi-x`	`int`	`160`	Горизонтальная координата левого верхнего угла зоны интереса. Задается от верхнего левого угла кадра. Не рекомендуется изменять данный параметр.
`roi-y`	`int`	`0`	Вертикальная координата левого верхнего угла зоны интереса. Задается от верхнего левого угла кадра. Не рекомендуется изменять данный параметр.
`roi-width`	`int`	`320`	Ширина зоны интереса. Не рекомендуется изменять данный параметр.
`roi-height`	`int`	`480`	Высота зоны интереса. Не рекомендуется изменять данный параметр.

Раздел IntelRealSense#

Наименование параметра	Тип данных	Знач. по умолч.	Описание
`liveness-ir`	`int`	`1`	Проверка IR Liveness. `0` – отключено; `1` – включено
`frame-rotation`	`int`	`0`	Угол поворота видеокадра камеры. Возможные значения: `0`, `90`, `180`, `270`. Расположение камеры в зависимости от угла поворота видеокадра см. на схеме ниже (Рисунок 5)
`ir-stream-darkness-check`	`int`	`0`	Проверка недостатка освещения изображения на IR изображении.
`liveness-depth-osl`	`int`	`1`	Проверка LivenessOneShotRGB. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`liveness-depth-osl-threshold`	`float`	`0.7`	Минимальный порог значения Liveness при проверки лица. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows), где: `0` – проверка не проводится `0.1` – высокая вероятность пропуска фейка `1` – малая вероятность пропуска фейка, высокая вероятность пропуска реального человека
`rgb-ir-match`	`int`	`0`	Использование данных с RGB и IR камер для проведения проверок. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`rgb-ir-match-threshold`	`float`	`1.2`	Порог сравнения лица с IR и RGB изображений. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`rgb-coordinates-transfer`	`int`	`1`	Передача координат Bbox лица с RGB изображения в IR изображения для последующей обработки. `0` – отключено; `1` – включено.
`iou-liveness-threshold`	`float`	`0.5`	Пороговое значения для использования IOU при построении Bbox. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).

Раздел VLSLunaCamera3D#

Наименование параметра	Тип данных	Знач. по умолч.	Описание
`liveness-ir`	`int`	`1`	Проверка IR Liveness. `0` – отключено; `1` – включено
`frame-rotation`	`int`	`0`	Угол поворота видеокадра камеры. Возможные значения: `0`, `90`, `180`, `270`. Расположение камеры в зависимости от угла поворота видеокадра см. на схеме ниже (Рисунок 5)
`ir-stream-darkness-check`	`int`	`0`	Проверка недостатка освещения изображения на IR изображении.
`liveness-depth-osl`	`int`	`1`	Проверка LivenessOneShotRGB. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`liveness-depth-osl-threshold`	`float`	`0.7`	Минимальный порог значения Liveness при проверки лица. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows), где: `0` – проверка не проводится `0.1` – высокая вероятность пропуска фейка `1` – малая вероятность пропуска фейка, высокая вероятность пропуска реального человека
`rgb-ir-match`	`int`	`0`	Использование данных с RGB и IR камер для проведения проверок. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`rgb-ir-match-threshold`	`float`	`1.2`	Порог сравнения лица с IR и RGB изображений. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).

Раздел VLSLunaCamera2D#

Наименование параметра

Тип данных

Знач. по умолч.

Описание

liveness-ir

int

1

Проверка IR Liveness.

0 – отключено;
1 – включено

frame-rotation

int

0

Угол поворота видеокадра камеры.

Возможные значения: 0, 90, 180, 270. Расположение камеры в зависимости от угла поворота видеокадра см. на схеме ниже (Рисунок 5)

Параметры конфигурации реестра Windows#

Наименование параметра	Тип данных	Знач. по умолч.	Описание
`DataPath`	`REG_SZ`	`{Path to system` `files}/data`	Путь к каталогу данных RSE Server. Не рекомендуется изменять значение параметра.
`CSCommunication`	`REG_SZ`	`msg-pack`	Тип взаимодействия сервера с клиентом. Зависит от выбранной конфигурации Системы. Может принимать следующие значения: `json`: возвращаемый сервером тип данных – JSON; `msg-pack`: возвращаемый сервером тип данных – MessagePack
`BestshotFormat`	`REG_SZ`	`jpg`	Возвращаемый формат изображения лучших кадров. Выбирается исходя из требований внешнего ПО. Может принимать следующие значения: `jpg`: Формат JPEG; `png`: Формат PNG
`SaveBest` `shotonDisk`	`REG_DWORD`	`0`	Сохранение лучших кадров на диск в директорию `save-bestshot-path/SaveBestshotPath`. `0` – не сохранять; `1` – сохранять.
`save-bestshot-path`	`string`	`./bestshots`	Директория сохранения лучших кадров при активации переменной `save-bestshot-ondisk/SaveBestshotonDisk`.
`EncryptBestshot`	`REG_DWORD`	`0`	Шифрование лучших кадров при их сохранении. Не используется в этой версии Системы. `0` – не шифровать; `1` – шифровать.
`ServerHost`	`REG_SZ`	`127.0.0.1`	Адрес сервера на котором развернут RSE Server. При использовании одной копии необходимо указывать localhost, при Использовании нескольких запущенных копий – указывать главный сервер.
`ServerPort`	`REG_DWORD`	`4444`	Порт, на котором RSE Server принимает соединения
`LogLevel`	`REG_DWORD`	`1`	Уровень логирования фильтрует сообщения журнала и имеет следующие уровни от 0 до 3: `0` – отключение логирования; `1` – логирование информации о работе; `2` – логирование предупреждений и информации о работе; `3` – логирование ошибок, предупреждений и информации о работе.
`LogPath`	`REG_SZ`	`C:\RSE\logs`	Путь к доступному для записи каталогу для хранения журналов сервера
`Processor` `Strategy`	`REG_SZ`	`IntelRealSense`	Режим работы Системы с камерами `IntelRealSense` – работа с камерами Intel RealSense; `VLSLunaCamera3D` – работа с камерами VLS LUNA CAMERA 3D; `VLSLunaCamera2D` – работа с камерами VLS LUNA CAMERA 2D.
`Camera` `Monitoring`	`REG_DWORD`	`1`	Параметр включает/выключает мониторинг состояния камеры. `0` – выключает мониторинг; `1` – включает мониторинг.
`Camera` `MonitoringDelay`	`REG_DWORD`	`300`	Параметр устанавливает в секундах частоту опроса состояния камеры у службы мониторинга
`RgbIrMatch`	`REG_DWORD`	`0`	Использование данных с RGB и IR камер для проведения проверок. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`CheckEyes`	`REG_DWORD`	`1`	Использование информации о положении статусе глаз при проверке Liveness. `0` – отключено; `1` – включено.
`CheckMouth`	`REG_DWORD`	`0`	Использование информации о статусе рта при проверке Liveness. `0` – отключено; `1` – включено.
`LivenessDepth`	`REG_DWORD`	`1`	Использование информации об объемности лица на изображении при проверке Liveness. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`LivenessDepthOSL`	`REG_DWORD`	`1`	Проверка LivenessOneShotRGB. Не рекомендуется изменять данный параметр. `0` – отключено; `1` – включено.
`LivenessDepth` `OSLThreshold`	`REG_DWORD`	`0.7`	Минимальный порог значения Liveness при проверки лица. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows), где: `0` – проверка не проводится `0.1` – высокая вероятность пропуска фейка `1` – малая вероятность пропуска фейка, высокая вероятность пропуска реального человека
`RGBCoordinates` `Transfer`	`REG_DWORD`	`1`	Передача координат Bbox лица с RGB изображения в IR изображения для последующей обработки. `0` – отключено; `1` – включено.
`IOULiveness` `Threshold`	`REG_DWORD`	`50`	Пороговое значения для использования IoU при построении Bbox. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`Quality` `Threshold`	`REG_DWORD`	`80`	Минимальный порог оценки качества изображения перед проверкой Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`RgbIRMatch` `Threshold`	`REG_DWORD`	`120`	Порог сравнения лица с IR и RGB изображений. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`Margin`	`REG_DWORD`	`20`	Минимальный отступ между Bbox лица и границами кадра в пикселях. Лицо должно находиться в минимум 10 пикселях от граница кадра при проведении проверки Liveness, чтобы не была потеряна информация о лице. 10…100 пикселей.
`Suspicious` `Threshold`	`REG_DWORD`	`60`	Минимальный порог оценки качества изображения, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`LightThreshold`	`REG_DWORD`	`90`	Минимальный порог оценки качества освещенности лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`DarkThreshold`	`REG_DWORD`	`93`	Минимальный порог оценки качества затемненности лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`BlurThreshold`	`REG_DWORD`	`94`	Минимальный порог оценки качества размытости лица на изображении, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению. Порог задается в диапазоне от 0.0 до 1.0 (0…100 для Windows).
`YawThreshold`	`REG_DWORD`	`15`	Максимальный угол наклона головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`PitchThreshold`	`REG_DWORD`	`15`	Максимальный угол вращения головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`RollThreshold`	`REG_DWORD`	`10`	Максимальный угол поворота головы относительно оси камеры, при котором будет произведена проверка Liveness. Параметр подбирается аналитически разработчиками и не рекомендуется к изменению.
`AutoexpRGB`	`REG_DWORD`	`1`	Включение режима авто экспозиции для RGB изображения. Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`AutoexpIR`	`REG_DWORD`	`1`	Включение режима авто экспозиции для IR изображения. Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`IRStream` `DarknessCheck`	`REG_DWORD`	`0`	Проверка недостатка освещения изображения на IR изображении.
`RoiEnable`	`REG_DWORD`	`1`	Использование обрезки исходного кадра для уменьшения зоны интереса для повышения качества распознавания. Преднастроенные ниже параметры ограничивают центральную часть кадра, где лицо искажено меньше всего. Не рекомендуется отключать эту настройку. `0` – отключено; `1` – включено.
`RoiX`	`REG_DWORD`	`160`	Горизонтальная координата левого верхнего угла зоны интереса. Задается от верхнего левого угла кадра. Не рекомендуется изменять данный параметр.
`RoiY`	`REG_DWORD`	`0`	Вертикальная координата левого верхнего угла зоны интереса. Задается от верхнего левого угла кадра. Не рекомендуется изменять данный параметр.
`RoiWidth`	`REG_DWORD`	`320`	Ширина зоны интереса. Не рекомендуется изменять данный параметр.
`RoiHeight`	`REG_DWORD`	`480`	Высота зоны интереса. Не рекомендуется изменять данный параметр.
`LogFileRotation`	`REG_DWORD`	`0`	Посуточная ротация логов `0` – отключено; `1` – включено.
`Continuous` `Bestshots`	`REG_DWORD	`0`	Продолжать получать бестшоты в сессии, даже если бестшот уже был получен `0` – отключено; `1` – включено.
`FrameRotation`	`int`	`0`	Угол поворота видеокадра камеры. Возможные значения: `0`, `90`, `180`, `270`. Расположение камеры в зависимости от угла поворота видеокадра см. на схеме ниже (Рисунок 5) Примечание: При настройке параметра всегда используйте десятичный формат, чтобы избежать неправильной интерпретации системой.
`LivenessIr`	`int`	`1`	Проверка IR Liveness. `0` – отключено; `1` – включено
`SaveFullBestShotOnDisk`	`REG_DWORD`	`0`	Сохраняет полный лучший кадр на диск в директорию `save-bestshot-path/SaveBestshotPath`. `0`– не сохранять; `1`– сохранять. Примечание: Параметр работает независимо от `SaveBestshotonDisk`.
`SaveFullBestShotOnHttp`	`REG_DWORD`	`0`	Отправляет полный лучший кадр на указанный HTTP URL. `0`– не отправлять; `1`– отправлять. Примечание: Параметр работает независимо от `SaveBestshotonDisk`.
`SaveFullBestShotOnWs`	`REG_DWORD`	`0`	Опциональный. Отправляет полный лучший кадр через WebSocket. `0`– не отправлять; `1`– отправлять. Примечание: Обрезанный лучший кадр отправляется всегда.

Расположение камеры VLS LUNA CAMERA 2D в зависимости от угла поворота видеокадра

Приложение 2. Коды статусов и описание ошибок#

Коды статусов и описание ошибок failureReason в полезных нагрузках ответа RSE_CAPTURE_META при выполнении проверки Liveness приведены в Таблице 11.

Коды общие для ответов msg-pack и JSON.

Таблица 11. Коды статусов и описание ошибок failureReason в ответе RSE_CAPTURE_META

Код статуса	Описание
0	Ошибок нет, кадр прошел проверки
1	Некорректный RGB-кадр
2	Некорректный Depth-кадр
3	Некорректный ИК-кадр
4	Лицо не обнаружено
5	Лицо не обнаружено (лицо в кадре слишком маленькое)
6	Обнаруженное лицо не проходит по одному из параметров конфигурации
7	Невозможно оценить лицо в кадре по 5 точкам
10	Лицо в кадре обрезано
11	Лицо повернуто — слишком короткое расстояние между глазами
12	Liveness проверка глаз не пройдена
13	Не удалось нормализовать RGB-кадр
14	Не удалось нормализовать Depth-кадр
15	Не удалось нормализовать ИК-кадр
16	Некорректное положение головы
17	Глаза закрыты
18	Необходима нейтральная мимика мышц рта
19	Liveness проверка Depth-кадра не пройдена
20	Liveness проверка ИК-кадра не пройдена
21	Низкое качество кадра
22	RGB-кадр слишком яркий
23	RGB-кадр слишком темный
25	Изображение размыто
26	Проверка LivenessOneShotRGB не пройдена
28	Идет Liveness проверка сравнение RGB- и ИК-кадра
29	Liveness проверка ИК-кадра без подсветки
31	Ошибка распознавания лица в кадре
32	Не удалось обнаружить лицо на ИК-кадре
33	Низкое качество Depth-кадра
34	Обнаружено несколько лиц с пересекающимися зонами BBox