Skip to content

Service architecture#

The Service architecture is shown in the diagram (Figure 1), a description of the architecture components is presented below (Table 1).

General scheme of LUNA PASS architecture
Figure 1. General scheme of LUNA PASS architecture

Table 1. Components of the LUNA PASS architecture

Component name

Description of interaction

LUNA PASS UI

LUNA PASS client component responsible for capturing video stream, sending video stream frames to LUNA PASS API and displaying processing results.

An external system with similar functions can be used instead of LUNA PASS UI, provided that the LPProto protocol is used to connect to the Backend (see the "LPProto protocol" section for operating principle).

LUNA PASS API

LUNA PASS server component, built on AIOHTTP. It processes frame, checks image and Liveness using plugins, then, based on the results of the check, makes decisions about whether the image passes inspection.

LUNA SDK

VisionLabs development kit including libraries and neural networks for detection, attribute estimation and Liveness estimation on the acquired face image.

FaceMatcher plugin

LUNA PASS API plugin, allows you to terminate the session if several main faces are detected on two frames within one session.

VirtualCameraChecker plugin

LUNA PASS API plugin, detects when a user is using a virtual camera instead of a real device camera.

AggregateLiveness plugin

LUNA PASS API plugin, calculates aggregated Liveness value over several frames.

ActiveLiveness plugin

LUNA PASS API plugin, confirms 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.

VideoRedis plugin

LUNA PASS API plugin, stores a sequence of frames together with results of checks for further gluing and creating video in LUNA PASS VIDEO.

The plugin requires Redis to work.

LUNA PASS VIDEO

LUNA PASS server component that implements the gluing of frames received within LUNA PASS API sessions into video.

NGINX

Optional component. HTTP server and reverse proxy server for load balancing.

It is not part of the product, install and configure component separately (see the "Appendix" secion).

LPProto

A transport layer information transfer protocol that defines the structure of transmitted frames using WebSocket.

Frame is a fragment of protocol data. See LPProto Protocol section for the list of frames.

LUNA PASS API forms a JWT packet with the bestshot, on successful passing of Liveness . The network communication scheme is shown below (Figure 2).

Scheme of network interaction of LUNA PASS components
Figure 2. Scheme of network interaction of LUNA PASS components

LPProto Protocol#

LPProto is a transport layer protocol developed by VisionLabs to restrict information transmitted using WebSocket. The principle of operation is transmission of consecutive frames with messages.

Frame is a fragment of protocol data, which must be specified strictly according to the template. The definition applies only to this section, in the rest of the document the frame is a part of the video stream. The first line of each frame specifies its command within the protocol.

Connection settings that are transmitted as part of the CONNECT command:

  • heartbeat:1000
  • session-id:623e1bbc-24f9-4d84-907f-8000978ec2a1

The session ID is passed in the session-id header when the connection is initialized.

LPProto protocol format#

A schematic representation of the protocol format is shown below (Figure 3).

Protocol format
Figure 3. Protocol format

The message consists of three lines:

  • First line – message type or command (Table 2);
  • The second line – section with any number of headers;
  • The third line – message body, separated by an empty line.

Table 2. Supported message types

Command

Description

Example

CONNECT

Start request to establish a connection to the LUNA PASS API.

Without an established connection, work is not possible.

Acceptable headings:

  • version – LPProto protocol version.

  • heartbeat – optional activation of background requests every N ms to keep WebSocket open (see the HEARTBEAT command).

Possible answers:

  • CONNECTED – successful connection;

  • ERROR – connection error.

CONNECT

version:1.0

heartbeat:1000

CONNECTED

Response from LUNA PASS API about successful connection to LUNA PASS UI over WebSocket.

Acceptable headings:

  • session-id – Session UUID, the unique value of the connection;

  • version – LPProto protocol version.

CONNECTED

session-id:623e1bbc-24f9-4d84 -907f-8000978ec2a1

version: 1.0

FRAME

A request from LUNA PASS UI containing information about the image: a frame of the video stream in the format specified in the content-type header.

Acceptable headings:

  • content-type – type of transmitted image

  • One line indent

  • Frame body – base64 image.

Possible answers:

STATS – image/face failed the test;

SUCCESS – the test was successful;

ERROR – error within a frame check request.

LUNA PASS UI restriction: the next FRAME cannot be sent until a response is received, this is necessary to synchronize data sending, including cases of using multiple LUNA PASS UI instances and minimize errors.

FRAME

content-type:image/x-jpeg-base64

/9j/4AAQSkZJRgABAQABAA…

STATS

LUNA PASS API response after unsuccessful image estimation, containing the error codes detected (see /docs/jslib/lpErrors.js.html for a list of errors).

If a face was found in the image, the BBox information is returned.

Acceptable headings:

  • content-type—the type of message being transmitted;

  • details—frame estimates, including BBox position The set of estimates depends on server implementation, there are no restrictions within the protocol.

  • errors—error list after image estimation (see /docs/jslib/lpErrors.js.html for error codes).

  • isOk—a boolean value that indicates whether the FRAME request was successfully executed.

STATS

content-type:application/json

{isOk: false, errors: [12], details: {,…}}

details: {,…}

details: {,…}

errors: [12]

isOk: false

SUCCESS

LUNA PASS API response after successfully validating the image, selecting the bestshot and evaluating the face.

Acceptable headings:

  • content-type – the type of message being transmitted;

  • One line indent.

  • Frame body – information about image estimation in JWT format

After receiving the frame WebSocket connection is closed. Further work requires reconnection.

SUCCESS

content-type:application/jwt

eyJ0eXAiOiJKV…

ERROR

LUNA PASS API response when an internal error occurs:

  • Incorrect installation;

  • Communication break;

  • Incorrect license;

  • Other system errors.

Acceptable headings:

  • error – error code.

The following system errors exist in this version:

  • 1002 – internal server error

ERROR

error: 1002

HEARTBEAT

Optional recurring background request from Backend to keep WebSocket open. See CONNECT for how to enable it.

Sends an empty frame every N ms.

HEARTBEAT

JWT package#

JSON Web Token (JWT) – A JSON object that allows signed text information to be transmitted. JWT uses Base64 encoding.

JThe WT consists of 3 parts, separated by dots—header.payload.signature. The Header and Payload sections use Base64 encoding:

1․ Title: Header

Description: JWT Type Information.

Example of decoded Base64:

The following attributes are used during LUNA PASS operation: { "alg": "HS256", "typ": "JWT" }. The "algorithm" attribute is configured in lunapassapi in JWT configuration parameters.

2․ Title: Payload

Description: A message body containing information on the recognized attributes.

See /docs/jslib/LunaPass.js.html for a detailed description.

Example decoded Base64: 

   {
   "details":
    {
        "ags":0.9812286496162415,
        "quality":
        {
            "blur":0.9293031692504883,
            "isBlurred":false,
            "light":0.6043056845664978,
            "isHighlighted":false,
            "darkness":0.8230781555175781,
            "isDark":false,
            "illumination":0.18545985221862793,
            "isIlluminated":false,
            "specularity":0.5418229103088379,
            "isSpecular":false
            },
        "faceFramePosition":
        {
            "faceRect":
            {
                "x":229,
                "y":138,
                "width":207,
                "height":281
                },
           "frameRect":{"x":0,"y":0,"width":640,"height":480},
           "margins":[138,204,61,229]},
           "headPose":{
               "yaw":-3.0735106468200684, "roll":1.396299958229065,"pitch":0.3325376510620117},
           "mouth":{"opened":0.29780369997024536, "smile":0.0018320679664611816, "occluded":0.016269110143184662},
           "eyeglasses":"GlassesEstimation.NoGlasses",
           "liveness":{"score":0.8843579292297363, "qualityScore":1.0}},
           "errors":[],
           "isOk":true,
           "bestshot":"<Face image in Base64>",
           "iat":1680679123,
           "jti":"a9be95d6-6653-4279-bac1-a2a01618a158"}

3․ Title: Signature

Description: Unique message signature.

The signature is not Base64 encoded.