.. _cameras:

*****************************
Camera Management
*****************************

To configure video-based biometric identification, add cameras to FindFace Security, grouping them subject to their location.


.. note::
   Privileges to create camera groups and cameras are managed in user's permissions (see :ref:`users`). 

.. rubric:: In this chapter:

.. contents::
   :local:

.. _camera-group:

Create Camera Group
============================

.. tip::
   A default preconfigured camera group is available in the system.

To create a group of cameras, do the following:

#. Navigate to the :guilabel:`Preferences` tab. Click :guilabel:`Camera Groups`.
#. Click :guilabel:`+`.

    |create_camera_group_en|

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

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

#. On the :guilabel:`Information` tab, specify the group name. Add a comment if needed.

     |camera_group_en|

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

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


#. If you want to allocate a certain ``findface-video-worker`` instance to process video streams from the group, create or select one or several allocation labels.

   .. note::
      To complete the allocation, list the labels in the ``findface-video-worker`` configuration file. See :ref:`video-allocation` for details.

#. If you want to deduplicate events from cameras that belong to the same group, i. e. exclude coinciding events, check :guilabel:`Deduplicate Events` and specify the deduplication interval (interval between 2 consecutive checks for event uniqueness).

   .. warning::
      Use deduplication with extreme caution. If cameras within a group observe different scenes, some faces may be skipped. See :ref:`deduplication` for details.

#. By default, all camera groups in the system are applied the :ref:`generic confidence threshold <settings>`. To set an individual threshold for the camera group, check :guilabel:`Confidence Threshold` and specify the threshold value. 

   .. include:: /_inclusions/threshold_important.rst

#. Check :guilabel:`Active`.
#. Click :guilabel:`Save`.
#. On the :guilabel:`Permissions` tab, assign privileges on the camera group, specifying which user roles are allowed to change/view the camera group settings.

     |camera_group_permissions_en|

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

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

#. Click :guilabel:`Save`.

.. _add-camera:

Add Camera
====================================

To add a camera, do the following:

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

     |create_camera_en|

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

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


#. Specify the name of a camera and add it to a group. If necessary, add a comment.

     |camera_en|

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

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

#. Specify the camera URL or path to the video file, for example, ``file:///data/some.mp4``.
#. (Optional) Specify the camera geographical location.
#. By default, all cameras in the system are applied the :ref:`generic confidence threshold <settings>`. To set an individual threshold for the camera, check :guilabel:`Confidence Threshold` and specify the threshold value. 

   .. include:: /_inclusions/threshold_important.rst

#. Check :guilabel:`Active`.
#. To configure video processing, click :guilabel:`Parameters` and make adjustments:

   * :guilabel:`Minimum face snapshot quality` (``filter_min_quality``): Minimum quality of a face snapshot to post. Do not change the default value (0.45) without consulting with our technical experts (support@ntechlab.com).
   * :guilabel:`Minimum face size` (``filter_min_face_size``): Minimum face size in pixels to post.
   * :guilabel:`Maximum face size` (``filter_max_face_size``): Maximum face size in pixels in post.
   * :guilabel:`Compression quality` (``jpeg_quality``): Full frame compression quality.
   * :guilabel:`FFMPEG options` (``ffmpeg_params``): FFMPEG options for a video stream in the key-value format [“rtsp_transpotr=tcp”, “ss=00:20:00”].
   * :guilabel:`Offline mode` (``overall_only``): Offline mode. Enable posting one snapshot of the best quality for each face.
   * :guilabel:`Time interval` (``realtime_post_interval``): Time interval in seconds (integer or decimal) within which the face tracker picks up the best snapshot in realtime mode.
   * :guilabel:`Post first face immediately` (``realtime_post_first_immediately``): If ``true``, post the first face from a track immediately after it passes through the quality, size, and ROI filters, without waiting for the first ``realtime_post_interval`` to complete. The way the subsequent snapshots are posted depends on the ``realtime_post_every_interval`` value. If false, post the first face after the first ``realtime_post_interval`` completes. 
   * :guilabel:`Post best snapshot` (``realtime_post_every_interval``): If true, post the best snapshot obtained within each Time interval (realtime_post_interval) in realtime mode. If false, post the best snapshot only if its quality has improved comparing to the previously posted snapshot.
   * :guilabel:`Posting timeout` (``router_timeout_ms``): Timeout in milliseconds for posting faces.
   * :guilabel:`Retrieve timestamps from stream` (``use_stream_timestamp``): If true, retrieve and post timestamps from a video stream. If false, post the actual date and time.
   * :guilabel:`Add to timestamps` (``start_stream_timestamp``): Add the specified number of seconds to timestamps from a stream.
   * :guilabel:`Play speed limit` (``play_speed``): If less than zero, the speed is not limited. In other cases, the stream is read with the given ``play_speed``. Not applicable for live streams.
   * :guilabel:`Region of Tracking` (``ROT``): Enable detecting and tracking faces only inside a clipping rectangle. Use this option to reduce the video face detector load.
   * :guilabel:`Region of Interest` (``ROI``): Enable posting faces detected only inside a region of interest.

     .. tip::
        To specify ROT/ROI, use the visual wizard. First, create a camera without ROT/ROI. Then open it for editing and click :guilabel:`Parameters`. You will see the visual wizard appear.

   If necessary, specify optional parameters for video processing. Click :guilabel:`Advanced Parameters`.

   * :guilabel:`Force input format` (``ffmpeg_format``): Pass FFMPEG format (mxg, flv, etc.) if it cannot be detected automatically.
   * :guilabel:`Verify SSL` (``router_verify_ssl``): If true, enable verification of the server SSL certificate when the face tracker posts faces to the server over https. If false, a self-signed certificate can be accepted.
   * :guilabel:`Minimum motion intensity` (``imotion_threshold``): Minimum motion intensity to be detected by the motion detector. 

#. Click :guilabel:`Save`.


.. note::
   Each created camera is associated with a so-called job, a video processing task that contains configuration settings and stream data and is assigned to ``findface-video-worker``. This task can be restarted (see :ref:`monitor-camera`).   


.. _monitor-camera:

Monitor Camera Operation
============================

To monitor the operation of cameras, navigate to the :guilabel:`Cameras` tab.

     |monitor_cameras_en|

     .. |monitor_cameras_en| image:: /_static/monitor_cameras_en.png
        :scale: 40%

     .. |monitor_cameras_ru| image:: /_static/monitor_cameras_ru.png
        :scale: 40%

Camera statuses:

* Green: the video stream is being processed without errors.
* Yellow: the video stream is being processed for less than 30 seconds, or one or more errors occurred when posting a face.
* Red: the video stream cannot be processed.
* Grey: camera disabled.

.. tip::
   You can configure the yellow and red statuses based on the portion of dropped frames and failed face postings. To do so, modify the following parameters in the ``findface-security`` configuration file:

   .. code::

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

      FFSECURITY = {
          ...
          # max camera frames_dropped percent
          'MAX_CAMERA_DROPPED_FRAMES': {'yellow': 0.1, 'red': 0.3},
          # max camera faces_failed percent
          'MAX_CAMERA_FAILED_FACES': {'yellow': 0.1, 'red': 0.3},
          ...
      }    


For each camera, you will be provided with complete statistics such as current session duration, the number of successfully posted faces, the number of faces processed with errors after the last job restart, the number of frame drops, and other data.

.. note::
   Each created camera is associated with a so called job, a video processing task that contains configuration settings and stream data and is assigned to ``findface-video-worker``. This task can be restarted.

To restart a job, click |restart| in the :guilabel:`Action` column. In this case, the number of errors will be reset to ``0``.

.. |restart| image:: /_static/restart_button.png
        :scale: 60%

With a large number of cameras in the system, use the following filters:

* :guilabel:`Camera groups`,
* :guilabel:`Active`,
* :guilabel:`Status`.


.. seealso::
   
   * :ref:`video-allocation`
   * :ref:`deduplication`