.. _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 ``docker.int.ntl/ntech/universe/extraction-api-cpu`` image) or GPU (installed from the ``docker.int.ntl/ntech/universe/extraction-api-gpu`` image). For both CPU- and GPU-accelerated services, configuration is done through the ``findface-extraction-api.yaml`` configuration file. You can find its default content :download:`here for CPU <_scripts/findface-extraction-api-cpu.yaml>` and :download:`here for GPU <_scripts/findface-extraction-api-gpu.yaml>`.

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


.. list-table::
     :widths: 14 45
     :header-rows: 1

     * - Parameter
       - Description
     * - ``detectors`` → ``max_batch_size``
       - Upper limit on detection batch size. When using the CPU, you can specify ``max_batch_size: -1``, then the detector maximum batch size will correspond to the number of CPU cores (default 1).
     * - ``normalizers`` → ``max_batch_size``
       - Upper limit on normalization batch size. When using the CPU, you can specify ``max_batch_size: -1``, then the normalizer maximum batch size will correspond to the number of CPU cores (default 1).
     * - ``extractors`` → ``max_batch_size``
       - Upper limit on extraction batch size. When using the CPU, you can specify ``max_batch_size: -1``, then the extractor maximum batch size will correspond to the number of CPU cores (default 1).
     * - ``detectors`` → ... → ``min_object_size``
       - The minimum size of an object (bbox) guaranteed to be detected. The larger the value, the less resources required for object detection.
     * - ``gpu_device``
       - (Only for GPU) GPU device ID used by ``findface-extraction-api-gpu``.
     * - ``license_ntls_server``
       - The ``findface-ntls`` license server IP address and port.

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

* :ref:`face-features`.
* :ref:`liveness`
* :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.