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.46.0
It has the following arguments:
--name idliveface
names the started container asidliveface
,-d
starts the container in the background,-p 8080:8080
exposes the port8080
,idface-server-eval:1.46.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
SYS_PTRACE capability
If you use Linux kernel older than 4.8 or your Docker’s version is older than 19.03 you need to additionally enable ptrace capability when starting the container:
docker run --name idliveface --cap-add=SYS_PTRACE ...
Otherwise the Server may fail to start. This requirement was removed in the version 1.31.
Perform liveness check¶
How to use code examples
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
orUNKNOWN
(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.
Note
Before the version 1.30 the name of the fields in JSON were required to be in upper-case.
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.