`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, gender, age and emotions data, should these data be requested by findface-sf-api.

Functionality:

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

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: ''
    emotions: ''
    face: face/elderberry_576.cpu.fnk
    gender: ''
  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: :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: false
  quality_estimator_model: /usr/share/nnd/quality_estimator_v2.dat
  options:
    min_face_size: 30
    max_face_size: .inf
    scale_factor: 0.79
    p_net_thresh: 0.5
    r_net_thresh: 0.5
    o_net_thresh: 0.9
    p_net_max_results: 0
detector_instances: 0
extractors:
  models_root: /usr/share/findface-data/models
  max_batch_size: 16
  instances: 0
  models:
    age: faceattr/age.v1.cpu.fnk
    emotions: faceattr/emotions.v1.cpu.fnk
    face: face/elderberry_576.cpu.fnk
    gender: faceattr/gender.v2.cpu.fnk
license_ntls_server: 127.0.0.1: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.

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/elderberry_576.cpu.fnk
  gender: faceattr/gender.v2.cpu.fnk
  beard: faceattr/beard.v0.cpu.fnk

The following models are available:

Face feature	Acceleration	Configuration file parameter
face (biometry)	CPU	`face: face/elderberry_576.cpu.fnk`
face (biometry)	GPU	`face: face/elderberry_576.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`¶