.. _face-features:

Face Features Recognition
======================================

Subject to your needs, you can enable automatic recognition of such face features as gender, age, emotions, glasses, beard, and face mask. This functionality can be activated on both GPU- and CPU-accelerated video face detectors.

.. rubric:: In this section:

.. contents::
   :local:


Enable Face Features Recognition
---------------------------------

.. important::
   This step will enable face features recognition via HTTP API.

To enable automatic recognition of face features, open the ``/etc/findface-extraction-api`` configuration file and enable relevant recognition models: gender, age, emotions, glasses, beard, and face mask. Be sure to choose the right acceleration type for each model, matching the acceleration type of ``findface-extraction-api``: CPU or GPU. Be aware that ``findface-extraction-api`` on CPU can work only with CPU-models, while ``findface-extraction-api`` on GPU supports both CPU- and GPU-models.   

.. code::
   
   sudo vi /etc/findface-extraction-api.ini
  
   models:
     age: faceattr/age.v1.cpu.fnk
     emotions: faceattr/emotions.v1.cpu.fnk
     face: face/ifruit_320.cpu.fnk
     gender: faceattr/gender.v2.cpu.fnk
     beard: faceattr/beard.v0.cpu.fnk
     glasses3: faceattr/glasses3.v0.cpu.fnk
     medmask3: faceattr/medmask3.v2.cpu.fnk

The following models are available:

.. note::
   You can find face features recognition models at ``/usr/share/findface-data/models/faceattr/``.

   .. code::

      ls /usr/share/findface-data/models/faceattr/
      age.v1.cpu.fnk  age.v1.gpu.fnk  beard.v0.cpu.fnk  beard.v0.gpu.fnk  emotions.v1.cpu.fnk  emotions.v1.gpu.fnk  gender.v2.cpu.fnk  gender.v2.gpu.fnk  glasses3.v0.cpu.fnk  glasses3.v0.gpu.fnk medmask3.v2.cpu.fnk medmask3.v2.gpu.fnk liveness.v3.gpu.fnk quality.v1.cpu.fnk quality.v1.gpu.fnk

   +------------------+--------------+--------------------------------------------------------------------------------+
   | Face feature     | Acceleration | Configuration file parameter                                                   |
   +==================+==============+================================================================================+
   | face             | CPU          | ``face: face/ifruit_320.cpu.fnk`` ``face: face/ifruit_160.cpu.fnk``            |
   | (biometry)       +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face: face/ifruit_320.gpu.fnk`` ``face: face/ifruit_160.gpu.fnk``            |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | age              | CPU          | ``age: faceattr/age.v1.cpu.fnk``                                               |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``age: faceattr/age.v1.gpu.fnk``                                               |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | gender           | CPU          | ``gender: faceattr/gender.v2.cpu.fnk``                                         |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``gender: faceattr/gender.v2.gpu.fnk``                                         |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | emotions         | CPU          | ``emotions: faceattr/emotions.v1.cpu.fnk``                                     |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``emotions: faceattr/emotions.v1.gpu.fnk``                                     |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | glasses          | CPU          | ``glasses3: faceattr/glasses3.v0.cpu.fnk``                                     |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``glasses3: faceattr/glasses3.v0.gpu.fnk``                                     |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | beard            | CPU          | ``beard: faceattr/beard.v0.cpu.fnk``                                           |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``beard: faceattr/beard.v0.gpu.fnk``                                           |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | face mask        | CPU          | ``medmask3: faceattr/medmask3.v2.cpu.fnk``                                     |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``medmask3: faceattr/medmask3.v2.gpu.fnk``                                     |
   +------------------+--------------+--------------------------------------------------------------------------------+


.. tip::
   To disable a recognition 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::

      models:
        gender: ""
        age: ""
        emotions: ""

Restart ``findface-extraction-api``.

.. code::

   sudo systemctl restart findface-extraction-api

Once the models are enabled, be sure to :ref:`configure <features-web>` the web interface to display the recognition results.  


.. _features-web:

Display Features Recognition Results in Events
--------------------------------------------------

To display the face features recognition results in the event list, add the following line into the ``FFSECURITY`` section: ``'EVENTS_FEATURES': ['gender', 'age', 'emotions', 'beard', 'glasses', 'medmask']``, subject to the list of enabled models. 

.. warning::
   This line must be placed between ``SF_API_ADDRESS`` and ``LIVENESS_THRESHOLD`` as shown in the example. 
     
.. code::
 
   sudo vi /etc/findface-security/config.py

   ...
   FFSECURITY = {
   ...
   'SF_API_ADDRESS': 'http://127.0.0.1:18411',
   'EVENTS_FEATURES': ['gender', 'age', 'emotions', 'beard', 'glasses', 'medmask'],
   'LIVENESS_THRESHOLD': 0.75,
   'BEARD_THRESHOLD': 0.7,
    }


Restart ``findface-security``.

.. code::

   sudo systemctl restart findface-security

Face Features in Events
---------------------------------

Once the face features recognition configured, you will see the recognition result for each found face in the following format: 

+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Face feature     | Result format                                                                                             | Example                |
+==================+===========================================================================================================+========================+
| Age              | Feature: ``age``: number of years                                                                         | age: 33                |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Gender           | Result: ``male/female`` (feature: ``gender``): algorithm confidence in result                             | female (gender): 0.95  |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Emotions         | Result: ``angry/disgust/fear/happy/sad/surprise`` (feature: ``emotions``): algorithm confidence           | happy (emotions): 0.99 |
|                  | in result                                                                                                 |                        |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Glasses          | Result: ``eye/sun/none`` (feature: ``glasses``): algorithm confidence in result                           | none (glasses): 0.87   |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Beard            | Result: ``beard/none`` (feature: ``beard``): algorithm confidence in result                               | none (beard): 0.91     |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+
| Face mask        | Result: ``none/correct/incorrect`` (feature: ``face mask``): algorithm confidence in result               | none (face mask): 0.93 |
+------------------+-----------------------------------------------------------------------------------------------------------+------------------------+

Filter events by face features when needed.

|filters_en|

.. |filters_en| image:: /_static/filters_en.png
   :scale: 50%

.. |filters_ru| image:: /_static/filters_ru.png
   :scale: 50%