.. _face-features:

Enable Face Attribute Recognition
======================================

Face attributes, such as age, gender, emotions, etc., are present in the filter set for detected face analysis during a :ref:`case investigation <case-files>`. 

Face attribute recognition can be automatically enabled and configured during the :ref:`FindFace CIBR installation <installer>`. If you skip this step, you can manually do it later. Face attribute recognition works on both GPU- and CPU-acceleration. 


Do the following:

#. Open the ``/opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml`` configuration file.

   .. code::
   
      sudo vi /opt/findface-cibr/configs/findface-extraction-api/findface-extraction-api.yaml

#. Specify the relevant recognition models in the ``extractors`` section, as shown in the example below. Be sure to indicate 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.   

   .. rubric:: GPU

   .. code::
  
      extractors:
        ...
        models:
          face_age: faceattr/age.v2.gpu.fnk
          face_beard: faceattr/beard.v0.gpu.fnk
          face_beard4: ''
          face_countries47: ''
          face_emben: face/mango_320.gpu.fnk
          face_emotions: faceattr/emotions.v1.gpu.fnk
          face_eyes_attrs: ''
          face_eyes_openness: ''
          face_gender: faceattr/gender.v2.gpu.fnk
          face_glasses3: faceattr/glasses3.v0.gpu.fnk
          face_glasses4: ''
          face_hair: ''
          face_headpose: ''
          face_headwear: ''
          face_highlight: ''
          face_liveness: faceattr/liveness.web.v0.gpu.fnk
          face_luminance_overexposure: ''
          face_luminance_underexposure: ''
          face_luminance_uniformity: ''
          face_medmask3: faceattr/medmask3.v2.gpu.fnk
          face_medmask4: ''
          face_mouth_attrs: ''
          face_quality: faceattr/quality_fast.v1.gpu.fnk
          face_scar: ''
          face_sharpness: ''
          face_tattoo: ''
          face_validity: ''

   .. rubric:: CPU

   .. code::
  
      extractors:
        ...
        models:
          face_age: faceattr/age.v2.cpu.fnk
          face_beard: faceattr/beard.v0.cpu.fnk
          face_beard4: ''
          face_countries47: ''
          face_emben: face/mango_320.cpu.fnk
          face_emotions: faceattr/emotions.v1.cpu.fnk
          face_eyes_attrs: ''
          face_eyes_openness: ''
          face_gender: faceattr/gender.v2.cpu.fnk
          face_glasses3: faceattr/glasses3.v0.cpu.fnk
          face_glasses4: ''
          face_hair: ''
          face_headpose: ''
          face_headwear: ''
          face_highlight: ''
          face_liveness: faceattr/liveness.web.v0.cpu.fnk
          face_luminance_overexposure: ''
          face_luminance_underexposure: ''
          face_luminance_uniformity: ''
          face_medmask3: faceattr/medmask3.v2.cpu.fnk
          face_medmask4: ''
          face_mouth_attrs: ''
          face_quality: faceattr/quality_fast.v1.cpu.fnk
          face_scar: ''
          face_sharpness: ''
          face_tattoo: ''
          face_validity: ''

   The following extraction models are available:

   +------------------+--------------+--------------------------------------------------------------------------------+
   | Extractor        | Acceleration | Configure as follows                                                           |
   +==================+==============+================================================================================+
   | age              | CPU          | ``face_age: faceattr/age.v2.cpu.fnk``                                          |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_age: faceattr/age.v2.gpu.fnk``                                          |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | beard            | CPU          | ``face_beard: faceattr/beard.v0.cpu.fnk``                                      |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_beard: faceattr/beard.v0.gpu.fnk``                                      |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | face feature     | CPU          | ``face_emben: face/mango_320.cpu.fnk``                                         |
   | vector           +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_emben: face/mango_320.gpu.fnk``                                         |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | gender           | CPU          | ``face_gender: faceattr/gender.v2.cpu.fnk``                                    |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_gender: faceattr/gender.v2.gpu.fnk``                                    |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | emotions         | CPU          | ``face_emotions: faceattr/emotions.v1.cpu.fnk``                                |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_emotions: faceattr/emotions.v1.gpu.fnk``                                |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | glasses          | CPU          | ``face_glasses3: faceattr/glasses3.v0.cpu.fnk``                                |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_glasses3: faceattr/glasses3.v0.gpu.fnk``                                |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | face liveness    | CPU          | ``face_liveness: faceattr/liveness.web.v0.cpu.fnk``                            |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_liveness: faceattr/liveness.web.v0.gpu.fnk``                            |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | face mask        | CPU          | ``face_medmask3: faceattr/medmask3.v2.cpu.fnk``                                |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_medmask3: faceattr/medmask3.v2.gpu.fnk``                                |
   +------------------+--------------+--------------------------------------------------------------------------------+
   | face quality     | CPU          | ``face_quality: faceattr/quality_fast.v1.cpu.fnk``                             |
   |                  +--------------+--------------------------------------------------------------------------------+
   |                  | GPU          | ``face_quality: faceattr/quality_fast.v1.gpu.fnk``                             |
   +------------------+--------------+--------------------------------------------------------------------------------+

   .. tip::
      To leave a model disabled, pass the empty value ``''`` to the relevant parameter. Do not remove the parameter itself. Otherwise, the system will be searching for the default model. E.g., to disable emotions and face mask recognition, pass the empty value to the corresponding extraction models:

      .. code::

         extractors:
           ...
           models:
             ...
             face_emotions: ''
             face_medmask3: ''

         
   .. note::
      You can find face attribute recognition models at ``/opt/findface-cibr/models/faceattr/``.

      .. code::

         ls /opt/findface-cibr/models/faceattr/

         age.v2.cpu.fnk    emotions.v1.cpu.fnk  glasses3.v0.cpu.fnk      medmask3.v2.cpu.fnk
         age.v2.gpu.fnk    emotions.v1.gpu.fnk  glasses3.v0.gpu.fnk      medmask3.v2.gpu.fnk
         beard.v0.cpu.fnk  gender.v2.cpu.fnk    liveness.web.v0.cpu.fnk  quality_fast.v1.cpu.fnk
         beard.v0.gpu.fnk  gender.v2.gpu.fnk    liveness.web.v0.gpu.fnk  quality_fast.v1.gpu.fnk


#. Restart the ``findface-cibr-findface-extraction-api-1`` container.

   .. code::

      sudo docker container restart findface-cibr-findface-extraction-api-1

#. Enable recognition of face attributes in the ``/opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file. In the ``FFSECURITY`` section, specify the face attributes that you want to display for the face recognition events.

   .. code::

      # make sure that corresponding extractors are licensed
      # and enabled at findface-extraction-api config file
      # available features: age, beard, emotions, gender, glasses, medmask
      'FACE_EVENTS_FEATURES': ['emotions', 'beard', 'gender', 'age', 'medmask', 'glasses'],

#. Restart the ``findface-cibr-findface-multi-legacy-1`` container.

   .. code::

      sudo docker container restart findface-cibr-findface-multi-legacy-1