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

# Глоссарий

Термин | Определение
--- | ---
Bestshot | Кадр видеопотока, на котором лицо зафиксировано в оптимальном ракурсе для дальнейшего использования в системе распознавания лиц
Liveness | Программный способ подтверждения витальности (живучести, жизненности) человека по одному или нескольким изображениям с целью предотвращения спуфинг-атак
Детекция | Действия по нахождению областей изображения, содержащих лица
Спуфинг-атака | Тип атаки, основанной на фальсификации передаваемых данных, в частности подмена живого человека на поддельное изображение (например, фотографию) с целью обмана системы

# Введение

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

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

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

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

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

## Минимальные системные требования для архитектуры 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-го поколения

# Лицензирование

Чтобы получить лицензию, обратитесь к представителю VisionLabs. В ответе будут указаны необходимые параметры активации лицензии.

> Примечание: Вы можете использовать одни и те же данные для активации лицензии на всех поддерживаемых платформах, включая Windows, Ubuntu, Debian и Armbian. Процесс активации лицензии см. в разделе Установка.

## Получение fingerprint устройства

Получите уникальный аппаратный идентификатор, необходимый для генерации лицензии:

    $ ./RSE-server.exe --get_hardware_id

Пример вывода:

    The device fingerprint is
    <fingerprnt>

## Обновление онлайн-лицензии

1. Поместите новый файл license.conf в каталог лицензий.
2. Выполните команду:

    $ ./RSE-server.exe --update_licence

LUNA KIOSK автоматически удалит все предыдущие артефакты лицензии, активирует новую конфигурацию, сохранит активированные артефакты лицензии и завершит работу.

> Примечание: Если срок действия кешированной лицензии Zeus истек, кеш автоматически удаляется, после чего LUNA KIOSK инициирует повторную активацию.

## Обновление офлайн-лицензии

Замените файлы лицензии и перезапустите сервис:

    scp new_license.conf user@device:/opt/rse/licenses/license.conf
    scp new_license.dat user@device:/opt/rse/licenses/license.dat

## Смена типа лицензии

Вы можете выбрать тип лицензии, FIT или Zeus, который будет использоваться системой, изменив параметр `licenseModel`.

Для этого присвойте одно из следующих значений параметру `licenseModel` в файле data/license.conf:

- `1` для использования лицензии FIT.
- `2` для использования лицензии Zeus.

После настройки сохраните файл и перезапустите сервис для инициализации нового типа лицензии.

# Установка

LUNA KIOSK поставляется в двух конфигурациях, отличающихся способом хранения настроек:

- На Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23: Используются файлы конфигурации server.conf и rsengine.conf, расположенные в папке /client.
- server.conf - содержит настройки работы сервера и логирования.
- rsengine.conf - определяет пороговые значения для проверок Liveness.
- На Windows: Настройки для RSE Server и библиотеки RSEngine по умолчанию сохраняются в реестре Windows после установки.

> Примечание: По умолчанию файлы конфигурации в поставке под ОС Windows в папке /client отсутствуют, так как рекомендуется использование конфигурации на основе реестра. Запросите файлы конфигурации в VisionLabs, если вы используете их в качестве способа настройки.

## Установка на Windows

RSE Server устанавливается как сервис Windows.

### Необходимые компоненты

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

Компонент | Описание | Ссылка
--- | --- | ---
Visual C++ Redistributable | Библиотеки времени выполнения для C++-приложений. Требуется последняя версия. | vc_redist.x64.exe
Драйвер Orbbec Sensor | Пакет драйверов для корректной работы с глубинными камерами Orbbec. | SensorDriver_V4.3.0.22.exe

### Шаг 1: Активация лицензии

Перед установкой настройте лицензию, отредактировав файл data/license.conf значениями, указанными в вашем лицензионном письме от VisionLabs.

В таблице ниже описаны параметры, необходимые для активации лицензии:

Параметр | Описание | Пример
--- | --- | ---
`Server` | URL сервера активации, используемого для проверки и активации лицензии. | https://
`EID` | Идентификатор права доступа. | 00000000-0000-0000-0000-0000-0000-000000000000
`ProductID` | Идентификатор продукта. | 00000000-0000-0000-0000-0000-0000-000000000000
`LICENSE_FILENAME` | Имя файла лицензии. Непубличный параметр, не изменяйте. | license.dat
`LICENSE_CONTAINERMODE` | Режим запуска лицензии: `0` - запуск в контейнере `1` - локально (рекомендуется) | `1`

### Шаг 2: Подготовка к установке LUNA KIOSK

1․ Запустите InstallService.bat от имени администратора из корневой директории дистрибутивного пакета.

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

- проверка прав администратора;
- создание и обновление службы RSEngine Server (`RSE-server.exe svc`);
- установка зависимости (VC++ Redistributable), если файл установщика находится в том же каталоге;
- создание папки для хранения логов;
- запись настроек в реестр по пути HKLM\Software\VisionLabs\RSEServer;
- запуск службы RSEngine Server.

2․ Во время установки:

- Сервис регистрируется в реестре Windows.
- Директория для логов создаётся по умолчанию в C:\RSE\logs.
  Уровни логирования можно изменить позже в реестре Windows.

### Шаг 3: Конфигурирование системы

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

### Шаг 4: Управление системой

После завершения установки можно управлять RSE Sever с помощью менеджера служб `services.msc`.

> Важно: Не меняйте расположение RSE Server и файлов *.conf после установки. В противном случае работоспособность системы будет нарушена.

### Отложенный запуск сервиса

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

Для этого используйте параметр `StartService` скрипта установки installService.bat. Параметр имеет следующие значения:

Значение | Описание
--- | ---
`true` | По умолчанию. Сервис будет запущен автоматически после установки.
`false` | Сервис будет установлен, но его запуск будет пропущен.

### Устранение проблем с выборкой метаданных для сенсоров камеры RealSense

ОС Windows требует наличия специальной записи в реестре для каждого уникального видеоустройства, чтобы предоставлять метаданные. Метаданные, или атрибуты метаданных, относятся к дополнительной информации, предоставляемой библиотекой `librealsense`, и необходимы для правильного взаимодействия с сенсорами камеры RealSense.

Для активации функционала, связанного с атрибутами метаданных, в комплект поставки LUNA KIOSK включён файл realsense_metadata_win10.ps1. Скрипт в файле создает и изменяет записи в реестре Windows для обеспечения корректной работы сенсоров камеры RealSense. Более подробная информация по активации метаданных представлена в документации библиотеки librealsense.

## Установка на ОС Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23

### Предварительные требования

Используйте Ansible для автоматизации установки на системах на базе Linux:

1․ Установите Ansible:

    apt-get install ansible

2․ Проверьте установку:

    ansible --version

Если установка прошла успешно, в консоли будет отображена версия Ansible и друга информация:

      ansible [core 2.12.4]
        config file = /etc/ansible/ansible.cfg
        configured module search path = ['/home/vivek/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
        ansible python module location = /usr/lib/python3/dist-packages/ansible
        ansible collection location = /home/vivek/.ansible/collections:/usr/share/ansible/collections
        executable location = /usr/bin/ansible
        python version = 3.8.10 (default, Mar 15 2022, 12:22:08) [GCC 9.4.0]
        jinja version = 2.10.1
        libyaml = True

### Шаг 1: Предварительные действия и активация лицензии

Перед запуском установки:

1․ Добавьте адреса (`ip` or `hostname`) целевых устройств в файл ansible/hosts для установки дистрибутива. Каждая строка содержит один адрес. Например:

    [rse]
    12.16.58.33

2․ Настройте общие переменные и данные лицензии в файле group_vars/all.yml:

> Note: `LICENSE_SERVER`, `LICENSE_EID`, `LICENSE_PRODUCTID` are responsible for licensing and provided by VisionLabs.

Переменная | Описание | Возможные значения
--- | --- | ---
`RSE_HOME` | Директория установки. Непубличное значение, не изменяйте. | /var/lib/kiosk
`RSE_VERSION` | Версия системы. Значение должно совпадать с именем архива. | ub1804_x64_v1.0.4_rc2
`RSE_ZIP_LOCATION` | Абсолютный или относительный путь к дистрибутиву RSE Server внутри пакета дистрибутива. | ../distr/rse-server_v.2.5.0.zip
`LICENSE_SERVER` | Адрес сервера лицензий. Запросите данные в VisionLabs. | https://.com
`LICENSE_EID` | Идентификатор права доступа. Запросите данные в VisionLabs. | 00000000-0000-0000-0000-0000-000000000000
`LICENSE_PRODUCTID` | Идентификатор продукта. Запросите данные в VisionLabs. | 00000000-0000-0000-0000-0000-0000-000000000000
`LICENSE_FILENAME` | Имя файла лицензии. Непубличный параметр, не изменяйте. | license.dat
`LICENSE_CONTAINERMODE` | Режим запуска лицензии. | `0` - запуск в контейнере `1` - локальный (рекомендуется)
`licenseModel` | Используемая лицензия. Запросите данные в VisionLabs. | `1` - Система использует лицензию FIT. `2` - Система использует лицензию Zeus.

### Шаг 2: Установка LUNA KIOSK

Место установки системы указывается в переменной `RSE_HOME`.

Перейдите в папку ansible и выполните:

- Для удаленных хостов:

Если установка выполняется на нескольких устройствах одновременно (в файле hosts указано более одного IP-адреса), выполните команду:

    ansible-playbook -I hosts install_rse.yml

Во время установки Ansible пытается подключиться как системный пользователь (по умолчанию root) с помощью соответствующей пары SHH-ключей. Если вместо ключей используется пароль, добавьте флаг `--ask-pass` в команду установки.

- Для локальной установки:

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

    ansible-playbook -i hosts--connection=local--inventory 127.0.0.1, install_rse.yml

### Шаг 3: Настройка LUNA KIOSK

При запуске RSE Server, LUNA KIOSK использует настройки из файлов конфигурации server.conf и rsengine.conf. Описание параметров см. в Приложении 1.

Если вам нужно изменить настройки конфигурации клиента, внесите изменения в файлы server.conf и rsengine.conf и перезапустите RSE Server.

Если установка прошла успешно, логи будут записываться в файлы журналов в директории по умолчанию ./logs после запуска LUNA KIOSK. Чтобы изменить местоположение, обновите параметр `log-path` в файле server.conf.

### Шаг 4: Управление LUNA KIOSK в Linux

После завершения установки можно управлять RSE Sever с помощью утилиты командной строки `systemctl`.

Для запуска RSE Sever необходимо запустить следующую команду:

    systemctl start kiosk

Для остановки RSE Sever необходимо запустить следующую команду:

    systemctl stop kiosk

## Установка на Astra Linux

Процесс установки LUNA KIOSK на Astra Linux аналогичен установке на Ubuntu/Debian и выполняется через Ansible с использованием тех же скриптов и переменных. Подробная информация приведена в разделе Установка на ОС Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23.

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

#### Для всех камер

Для корректной работы Orbbec камер на всех Linux-платформах (Ubuntu/Debian 10/Astra Linux SE) необходимо выполнить скрипт настройки правил udev:

- install_udev_rules.sh

#### RealSense на Astra Linux

На Astra Linux для камер Intel RealSense доступны два режима работы:

Режим | Когда использовать
--- | ---
L4V2 | Если в ядре ОС доступен и загружен модуль uvcvideo с поддержкой расширенных метаданных.
UVC | Если L4V2 недоступен, не загружен или вызывает конфликты в вашей конфигурации безопасности.

Независимо от выбранного режима (L4V2 или UVC), для камер RealSense обязательно выполните специализированный скрипт настройки:

- setup_udev_rules.sh

## Активация лицензии в офлайн-режиме

Используйте оффлайн-активацию, когда целевое устройство не имеет доступа к интернету. В этом сценарии:

- отпечаток устройства генерируется на оффлайн-устройстве;
- лицензия активируется на устройстве с доступом в интернет с использованием этого отпечатка.

### Предварительные требования

Перед началом получите адрес сервера лицензий и EID у VisionLabs

### Шаг 1: Генерация отпечатка устройства

На оффлайн-устройстве, где будет установлена лицензия:

1․ Откройте файл license.conf, расположенный в директории data. 2․ Укажите `EID` и сохраните файл. 3․ Запустите утилиту `FingerprintViewer` для генерации отпечатка:
- На Linux/Armbian:
1․ Перейдите в папку extras.

    2․ Предоставьте права доступа утилите FingerprintViewer:

      ```bash
        chmod +x FingerprintViewer
      ```

    3․ Запустите утилиту, указав путь к файлу *license.conf*:

      ```bash
      ./FingerprintViewer ../data/license.conf
      ```

- На Windows:

  Запустите FingerprintViewer.exe из корневой папки дистрибутивного пакета.

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

### Шаг 2: Активация лицензии

На устройстве с доступом в интернет:

1. Перейдите на портал активации лицензий (URL, полученный от VisionLabs).
2. Войдите в систему, используя свой EID.
3. Вставьте скопированный отпечаток устройства для активации лицензии.
4. Скачайте сгенерированный лицензионный сертификат (licenseFile.v2c).
5. Переместите licenseFile.v2c в папку data.
6. Переименуйте файл одним из следующих способов:
7. Измените параметр `Filename` в файле license.conf в соответствии с примером:

       <param name="Filename" type="Value::String" text="licenseFile.v2c"/>

8. Переименуйте licenseFile.v2c в license.dat и убедитесь, что параметр `Filename` в файле license.conf соответствует фактическому имени:

       <param name="Filename" type="Value::String" text="license.dat"/>

Шаг 3: Развертывание лицензии

Скопируйте полученный лицензионный ключ license.dat в каталог data.

# Удаление

## Удаление на ОС Windows

Для удаления RSE Server и логов на ОС Windows необходимо запустить пакетный файл `uninstallService.bat`, который находится в корневой папке поставки.

Пакетный файл `uninstallService.bat`:

- удаляет все параметры из реестра;
- останавливает и удаляет службу RSE Server.

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

## Удаление на ОС Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23

Удаление RSE Server и логов на ОС Ubuntu 24.04 x64, Debian 10 x64 и Armbian 23 осуществляется администратором вручную, исполняемый пакетный файл в поставке отсутствует. Для этого требуется:

1. Удалить данные из директории `RSE_HOME`;

2. Удалить файл `systemd service` из директории `/etc/systemd/system/kiosk.service`.