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

# Глоссарий

Термин | Определение
--- | ---
Лучший кадр, 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`.

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

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

1. Откройте в текстовом редакторе скрипт installService.bat.
2. Найдите строчку вида `set ProcessorStrategy=IntelRealSense`.
3. Замените `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.

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

1. Start the test HTTP server.
2. Enable HTTP best shot delivery. Set `send-bestshot-on-http = 1` and `http-bestshot-path = http://localhost:8080`.
3. After generating the best shot, the server will send the image via a POST request.

4. Check the server’s directory – a file named received.jpg or received.png should appear.

5. Запустите тестовый HTTP сервер.

6. Включите отправку лучшего кадра по HTTP. Установите `send-bestshot-on-http = 1` и `http-bestshot-path = http://localhost:8080`.
7. После формирования лучшего кадра сервер отправит изображение POST запросом.
8. Проверьте каталог сервера. Должен появиться файл received.jpg или received.png.

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

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

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

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

В первый запрос добавляется заголовок `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