.. _counters:

*************************************************
Face and Body Counters. Distance between People
*************************************************


.. important::
   To count bodies (silhouettes) and measure the distance between them, you first must enable :ref:`body detection <bodies>`.

FindFace Multi allows you to count faces and bodies on connected cameras and measure the distance between bodies. These features can apply to a wide range of situations, such as people counting in queues and waiting areas, monitoring public gatherings, crowding prevention, and others.

The counting method is based on time slices, which means that the system counts faces and bodies in static screenshots taken with a given ``count interval``. 

You can opt for counting faces/bodies either on each camera independently, or collectively on all selected cameras.


.. rubric:: In this section:

.. contents::
   :local:

   

Create Counter
===========================

To set up a counter, do the following:

#. Navigate to the :guilabel:`Counters` tab. 
#. Click :guilabel:`+`.

     |create_counter_en|

     .. |create_counter_en| image:: /_static/create_counter_en.png
        :scale: 60%

     .. |create_counter_ru| image:: /_static/create_counter_ru.png
        :scale: 60%

#. Specify the counter name.
#. Select one or several camera groups for counting. 
 
   .. tip::
      By default, counting will apply to all cameras within the groups. If necessary, you can disable counting on specific cameras.

#. Specify the interval in seconds between two consecutive screenshots used for counting.
#. Check :guilabel:`Detect faces` to count faces.  
#. Check :guilabel:`Detect silhouettes` to count bodies. Body detection must be :ref:`enabled <bodies>`.
#. Make sure that the counter is :guilabel:`Active`. 
#. If the :guilabel:`Detect silhouettes` is checked and you want to enable the distance measurement, check :guilabel:`Detect distance`.
#. Click :guilabel:`Save`. Now you can calibrate the counter for the distance measurement if you have enabled this function and specify the face/body tracking regions if needed. Do the following:

     |counter_en|

     .. |counter_en| image:: /_static/counter_en.png
        :scale: 70%

     .. |counter_ru| image:: /_static/counter_ru.png
        :scale: 70%

   #. On the same :guilabel:`Information` tab, set the calibration duration in the range from 15 to 300 seconds. Click :guilabel:`Start calibration`. You will see the calibration guide appear. Read it and close it by clicking :guilabel:`OK`. 

      .. rubric:: Calibration guide:
     
      * The person in the frame must be visible at full height.
      * The person must walk through the area visible by the camera, along which the distances will be calculated.
      * To achieve the best quality, the person must walk on a flat surface. 

   #. Perform the calibration following the calibration guide until the status of the counter changes to ``Calibrated``.
   #. (Optional) On the :guilabel:`Region of Interest` tab, specify the face/body tracking region within the camera(s) field.

     |counter_roi_en|

     .. |counter_roi_en| image:: /_static/counter_roi_en.png
        :scale: 60%   

     .. |counter_roi_ru| image:: /_static/counter_roi_ru.png
        :scale: 60%   


Counter Chart
====================

To see the counter chart for the last hour, 24 hours, or week, navigate to the :guilabel:`Chart` tab in the counter settings.


     |counter_chart_en|

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

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


Monitor Counter Operation
============================

To monitor the operation of counters, navigate to the :guilabel:`Counters` tab.

     |monitor_counters_en|

     .. |monitor_counters_en| image:: /_static/monitor_counters_en.png
        :scale: 55%

     .. |monitor_counters_ru| image:: /_static/monitor_counters_ru.png
        :scale: 55%

Counter statuses:

* Green: the counter is running without errors, or the number of errors doesn't pass the acceptable threshold.
* Yellow: the number of errors exceeds the threshold.
* Red: the number of errors is critical.
* Grey: the counter disabled.

.. tip::
   You can configure the yellow and red statuses based on the portion of failed counter records and change the time window duration between two consecutive checks of the counter health status. To do so, modify the following parameters in the ``/etc/findface-security/config.py`` configuration file:

   .. code::

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

      FFSECURITY = {
          ...
          # Counter health status config:
          # max percent of camera records with errors
          'MAX_COUNTER_ERROR_RECORDS': {'yellow': 0.3, 'red': 0.5},
          # time window for computing health status (in seconds)
          'COUNTER_HEALTH_STATUS_TIME_WINDOW': 30,
          ...
      }    


Work with Counter Records
=================================

Static screenshots taken by a counter, with the number of faces and bodies, are saved as counter records. 

If you have enabled the distance measurement, each record will also contain a minimum, average, and maximum detected distance in meters.

If the counter is running with errors, the system will be creating blank records with an error message.

To see the counter records, navigate to the :guilabel:`Counters` tab. Click on any column for the counter, except ``ID`` (leads to the counter settings). 
  
     |counter_records_en|

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

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

To work with counter records, use the following filters:

* Counter
* Cameras
* Camera groups
* Time
* Number of faces in record
* Number of bodies in record
* Record id
* Ranges of minimum/average/maximum detected distances, meters (if enabled for the counter)



Set Webhook for Counter
===================================

To take it up a notch, :ref:`configure a webhook <webhooks>` for counter records with a specific number of faces and bodies.  

.. seealso::

   * :ref:`bodies`
   * :ref:`webhooks`


Configure Screenshot Saving Options
=========================================

You can configure how screenshots (full frames) that you see in counter records, and their thumbnails, are saved in the system. To do so, open the ``/etc/findface-security/config.py`` configuration file and modify the following parameters:     

* ``COUNTERS_SAVE_FULLFRAME`` determines saving options of full frames in counters: ``always``, ``detect`` - only save if faces or bodies have been detected, ``never``.
* ``COUNTERS_FULLFRAME_JPEG_QUALITY``: JPEG quality of full frames,
* ``COUNTERS_THUMBNAIL_JPEG_QUALITY``: JPEG quality of thumbnails.

.. code::

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

   # counters full frame saving options:
   # `always` - save always
   # `detect` - save only if faces or bodies have been detected
   # `never` - never save full frames
   'COUNTERS_SAVE_FULLFRAME': 'always',
   'COUNTERS_FULLFRAME_JPEG_QUALITY': 75,
   'COUNTERS_THUMBNAIL_JPEG_QUALITY': 75,
   ...