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: ''
    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:

allow_cors: false
detector_instances: 0
dlib:
  model: /usr/share/findface-data/normalizer.dat
  options:
    adjust_threshold: 0
    upsample_times: 1
extractors:
  instances: 2
  max_batch_size: 16
  models:
    age: ''
    emotions: ''
    face: face/elderberry_576.gpu.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.8999999761581421
    p_net_max_results: 0
    p_net_thresh: 0.5
    r_net_thresh: 0.5
    scale_factor: 0.7900000214576721
  quality_estimator: true
  quality_estimator_model: /usr/share/nnd/quality_estimator_v2.dat
prometheus:
  faces_buckets:
  - 0
  - 1
  - 2
  - 5
  - 10
  - 20
  - 50
  - 75
  - 100
  - 200
  - 300
  - 400
  - 500
  - 600
  - 700
  - 800
  - 900
  - 1000
  resolution_buckets:
  - 10000
  - 20000
  - 40000
  - 80000
  - 100000
  - 200000
  - 400000
  - 800000
  - 1e+06
  - 2e+06
  - 3e+06
  - 4e+06
  - 5e+06
  - 6e+06
  - 8e+06
  - 1e+07
  - 12000000.0
  - 15000000.0
  - 18000000.0
  - 2e+07
  - 3e+07
  - 5e+07
  - 1e+08
  timing_buckets:
  - 0.001
  - 0.005
  - 0.01
  - 0.02
  - 0.03
  - 0.05
  - 0.1
  - 0.2
  - 0.3
  - 0.5
  - 0.75
  - 0.9
  - 1
  - 1.1
  - 1.3
  - 1.5
  - 1.7
  - 2
  - 3
  - 5
  - 10
  - 20
  - 30
  - 50
ticker_interval: 5000

When configuring findface-extraction-api (CPU- or GPU-based), 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.
models -> model_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 you license. The default value (0) means that this number is equal to the number of CPU cores. This parameter severely affects RAM consumption.
license_ntls_server	The ntls license server IP address and port.
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/elderberry_576.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/elderberry_576.cpu.fnk
	GPU	face: face/elderberry_576.gpu.fnk
age	CPU	age: faceattr/age.v1.cpu.fnk
	GPU	age: faceattr/age.v1.gpu.fnk
gender	CPU	gender: faceattr/gender.v2.cpu.fnk
	GPU	gender: faceattr/gender.v2.gpu.fnk
emotions	CPU	emotions: faceattr/emotions.v1.cpu.fnk
	GPU	emotions: faceattr/emotions.v1.gpu.fnk
glasses3	CPU	glasses3: faceattr/glasses3.v0.cpu.fnk
	GPU	glasses3: faceattr/glasses3.v0.gpu.fnk
beard	CPU	beard: faceattr/beard.v0.cpu.fnk
	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: ""