.. _ai_models:

=========
AI Models
=========

This SDK makes extensive use of AI models, particularly for detection, analysis and facial recognition tasks.
Wherever possible, one model is used for several tasks, as in the case of the face attributes classifier model, which detects glasses, hats, make-up, mouth opening, smiles and gender. But as a general rule, an AI model is dedicated to a single task.

The following models are available:

.. |FaceBackgroundUniformityEstimator1A| replace:: face_background_uniformity_estimator_v1a.id3nn

.. _face_detection_models:

Face detection models
=====================

.. list-table::
    :width: 100
    :widths: 20 20 60
    :header-rows: 1

    * - Name
      - Size
      - Description

    * - FaceDetector4A
      - 8.29 MB
      - This model provides the best accuracy. It is recommended for 1-to-N applications or in an uncontrolled environment.

    * - FaceDetector4B
      - 1.25 MB
      - This model provides a good balance of accuracy, speed, and size. This model is less robust to variations of head pose than the 4A version and should therefore only be used in a controlled environment.

    * - FaceDetector3A
      - 57.66 MB
      - :guilabel:`Obsolete`. Provided for backward compatibility. Use model 4A whenever possible.

    * - FaceDetector3B
      - 0.98 MB
      - :guilabel:`Obsolete`. Provided for backward compatibility. Use model 4B whenever possible.

    * - FaceDetector3C
      - 0.22 MB
      - Ultra-light detector, dedicated to short-range real-time detection/tracking applications only.

.. _face_analysis_models:

Face analysis models
====================

.. list-table:: 
    :widths: 20 80
    :header-rows: 1

    * - Name
      - Description

    * - CompressionArtifactsRemover1A
      - Removes image compression artifacts.  

    * - EyeGazeEstimator2A
      - Estimates the direction of gaze.

    * - EyeOpennessDetector1A
      - Detects the degree of eye opening.
      
    * - EyeRednessDetector1A
      - Detects red-eye.

    * - FaceAgeEstimator1A
      - Estimates the subject's age. 

    * - FaceAttributesClassifier2A
      - Detects facial attributes such as glasses, hat, make-up, mouth opening, smile and gender of the subject.  

    * - FaceBackgroundSegmenter1A
      - Removes the background.   

    * - FaceBackgroundUniformityEstimator1A
      - Estimates color and structure uniformity of the background.   

    * - FaceEncodingQualityEstimator3A
      - Estimates the quality of the encoded template. 

    * - FaceExpressionClassifier1A
      - Face expression classifier. 

    * - FaceLandmarksEstimator2A
      - Extracts 68 landmark features. 

    * - FaceMaskClassifier2A
      - Detects the presence of a protective mask on a subject's face. 

    * - FaceOcclusionDetector2A
      - Detects occlusions on the subject's face (eyes, nose, mouth) 

    * - FacePoseEstimator1A
      - Estimates the pose of the face (yaw pitch, roll). 

    * - FaceSegmenter2A
      - Divides the input face image into distincts facial regions (e.g., eyes, nose, mouth, and other key landmarks).

.. _face_encoding_models:

Face encoding models
====================

.. list-table::
    :width: 100
    :widths: 20 20 60
    :header-rows: 1

    * - Name
      - Size
      - Description

    * - FaceEncoder9A
      - 127.36 MB
      - This model provides the best accuracy. It is recommended for 1-to-N applications or in an uncontrolled environment. Generated template size is 264 bytes.

    * - FaceEncoder9B
      - 1.99 MB
      - This model provides a good balance of accuracy, speed, and size. This model is less robust to variations of head pose than the 9A version and should therefore only be used in a controlled environment. Generated template size is 140 bytes.

    * - FaceEncoder8A
      - 152.46 MB
      - :guilabel:`Obsolete`. Provided for backward compatibility. Use model 9A whenever possible. Generated template size is 268 bytes.

    * - FaceEncoder8B
      - 2.12 MB
      - :guilabel:`Obsolete`. Provided for backward compatibility. Use model 9B whenever possible. Generated template size is 140 bytes.

    * - FaceEncodingQualityEstimator3A
      - 3.09 MB
      - Estimates the quality of the encoded template. 

    * - FacePeriocularEncoder2A
      - 120 MB
      - Encodes templates using only the periocular region of the subject's  face. Highest accuracy periocular encoder in this SDK. Provides an efficient alternative to face encoders when people wear masks in server-based 1:N applications. 

Presentation attack detection models
====================================

.. list-table:: 
    :widths: 20 20 60
    :header-rows: 1

    * - Name
      - Size
      - Description

    * - FaceAttackSupportDetector3A
      - 5.82 MB
      - | :guilabel:`Obsolete` Detects presentation attacks that use media such as screen, print, or ID card.   

    * - FaceBlurinessDetector1A
      - 0.79 MB
      - :guilabel:`Obsolete` Detects presentation attacks that tend to create blurry images.   

    * - FaceColorBasedPad2A
      - 21.8 MB
      - | Detects presentation attacks using a color-based method.  
        | :guilabel:`Obsolete` Replaced by version 3A.

    * - FaceColorBasedPad3A
      - 6.72 MB
      - Detects presentation attacks using a color-based method.  

    * - FaceDepthPad3A
      - 0.04 MB
      - Detects presentation attacks using depth-based method.  


AI model files
==============

AI model files have the ``.id3nn`` extension. You must copy the necessary data files into your application package. If you wish to reduce the size of your application, we recommend copying only the files required by the biometric algorithm.

In your application's source code you should specify location of these files.


.. important::
    
    | Models can be downloaded at the following URL: 
    | https://cloud.id3.eu/index.php/s/y63PysbS3w6NPm6 

.. warning::

    AI model files MUST NOT be renamed.


.. _model_loading:

Loading AI models
=================

It is recommended to load the AI models on application startup. The :ref:`id3_face_face_library_class` provides methods for loading and unloading AI model file in memory.

An example is given below:

.. tab-set::

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

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


Warm-up
=======

The first execution, or inference, of a model takes generally more time. 
To mitigate this problem, a warm-up method can be called on application startup to prepare the inference of model.

For example, you can prepare the face detection model by calling the :ref:`id3_face_face_detector_warm_up_class_method`.

Processing units
================

The inference of the AI models can be executed on either the CPU or the GPU if available, by specifying a :ref:`id3_face_processing_unit_enum`.
The GPU options selects a default backend depending on your platform. Detailed backend options are available to ensure a specific backend.

.. warning::

  Inference on GPU is an experimental feature. Some models might be unstable on some backend or provide nonsense result. 
  We strongly encourage you to verify the results on those backends, and contact our support in case of inadequate behaviour.

See also
========
- :ref:`id3_face_face_library_class`
- :ref:`id3_face_face_library_load_model_class_method`