`findface-extraction-api`

The findface-extraction-api service uses neural networks to detect a face in an image, extract face biometric data (feature vector), and recognize gender, age, emotions, and other features.

It interfaces with the findface-sf-api service as follows:

Gets original images with faces and normalized face images.
Returns the coordinates of the face bounding box, and (optionally) feature vector, face feature data, should these data be requested by findface-sf-api.

Tip

You can use HTTP API to directly access findface-extraction-api.

Functionality:

face detection in an original image (with return of the bbox coordinates),
face normalization,
feature vector extraction from a normalized image,
gender/age/emotions/country recognition.

The findface-extraction-api service can be based on CPU (installed from the findface-extraction-api package) or GPU (installed from the findface-extraction-api-gpu package). For both CPU- and GPU-accelerated services, configuration is done through the /etc/findface-extraction-api.ini configuration file. Its content varies subject to the acceleration type.

CPU-service configuration file:

allow_cors: false
detector_instances: 0
dlib:
  model: /usr/share/findface-data/normalizer.dat
  options:
    adjust_threshold: 0
    upsample_times: 1
extractors:
  instances: 1
  max_batch_size: 16
  models:
    age: ""
    beard: ""
    emotions: ""
    face: face/grapefruit_480.cpu.fnk
    gender: ""
    glasses3: ""
    liveness: ""
  models_root: /usr/share/findface-data/models
fetch:
  enabled: true
  size_limit: 10485760
license_ntls_server: 127.0.0.1:3133
listen: 127.0.0.1:18666
max_dimension: 6000
nnd:
  model: /usr/share/nnd/nnd.dat
  options:
    max_face_size: .inf
    min_face_size: 30
    o_net_thresh: 0.9
    p_net_max_results: 0
    p_net_thresh: 0.5
    r_net_thresh: 0.5
    scale_factor: 0.79
  quality_estimator: true
  quality_estimator_model: /usr/share/nnd/quality_estimator_v2.dat
ticker_interval: 5000

GPU-service configuration file:

listen: 127.0.0.1:18666
dlib:
  model: /usr/share/findface-data/normalizer.dat
  options:
    adjust_threshold: 0
    upsample_times: 1
nnd:
  model: /usr/share/nnd/nnd.dat
  quality_estimator: true
  quality_estimator_model: /usr/share/nnd/quality_estimator_v2.dat
  options:
    min_face_size: 30
    max_face_size: .inf
    scale_factor: 0.7900000214576721
    p_net_thresh: 0.5
    r_net_thresh: 0.5
    o_net_thresh: 0.8999999761581421
    p_net_max_results: 0
detector_instances: 0
extractors:
  models_root: /usr/share/findface-data/models
  max_batch_size: 3
  instances: 2
  models:
    age: ""
    beard: ""
    emotions: ""
    face: face/grapefruit_480.gpu.fnk
    gender: ""
    glasses3: ""
    liveness: ""
  cache_dir:
  gpu_device: 0
license_ntls_server: 172.17.46.26:3133
fetch:
  enabled: true
  size_limit: 10485760
max_dimension: 6000
allow_cors: false
ticker_interval: 5000

When configuring findface-extraction-api (on CPU or GPU), refer to the following parameters:

Parameter	Description
`nnd` -> `quality_estimator`	Enables face quality estimation. In this case, `findface-extraction-api` returns a face quality score in the `detection_score` field. Interpret the quality score further in analytics. Upright faces in frontal position are considered the best quality. They result in values around 0, mostly negative (such as -0.00067401276, for example). Inverted faces and large face angles are estimated with negative values some -5 and less.
`nnd` -> `min_face_size`	The minimum size of a face (bbox) guaranteed to be detected. The larger the value, the less resources required for face detection.
`nnd` -> `max_face_size`	The minimum size of a face (bbox) guaranteed to be detected.
`license_ntls_server`	The `ntls` license server IP address and port.
`gpu_device`	(Only for GPU) The number of the GPU device used by `findface-extraction-api-gpu`.
`models` -> `instances`	The number of neural network instances (and, consequently, the number of simultaneously processed requests) that are loaded into RAM by `findface-extraction-api`. Specify the number of instances from your license. The default value (0) means that this number is equal to the number of CPU cores. This parameter severely affects RAM consumption.
`fetch` -> `enabled`	Enables fetching images from the Internet.
`fetch` -> `size_limit`	The maximum size of an Internet image to be fetched.

You will also have to enable recognition models for face features such as gender, age, emotions, glasses3, and/or beard, subject to your needs. Be sure to choose the right acceleration type for each model, matching the acceleration type of findface-extraction-api: CPU or GPU. Be aware that findface-extraction-api on CPU can work only with CPU-models, while findface-extraction-api on GPU supports both CPU- and GPU-models.

models:
  age: faceattr/age.v1.cpu.fnk
  emotions: faceattr/emotions.v1.cpu.fnk
  face: face/grapefruit_480.cpu.fnk
  gender: faceattr/gender.v2.cpu.fnk
  beard: faceattr/beard.v0.cpu.fnk
  glasses3: faceattr/glasses3.v0.cpu.fnk

The following models are available:

Face feature	Acceleration	Configuration file parameter
face (biometry)	CPU	`face: face/grapefruit_480.cpu.fnk` `face: face/grapefruit_160.cpu.fnk`
face (biometry)	GPU	`face: face/grapefruit_480.gpu.fnk` `face: face/grapefruit_160.gpu.fnk`
age	CPU	`age: faceattr/age.v1.cpu.fnk`
age	GPU	`age: faceattr/age.v1.gpu.fnk`
gender	CPU	`gender: faceattr/gender.v2.cpu.fnk`
gender	GPU	`gender: faceattr/gender.v2.gpu.fnk`
emotions	CPU	`emotions: faceattr/emotions.v1.cpu.fnk`
emotions	GPU	`emotions: faceattr/emotions.v1.gpu.fnk`
glasses3	CPU	`glasses3: faceattr/glasses3.v0.cpu.fnk`
glasses3	GPU	`glasses3: faceattr/glasses3.v0.gpu.fnk`
beard	CPU	`beard: faceattr/beard.v0.cpu.fnk`
beard	GPU	`beard: faceattr/beard.v0.gpu.fnk`

Tip

To disable a recognition model, simply pass an empty value to a relevant parameter. Do not remove the parameter itself as in this case the system will be searching for the default model.

models:
  gender: ""
  age: ""
  emotions: ""

findface-extraction-api

`findface-extraction-api`