.. _persons:

********************************************************
Person Recognition
********************************************************


FindFace Multi allows for automatic person recognition. The system on-the-fly recognizes faces belonging to the same person and clusters them, building a person gallery. You can work with the person gallery on the :guilabel:`Persons` tab. 

 
.. note::
   In the person clusterization is enabled, the system databases will hold the ``person event`` entity linked to all :ref:`episodes <episodes>` that feature a person's face.

.. important::

   By default, person clusterization is disabled. :ref:`Enable and configure it <enable-clusterization>` via the ``/etc/findface-security/config.py`` configuration file.    


.. rubric:: In this section:

.. contents::
   :local:

Clusterization Methods
============================

FindFace Multi uses the following methods to cluster faces belonging to the same person:

* Dynamic clusterization. The clusterization takes place on-the-fly after an episode is closed. The result of dynamic clusterization is shown in real-time on the :guilabel:`Persons` tab. 

  .. note::
     The technical details are as follows.
     Not every episode is qualified: the number of events in it must be equal or greater than ``PERSON_EVENT_MIN_EPISODE_EVENTS`` (set up via the ``/etc/findface-security/config.py`` configuration file). If an episode meets this requirement, the system selects the best quality event and performs the following operations:

       * Creates a new entity ``PersonEvent`` in the main system database :program:`PostgreSQL`. The entity contains the event metadata, a link to the parent episode, face feature vector, and thumbnail.
       * Searches for a similar face centroid in the ``person_events`` gallery of the :program:`Tarantool` feature vector database. A face centroid is a virtual feature vector averaged across all person's faces that have been detected so far. If a similar centroid is found, the system updates it using the new event. Otherwise, it creates a new centroid.
 

* Scheduled clusterization. We recommend scheduling it on late night hours as it takes up a lot of CPU resources and time.

  .. note::
     The schedule is defined in the RRULE format as ``PERSONS_CLUSTERIZATION_SCHEDULE`` in the ``/etc/findface-security/config.py`` configuration file.
     The rest of the technical implementation resembles the dynamic method. However, the face centroid quality is better in the scheduled method as centroids are averaged across a larger array of accumulated feature vectors.

  .. important::
     The scheduled clusterization completely overwrites the person gallery, including ids.   



.. _enable-clusterization:

Enable and Configure Person Clusterization
==================================================

By default, person clusterization is disabled. To enable it, open the ``/etc/findface-security/config.py`` configuration file and modify the ``SERVICES`` section as such:   

.. code::

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

   ...
   SERVICES = {
       "ffsecurity": {
           ...
           "persons": True,
       }
   ...

You will see the :guilabel:`Persons` tab appear in the FindFace Multi web interface.

In the same configuration file, you can modify the following parameters:

* ``PERSON_EVENT_MIN_QUALITY``: minimum quality of faces used in person clusterization.
* ``PERSON_EVENT_MIN_EPISODE_EVENTS``: minimum number of events in episodes used in person clusterization.
* ``PERSONS_CONFIDENCE_THRESHOLD``: confidence threshold to match a face to a person.  

  .. warning::
     Consult with our experts by support@ntechlab.com before changing this parameter.

* ``PERSONS_CLUSTERIZATION_SCHEDULE``: recurrence rule (RRULE) for scheduling person clusterization.


  .. tip::

     See the RRULE calculator `here <https://jkbrzt.github.io/rrule/>`_.

.. code::

   # -- Persons configuration --
   # rrule (recurrence rule) for scheduling persons clusterization
   # WARNING: all scheduling works with UTC time and NOT aware of any timezone
   'PERSONS_CLUSTERIZATION_SCHEDULE': 'RRULE:FREQ=DAILY;INTERVAL=1;WKST=MO;BYHOUR=0;BYMINUTE=0',
   # face to person matching confidence threshold
   'PERSONS_CONFIDENCE_THRESHOLD': 0.739,
   # minimum required face quality for person creation
   'PERSON_EVENT_MIN_QUALITY': 0.45,
   # minimum required number events in episode for person creation
   'PERSON_EVENT_MIN_EPISODE_EVENTS': 1,


Work with Person Gallery
=================================
 

To see the person gallery, navigate to the :guilabel:`Persons` tab.
  
     |person_gallery_en|

     .. |person_gallery_en| image:: /_static/person_gallery_en.png
        :scale: 45%   

     .. |person_gallery_ru| image:: /_static/person_gallery_ru.png
        :scale: 45%   

To work with the person gallery, use the following filters:

* Dossier
* Matches
* Cameras
* Camera groups
* Watch lists
* Time period
* Person id
* Face features (if enabled)
* Liveness (if enabled)

.. seealso::

   * :ref:`Configuration file of findface-security <security-config>`
   * :ref:`webhooks`
   * :ref:`social-interaction`
   * :ref:`analytics`