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

LUNA PASS API#

Общий принцип работы LUNA PASS API следующий:

  • на вход приходит кадр;
  • LUNA SDK оценивает и проверяет кадр;
  • последовательно выполняются плагины, если они включены:
  • плагин FaceMatcher;
  • плагин VirtualCameraChecker;
  • плагин Bestshot;
  • плагин Luna3DescriptorQualityCheck;
  • плагин AggregateLiveness;
  • плагин ActiveLiveness;
  • анализируется полученный результат работы плагинов.

Процесс оценки кадра#

Процесс оценки кадра — последовательное выполнение проверок. Описание проверок представлено ниже (Таблица 4).

Таблица 4. Проверки для оценки кадра

Проверка

Описание

Multiface

— является ли лицо:

  • единственным в кадре;

  • самым крупным (главным) в кадре;

  • ближайшим к центру

Качество изображения

  • размытость;

  • засвеченность;

  • затемненность;

  • наличие бликов на лице;

  • контрастность

Размер и позиция лица в кадре

— отступ границы лица от границы кадра:

  • сверху;

  • снизу;

  • справа;

  • слева;

— размер кадра:

  • по ширине;

  • по высоте;

— размер лица в кадре:

  • по ширине;

  • по высоте

Положение головы

  • угол наклона головы вправо/влево (roll);

  • угол наклона головы вверх/вниз (pitch);

  • угол поворота головы вправо/влево (yaw)

Состояние глаз

  • глаза открыты;

  • глаза закрыты

Статус рта

  • рот открыт;

  • обнаружена улыбка;

  • рот перекрыт

Наличие очков

  • очки отсутствуют;

  • очки присутствуют;

  • солнцезащитные очки

AGS, общая метрика качества изображения

\—

Liveness

  • оценка Liveness;

  • оценка качества Liveness

Deepfake
  • оценка Deepfake с заданной точностью

Если кадр не прошел одну из проверок, тогда анализируется следующий кадр. Пользователь при этом видит соответствующие подсказки на странице с LUNA PASS UI.

Принцип работы плагина FaceMatcher#

Плагин FaceMatcher включается в файле config.toml. Для этого в параметрах конфигурации LIVENESS необходимо установить параметр disallowMultipleFacesInSession = 1. Позволяет обрывать сессию, если на двух кадрах в рамках одной сессии обнаружены несколько основных лиц.

Описание общего принципа работы плагина FaceMatcher:

Если пришел только первый кадр, Facematcher запоминает фотографию лица. Если пришел второй кадр, Facematcher сравнивает фотографию лица с пришедшего кадра с фотографией лица предыдущего кадра:

  • если на фотографиях с двух кадров разные лица, то дальнейшие проверки не проводятся;

  • если на фотографиях с двух кадров лица одинаковые, то кадр отправляется для дальнейших проверок

Описание работы плагина VirtualCameraChecker#

Плагин VirtualCameraChecker включается в файле config.toml. Позволяет обнаруживать использование пользователем виртуальной камеры вместо реальной камеры устройства. Данные об обнаружении виртуальной камеры фиксируются в логах.

Принцип работы плагина Bestshot#

Плагин Bestshot включается в файле config.toml. Позволяет выбрать в качестве bestshot кадр с наибольшей оценкой Liveness, путем сравнения оценки Liveness со значениями на предыдущих кадрах. Для bestshot не может быть выбран кадр, на котором оба глаза закрыты, за исключением случаев, когда разрешено использование солнцезащитных очков.

Принцип работы плагина Bestshot представлен на схеме (Рисунок 5). Описание общего принципа работы плагина представлено ниже (Таблица 6).

Принцип работы плагина Bestshot
Рисунок 5. Принцип работы плагина Bestshot

Таблица 6. Описание общего принципа работы плагина Bestshot

Шаг

Описание

(1)

Выполняется проверка значения Liveness текущего кадра: liveness_score >= LIVENESS_SCORE_THRESHOLD

Если проверка текущего кадра на Liveness не пройдена, то процесс прекращается, текущий кадр далее не используется.

Если проверка текущего кадра на Liveness пройдена, то переход к следующему шагу

(2)

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

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

Если текущий кадр — первый кадр, прошедший порог качества Liveness, то он автоматически становится лучшим кадром

(3)

Если значение Liveness текущего кадра выше, чем у существующего лучшего кадра, выбранного данным плагином, то текущий кадр становится лучшим кадром

Принцип работы плагина Luna3DescriptorQualityCheck#

Плагин Luna3DescriptorQualityCheck включается в файле config.toml. Позволяет отправлять запрос к LUNA PLATFORM 3 на извлечение дескриптора и проверку его качества.

Плагин Luna3DescriptorQualityCheck работает только с LUNA PLATFORM версии 3.х.

Плагин позволяет снизить количество ошибок фильтрации по качеству дескриптора на стороне LUNA PLATFORM 3.

Принцип работы плагина Luna3DescriptorQualityCheck представлен на схеме (Рисунок 6). Описание общего принципа работы плагина представлено ниже (Таблица 7).

Принцип работы плагина Luna3DescriptorQualityCheck
Рисунок 6. Принцип работы плагина Luna3DescriptorQualityCheck

Таблица 7. Описание общего принципа работы плагина Luna3DescriptorQualityCheck

Шаг

Описание

(1)

Выполняется проверка включен ли плагин Bestshot.

Если плагин Bestshot включен, то переход к шагу 6

Если плагин Bestshot выключен:

(2)

Если плагин Bestshot выключен, то выполняется проверка качества Liveness текущего кадра: liveness_quality_score >= LIVENESS_QUALITY_SCORE_THRESHOLD

Если проверка текущего кадра на качество Liveness не пройдена, то процесс прекращается, текущий кадр далее не используется

(3)

Если проверка текущего кадра на качество Liveness пройдена, то выполняется проверка значения Liveness: сравнение значений Liveness текущего кадра и существующего лучшего кадра в данном плагине.

Если у текущего кадра Liveness меньше, чем Liveness у лучшего кадра данного плагина, то процесс прекращается, текущий кадр далее не используется.

Если текущий кадр — первый кадр, прошедший проверку качества Liveness (в текущем плагине или плагине Bestshot), то он становится лучший кадром

(4)

Если у текущего кадра Liveness больше, чем Liveness у лучшего кадра данного плагина, то выполняется запрос в LUNA PLATFORM 3 на извлечение дескриптора из текущего кадра и проверку качества его дескриптора.

Если валидация в LUNA PLATFORM 3 не пройдена (качество дескриптора оказалось недостаточным), то процесс прекращается, текущий кадр далее не используется

(5)

Если валидация в LUNA PLATFORM 3 пройдена (качество дескриптора в норме), то текущий кадр становится лучшим кадром в данном плагине

Если плагин Bestshot включен:

(6)

Выполняется проверка, выбран ли лучший кадр в плагине Bestshot.

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

(7)

Если лучший кадр в плагине Bestshot выбран, то сравнивается его значение Liveness со значением Liveness лучшего кадра данного плагина

(8)

Если Liveness лучшего кадра из Bestshot ниже, то лучший кадр из данного плагина становится лучшим в плагине Bestshot

(9)

Если Liveness лучшего кадра из Bestshot выше, то этот кадр отправляется в LUNA PLATFORM 3 на извлечение дескриптора и проверку качества его дескриптора. Если лучший кадр из Bestshot не прошел валидацию в LUNA PLATFORM 3 (качество дескриптора оказалось недостаточным), то лучший кадр из данного плагина становится лучшим в плагине Bestshot

(10)

Если лучший кадр из Bestshot прошел валидацию в LUNA PLATFORM 3 (качество дескриптора в норме), то лучший кадр из Bestshot становится лучшим в данном плагине

Принцип работы плагина AggregateLiveness#

Плагин AggregateLiveness включается в файле config.toml. Позволяет рассчитывать агрегированное значение Liveness по нескольким кадрам.

Принцип работы плагина AggregateLiveness представлен на схеме (Рисунок 7). Описание общего принципа работы плагина представлено ниже (Таблица 8).

Принцип работы плагина AggregateLiveness
Рисунок 7. Принцип работы плагина AggregateLiveness

Таблица 8. Описание общего принципа работы плагина AggregateLiveness

Шаг

Описание

(1)

Выполняется проверка качества Liveness текущего кадра: liveness_quality_score >= LIVENESS_QUALITY_SCORE_THRESHOLD

Если проверка текущего кадра на качество Liveness не пройдена, то процесс прекращается, текущий кадр далее не используется.

Если проверка текущего кадра на качество Liveness пройдена, то выполняется переход к следующему шагу

(2)

Плагин сохраняет значения качества liveness_score1 по кадрам в рамках сессии, количество таких значений ограничено переменной AGGREGATE_LIVENESS_FRAMES_COUNT.

(3)

Плагин формирует агрегированное значение Liveness из значений, сохраненных на шаге 2

Принцип работы плагина ActiveLiveness#

Плагин ActiveLiveness включается в файле config.toml. Позволяет подтвердить витальность человека по нескольким кадрам, на которых пользователь взаимодействует с Сервисом: моргает, поворачивает голову влево-вправо по оси Y, наклоняет голову вверх-вниз по оси X. Описание общего принципа работы плагина представлено ниже (Таблица 9).

Таблица 9. Описание общего принципа работы плагина ActiveLiveness

Шаг

Описание

(1)

Выбирается произвольный набор проверок, количество которых задаётся в настройках.

(2)

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

(3)

Если проверка текущего кадра на Liveness пройдена, то пропускается один или несколько кадров, чтобы фото с полуоткрытыми глазами или в процессе поворачивания головы не засчитывались. За количество пропускаемых кадров отвечает параметр cooldownFramesCount.

Полученный кадр становится Bestshot.

Проверки ActiveLiveness#

Моргание

Проверка начинается в момент, когда открыты оба глаза, либо открыт один глаз и включен параметр args.acceptOneEyed. Для того, чтобы проверка считалась пройденной далее должны прийти два кадра: с закрытыми глазами и снова с открытыми, либо, при включенном параметре args.acceptOneEyed, — кадр с одним закрытым глазом и кадр с открытым.

Повороты головы

Для начала проверки угол поворота головы должен быть меньше значения args.yawStartDeg. Далее должны прийти два кадра: со значением угла поворота больше args.yawThresholdDeg и со значением угла повороты меньше args.yawStartDeg.

Запрокидывание головы

Для начала проверки угол запрокидывания головы должен быть меньше значения args.pitchStartDeg. Далее должны прийти два кадра: со значением угла поворота больше args.pitchThresholdDeg и со значением угла повороты меньше args.pitchStartDeg.

Подробнее о значениях углов поворота и углов запрокидывания см. в параметрах конфигурации плагина ActiveLiveness

Обработка результатов#

Общий принцип работы LUNA PASS API представлен на схеме (Рисунок 8). Описание общего принципа работы представлено ниже (Таблица 10).

Общий принцип работы LUNA PASS API
Рисунок 8. Общий принцип работы LUNA PASS API

Таблица 10. Описание общего принципа работы LUNA PASS API

Шаг

Описание

(0)

В LUNA PASS API поступает кадр

(1)

LUNA PASS API выполняет оценку кадра с помощью LUNA SDK и сравнивает полученные значения с пороговыми. Подробнее см. "Проверки при процессе оценки кадра"

(2)

Если включен плагин FaceMatcher, то выполняется обработка в соответствии с процессом описанным в общем принципе работы плагина

(3)

Если включен плагин VirtualCameraChecker, то выполняется проверка на использование пользователем виртуальной камеры вместо реальной камеры устройства

(4)

Если включен плагин Bestshot, то выполняется обработка в соответствии с процессом описанным в общем принципе работы плагина

(5)

Если включен плагин Luna3DescriptorQualityCheck, то выполняется обработка в соответствии с процессом описанным в общем принципе работы плагина

(6)

Если включен плагин AggregateLiveness, то выполняется обработка в соответствии с процессом описанным в общем принципе работы плагина

(7)

Если включен плагин ActiveLiveness, то выполняется обработка в соответствии с процессом описанным в общем принципе работы плагина

(8)

После выполнения действий в указанных плагинах LUNA PASS API обрабатывает полученные результаты.

LUNA PASS API проверяет, является ли поступивший кадр первым. В зависимости от результатов данной проверки выполняются шаги:

  • Если поступивший кадр не первый, то выполняется переход к шагу 9

  • Если поступил только первый кадр, то выполняется переход к шагу 11

(9)

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

  • Если лица не совпадают, то выполняется переход к шагу 10

  • Если лица на двух кадрах совпадают, то выполняется переход к шагу 11

(10)

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

(11)

LUNA PASS API проверяет является ли камера реальной. В зависимости от результатов данной проверки выполняются шаги:

  • Если камера виртуальная, то выполняется переход к шагу 12

  • Если камера реальная, то выполняется переход к шагу 13

(12)

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

(13)

LUNA PASS API проверяет количество кадров, дошедших до проверки Liveness больше или равно значению LIVENESS_MAX_ATTEMPS

В зависимости от данной проверки дальнейший анализ делится на две части:

  1. Проверка включения плагинов и отправка результата.

  2. Проверка включения плагинов и попытки получить дополнительные кадры для обработки

Если на шаге 13 количество кадров, дошедших до проверки Liveness, меньше допустимого, выполняются следующие шаги:

(14)

LUNA PASS API проверяет включен ли плагин AggregateLiveness

Если плагин включен, то выполняется переход к следующему шагу

Если плагин выключен, то выполняется переход к шагу 15

(15)

LUNA PASS API проверяет заполнено ли окно агрегации: количество полученных значений Liveness больше или равно значению AGGREGATE_LIVENESS_FRAMES_COUNT

Если окно агрегации не заполнено, то выполняется переход к шагу 39. Если окно агрегации заполнено, то выполняется переход к следующему шагу

(16)

LUNA PASS API проверяет значение полученного агрегированного Liveness: агрегированный Liveness больше или равен значения LIVENESS_SCORE_THRESHOLD

Если значение полученного агрегированного Liveness ниже порога, то выполняется переход к шагу 39

Если значение полученного агрегированного Liveness выше или равен порогу, то выполняется переход к следующему шагу

(17)

LUNA PASS API проверяет результат плагина Bestshot.

Если в плагине Bestshot не удалось выбрать успешный кадр, то выполняется переход к шагу 39

(18)

Если в плагине Bestshot удалось выбрать успешный кадр, то LUNA PASS API проверяет включен ли плагин ActiveLiveness

(19)

Если плагин ActiveLiveness включен, то выполняется проверка результата работы плагина ActiveLiveness. Сессия продолжается до прохождения кадром активного Liveness

(20)

Когда проверка результата работы плагина ActiveLiveness пройдена, то LUNA PASS API отправляет кадр в LUNA PASS UI как успешный

(21)

Если плагин ActiveLiveness выключен LUNA PASS API отправляет кадр в LUNA PASS UI как успешный

(22)

LUNA PASS API проверяет включен ли плагин Luna3DescriptorQualityCheck.

Если плагин включен, то выполняется переход к следующему шагу

Если плагин выключен, то выполняется переход к шагу 25

(23)

LUNA PASS API выполняет проверку результата плагина Luna3DescriptorQualityCheck.

Если по результатам работы плагина Luna3DescriptorQualityCheck не удалось выбрать успешный кадр, то выполняется обработка следующего кадра (переход к шагу 1)

(24)

Если по результатам работы плагина Luna3DescriptorQualityCheck удалось выбрать успешный кадр, прошедший проверку качества дескриптора, то LUNA PASS API отправляет в LUNA PASS UI именно этот кадр как успешный

(25)

LUNA PASS API проверяет включен ли плагин Bestshot. Если плагин включен, то выполняется переход к шагу 17

(26)

Если плагин выключен, то LUNA PASS API отправляет в LUNA PASS UI первый кадр, прошедший все проверки

Если на шаге 13 количество кадров, дошедших до проверки Liveness, больше или равно допустимому, выполняются следующие шаги:

(27)

LUNA PASS API проверяет включен ли плагин Luna3DescriptorQualityCheck

Если плагин включен, то выполняется проверка наличия лучшего кадра в данном плагине (следующий шаг)

Если плагин выключен, то выполняется переход к шагу 31

(28)

Выполняется проверка наличия лучшего кадра в данном плагине

(29)

Если в плагине Luna3DescriptorQualityCheck выбран лучший кадр, то LUNA PASS API отправляет в LUNA PASS UI именно этот кадр как успешный

(30)

Если в плагине Luna3DescriptorQualityCheck не выбран лучший кадр, то сессия закрывается без успешного кадра

(31)

Выполняется проверка включен ли плагин Bestshot

Если плагин включен, то выполняется переход к следующему шагу

Если плагин выключен, то выполняется переход к шагу 32

(32)

Выполняется проверка наличия лучшего кадра в плагине Bestshot

(33)

Если лучший кадр в плагине Bestshot не выбран, то сессия закрывается без успешного кадра

(34)

Если лучший кадр в плагине Bestshot выбран, то LUNA PASS API проверяет включен ли плагин ActiveLiveness

(35)

Если плагин ActiveLiveness включен, то выполняется проверка результата работы плагина ActiveLiveness

Сессия продолжается до прохождения кадром активного Liveness

(36)

Когда проверка результата работы плагина ActiveLiveness пройдена, то LUNA PASS API отправляет кадр в LUNA PASS UI как успешный

(37)

Если плагин ActiveLiveness выключен LUNA PASS API отправляет кадр в LUNA PASS UI как успешный

(38)

Если плагин Bestshot выключен, то отправляется первый кадр, прошедший все проверки

(39 )

  • Если кадр, прошедший проверки, был последним, то выполняется переход к шагу 40

  • Если кадр, прошедший проверки, — не последний, то все проверки начинаются заново с шага 1 для нового кадра

(40)

Текущая сессия закрывается без успешного кадра

  1. liveness_quality_score — оценка качества изображения для распознавания Liveness. ↩