DOT Core Server
v6.17.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 folderapplication.yml
– The application configuration file, see Externalized configuration
doc
– The documentation folderInnovatrics_DOT_Core_Server_6.17.0_Technical_Documentation.html
– The technical documentationInnovatrics_DOT_Core_Server_6.17.0_Technical_Documentation.pdf
– The technical documentationswagger.json
– The Swagger API fileEULA.txt
- The license agreement
docker
– The Docker folderDockerfile
– The text document that contains all the commands to assemble a Docker image, see Docker
iface
– The IFace library folderlibiface.so.5.6.0
– The Innovatrics IFace librarylibinnoonnxruntime.so
– The Innovatrics runtime librarysolvers
– The Innovatrics IFace library solvers
dot-core-server.jar
– The executable JAR file, see How to runInnovatrics_DOT_Core_Server_6.17.0_postman_collection.json
– Postman collection
Installation
System requirements
Ubuntu 18.04 (64-bit)
Steps
Install the following packages:
OpenJDK Runtime Environment (JRE) (
temurin-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 5.6.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)
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 face template extraction speed accuracy mode. Valid values are accurate , balanced and fast . The fast mode is compatible with DOT Mobile Kits. |
9 | The expert parameter of the eye tracker defines the eye validity threshold for the liveness check. The interval is [0, 10000]. |
10 | The expert parameter of the eye tracker defines the eye status threshold for the liveness check. The interval is [-10000, 10000]. |
11 | 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]. |
12 | The parameter determines type of returned image. Valid values are mask , masked , masked_alpha . See more in Background removal configuration. |
13 | The parameter defining type of matting used after head shoulder segmentation. Valid values are off , global . See more in Background removal configuration. |
14 | The parameter defining threshold for segmentation mask. The parameter should be in range <-10000, 10000>. See more in Background removal configuration. |
15 | 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. |
16 | 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. |
17 | 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. |
18 | 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. |
19 | 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. |
20 | 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.
original | cropped | mask | masked | masked_alpha |
---|---|---|---|---|