Версия: 3.11

Плагин Face SDK VideoEngine JS

Плагин Face SDK VideoEngine JS реализует функции детекции и трекинга лиц и определения принадлежности лица живому человеку (Active Liveness). В данном разделе представлена информация по установке, инициализации и запуску плагина Face SDK VideoEngine JS, доступным параметрам запуска и публичным методам.

Установка плагина

Выполните одну из следующих команд в консоли, в зависимости от платформы, которую Вы используете (Node или Yarn):

npm install @3divi/face-sdk-video-engine-js
yarn add @3divi/face-sdk-video-engine-js

Инициализация плагина

Импортируйте библиотеку VideoEngine из Face SDK:
import { VideoEngine } from '@3divi/face-sdk-video-engine-js';
Создайте экземпляр класса VideoEngine (см. описание опциональных параметров запуска в пункте Параметры запуска плагина):
const videoEngine = new VideoEngine(?options);

Запуск плагина

Выполните вызов метода load для загрузки модуля: videoEngine.load();
Для запуска плагина вызовите метод videoEngine.start(input, callback);, где:
- input — HTML-элемент HTMLVideoElement, который можно получить из тэга <video></video> и передать его в качестве input в метод. Внутри тэга должен быть указан видеопоток (video stream) (см. пункт Инициализация камеры)
- callback — функция обратного вызова, в которой можно получить объект prediction (см. описание объекта в пункте Публичные методы) и обрабатывать данные в реальном времени во время процессинга (режим, в котором происходит обработка видеопотока с камеры: детекция лица, определение Liveness), например, отобразить ограничивающий прямоугольник, получить данные и вывести их на экран.

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

Пример инициализации плагина:

const initVideoEngine = async () => {
 try {
  // Do something
  const videoEngine = new VideoEngine();
  await videoEngine.load();
  // Do something
 } catch (error) {
   console.log(error.message);
 }
};

Инициализация камеры

Для инициализации камеры необходимо:

Добавить в HTML тэг <video></video>
Получить тэг видео:
const video = documnet.querySelector('video');
Инициализировать поток (stream). Полный пример: demo/src/utils.js.

try {
  const stream = await navigator.mediaDevices.getUserMedia({
   audio: false,
   video: {
    facingMode: 'user',
    width: VIDEO_SIZE,
    height: VIDEO_SIZE,
   },
  });
  video.srcObject = stream;
  return new Promise((resolve) => {
   video.onloadedmetadata = () => {
    resolve(video);
   };
  });
 } catch (error) {
  throw new Error(error);
}

Параметры запуска плагина

Функция new VideoEngine() принимает опциональный объект options, который содержит следующие поля:

backend — используемое средство для обработки видеопотока. Значения: webgl — для обработки используется видеокарта GPU, cpu — для обработки используется ЦП. Значение по умолчанию: webgl
pose — объект, хранящий в себе поворот головы в градусах. Используется для проверки Активного Liveness и ограничения максимально разрешенного угла поворота головы (см. Рекомендации по размещению камер и съемке). Имеет поле maxRotation. Принимает значение типа Number (градус поворота). Значение по умолчанию: 15
eyes — объект, хранящий в себе информацию о положении и состоянии глаз. Принимает следующие поля:
- minDistance — минимальное расстояние между зрачками в пикселях. Тип: Number. Значение по умолчанию: 60. Также возможно импортировать константы для последующей передачи:
  - REGISTRATION_EYES_MIN_DISTANCE хранит значение 60. Лицо добавляется в базу, если удовлетворено данное значение.
  - IDENTIFICATION_EYES_MIN_DISTANCE хранит значение 40. Лицо идентифицируется, если удовлетворено данное значение.
- closeLowThreshold — минимальное пороговое значение для состояния “глаза открыты” (от 0 до 1). Если значение меньше порога closeLowThreshold, результатом является статус “глаза закрыты”. Принимает значение типа Number (от 0 до 1). Значение по умолчанию: 0.25.
- closeHighThreshold — максимальное пороговое значение для состояния “глаза открыты”. Если глаза закрыты, используется значение closeHighThreshold. Если значение >= closeHighThreshold, результатом является статус “глаза открыты”, иначе — “глаза закрыты”. Принимает значение типа Number (от 0 до 1). Значение по умолчанию: 0.3. Если значение closeHighThreshold не указано, оно высчитывается автоматически в зависимости от closeLowThreshold.
- maxDurationClose — значение, используемое для определения действия “моргание”. Если промежуток времени между состояниями “глаза открыты” и “глаза закрыты” меньше значения maxDurationClose, результатом является статус “было произведено моргание”. Принимает значение типа Number (время в мс). Значение по умолчанию: 500.

Публичные методы

load — асинхронная инициализация библиотеки. Может принимать поле backend (см. Параметры запуска плагина). Возвращает объект Promise. В результате завершения вызова приходит объект Status:
```
{
    type: 'success',
    message: 'ok',
};
```
reset — полная очистка данных в библиотеке о последнем процессинге.
start — запускает обработку видеопотока. Возвращает объект Promise, который содержит в себе объект Status (см. выше). При первом выполнении метода start происходит инициализация модели и объекта backend. Принимает следующие параметры:
- input — HTML-элемент HTMLVideoElement (см. Запуск плагина).
- callback — функция обратного вызова, внутри которой в режиме реального времени можно обрабатывать получаемые данные. Аргумент данной функции — объект prediction.
  - prediction:
    - pose — объект, хранящий информацию о текущем положении головы:
      - axes — объект связанной системы координат roll/pitch/yaw, поля которого имеют тип Number.
      - poseInRequiredRange — переменная, означающая, что положение головы находится в корректном диапазоне связанной системы координат (углы наклона не превышают значение maxRotation). Тип: Boolean.
    - headWasTurned — была ли повернута голова во время процессинга. Тип: Boolean.
    - imageBase64 — изображение текущего объекта prediction. Тип: String, формат данных: Base64.
    - face — объект, который содержит информацию о глазах и точках лица:
      - boundingBox — объект ограничивающего прямоугольника лица:
        topLeft — массив 2D координат [x:number, y:number]; (верхний левый угол).
        bottomRight — массив 2D координат [x:number, y:number]; (нижний правый угол).
      - faceInViewConfidence — вероятность присутствия лица. Тип: Number (от 0 до 1).
      - mesh — массив с вложенными массивами 3D координат точек лица [...[x:number, y:number, z:number]].
      - scaledMesh — нормализированный массив (координаты точек скорректированы в соответствии с размером лица на видеопотоке) с вложенными массивами 3D координат точек лица [...[x:number, y:number, z:number]].
      - annotations — семантические группы координат scaledMesh.
      - eyes — объект, в котором хранится информация о глазах:
        isClosed — закрыты ли глаза в текущий момент времени. Тип: Boolean.
        isBlinked — было ли произведено моргание в текущий момент времени. Тип: Boolean.
        wasBlinked — было ли произведено моргание в течение всего периода процессинга. Тип: Boolean.
        eyesDistanceInRequiredRange — находится ли пользователь на корректном растоянии до камеры. При расчете учитывается значение параметра minDistance (минимальное расстояние между зрачками). Тип: Boolean.
        levelOpeningEyes — объект, хранящий текущую степень открытия каждого глаза:
        left — левый глаз. Тип: Number.
        right — правый глаз. Тип: Number.
- Поскольку первая инициализация после вызова метода start может занимать много времени, Вы можете дополнить код вызова, чтобы в процессе инициализации отображалось сообщение (например, “Происходит инициализация”).
stop — останавливает процесс обработки, но сохраняет текущие значения. В случае вызова метода start обработка продолжится. Возвращает лучший объект prediction.

Пример интерфейса, возвращаемого в объекте prediction:

interface OutputData {
  pose: {
    axes: Axes;
    poseInRequiredRange: boolean;
  };
  face: {
    boundingBox: BoundingBox;
    mesh: Coord3D[];
    scaledMesh: Coord3D[];
    annotations?: { [key: string]: Coord3D };
    faceInViewConfidence: number;
    eyes: {
        isClosed: boolean;
        isBlinked: boolean;
        wasBlinked: boolean;
        eyesDistanceInRequiredRange: boolean;
        levelOpeningEyes: {
          left: number;
          right: number;
        };
  };
};
  headWasTurned: boolean;
  imageBase64?: string;
}

Публичные поля

backend — используемое средство для процессинга (см. Параметры запуска плагина). Возвращает данные типа String.
inProgress — был ли запущен процессинг. Возвращает булево значение.
isInitialised — была ли инициализирована модель. Инициализация модели происходит во время первого выполнения метода start. Возвращает булево значение.
isLoaded — была ли загружена модель. Возвращает булево значение.
bestPrediction — возвращает лучший объект prediction.
bestShot — возвращает лучшее изображение лучшего объекта prediction.

Установка плагина​

Инициализация плагина​

Запуск плагина​

Инициализация камеры​

Параметры запуска плагина​

Публичные методы​

Публичные поля​