Плагин 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
.