.. _extraction-api-config: ``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 :ref:`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. .. rubric:: CPU-service configuration file: .. code:: 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 .. rubric:: GPU-service configuration file: .. code:: 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. .. code:: 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 | CPU | ``face: face/grapefruit_480.cpu.fnk`` ``face: face/grapefruit_160.cpu.fnk`` | | (biometry) +--------------+--------------------------------------------------------------------------------+ | | GPU | ``face: face/grapefruit_480.gpu.fnk`` ``face: face/grapefruit_160.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. .. code:: models: gender: "" age: "" emotions: ""