.. _extraction-api-config:


``findface-extraction-api``
---------------------------------

The ``findface-extraction-api`` service uses neural networks to detect an object in an image, extract the object feature vector, and recognize object attributes (for example, the clothing color for bodies). 

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

* Gets original images with objects and normalized object images.
* Returns the object bounding box coordinates and, if requested by ``findface-sf-api``, feature vector and object attribute data.

Functionality:

* object detection in an original image (with a return of the bbox coordinates),
* object normalization,
* feature vector extraction from a normalized image,
* object attribute recognition (a person's gender, age, emotions; clothing color; car color, car model, 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. You can find its default content :download:`here for CPU <_scripts/findface-extraction-api-cpu.ini.txt>` and :download:`here for GPU <_scripts/findface-extraction-api-gpu.ini.txt>`.

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

+-----------------------------------+----------------------------------------------------------------------------------------------------------+
| Parameter                         | Description                                                                                              |
+===================================+==========================================================================================================+
| ``cheetah`` ->                    | The minimum size of a face (bbox) guaranteed to be detected. The larger the value, the less resources    |
| ``min_object_size``               | required for face detection.                                                                             |
+-----------------------------------+----------------------------------------------------------------------------------------------------------+
| ``gpu_device``                    | (Only for GPU) The number of the GPU device used by ``findface-extraction-api-gpu``.                     |
+-----------------------------------+----------------------------------------------------------------------------------------------------------+
| ``license_ntls_server``           | The ``ntls`` license server IP address and port.                                                         |
+-----------------------------------+----------------------------------------------------------------------------------------------------------+


If necessary, you can also enable recognition models for face attributes, body and body attributes, car and car attributes, and liveness detection. You can find the detailed step-by-step instructions in the following sections:

* :ref:`face-features`.
* :ref:`liveness`
* :ref:`liveness-api`
* :ref:`bodies`
* :ref:`cars`

.. important::
   The acceleration type for each model must match the acceleration type of ``findface-extraction-api``: CPU or GPU. Note that ``findface-extraction-api`` on CPU can work only with CPU-models, while ``findface-extraction-api`` on GPU supports both CPU- and GPU-models. 

.. tip::
   To disable an extractor 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::

      ...
      extractors:
      ...
        models:
          body_color: ''
          body_emben: ''
          body_quality: ''
          car_color: ''
          car_description: ''
          car_emben: ''
          ...