Skip to content

LUNA PASS API#

The general principle of operation of LUNA PASS API is as follows:

  • a frame comes to the input;
  • LUNA SDK estimates and checks the frame;
  • plugins are executed sequentially if they are enabled:
  • FaceMatcher plugin;
  • VirtualCameraChecker plugin;
  • ActiveLiveness plugin;
  • the aggregated value of Liveness, Deepfake, as well as mouth, eye status and glasses type estimations are calculated;
  • the result of the plugin and check work is analyzed.

By default, all plugins are enabled.

Frame estimation process#

The frame estimation process is the sequential execution of checks. A description of the checks is presented below (Table 4).

Table 4. Checks for frame estimation process

Check

Internal checks

Multiface

whether the face is:

  • the only one in the frame;

  • the largest (main) in the frame;

  • the face closest to the center

Image quality

  • blur;

  • exposure;

  • darkening;

  • glare on the face;

  • contrast

The size and position of the face in the frame

indentation of the face border from the frame border:

  • top;

  • at the bottom;

  • to the right;

  • on the left;

frame size:

  • in width;

  • in height;

the size of the face in the frame:

  • in width;

  • by height

Head position

  • head tilt angle to the right/left (roll);

  • head tilt angle up/down (pitch);

  • head rotation angle right/left (yaw)

Eyes status

  • eyes open;

  • eyes closed

Mouth status

  • the mouth is open;

  • a smile is detected;

  • the mouth is closed

Glasses

  • no glasses;

  • glasses are present;

  • sunglasses

AGS (check the overall image quality metric)

\—

Liveness
  • Liveness estimation;

Deepfake
  • Deepfake estimation with specified accuracy

If a frame does not pass any of the checks, then the next frame is analyzed. The user sees the corresponding prompts on the page with LUNA PASS UI.

FaceMatcher plugin#

The FaceMatcher plugin is enabled in the config.toml file. For this, set the parameter disallowMultipleFacesInSession = 1 in the LIVENESS configuration parameters. It allows you to terminate the session if several main faces are detected on two frames within one session.

Description of the general working principle of the FaceMatcher plugin:

If the first frame arrives, Facematcher remembers photo of face. If the second frame arrives, Facematcher compares photo of face from the received frame with the photo of the face from the previous frame:

  • if faces on the photos from the two frames are different, then no further checks are carried out;

  • if faces on the photos from the two frames are the same, then the frame is sent for further checks.

VirtualCameraChecker plugin#

VirtualCameraChecker plugin is enabled in the config.toml file. It allows you to detect when a user is using a virtual camera instead of a real device camera. Virtual camera detection data is recorded to the logs.

ActiveLiveness plugin#

The ActiveLiveness plugin is in the config.toml file. It allows you to confirm vitality by several frames in which the user interacts with the Service: blinks, turns his head left and right along the Y axis, tilts his head up and down along the X axis. The description of the general working principle of the plugin is presented below (Table 5).

Table 5. Description of the general principle of operation of the ActiveLiveness plugin

Step

Description

1

The administrator selects an arbitrary set of checks*. The number of checks is specified in the settings.

2

If the current frame fails Liveness check, the plugin generates errors. Errors tell what the user should do to pass the verification.

3

If the current frame passes Liveness check, then one or more frames are skipped so that photos with half-open eyes or in the process of turning the head are not counted. The cooldownFramesCount parameter is responsible for the number of skipped frames.

The resulting frame becomes a bestshot.

ActiveLiveness checks#

Blinking

The check begins when both eyes are open, or one eye is open and the acceptOneEyeOpen parameter is enabled. To pass the check, the two frames must then arrive: with eyes closed and again with open ones, or, if the acceptOneEyeOpen parameter is enabled, a frame with one eye closed and a frame with one open.

Head turn

To start checking, the head turn angle must be less than the value of args.yawStartDeg. Next, the two frames must arrive: with a turn angle value greater than args.yawThresholdDeg and with a turn angle value less than args.yawStartDeg.

Head tilt

To start checking, the head tilt angle must be less than the value of args.pitchStartDeg. Next, the two frames must arrive: with a tilt angle value greater than args.pitchThresholdDeg and with a tilt angle value less than args.pitchStartDeg.

For more information about the values of the turn and tilt angles, see configuration parameters of the ActiveLiveness plugin

Results processing#

The general working principle of LUNA PASS API is shown in the diagram (Figure 9). The description of the general working principle is presented below (Table 6).

General principle of operation of LUNA PASS API
Figure 9. General principle of operation of LUNA PASS API

Table 6. Description of the general principle of operation of LUNA PASS API

Step

Description

0

The LUNA PASS API gets the frame

1

LUNA PASS API evaluates the frame using the LUNA SDK and compares the resulting values with thresholds. More details in the "Frame estimation process"

2

If the FaceMatcher plugin is enabled, processing is performed according to the process described above

3

If the VirtualCameraChecker plugin is enabled, then it checks whether the user is using a virtual camera instead of the real device camera

4

If the ActiveLiveness plugin is enabled, processing is performed according to the process described above

5

After performing actions in the specified plugins, the LUNA PASS API processes the obtained results.

LUNA PASS API checks if the received frame is the first one. Depending on this check, the following steps are performed:

  • If the received frame is not the first one, then go to step 6

  • If only the first frame has arrived, then go to step 8

6

If the received frame is not the first, then the face from the current is compared with the face from the first frame:

  • If the faces do not match, then go to step 7

  • If the faces in the two frames match, then go to step 8

7

Multiple principals detected within the same session, the session is closed without a successful frame.

8

LUNA PASS API checks if the camera is real. Depending on the results of this check, the following steps are performed:

  • If the camera is virtual, then go to step 9

  • If the camera is real, then go to step 10

9

The user is detected using a virtual camera instead of a real device camera, the session is closed without a successful frame.

10

LUNA PASS API checks: the number of frames that reached the Liveness estimation is greater than or equal to the value maxLivenessAttempts

Depending on this check, further analysis is divided into two parts:

  1. Checking if plugins are enabled and sending the result;

  2. Checking if plugins are enabled and trying to get additional frames for processing

If at step 10 the number of frames that reached the Liveness estimation is less than allowed, the following steps are performed:

11

LUNA PASS API checks if the number of received frames is greater than or equal to the value aggregateFrames value

  • If the aggregation window is not full, then go to step 21;

  • If the aggregation window is full, then go to the next step

12

LUNA PASS API checks the values:

  • aggregated Liveness is greater than or equal to the threshold liveness_score;

  • aggregated Deepfake is greater than or equal to the threshold deepfake;

  • aggregated mouth score is greater than or equal to the threshold mouth;

  • aggregated eye status value is equal to the one specified in the acceptOneEyeOpen parameter;

  • aggregated glasses type value is equal to the one specified in the glasses parameter;

If the values ​​of the obtained aggregated values ​​are higher than or equal to the threshold, then go to the next step

13

LUNA PASS API checks if the ActiveLiveness plugin is enabled

14

If the ActiveLiveness plugin is enabled, LUNA PASS API performs a check on the result of the ActiveLiveness plugin. The session continues until the frame passes active Liveness

15

When the ActiveLiveness plugin results check is passed, the LUNA PASS API sends this frame to the LUNA PASS UI as a successful frame

16

If the ActiveLiveness plugin is disabled, the LUNA PASS API sends this frame to the LUNA PASS UI as a successful frame

If at step 10 the number of frames that reached the Liveness estimation is greater or equal to the allowable, the following steps are performed:

17

The LUNA PASS API checks if the ActiveLiveness plugin is enabled

18

If the ActiveLiveness plugin is enabled, LUNA PASS API performs a check on the result of the ActiveLiveness plugin The session continues until the frame passes active Liveness

19

When the ActiveLiveness plugin results check is passed, the LUNA PASS API sends this frame to the LUNA PASS UI as a successful frame

20

If the ActiveLiveness plugin is disabled, the LUNA PASS API sends this frame to the LUNA PASS UI as a successful frame

21

  • If the frame, that passed the checks, is the last one, then go to step 22

  • If the frame, that passed the checks, is not the last one, then all checks begin again from step 1 for the new frame

22

The current session is closed without a successful frame