Глоссарий#

Введение#

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

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

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

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

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

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

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

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

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

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

Система оптимизирована и протестирована для надежной работы со следующими 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 мм.
  

  
  

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

Для стабильной работы подключайте все поддерживаемые камеры через 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 не поддерживаются:

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

Высокоуровневая схема архитектуры Системы представлена ниже (Рисунок 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. Описание диаграммы взаимодействия компонентов Системы при выборе лучшего кадра

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

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

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

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

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

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

Компонент 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:

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

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

Проверка DepthLivenessEstimator#

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

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

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

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

• Пиксели со значениями глубины больше 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

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

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

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

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

Компонент 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 \*\*

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

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

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

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

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

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

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

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

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

Комбинация 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:

Windows Registry#

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

Работа с RTPS-сервером#

RTSP-сервер позволяет получать цветное изображение с подключённой камеры в виде сетевого видеопотока. Одновременно могут быть доступны два потока:

• HD — поток исходного или повышенного разрешения;
• SD — поток разрешением 640×480.

RTSP-сервер работает независимо от основного канала обработки кадров. Включение трансляции не изменяет формат данных, передаваемых в основной алгоритм обработки.

Общий принцип работы#

RTSP-сервер запускается вместе с RSEngine, если он включён в конфигурации. Фактическое создание видеопотоков выполняется после получения первого корректного цветного кадра от камеры.

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

• доступного разрешения;
• возможности создания HD-потока;
• необходимости включения SD-потока;
• формата выходного изображения;
• доступного аппаратного H.264 энкодера;
• фактической частоты кадров камеры.

Кодирование начинается только после подключения RTSP-клиента. Если клиентов нет, RSEngine не выполняет лишнее преобразование и кодирование изображений.

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

RTSP-трансляция поддерживается для:

• Intel RealSense D415;
• Intel RealSense D435;
• Orbbec Gemini E;
• Orbbec Gemini UW.

Примечание: Для других камер RTSP может быть недоступен. При этом основная функциональность камеры и RSEngine продолжает работать штатно.

Особенности Orbbec Gemini UW#

Orbbec Gemini UW работает с более низкой частотой кадров, чем остальные поддерживаемые камеры.

В RTSP-режиме ожидается:

• цветной поток до 1280×960;
• фактическая частота около 10 FPS;
• отсутствие дополнительного ограничения по target-fps, если входной поток уже работает не на 30 FPS.

Это штатное поведение и не является ошибкой RTSP-сервера.

Ориентация изображения#

RTSP получает изображение с учётом настроенного поворота камеры.

Если в конфигурации задан поворот на 90°, 180° или 270°, в RTSP передаётся уже повернутое изображение.

После поворота разрешение может поменять ориентацию. Например, изображение 1280×960 при повороте на 90° становится 960×1280.

Подключение к RTSP#

При локальном запуске:

rtsp://127.0.0.1:8554/HD
rtsp://127.0.0.1:8554/SD

При подключении с другого компьютера:

rtsp://<IP-адрес-компьютера>:8554/HD
rtsp://<IP-адрес-компьютера>:8554/SD

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

FFplay#

Рекомендуемый вариант проверки:

ffplay -rtsp_transport tcp \
  -fflags nobuffer \
  -flags low_delay \
  rtsp://127.0.0.1:8554/HD

Для SD:

ffplay -rtsp_transport tcp \
  -fflags nobuffer \
  -flags low_delay \
  rtsp://127.0.0.1:8554/SD

GStreamer#

gst-launch-1.0 \
  rtspsrc location=rtsp://127.0.0.1:8554/HD protocols=tcp latency=0 \
  ! decodebin \
  ! videoconvert \
  ! autovideosink

VLC#

Не все сборки VLC содержат полноценный RTSP-клиент. В частности, некоторые дистрибутивные сборки VLC могут быть собраны без live555.

Если поток работает через FFplay, но не открывается через VLC, необходимо проверить состав конкретной сборки VLC. Такая ситуация не обязательно означает ошибку RTSP-сервера или H.264-потока.

Ленивый запуск и клиенты#

RTSP-сервер использует несколько уровней отложенной инициализации:

1. RTSP включается через конфигурацию.
2. Параметры потоков определяются после первого корректного кадра.
3. Кодирование начинается после подключения клиента.
4. При отключении всех клиентов неиспользуемое кодирование останавливается.
5. При новом подключении передача возобновляется автоматически.

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

Поведение при переподключении#

Поддерживаются:

• повторные подключения клиента;
• одновременное подключение к HD и SD;
• несколько последовательных подключений;
• отключение клиента без остановки RSEngine;
• новое подключение после длительного отсутствия клиентов.

При закрытии клиента RTSP-сервер освобождает связанный с ним медиаконтекст. Камера и основной конвейер RSEngine продолжают работать.

Конфигурация#

Настройки находятся в секции <section name="rtsp_server"> конфигурационного файла.

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

<section name="rtsp_server">
    <param name="enable" type="Value::Int1" x="1" />

    <param name="enable-hd" type="Value::Int1" x="1" />
    <param name="enable-sd" type="Value::Int1" x="1" />

    <param name="target-fps" type="Value::Int1" x="30" />
    <param name="use-16x9" type="Value::Int1" x="0" />

    <param name="codec" type="Value::String" text="H264" />
    <param name="backend" type="Value::String" text="AUTO" />

    <param name="hd-mount-point" type="Value::String" text="HD" />
    <param name="sd-mount-point" type="Value::String" text="SD" />

    <param name="allow-mjpeg-fallback" type="Value::Int1" x="1" />

    <param name="mjpeg-quality" type="Value::Int1" x="85" />
    <param name="hd-bitrate-kbps" type="Value::Int1" x="4000" />
    <param name="sd-bitrate-kbps" type="Value::Int1" x="1000" />

    <param name="bind-address" type="Value::String" text="0.0.0.0" />
    <param name="port" type="Value::Int1" x="8554" />
</section>

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

enable#

Включает или выключает RTSP-сервер.

Допустимые значения:

• 0 - По умолчанию. RTSP-сервер выключен.
• 1 - RTSP-сервер включён.

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

enable-hd#

Включает или выключает HD endpoint.

Допустимые значения:

• 0 - HD-поток выключен.
• 1 - HD-поток включён.

Ожидаемое разрешение:

• 1280×960 при выключенном формате 16:9;
• 1280×720 при включённом формате 16:9.

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

enable-sd#

Включает или выключает SD endpoint.

Допустимые значения:

• 0 - SD-поток выключен.
• 1 - SD-поток включён.

Разрешение SD-потока: 640×480.

HD и SD разрешается включать одновременно. Хотя бы один из потоков должен быть включён.

Автоматическое переключение на SD#

Если HD-поток включён, но камера фактически предоставляет цветной кадр только 640×480, сформировать полноценный HD-поток невозможно.

В такой ситуации RSEngine:

1. Записывает предупреждение в лог.
2. Отключает недоступный HD-поток.
3. Активирует SD-поток, даже если enable-sd изначально был выключен.

Это позволяет сохранить доступность трансляции при переходе камеры на резервный профиль.

target-fps#

Задаёт требуемую частоту RTSP-потока.

Допустимые значения: 1, 2, 5, 10, 15, 30.

Если камера предоставляет 30 кадров в секунду, RSEngine отбирает кадры следующим образом:

Если камера фактически работает с частотой, отличной от 30 FPS, дополнительное ограничение отключается. RTSP-сервер передаёт кадры с фактической частотой камеры.

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

use-16x9#

Переключает формат HD-потока между 4:3 и 16:9.

При включении 16:9 изображение не растягивается. Из исходного изображения выполняется центральное кадрирование: одинаковые области удаляются сверху и снизу.

Параметр не изменяет SD-поток — он остаётся 640×480.

codec#

Задаёт формат кодирования видео.

Допустимые значения:

Рекомендуемое значение: H264.

H.264 обычно обеспечивает меньший сетевой трафик при сопоставимом качестве. MJPEG предъявляет меньше требований к аппаратному видеокодированию, но обычно требует большей пропускной способности сети.

backend#

Определяет backend аппаратного кодирования H.264.

Допустимые значения:

Рекомендуемое значение: AUTO

Доступность backend зависит от:

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

VAAPI предназначен для Linux. MF предназначен для Windows.

При выборе MJPEG параметр аппаратного H.264 backend не используется.

Автоматический выбор backend#

В режиме AUTO RSEngine последовательно проверяет доступные аппаратные энкодеры и выбирает первый, который способен запустить рабочий H.264-конвейер.

Общий приоритет:

• для Linux: QSV → VAAPI
• для Windows: QSV → MF

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

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

allow-mjpeg-fallback#

Разрешает автоматический переход с H.264 на MJPEG, если ни один подходящий аппаратный H.264 энкодер не удалось запустить.

Fallback применяется только при запросе H.264. Если codec изначально равен MJPEG, этот параметр не влияет на работу.

Факт перехода на MJPEG записывается в лог.

mjpeg-quality#

Задаёт качество JPEG для MJPEG-потока.

Допустимый диапазон: 0–100

Рекомендуемое значение: 85

Чем выше значение:

• тем выше визуальное качество;
• тем больше размер каждого кадра;
• тем выше нагрузка на сеть.

Параметр применяется при явном выборе MJPEG и при автоматическом переходе с H.264 на MJPEG.

hd-bitrate-kbps#

Задаёт целевой битрейт HD-потока H.264 в килобитах в секунду.

Например, 4000 приблизительно соответствует 4 Мбит/с.

Значение должно быть положительным.

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

sd-bitrate-kbps#

Задаёт целевой битрейт SD-потока H.264 в килобитах в секунду.

Рекомендуемое значение: 1000, что приблизительно соответствует 1 Мбит/с.

Значение должно быть положительным.

Параметры битрейта не применяются к MJPEG.

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

hd-mount-point#

Задаёт имя HD endpoint.

Пример:

<param name="hd-mount-point" type="Value::String" text="HD" />

Результирующий адрес:

rtsp://<адрес-сервера>:8554/HD

sd-mount-point#

Задаёт имя SD endpoint.

Пример:

<param name="sd-mount-point" type="Value::String" text="SD" />

Результирующий адрес:

rtsp://<адрес-сервера>:8554/SD

Имена HD и SD должны различаться.

Шаблоны в именах endpoint#

В hd-mount-point и sd-mount-point можно использовать шаблоны:

Например:

<param
    name="hd-mount-point"
    type="Value::String"
    text="${codec}_${stream}" />

При выборе H.264 результирующий endpoint может иметь имя h264_HD.

Если H.264 недоступен и выполнен переход на MJPEG- mjpeg_HD.

Если шаблоны не используются, имя остаётся неизменным.

Клиент должен подключаться к результирующему имени endpoint. Оно записывается в лог при запуске RTSP-сервера.

bind-address#

Задаёт сетевой адрес, на котором RTSP-сервер принимает подключения.

Для приёма подключений через все сетевые интерфейсы:

0.0.0.0

Для доступа только с локального компьютера:

127.0.0.1

Чтобы клиенты с других компьютеров могли подключиться к серверу, необходимо использовать 0.0.0.0 либо конкретный адрес сетевого интерфейса.

Этот параметр задаёт адрес прослушивания. В RTSP URL клиента вместо 0.0.0.0 необходимо указывать реальный IP-адрес компьютера с RSEngine.

Например:

rtsp://192.168.1.50:8554/HD

port#

Задаёт TCP-порт RTSP-сервера.

Значение по умолчанию: 8554.

Порт должен:

• находиться в диапазоне 1–65535;
• не использоваться другим процессом;
• быть разрешён локальным firewall;
• быть доступен клиенту по сети.

Разрешения потоков

Фактическая доступность HD зависит от камеры и успешного запуска соответствующего цветного профиля.

Типовые сценарии настройки#

Универсальная рекомендуемая конфигурация#

• RTSP включён;
• HD и SD включены;
• H.264;
• backend AUTO;
• MJPEG fallback разрешён;
• 30 FPS;
• HD bitrate 4000 Kbit/s;
• SD bitrate 1000 Kbit/s;
• порт 8554;
• bind address 0.0.0.0.

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

Только локальный просмотр#

Установить:

bind-address = 127.0.0.1

В этом случае подключение с другого компьютера невозможно.

Минимальная нагрузка на сеть#

Рекомендуется:

• включить только SD;
• установить target-fps в 5 или 10;
• использовать H.264;
• уменьшить SD bitrate.

Максимальное качество#

Рекомендуется:

• включить HD;
• использовать 1280×960;
• установить target-fps=30;
• использовать H.264;
• увеличить HD bitrate при достаточной пропускной способности сети.

Работа без аппаратного H.264 encoder#

Рекомендуется:

• оставить codec=H264;
• установить backend=AUTO;
• включить allow-mjpeg-fallback.

Если аппаратное кодирование недоступно, сервер автоматически перейдёт на MJPEG.

Логирование работы#

При включении RTSP в общем логе RSEngine отражаются основные этапы работы.

Запуск#

В логе указываются:

• версия RSEngine;
• факт включения RTSP;
• адрес прослушивания;
• порт;
• включённые HD и SD;
• требуемый кодек;
• требуемый бэкенд;
• целевой FPS.

Первый кадр#

После первого корректного кадра фиксируются:

• входное разрешение;
• формат кадра;
• фактический режим камеры;
• активные выходные потоки;
• разрешения HD и SD;
• используемый FPS.

Выбор энкодера#

Для H.264 в логе отображаются:

• проверяемый бэкенд;
• проверяемый энкодер;
• причина отклонения неподходящего энкодера;
• успешно выбранный энкодер;
• переход к следующему кандидату;
• переход на MJPEG, если fallback разрешён.

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

Адреса потоков#

После успешной настройки в логе должны появиться итоговые RTSP эндпоинты, например:

rtsp://0.0.0.0:8554/HD
rtsp://0.0.0.0:8554/SD

Для подключения с другого устройства 0.0.0.0 необходимо заменить реальным IP-адресом сервера.

Диагностика проблем#

Connection refused#

Сообщение Connection refused означает, что по указанному адресу и порту никто не принимает соединение.

Необходимо проверить:

• enable=1;
• процесс RSEngine запущен;
• камера успешно запущена;
• получен первый корректный кадр;
• порт совпадает с конфигурацией;
• сервер не был выключен после ошибки;
• порт не занят другим процессом;
• firewall разрешает соединение.

Эндпоинт не найден#

Проверить:

• включён ли требуемый поток;
• итоговое имя эндпоинта в логе;
• не изменилось ли имя из-за шаблона <codec>;
• не произошёл ли переход с HD на SD;
• учитывается ли регистр символов.

H.264 недоступен#

Проверить:

• выбранный бэкенд;
• наличие совместимого GPU;
• видеодрайвер;
• сообщения проверки энкодера в логе;
• разрешён ли MJPEG fallback.

Поток работает локально, но недоступен по сети#

Проверить:

• bind-address;
• IP-адрес сервера;
• порт firewall;
• маршрутизацию между клиентом и сервером;
• использование реального IP вместо 127.0.0.1;
• использование реального IP вместо 0.0.0.0.

Низкий FPS#

Необходимо учитывать фактический профиль камеры. Если камера работает не на 30 FPS, RTSP использует её реальную частоту и не применяет дополнительное ограничение.

Для Orbbec Gemini UW частота около 10 FPS является ожидаемой.

Большая задержка#

Рекомендуется:

• использовать RTSP over TCP;
• уменьшить клиентский network buffer;
• использовать low-latency режим клиента;
• проверить загрузку аппаратного encoder;
• проверить сеть;
• уменьшить разрешение или битрейт;
• использовать SD-поток.

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

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

server.conf#

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

rsengine.conf#

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

Раздел common#

Раздел IntelRealSense#

Раздел VLSLunaCamera3D#

Раздел VLSLunaCamera2D#

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

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

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

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

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