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

  • 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

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 {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)
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 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.
9The face template extraction speed accuracy mode. Valid values are accurate, balanced and fast. The fast mode is compatible with DOT Mobile Kits.
10The expert parameter of the eye tracker defines the eye validity threshold for the liveness check. The interval is [0, 10000].
11The expert parameter of the eye tracker defines the eye status threshold for the liveness check. The interval is [-10000, 10000].
12The 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].
13The parameter determines type of returned image. Valid values are mask, masked, masked_alpha. See more in Background removal configuration.
14The parameter defining type of matting used after head shoulder segmentation. Valid values are off, global. See more in Background removal configuration.
15The parameter defining threshold for segmentation mask. The parameter should be in range <-10000, 10000>. See more in Background removal configuration.
16The 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.
17The 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.
18The 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.
19The 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.
20The 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.
21The 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
Cropped
Mask
Masked
Masked Alpha

segmentation matting type: global
segmentation threshold: 0
segmentation matting possible threshold: 0
segmentation matting sure threshold: 500
background color: FFFFFF

Background Color

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. This parameter is taking in account only for the masked segmentation image type.

Table 2. Background Color Examples
masked white FFFFFFmasked red FF0000
Masked White
Masked Red

segmentation type: masked
segmentation matting type: global
segmentation threshold: 0
segmentation matting possible threshold: 0
segmentation matting sure threshold: 500

Segmentation Matting Type

You can enable global matting to soften mask edges. Otherwise, you will receive the masked image after segmentation without change. You can fine tune softening mask edges by two thresholds: the Segmentation Matting Possible Threshold and the Segmentation Matting Sure Threshold.

  • <-10000, POSSIBLE_THRESHOLD> - The background for sure, the matting doesn’t influence this range.

  • <POSSIBLE_THRESHOLD, SURE_THRESHOLD> - The unsure range, the matting decides what is the foreground and what is the background

  • <SURE_THRESHOLD, 10000> - The foreground for sure, the matting doesn’t influence this range.

Table 3. Segmentation Matting Type Examples
globaloff
Masked Matting On
Masked Matting Off

segmentation type: masked
segmentation threshold: 0
segmentation matting possible threshold: 0
segmentation matting sure threshold: 500
background color: FFFFFF

Externalized configuration via command line arguments

You can specify any Spring Boot property via command line arguments as you can see below:

java -jar dot-core-server.jar --server.port=9080

Logging

DOT Core Server logs to the console and writes the log file (logs/dot-core-server.log) as well. Log files rotate when they reach 10 MB. The maximum history is 60 files. This can be configured by Spring Boot application properties. See the specification at Common Application properties.

Accessing the log file via HTTP

The log file endpoint provides access to the contents of the application’s log file. This feature can be used by an external tool, such as Elasticsearch, Kibana, etc. For more information, see Spring Boot documentation, chapter Log File.

API Transaction Counter Log

The separate log file logs/transaction-counter.log contains information about counts of API calls (transactions). The same rolling policy is applied as for the application log, except the maximum history of this log file is 180 files.

The default logback configuration of API Transaction Counter logger is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <include resource="org/springframework/boot/logging/logback/base.xml"/>

    <appender name="TRANSACTION_COUNTER_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <encoder>
            <pattern>%msg%n</pattern>
        </encoder>
        <file>logs/transaction-counter.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>logs/transaction-counter.log.%d{yyyy-MM-dd}.%i.gz</fileNamePattern>
            <maxFileSize>${LOG_FILE_MAX_SIZE:-100MB}</maxFileSize>
            <maxHistory>180</maxHistory>
        </rollingPolicy>
    </appender>

    <logger name="com.innovatrics.dot.coreserver.service.TransactionCounterService" level="INFO" additivity="false">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="TRANSACTION_COUNTER_FILE"/>
    </logger>

</configuration>

If you would like to override the default configuration, create a file with the name logback-spring.xml, copy and modify the above content and start DOT Core Server using the following command:

java -Dlogging.config=logback-spring.xml -jar dot-core-server.jar

If you are using Docker, you need to modify the Dockerfile and build an image. To modify the Dockerfile, perform these steps:

...
# Add COPY command to copy your own logback configuration
COPY logback-spring.xml /srv/dot-core-server
...
# Replace original CMD command
CMD java -Dlogging.config=logback-spring.xml -jar dot-core-server.jar
...

Docker: Keeping log files in local filesystem

When you run DOT Core Server as a Docker container, you may have access to log files, even after the container doesn’t exist anymore. This can be achieved by using Docker volumes. To find out how to run a container, see Docker.

Monitoring

Information as build or license info can be accessed on /api/v6/actuator/info. Information about available endpoints can be viewed under /swagger-ui.html.

The health endpoint accessible under /actuator/health provides information about the health of the application. This feature can be used by an external tool such as Spring Boot Admin, etc.

Application also supports exposing metrics in standardised prometheus format. These are accessible under /actuator/prometheus. You can expose this endpoint in your configuration:

management:
  endpoints:
    web:
      exposure:
        include: health, info, prometheus

For more information, see Spring Boot documentation, section Production ready features. Spring Boot Actuator Documentation also provides info about other monitoring endpoints that can be enabled.

Tracing

OpenTracing API with Jaeger implementation is used for tracing purposes. The DOT Core Server tracing implementation supports SpanContext extraction from HTTP request using HTTP Headers format. For more information, see OpenTracing Specification. Tracing is disabled by default. To enable Jaeger tracing:

Set these application properties:

opentracing:
  jaeger:
    enabled: true
    udp-sender:
      host: jaegerhost
      port: portNumber

For more information about Jaeger configuration, see Jaeger Client Lib Docs.

Face size ratio

The Face size ratio is a ratio between the face size and the shorter side of an image.

The service detects only faces with a face size ratio within a certain range that is configurable via min-face-size-ratio and max-face-size-ratio properties.

Optionally you can override the configuration by specifying a custom face size ratio in the request.

Min face size ratio restrictions

The size of detectable faces depends on the input image and the configured face detection speed accuracy mode.

The allowed min face size ratio is restricted based on the size of the input image. If the requested min face ratio is too small for the input image, the detection request will end up with an error: FACE_SIZE_MEMORY_LIMIT.

Table 4. Min valid face size calculation per detection mode
Face detection speed accuracy modeMin valid face size ratio calculation

fast

\$12 / "ShorterSide"\$

balanced

\$max{ (3 / "ShorterSide"), (10 / "FD_MAX_IMAGE_SIZE" * "LongerSide" / "ShorterSide") }\$

accurate

ShorterSide and LongerSide values are in pixels.

FD_MAX_IMAGE_SIZE is configurable via the face-detection.max-image-size parameter.

ICAO attributes

The following attributes can be taken as ICAO features.

NameDescription

sharpness

The face attribute for evaluating whether an area of the face image is blurred. Sharpness values are within the interval [-10000,10000]. Values near -10000 indicate 'very blurred', values near 10000 indicate 'very sharp'. The decision threshold is around 0.

brightness

The face attribute for evaluating whether an area of the face is correctly exposed. Brightness values are within the interval [-10000,10000]. Values near -10000 indicate 'too dark', values near 10000 indicate 'too light', values around 0 indicate OK. The decision thresholds are around -5000 and 5000.

contrast

The face attribute for evaluating whether an area of the face is contrast enough. Contrast values are within the interval [-10000,10000]. Values near -10000 indicate 'very low contrast', values near 10000 indicate 'very high contrast', values around 0 indicate OK. The decision thresholds are around -5000 and 5000.

uniqueIntensityLevels

The face attribute for evaluating whether an area of the face has an appropriate number of unique intensity levels. Unique intensity levels values are within the interval [-10000,10000]. Values near -10000 indicate 'very few unique intensity levels', values near 10000 indicate 'enough unique intensity levels'. The decision threshold is around 0.

shadow

The face attribute for evaluating whether an area of the face is overshadowed. Shadow values are within the interval [-10000,10000]. Values near -10000 indicate 'very strong global shadows present', values near 10000 indicate 'no global shadows present'. The decision threshold is around 0.

noseShadow

The face attribute for evaluating whether eyes or the nose cast sharp shadows. Nose shadow values are within the interval [-10000,10000] . Values near -10000 indicate 'very strong local (eyes or nose) shadows present', values near 10000 indicate 'no local shadows present'. The decision threshold is around 0.

specularity

The face attribute for evaluating whether spotlights are present on the face. Specularity values are within the interval [-10000,10000]. Values near -10000 indicate 'very strong specularity present', values near 10000 indicate 'no specularity present'. The decision threshold is around 0.

eyeGaze

The face attribute for evaluating whether the gaze-direction is frontal. Eye gaze values are within the interval [-10000,10000]. Values near -10000 indicate 'sideway ahead eyes gaze', values near 10000 indicate 'straight ahead eyes gaze'. The decision threshold is around 0.

eyeStatusRight

The face attribute for evaluating the right eye status. Right eye values are within the interval [-10000,10000]. Values near -10000 indicate 'closed, narrowed or bulged eye', values near 10000 indicate 'normally opened eye'. The decision threshold is around 0.

eyeStatusLeft

The face attribute for evaluating the left eye status. Left eye values are within the interval [-10000,10000]. Values near -10000 indicate 'closed, narrowed or bulged eye', values near 10000 indicate 'normally opened eye'. The decision threshold is around 0.

heavyFrame

The face attribute for evaluating whether glasses with heavy frames are present. Heavy frame glasses values are within the interval [-10000,10000]. Values near -10000 indicate 'no heavy frame glasses present', values near 10000 indicate 'heavy frame glasses present'. The decision threshold is around 0.

mouthStatus

The face attribute for evaluating the mouth status. Mouth status values are within the interval [-10000,10000]. Values near -10000 indicate 'open mouth, smile showing teeth or round lips present', values near 10000 indicate 'mouth with no expression'. The decision threshold is around 0.

backgroundUniformity

The face attribute for evaluating whether the background is uniform. Background uniformity values are within the interval [-10000,10000]. Values near -10000 indicate a 'very non-uniform background present', values near 10000 indicate a 'uniform background present'. The decision threshold is around 0.

redEyeRight

The face attribute for evaluating whether the red-eye effect is present on the right eye. Right red-eye effect values are within the interval [-10000,10000]. Values near -10000 indicate 'no red-eye effect present', values near 10000 indicate 'red-eye effect present'. The decision threshold is around 0.

redEyeLeft

The face attribute for evaluating whether the red-eye effect is present on the left eye. Left red-eye effect values are within the interval [-10000,10000]. Values near -10000 indicate 'no red-eye effect present', values near 10000 indicate 'red-eye effect present'. The decision threshold is around 0.

roll

This attribute is deprecated in favor of rollAngle attribute and will be removed in the next major relase.

The face attribute for evaluating whether the head roll is within a specific interval. Roll rotation values are within the interval [-10000,10000]. Values near -10000 indicate 'too left rotated', values near 10000 indicate 'too right rotated', values around 0 indicate OK. The decision thresholds are around -5000 and 5000.

yaw

This attribute is deprecated in favor of yawAngle attribute and will be removed in the next major relase.

The face attribute for evaluating whether the head yaw is within a specific interval. Yaw rotation values are within the interval [-10000,10000]. Values near -10000 indicate 'too left rotated', values near 10000 indicate 'too right rotated', values around 0 indicate OK. The decision thresholds are around -5000 and 5000.

pitch

This attribute is deprecated in favor of pitchAngle attribute and will be removed in the next major relase.

The face attribute for evaluating whether the head pitch is within a specific interval. Pitch rotation values are within the interval [-10000,10000]. Values near -10000 indicate 'pitch too down', values near 10000 indicate 'pitch too up', values around 0 indicate OK. The decision thresholds are around -5000 and 5000.

rollAngle

The face attribute representing angle rotation of head towards camera reference frame around Z-axis as per DIN9300.

yawAngle

The face attribute representing angle rotation of head towards camera reference frame around Y-axis as per DIN9300.

pitchAngle

The face attribute representing angle rotation of head towards camera reference frame around X-axis as per DIN9300.

eyeDistance

The face attribute for evaluating the distance between eyes in pixels.

faceConfidence

The face attribute for evaluating the confidence score of the face related to the face detection. Face confidence values are within the interval [0,10000]. The higher the value of the attribute, the better quality of the face. The decision thresholds are around 600, but it depends on the face image quality, camera angle, etc.

Non-ICAO attributes

NameDescription

glassStatus

The face attribute for evaluating the presence of glasses. Glasses values are within the interval [-10000,10000]. Values near -10000 indicate 'no glasses present', values near 10000 indicate 'glasses present'. The decision threshold is around 0. This attribute can be also taken as an ICAO feature.

passiveLiveness

The face attribute for evaluating the passive liveness score of a face. Passive liveness score values are within the interval [0,100]. Values near 0 indicate 'face not live', values near 100 indicate 'face live'.

Appendix

Changelog

6.9.0 - 2021-12-10

Changed
  • Update IFace to 4.14.0

  • Change default face detection mode and age and gender detection mode to accurate.

  • Updated documentation to explain the restrictions for min face size ratio.

  • API: new error with code FACE_SIZE_MEMORY_LIMIT will be returned if the requested face size ratio is out of acceptable range.

Added
  • New application property: innovatrics.dot.core.iface.face-detection.max-image-size

Fixed
  • Fix the dependenciesFulfilled value for passiveLiveness attribute.

6.8.0 - 2021-10-01

Added
  • API: IcaoAttributes yawAngle, rollAngle and pitchAngle added. Old attributes yaw,roll and pitch are deprecated.

  • Check if logs directory is properly mounted to host machine when application is running in the docker image # Changed

  • API: All decimal numbers will be returned rounded to 7 decimal places.

  • API: Passive liveness value will be normalized to <0.0, 100.0>

  • Update IFace to 4.13.0

6.7.0 - 2021-06-03

  • Update IFace to 4.10.0

6.6.0 - 2021-05-04

  • Add Tinted Glasses Face Attribute

  • Update IFace to 4.9.1

6.5.0 - 2021-04-21

Added
  • New application property: innovatrics.dot.core.iface.age-gender-speed-accuracy-mode.

6.4.0 - 2021-04-12

  • Update IFace to 4.8.0 (templates are incompatible).

6.3.0 - 2021-03-12

Changed
  • Update IFace to 4.4.0 (templates are incompatible).

  • Deployment now requires library and solver files (details in documentation)

  • Configure tracing by properties instead of environment variables

Added
  • API: added CORRUPTED_TEMPLATES and WRONG_VERSION_TEMPLATES error codes to /face/verify

  • API: property added to /face/detect and /face/detect-many request

  • Allows removal of background from cropped image

  • New application property: innovatrics.dot.core.iface.solvers.path.

  • New application properties for the background removal: innovatrics.dot.core.iface.background-removal.*

6.2.1 - 2020-09-08

Fixed
  • Postman collection.

6.2.0 - 2020-09-07

Changed
  • Update IFace to 3.13.1 (templates are incompatible).

Fixed
  • Fix Technical documentation.

6.1.0 - 2020-07-24

Added
  • New application property: innovatrics.dot.core.iface.face-detection.speed-accuracy-mode.

6.0.0 - 2020-06-29

Changed
  • API: Increasing the version and the endpoints reorganization.

  • Enhance the endpoints /face/detect and /face/detect-many to serve face attributes. The face attributes contain glassStatus and passiveLiveness attributes.

  • Remove the endpoint /face/check-liveness-passive.

  • Update IFace to 3.10.2 (templates are incompatible).

5.2.0 - 2020-02-21

Added
  • API: Endpoint /v5/face/check-liveness-passive: perform passive liveness check.

Changed
  • API:

  • /v5/face/check-liveness?type=active/v5/face/check-liveness-active

  • Update IFace to 3.8.1.

  • New accuracy mode balanced for the template extraction.

  • The template version changed from 1.20 to 1.26. The template changes are not compatible.

Fixed
  • Postman collection (rename eyeDistancefaceSizeRatio).

5.1.0 - 2020-01-31

Changed
  • API: don’t provide a license expiration in the application info.

5.0.0 - 2020-01-23

Added
  • API: Endpoint /api/v5/face/detect-many: detect face images batch operation.

Changed
  • API: Increasing the version and the endpoints reorganization.

  • /v4/detect-faces/v5/face/detect

  • /v4/verify/v5/face/verify

  • /v4/verify-batch/v5/face/verify-many

  • /v4/check-liveness/v5/face/check-liveness?type=active

  • /v4/parse-machine-readable-zone/v5/machine-readable-zone/parse

  • /v4/decode-barcode/v5/barcode/decode

  • /v4/actuator/info/v5/actuator/info

  • API: The Core Server returns BAD_REQUEST HTTP status code only in cases when a request contains a syntax error or the request images can’t be processed (broken encoding, format,…​). When functionality can’t be delivered for an other reason as a broken request, the Core Server returns OK HTTP status code with the particular response that is going contain an error code. Changes are made for following bad request error codes:

  • NO_FACE_DETECTED

  • PROBE_IMAGE_NO_FACE_DETECTED

  • REFERENCE_IMAGE_NO_FACE_DETECTED

  • MULTIPLE_FACES_DETECTED

  • INCOMPATIBLE_TEMPLATES

  • NOT_ENOUGH_DATA

  • INVALID_MACHINE_READABLE_ZONE_CONTENT

  • NO_BARCODE_DETECTED

  • BARCODE_CHECKSUM_FAILED

  • BARCODE_INVALID_FORMAT

  • The application properties were moved under innovatrics.dot.core.

  • http.logging.payloadinnovatrics.dot.core.http.logging.payload

  • tracinginnovatrics.dot.core.tracing

  • iface.license.filepathinnovatrics.dot.core.iface.license.filepath

  • iface.face-detection.confidence-thresholdinnovatrics.dot.core.iface.face-detection.confidence-threshold

  • iface.face-template.extraction-speed-accuracy-modeinnovatrics.dot.core.iface.face-template.extraction-speed-accuracy-mode

  • iface.track.liveness-eye-valid-thresholdinnovatrics.dot.core.iface.track.liveness-eye-valid-threshold

  • iface.track.liveness-eye-status-thresholdinnovatrics.dot.core.iface.track.liveness-eye-status-threshold

  • iface.track.dot-position-time-deltainnovatrics.dot.core.iface.track.dot-position-time-delta

  • iface.min-face-size-ratioinnovatrics.dot.core.iface.min-face-size-ratio

  • iface.max-face-size-ratioinnovatrics.dot.core.iface.max-face-size-ratio

  • ` liveness.default-min-valid-segment-count` → innovatrics.dot.core.liveness.default-min-valid-segment-count

  • The application default port changed from 9000 to 8080.

Fixed
  • The transaction counting.

4.1.0 - 2019-10-03

Added
  • API: Endpoint /api/v4/decode-barcode: Barcode image decoding.

Fixed
  • Fix Technical documentation.

4.0.1 - 2019-09-20

Fixed
  • Fix Technical documentation.

4.0.0 - 2019-09-20

Added
  • Add application properties: iface.track.liveness-eye-status-threshold and iface.track.dot-position-time-delta.

  • API: Endpoint /api/v4/verify-batch: Multiple face image/template verification.

Changed
  • API: Endpoint URL /api/v3/detect-face changed to /api/v4/detect-faces.

  • API: Add support for multiple faces for /api/v4/detect-faces endpoint.

  • API: New elements in endpoint /api/v4/detect-faces response body: age, gender.

  • API: Remove all non-ICAO attributes from IcaoAttributes object.

  • API: Add new element rangeStatus to IcaoAttribute object.

  • Update IFace to 3.6.0.

  • Rename application property: iface.min-eye-distance-ratio to iface.min-face-size-ratio.

  • Rename application property: iface.max-eye-distance-ratio to iface.max-face-size-ratio.

3.5.1 - 2019-09-09

Fixed
  • Fix native crash when under heavy load on /api/v3/check-liveness endpoint.

3.5.0 - 2019-06-12

Added
  • Add application properties: iface.face-detection.confidence-threshold and iface.face-template.extraction-speed-accuracy-mode.

  • API: Actuator Info public endpoint.

3.4.1 - 2019-05-22

Fixed
  • Machine Readable Zone: Field position - last character index.

3.4.0 - 2019-05-17

Changed
  • Change default logs destination to /logs folder.

  • Change default logs max size to 100MB.

  • Update Technical documentation.

Fixed
  • Machine Readable Zone: Add support for long Document Number exception.

3.3.3 - 2019-05-06

Fixed
  • Fix native crash when under heavy load on /api/v3/check-liveness endpoint.

3.3.2 - 2019-04-26

Changed
  • Reduce eye confidence threshold for Liveness Check to minimize cases where liveness cannot be evaluated.

3.3.1 - 2019-04-17

Changed
  • Update IFace to 3.5.3.

3.3.0 - 2019-04-03

Added
  • API: New optional element in endpoint /api/v3/check-liveness request body: minValidSegmentCount.

Changed
  • Update Opentracing/Jaeger implementation.

  • Update Technical documentation: Tracing.

  • Update Technical documentation: Externalized configuration/DOT Core Server specific properties.

  • Rename application property: iface.licence.filepathiface.license.filepath.

3.2.0 - 2019-02-11

Changed
  • Turn off logfile, metrics, prometheus actuator endpoints by default.

  • Update IFace to 3.5.1. Face templates from previous versions are incompatible and must be regenerated.

  • Bundle IFace Shared Object to distribution package.

  • Update Technical documentation.

3.1.0 - 2019-02-04

Added
  • API: New element in endpoint /api/v3/detect-face response body: templateVersion.

Changed
  • Distribution package: application.yml - change placeholders to regular values.

DOT Core Server Dockerfile example

##########################################################################################################
#
# DOT Core Server Dockerfile
#
# Prepare for Docker image build:
# - set correct configuration values in config/application.yml
#
# Build Docker image:
# docker build -t dot-core-server:tag .
#
# Run the container:
# docker container run -v /local/path/to/license/dir/:/srv/dot-core-server/license -p 9000:8080 dot-core-server:tag
#
# Alternative: Run the container with persisting log files in the local filesystem:
# 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 9000:8080 dot-core-server:tag
#
# Keep in mind that your IFace license file must be present in the folder /local/path/to/license/dir/.
#
##########################################################################################################

# Use an openjdk:11-jre-slim as a parent image
FROM openjdk:11-jre-slim

# Defines default logs location
ENV LOGS_DIR=/srv/dot-core-server/logs
# Defines  java opts env
ENV JAVA_OPTS=''

# Set the working directory
WORKDIR /srv/dot-core-server

# Copy IFace shared object file
COPY libiface.so.4.14.0 /srv/dot-core-server/iface/

# Copy IFace solvers
COPY solvers /srv/dot-core-server/iface/solvers

# Copy the DOT Core Server JAR file
COPY dot-core-server.jar /srv/dot-core-server

# Copy the application configuration file
COPY config/application.yml /srv/dot-core-server/

# Install necessary libraries and create a link to the library previously copied to our workdir
RUN apt-get update && apt-get install -y curl libusb-0.1 libgomp1 && ldconfig /srv/dot-core-server/iface/

# Make the port 8080 available outside this container
EXPOSE 8080

# Run DOT Core Server when the container launches
CMD java -jar $JAVA_OPTS dot-core-server.jar -Djna.library.path=/srv/dot-core-server/iface/