Using IDLive Face Server¶

Start container¶

To start the IDLive Face Server's container use docker run command:

docker run --name idliveface -d -p 8080:8080 idface-server-eval:1.47.0

It has the following arguments:

• --name idliveface names the started container as idliveface,
• -d starts the container in the background,
• -p 8080:8080 exposes the port 8080,
• idface-server-eval:1.47.0 is the name of the image.

Note that the name of the image should always be the last argument.

If you use the GPU version of the Server you need to expose your GPU to the container:

docker run --name idliveface --gpus all ...

The Server is ready after it prints Started IDLiveFaceServerApplication to logs. You can check them with:

docker logs idliveface

Once you see the message the Server is ready to use. To stop and delete the container run these commands:

docker stop idliveface
docker rm idliveface

docker run --name idliveface --cap-add=SYS_PTRACE ...

Perform liveness check¶

apt-get install curl

python -m pip install requests

To make a liveness check you need to upload an image as a multipart/form-data HTTP request to the /check_liveness endpoint. For example to upload an image named selfie.png do:

curl "http://localhost:8080/check_liveness" --form image=@selfie.png

import requests

files = {"image": open("selfie.png", "rb")}
resp = requests.post("http://localhost:8080/check_liveness", files=files)

print(resp.text)

IDLive Face supports JPEG, PNG and other image formats.

The Server will return a JSON response like this one:

{ "probability": 0.9946032, "quality": 0.72107375, "score": 5.2165456 }

It contains the following values:

probability

The main factor to decide if the image is live or spoofed. The value can be in range [0,1]. The image can be considered live if the probability is 0.5 or higher.

quality

How "appropriate" the image is for the liveness check. The value can be in range [0,1]. Images with the quality values lower than 0.5 should generally be rejected.

score

The raw liveness score. The bigger the score the higher the image's liveness. Can be used for APCER / BPCER tuning and is provided mostly for calibration purposes. The value is unbound.

If you configured the Server to use multiple pipelines you can specify which one to use with the pipeline query parameter:

http://localhost:8080/check_liveness?pipeline=dionysus

Meta header¶

You can provide additional information about the image to improve the liveness checks. To do that you need to form a special JSON string and send it alongside with the image in the Meta HTTP header:

curl "http://localhost:8080/check_liveness" \
    --form image=@selfie.png \
    --header 'Meta: {"OS": "DESKTOP", "CALIBRATION": "SOFT"}'

import json
import requests

files = {"image": open("selfie.png", "rb")}
headers = {"Meta": json.dumps({"OS": "DESKTOP", "CALIBRATION": "SOFT"})}
resp = requests.post("http://localhost:8080/check_liveness",
                     files=files, headers=headers)

print(resp.text)

The JSON can contain the following fields:

OS

The environment the image was taken in. Possible values are IOS, ANDROID, DESKTOP or UNKNOWN (the default). DESKTOP corresponds to a desktop webcam or other IP camera. We strongly encourage you to specify this parameter if you know the source of the image because the software adjusts internal settings based on the image source. If you do not know the source of the image, the software will attempt to determine the source of the image based on characteristics in the image.

CALIBRATION

APCER / BPCER balance:

• REGULAR (the default) targets low APCER.
• SOFT achieves lower BPCER while still having acceptable APCER.
• HARDENED targets extra low APCER with higher BPCER.

Since the JSON is being sent as a HTTP header make sure it does not contain line breaks. The names of JSON fields and their values are case-insensitive.

Multiple images¶

You can send a series of images. The liveness check will be done for each one, and the single result will be produced by accumulating the results from the all images processed.

curl "http://localhost:8080/check_liveness" \
    --form image1=@selfie.png \
    --form image2=@another_selfie.png

import requests

files = {"image1": open("selfie.png", "rb"),
         "image2": open("another_selfie.png", "rb")}
resp = requests.post("http://localhost:8080/check_liveness", files=files)

print(resp.text)

Collect Business Intelligence logs¶

IDLive Face Server records the results of each liveness check in the Business Intelligence logs. You can see the history of the checks via the /bi_records endpoint:

curl 'http://localhost:8080/bi_records'

These logs are saved inside the container, and will be lost on each restart. To persist the logs use the Docker's volume:

docker run \
    --volume /var/log/idliveface:/logs \
    ...

This way the logs will be saved to /var/log/idliveface (or any other directory of your choice). You can read more about the Business Intelligence logs in the configuration section.