.. _face_analysis:

=============
Face analysis
=============

|product-name| can analyse a wide range of facial attributes. For instance, it can evaluate the compliancy of a portrait to the ISO/IEC 19794-5 full frontal and the ICAO Portrait Quality Standards thanks to the following modules:


.. list-table:: 
    :widths: 30 70
    :header-rows: 1

    * - Attribute
      - Description

    * - :ref:`Age<id3_face_face_analyser_compute_age_class_method>`
      - Estimated age of the subject.

    * - :ref:`Background uniformity<id3_face_face_analyser_compute_background_uniformity_class_method>`
      - Estimated color and structure uniformity of the background in a portrait image. See also :ref:`background_removal`.

    * - :ref:`Colorized image<id3_face_face_analyser_check_colorized_image_class_method>`
      - Value indicating whether an image is colorized or grayscale.

    * - :ref:`Expression<id3_face_face_analyser_compute_expression_class_method>`
      - Estimated facial expressions of a subject classified in six universal emotions: angriness, disgust, fear, happiness, sadness, surprise, and additionally neutral.

    * - :ref:`Eye gaze<id3_face_face_analyser_compute_eye_gaze_class_method>`
      - Estimated gaze direction for both eyes. When the subject looks directly towards the camera, the return values equal 0.

        .. image:: img/eye-gaze.jpg
          :width: 30%

    * - :ref:`Eye opening<id3_face_face_analyser_compute_eye_openness_class_method>`
      - Degree of opening of both eyes. The resulting scores are in the range 0 to 100.

    * - :ref:`Face attributes<id3_face_face_analyser_compute_attributes_class_method>`
      - Group of additional attributes, including:
        
        - Glasses
        - Hat
        - Make-up
        - Male (gender estimation)
        - Mouth opening
        - Smile

    * - :ref:`Face mask<id3_face_face_analyser_detect_face_mask_class_method>`
      - Presence of a protective mask on the subject face.

        .. image:: img/facemask.jpg
          :width: 30%

    * - :ref:`Geometric attributes<id3_face_face_analyser_compute_geometric_attributes_class_method>`
      - Set of geometric characteristics of a portrait image.

        - Resolution: Checks if the image resolution is sufficient.
        - Vertical position: Checks the distance from the bottom edge of the image to the imaginary line passing through the center of the eyes is between 50\% - 70\% of the total vertical length of the image.
        - Horizontal position: Checks if the head is correctly centered horizontally.
        - Width of head: Checks if the image width is conform to the (image width / head width) ratio of 7:5. The head width is defined as the distance between the left and right ears.
        - Length of head:  Checks if the distance between the base of the chin and the crown is less than 80\% of the total height of the image.

        .. image:: img/GeometricAttributes.jpg
          :width: 30%

    * - :ref:`Glasses attributes<id3_face_face_analyser_compute_glasses_attributes_class_method>`
      - Additional set of attributes related to glasses (if present). It includes:
        
        - Frame on eye
        - Heavy frame
        - Tinted glasses
 
        .. image:: img/frame-crossing-the-eyes.jpg
          :width: 30%

    * - :ref:`Head pose<id3_face_face_analyser_compute_pose_class_method>`
      - Estimation of the head pose. Yaw, pitch and roll angles are returned in degrees.

        .. image:: img/headpose.png
          :width: 30%

    * - :ref:`Landmarks<id3_face_face_analyser_compute_landmarks_class_method>`
      - Estimated 68 landmark features

        .. image:: img/facelandmarks.jpg
          :width: 30%

    * - :ref:`Noise<id3_face_face_analyser_compute_noise_class_method>`
      - Quantity of noise in the image.

    * - :ref:`Occlusions<id3_face_face_analyser_detect_occlusions_class_method>`
      - Presence of occlusions on the subject's face (eyes, nose, mouth).

    * - :ref:`Photographic attributes<id3_face_face_analyser_compute_photographic_attributes_class_method>`
      - Photographic quality attributes such as brigthness, dynamic range, flash reflection, natural skin color, exposure, pixelation, sharpness.

    * - :ref:`Red eyes<id3_face_face_analyser_compute_eye_redness_class_method>`
      - Detect if a person's eyes are red or not (due to flash mostly).

Parameters
==========

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

    * - Parameter 
      - Description

    * - :ref:`Expression sensibility<id3_face_face_analyser_expression_sensibility_class_member>`
      - The sensibility of the expression classifier.
    
    * - :ref:`Over-exposure sensibility<id3_face_face_analyser_over_exposure_sensibility_class_member>`
      - Sensibility of the over-exposure classifier. 

    * - :ref:`Under-exposure sensibility<id3_face_face_analyser_under_exposure_sensibility_class_member>`
      - Sensibility of the under-exposure classifier.

    * - :ref:`Thread count<id3_face_face_analyser_thread_count_class_member>`
      - Number of threads to be used for face analysis.


Example
=======

.. tab-set::

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

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


See also
========
- :ref:`id3_face_face_analyser_class`
