.. _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``                             |
   +------------------+--------------+--------------------------------------------------------------------------------+

         
   .. 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