DOT Core Server

v6.9.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
- application.yml – The application configuration file, see Externalized configuration
doc – The documentation folder
- Innovatrics_DOT_Core_Server_6.9.0_Technical_Documentation.html – The technical documentation
- Innovatrics_DOT_Core_Server_6.9.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.{iface-version} – The Innovatrics IFace library
- solvers – The Innovatrics IFace library solvers
dot-core-server.jar – The executable JAR file, see How to run
Innovatrics_DOT_Core_Server_6.9.0_postman_collection.json – Postman collection

Installation

Steps

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
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:

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

Visit our CRM portal and go to Products > Digital Onboarding Toolkit > Licenses.
Then, select Generate License and paste the Hardware ID.
Confirm again with Generate License and download the license.
Copy your license file iengine.lic for Innovatrics IFace SDK {iface-version} 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 -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)
        age-gender-speed-accuracy-mode: accurate (8)
        face-template:
          extraction-speed-accuracy-mode: accurate (9)
        track:
          liveness-eye-valid-threshold: 600 (10)
          liveness-eye-status-threshold: 0 (11)
          dot-position-time-delta: 300 (12)
        background-removal:
          segmentation-image-type: masked (13)
          segmentation-matting-type: global (14)
          segmentation-threshold: 0 (15)
          segmentation-matting-possible-threshold: 0 (16)
          segmentation-matting-sure-threshold: 500 (17)
          background-color: FFFFFF (18)
        min-face-size-ratio: 0.05 (19)
        max-face-size-ratio: 0.35 (20)
      liveness:
        default-min-valid-segment-count: 4 (21)

1	Enables HTTP payload logging.
2	Enables Jaeger tracing.
3	Innovatrics IFace solvers file path.
4	Innovatrics IFace license file path.
5	The face detection confidence threshold. Faces with a confidence score lower that this value will be ignored. The interval is [0, 10000].
6	The face detection speed accuracy mode. Valid values are `accurate`, `balanced` and `fast`. The `fast` mode is compatible with DOT Mobile Kits.
7	The 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.
8	The age gender evaluation speed accuracy mode. Valid values are `accurate` and `fast`. The `fast` mode is compatible with DOT Mobile Kits. The `accurate` mode requires more computing power and provides the best precision.
9	The face template extraction speed accuracy mode. Valid values are `accurate`, `balanced` and `fast`. The `fast` mode is compatible with DOT Mobile Kits.
10	The expert parameter of the eye tracker defines the eye validity threshold for the liveness check. The interval is [0, 10000].
11	The expert parameter of the eye tracker defines the eye status threshold for the liveness check. The interval is [-10000, 10000].
12	The 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].
13	The parameter determines type of returned image. Valid values are `mask`, `masked`, `masked_alpha`. See more in Background removal configuration.
14	The parameter defining type of matting used after head shoulder segmentation. Valid values are `off`, `global`. See more in Background removal configuration.
15	The parameter defining threshold for segmentation mask. The parameter should be in range <-10000, 10000>. See more in Background removal configuration.
16	The 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.
17	The 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.
18	The 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.
19	The 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.
20	The 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.
21	The 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).

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
original	cropped	mask	masked	masked_alpha