.. _liveness:

Real-time Face Liveness Detection
======================================

.. note::
   The :ref:`liveness detector <liveness>` is much slower on CPU than on GPU.

To spot fake faces and prevent photo attacks, use the integrated 2D anti-spoofing system that distinguishes a live face from a face image. Due to the analysis of not one, but a number of frames, the algorithm captures any changes in a facial expression and skin texture. This ensures that it is a live person in front of a camera and eliminates the possibility of fraud using images on paper or mobile device screens.

The liveness detector estimates a face liveness with a certain level of confidence and returns the confidence score along with a binary result ``real/fake``, depending on the pre-defined liveness threshold. 



.. rubric:: In this section:

.. contents::
   :local:


Enable Face Liveness Detector
---------------------------------

To enable the face liveness detector, do the following:

#. Open the ``/etc/findface-video-worker-gpu.ini`` (``/etc/findface-video-worker-cpu.ini``) configuration file. In the ``liveness`` section, specify the path to the neural network model (``fnk``) and normalizer (``norm``) which are used in the face liveness detector. 

   .. code::

      sudo vi /etc/findface-video-worker-gpu.ini

      #------------------------------
      [liveness]
      #------------------------------
      ## path to liveness fnk
      ## type:string env:CFG_LIVENESS_FNK longopt:--liveness-fnk
      fnk = /usr/share/findface-data/models/faceattr/liveness.v3.gpu.fnk

      ## path to normalization for liveness
      ## type:string env:CFG_LIVENESS_NORM longopt:--liveness-norm
      norm = /usr/share/findface-data/models/facenorm/crop2x.v2_maxsize400.gpu.fnk



   .. code::

      sudo vi /etc/findface-video-worker-cpu.ini

      #------------------------------
      [liveness]
      #------------------------------
      ## path to liveness fnk
      ## type:string env:CFG_LIVENESS_FNK longopt:--liveness-fnk
      fnk = /usr/share/findface-data/models/faceattr/liveness.v3.cpu.fnk

      ## path to normalization for liveness
      ## type:string env:CFG_LIVENESS_NORM longopt:--liveness-norm
      norm = /usr/share/findface-data/models/facenorm/crop2x.v2_maxsize400.cpu.fnk

#. Restart ``findface-video-worker``.
 
   .. code::

      sudo systemctl restart findface-video-worker-gpu
      sudo systemctl restart findface-video-worker-cpu


Configure Liveness Threshold
--------------------------------

If necessary, you can adjust the liveness ``threshold`` in the ``/etc/findface-security/config.py`` configuration file. The liveness detector will estimate a face liveness with a certain level of confidence. Depending on the threshold value, it will return a binary result ``real`` or ``fake``. 

.. note::
   The default value is optimal. Before changing the threshold, we recommend you to seek advice from our experts by support@ntechlab.com.


.. code::

   sudo vi /etc/findface-security/config.py

   ‘LIVENESS_THRESHOLD’: 0.75,


.. _filter-liveness:


Face Liveness in Web Interface
---------------------------------

Once the face liveness detector configured, you will see liveness estimation for each event. 

|liveness_en|

.. |liveness_en| image:: /_static/liveness_en.png
   :scale: 80%

.. |liveness_ru| image:: /_static/liveness_ru.png
   :scale: 80%

.. note::
   The liveness score is ``null`` when the liveness detector is unable to estimate the face liveness in the provided image.

Use the :guilabel:`Liveness` filter to display only real or only fake faces in the event list.

|liveness_filter_en|

.. |liveness_filter_en| image:: /_static/liveness_filter_en.png
   :scale: 80%

.. |liveness_filter_ru| image:: /_static/liveness_filter_ru.png
   :scale: 80%


.. seealso::
   :ref:`liveness-api`