.. index:: 
  !Face detection

.. _face_detection:

==============
Face detection
==============

The :ref:`FaceDetector<id3_face_face_detector_class>` class detects human faces in still images.

.. important:: 
  | The face detector requires a machine learning model to be loaded into memory. The model should be selected according to the target platform and use-case.
  | See :ref:`ai_models` for details.

.. note:: Call the :ref:`id3_face_face_library_load_model_class_method` to load the chosen model on application start.

.. hint:: On startup, call the :ref:`id3_face_face_detector_warm_up_class_method` to prepare inference of the AI model.

Tolerance
=========

The face detection tolerance depends on the AI model used. The following characteristics can be assumed:

.. list-table:: 
    :widths: 30 70

    * - Face angle tolerance
      - yaw < ±45°, pitch < ±30°, roll < 45°
      
    * - Minimal interocular distance (IOD)
      - 10 pixels

.. warning:: The algorithm searches for faces in the range [16px;512px]. If the image is too large to fit this range, one must resize it before the detection process.
.. hint:: For optimum facial recognition performance, a minimum distance of 100 pixels between eyes is recommended.

.. _detected_face:

Detected face
=============
The :ref:`FaceDetector<id3_face_face_detector_class>` outputs a list of :ref:`DetectedFace<id3_face_detected_face_class>` objects containing the following information:

- :ref:`face_id`
- :ref:`face_detection_score`
- :ref:`face_detection_face_bounds`
- :ref:`face_detection_portrait_bounds`
- Interocular distance (IOD)
- Landmarks (eyes, nose and mouth)

.. note:: Only faces with a confidence score above the configured threshold are returned. See :ref:`face_detection_parameters` for details.

.. _face_id:

Face ID
-------

The face ID is an auto-incremented value used to track faces.

.. warning:: The face ID is not linked to a user's identity.

.. _face_detection_score:

Confidence score
----------------

The confidence score ranges from 0 to 100. A high confidence score indicates that it is more likely that the face detected is really a face.

.. _face_detection_face_bounds:

Face bounds
-----------

|product-name| detects human faces and returns a rectangle around the detected faces, as shown in the figure
below.

.. image:: img/Multi-face-recognition.jpg
  :width: 50%


.. _face_detection_portrait_bounds:

Portrait bounds
---------------

|product-name| detects human faces and returns a rectangle for ISO/ICAO compliant portraits, as shown in the
figure below.

.. image:: img/face-portrait-rectangle.jpg
  :width: 50%


.. _face_detection_parameters:

Parameters
==========

The face detector is configured by default with the most common parameters. For specific applications, it may be useful to adjust certain parameters.

The following parameters are defined:

.. list-table:: 
  :width: 100%
  :widths: 30 70
  :header-rows: 1

  * - Name
    - Description

  * - Confidence threshold
    - | Value above which the detector considers the detected element to be a face.
      | Setting a high threshold reduces false detection but can increase the number of undetected faces.

  * - Model
    - :ref:`face_detection_models` used to detect faces.
  
  * - NMS IoU threshold
    - | Non-maximum suppression (NMS) intersection-over-union (IoU) threshold.
      | Setting a high threshold allows to detect more overlapping faces which can be useful in a multi-face scenario. On the contrary, in a portrait scenario, a low NMS IoU threshold should be preferred.

      .. image:: /_static/images/iou.bmp
        :width: 264

  * - Thread count
    - Number of threads to use for face detection. Default is 1.
 

Example
=======

The example below demonstrates how to detect faces in an image:

.. tab-set::

  .. tab-item:: Python
    :sync: Python

    .. literalinclude:: /../samples/sample.py
      :language: python
      :start-after: [face_detection]
      :end-before: [face_detection]
      :dedent: 4



See also
========

- :ref:`id3_face_face_detector_class`
- :ref:`id3_face_detected_face_list_class`
- :ref:`id3_face_detected_face_class`