.. _edge-devices:

External Detectors
========================================

It is possible to integrate FindFace Multi with the external detectors that can source frames for object recognition, e.g., Access Control terminals. In this case, once FindFace Multi receives a frame from an external detector, it will initiate the extraction of the object's feature vector and event creation. You can work with these events by analogy with the :ref:`events <events>` from CCTV cameras.


.. important:: 
   To use an external detector for object recognition, liveness detection must be enabled. If you have not enabled it during :ref:`installation <installer>`, you can do it now, using information from the :ref:`Enable Face Liveness Detection <liveness>` section.

The liveness model ``liveness.web.v0`` comes in the default configuration and is used for authentication by face. If your use case implies connection to an external detector for object recognition, replace the ``liveness.web.v0`` model with the ``liveness.pacs.v2`` model in the ``findface-extraction-api.yaml`` configuration file. Since both models employ the same normalizer ``facenorm.multicrop_full_crop2x_size400.cpu.fnk`` there is no need to change it.

Replace the liveness model in the ``/opt/findface-multi/configs/findface-extraction-api/findface-extraction-api.yaml`` configuration file:

.. rubric:: GPU

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

   extractors:
     ...
     models:
       face_liveness: faceattr/liveness.pacs.v2.gpu.fnk
       ...

.. rubric:: CPU

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

   extractors:
     ...
     models:
       face_liveness: faceattr/liveness.pacs.v2.cpu.fnk
       ...

Restart the ``findface-multi-findface-extraction-api-1`` container.

.. code::

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

The external detector integration is done through :ref:`HTTP API <api>`. After the primary configuration, FindFace Multi will issue a token. Specify this token in every API request sent by the external detector to FindFace Multi to authorize the device.

To integrate an external detector with FindFace Multi, do the following:

#. Navigate to the :guilabel:`Video Sources` -> :guilabel:`External Detectors`.
#. Click :guilabel:`+ Add` or :guilabel:`Add external detectors` if you don't have any detectors yet.

    |add_ext_detector_en|

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

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

#. In the opened tab, specify the external detector name and description. Add the external detector to a camera group, so it will be more convenient to filter events from this device later.  

    |ext_det_window_en|

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

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

   .. tip::
      You can allot a separate camera group specifically to external detectors.

#. On the :guilabel:`Add and configure` tab, enable liveness. On the same tab you will see a token.

    |ex_detect_config_en|

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

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

#. Specify this token in every API request that the external detector sends to FindFace Multi to create an event. As a result, frames passed in the requests will be associated with the external detector's relevant camera and processed by analogy with the frames from CCTV cameras.

    |detector_token_en|

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

   Detailed interactive documentation on the FindFace Multi HTTP API is available after installation at ``http://<findface-ip:port>/api-docs``. Learn and try it out.

   .. tip::
      You can also find it by navigating to :guilabel:`Settings -> API Documentation` in the web interface.