DOT Core Server

v6.12.0

Overview

DOT Core Server is a RESTful microservice making the integration of the browser and mobile client app with IFace as easy as possible.

API Reference

The DOT Core Server API reference is published here

Distribution package contents

You can find the distribution package in our CRM portal. It contains these files:

Your sales representative will provide you the credentials for the CRM login.
  • config – The configuration folder

  • doc – The documentation folder

    • Innovatrics_DOT_Core_Server_6.12.0_Technical_Documentation.html – The technical documentation

    • Innovatrics_DOT_Core_Server_6.12.0_Technical_Documentation.pdf – The technical documentation

    • swagger.json – The Swagger API file

    • EULA.txt - The license agreement

  • docker – The Docker folder

    • Dockerfile – The text document that contains all the commands to assemble a Docker image, see Docker

  • iface – The IFace library folder

    • libiface.so.4.20.0 – The Innovatrics IFace library

    • libinnoonnxruntime.so – The Innovatrics runtime library

    • solvers – The Innovatrics IFace library solvers

  • dot-core-server.jar – The executable JAR file, see How to run

  • Innovatrics_DOT_Core_Server_6.12.0_postman_collection.json – Postman collection

Installation

System requirements

  • Ubuntu 18.04 (64-bit)

Steps

  1. Install the following packages:

    • OpenJDK Runtime Environment (JRE) (openjdk-11-jre)

    • userspace USB programming library (libusb-0.1)

    • GCC OpenMP (GOMP) support library (libgomp1)

    apt-get update
    apt-get install -y openjdk-11-jre libusb-0.1 libgomp1
  2. Extract the DOT Core Server distribution package to any folder.

Activate the DOT license

The activation of the DOT license depends on the type of your deployment.

If you perform serverless or Docker deployments, please contact your sales representative or sales@innovatrics.com to receive a license. Once you receive the license, please deploy it as described in step 5 below.

If you perform a bare metal installation, or use a fixed VM or AWS instance, perform the following steps:

  1. Run DOT Core Server to generate the Hardware ID necessary for the license.

    java -Dspring.config.additional-location=file:config/application.yml -Djna.library.path=./iface/ -jar dot-core-server.jar

    Copy the Hardware ID, which you can find at the end of the output. See the example below:

    Unable to initialize IFace. Hardware ID: xxxxxxxxxxxx
  2. Visit our CRM portal and go to Products > Digital Onboarding Toolkit > Licenses.

  3. Then, select Generate License and paste the Hardware ID.

    Generate license
  4. Confirm again with Generate License and download the license.

  5. Copy your license file iengine.lic for Innovatrics IFace SDK 4.20.0 into {DOT_CORE_SERVER_DIR}/license/

How to run

As DOT Core Server is a stand-alone Spring Boot application with an embedded servlet container, there is no need to deploy it on a running web server. Instead, just run in the application folder:

java -Dspring.config.additional-location=file:config/application.yml -Djna.library.path=./iface/ -jar dot-core-server.jar

Embedded Tomcat web server will be started and the application will be listening on the port 8080 (or another configured port).

Docker

For building a Docker image, you can use the Dockerfile included in the distribution package. The Dockerfile can be also found in the Appendix.

cd docker
cp ../dot-core-server.jar .
cp ../iface/libiface.so.* .
cp ../iface/libinnoonnxruntime.so.* .
cp -r ../iface/solvers/ ./solvers
cp -R ../config/ .
docker build -t dot-core-server:latest .

Run the container according to the instructions below:

docker container run -v /local/path/to/license/dir/:/srv/dot-core-server/license -v /local/path/to/logs/dir/:/srv/dot-core-server/logs -p 8080:8080 dot-core-server:latest
Replace the path /local/path/to/license/dir/ in the command with your local path to the license directory.
Important Replace the path /local/path/to/logs/dir/ in the command with your local path to the logs directory (you need to create the directory mounted to a persistent drive). The volume mount into the docker is mandatory, otherwise application does not start successfully.

Externalized configuration

YAML configuration file is located under the config folder:

config/application.yml

There are two groups of properties:

  • Spring Boot properties

  • DOT Core Server specific properties

Spring Boot properties

See the specification at Common Application properties.

For example, if you would like to specify a different server port, just add the following property:

server:
    port: 9080

To fully understand how the externalized configuration works in Spring Boot, see Spring Boot documentation, chapter Externalized Configuration

DOT Core Server specific properties

These properties are tied with the DOT Core Server specific behavior. The following property collection is provided as a guideline and shows the default values and their meaning.

innovatrics:
  dot:
    core:
      http:
        logging:
          payload: false (1)
      tracing: false (2)
      iface:
        solvers:
          path: iface/solvers (3)
        license:
          filepath: license/iengine.lic (4)
        face-detection:
          confidence-threshold: 600 (5)
          speed-accuracy-mode: accurate (6)
          max-image-size: 1200 (7)
        face-template:
          extraction-speed-accuracy-mode: accurate (8)
        track:
          liveness-eye-valid-threshold: 600 (9)
          liveness-eye-status-threshold: 0 (10)
          dot-position-time-delta: 300 (11)
        background-removal:
          segmentation-image-type: masked (12)
          segmentation-matting-type: global (13)
          segmentation-threshold: 0 (14)
          segmentation-matting-possible-threshold: 0 (15)
          segmentation-matting-sure-threshold: 500 (16)
          background-color: FFFFFF (17)
        min-face-size-ratio: 0.05 (18)
        max-face-size-ratio: 0.35 (19)
      liveness:
        default-min-valid-segment-count: 4 (20)
1Enables HTTP payload logging.
2Enables Jaeger tracing.
3Innovatrics IFace solvers file path.
4Innovatrics IFace license file path.
5The face detection confidence threshold. Faces with a confidence score lower that this value will be ignored. The interval is [0, 10000].
6The face detection speed accuracy mode. Valid values are accurate, balanced and fast. The fast mode is compatible with DOT Mobile Kits.
7The parameter defines maximal image size of image entering to internal solver in balanced and accurate detection mode. It affects the memory requirements. When set to a higher number, the face detection consumes more memory. The value of this param affects the limit for minFaceSize. If you need to set the minFaceSize to a smaller value to detect smaller faces then you have to set this parameter to a higher value.
8The face template extraction speed accuracy mode. Valid values are accurate, balanced and fast. The fast mode is compatible with DOT Mobile Kits.
9The expert parameter of the eye tracker defines the eye validity threshold for the liveness check. The interval is [0, 10000].
10The expert parameter of the eye tracker defines the eye status threshold for the liveness check. The interval is [-10000, 10000].
11The expert parameter of the eye tracker defines how long (in ms) a frame can be registered for the liveness check after the dot position set. The interval is [10, 5000].
12The parameter determines type of returned image. Valid values are mask, masked, masked_alpha. See more in Background removal configuration.
13The parameter defining type of matting used after head shoulder segmentation. Valid values are off, global. See more in Background removal configuration.
14The parameter defining threshold for segmentation mask. The parameter should be in range <-10000, 10000>. See more in Background removal configuration.
15The parameter defining threshold for a possible foreground for generating trimap for matting. The parameter should be in range <-10000, 10000>. See more in Background removal configuration.
16The parameter defining threshold for a sure foreground for generating trimap for matting. The parameter should be in range <-10000, 10000>. See more in Background removal configuration.
17The parameter defining color which is used to fill in parts of cropped image that fall outside the original source image boundaries. Valid value is hexadecimal code string e.g. RRGGBB. See more in Background removal configuration.
18The minimal face size ratio of faces detected in discovery frames. The application will recognize a face in the image only if the face size ratio >= than this value.
19The maximal face size ratio of faces detected in discovery frames. The application will recognize a face in the image only if the face size ratio <= than this value.
20The minimal segment count in HTTP request payload.
The face size is defined as the larger of the two: the eye distance and the eye to mouth distance (distances are shown in the picture below).
Face size

Background removal configuration

By the background removal feature you can remove background from the cropped image of the face. The result image is in the PNG format to preserve the alpha channel.

Segmentation Image Type

At first, you can choose the segmentation image type. This parameter has three possible values:

  • mask - The segmentation mask only (single-channel)

  • masked - The three-channel image with applied segmentation. The masked areas are filled with the color defined by the background color parameter.

  • masked_alpha. - The four-channel image with applied segmentation. The masked areas are marked as transparent in the alpha channel.

The segmentation can be fine tune by the segmentation threshold parameter. The segmentation threshold is in range <-10000, 10000>. It’s quantile-normalized and 0 represents ERR. Higher segmentation threshold means that result image will contain more foreground. Lower segmentation threshold means that result image will contain more background.

Table 1. Segmentation Image Type Examples
originalcroppedmaskmaskedmasked_alpha
Original