.. _cameras:

***************************************
Video Sources
***************************************

To configure video-based object monitoring, add cameras to FindFace Multi, 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:`Settings` tab. Click :guilabel:`Camera Groups`.
#. Click :guilabel:`+ Add new camera group`.

    |create_camera_group_en|

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

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

#. 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.yaml`` 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, select :guilabel:`Deduplicate events with interval` 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 objects may be skipped. See :ref:`deduplication` for details.

#. By default, video from all camera groups is processed using the :ref:`generic confidence threshold <settings>`. To set an individual threshold for the camera group, select :guilabel:`Confidence Threshold` and specify the threshold value. 

   .. include:: /_inclusions/threshold_important.rst

#. 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:`Video Sources` → :guilabel:`Cameras`.
#. Click :guilabel:`+ Add cameras` or :guilabel:`+ Add`.

     |camera_add_en|

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

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

#. On the :guilabel:`Devices` tab, enter the stream URL and click :guilabel:`Next`.

     |camera_stream_url_en|

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

     .. |camera_stream_url_ru| image:: /_static/camera_stream_url_ru.png
        :scale: 60%
   
   * Enter the camera name.
   * Add the camera to a camera group. 
   * Select detectors that you want to enable on this camera: faces, bodies, vehicles.

     |camera_configure_en|

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

     .. |camera_configure_ru| image:: /_static/camera_configure_ru.png
        :scale: 60%
    
   * Click :guilabel:`Add and configure`. You will see additional tabs appear.

#. Select the camera on the list to open the processing configuration wizard. Set up the :ref:`video processing parameters <video_processing_parameters>`.

#. If the camera is ONVIF, select it from the list of detected devices to automatically load available settings and streams.

     |camera_onvif_en|

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

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


.. _video_processing_parameters:

Video processing parameters
================================

#. For each camera, you will be provided with complete statistics such as current session duration, the number of successfully posted objects, the number of objects processed with errors after the last job restart, the number of frame drops, and other data. To consult these data, click the camera and go to the :guilabel:`Info` tab.

     |camera_info_en|

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

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

#. On the :guilabel:`General` tab, you can change Camera Name, Camera group, or add Description. You can record video and enable liveness. Select detectors that you want to enable on this camera: faces, bodies, vehicles.

     |camera_general_en|

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

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

#. On the :guilabel:`Advanced` tab, fine-tune the camera:

     |camera_advanced_en|

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

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

   * If needed, change the video orientation.
   
     .. important::
        Be aware that the ``findface-multi-legacy`` server rotates the video using post-processing tools. It can negatively affect performance. Rotate the video via the camera functionality wherever possible.
   
   * :guilabel:`Timeout`: Specify the timeout in milliseconds for posting detected objects.
   * :guilabel:`Verify SSL certificate`: Select to enable verification of the server SSL certificate when the object tracker posts objects to the server over https. Deselect the option if you use a self-signed certificate.
   * :guilabel:`Retrieve timestamps from stream`: Select to retrieve and post timestamps from the video stream. Deselect the option to post the current date and time.
   * :guilabel:`Add to timestamps`: Add the specified number of seconds to timestamps from the stream.
   * :guilabel:`FFMPEG parameters`: FFMPEG options for the video stream in the key-value format, for example, [“rtsp_transpotr=tcp”, “ss=00:20:00”].
   * :guilabel:`Play speed limit`: 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-streaming.
   * :guilabel:`Force input format`: Pass FFMPEG format (mxg, flv, etc.) if it cannot be detected automatically.
   * :guilabel:`Minimum motion intensity`: Minimum motion intensity to be detected by the motion detector. 
   * :guilabel:`Read frames from source without drops`: By default (false), if ``findface-video-worker`` does not have enough resources to process all frames with objects, it drops some of them. If this option is active (true) ``findface-video-worker`` puts excessive frames on a waiting list to process them later. Set a variable to true when processing files as cameras.
   * :guilabel:`Process the stream once until the end or until the first error (single_pass)`: If true, disable restarting video processing upon error.
   * :guilabel:`Router URL (router_url)`: IP address for posting detected objects to external video workers from ``findface-video-worker``. By default, ``'http://127.0.0.1'``.

#. Specify the region of tracking within the camera field and region of interest (:guilabel:`Zones`). Click :guilabel:`Save`. 
 
     |camera_zones_en|

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

     .. |camera_zones_ru| image:: /_static/camera_zones_ru.png
        :scale: 80%
     
     The region of tracking enables detecting and tracking faces/bodies and vehicles only inside a clipping rectangle. You can use this option to reduce the video object detector load. The region of interest enables posting objects detected only within its boundaries.

#. On the :guilabel:`Faces`, :guilabel:`Bodies` and :guilabel:`Vehicles` tabs, specify settings for each object type detector.

     |camera_analytics_en|

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

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

   * :guilabel:`Size`: Minimum object size in pixels to post and maximum object size in pixels to post.
   * :guilabel:`Quality`: The minimum quality of the face image for detection. The allowed range is from 0 to 1. The recommended reference value is 0.45, which corresponds to object images of satisfying quality. Do not change the default value without consulting with our technical experts (support@ntechlab.com).
   * :guilabel:`JPEG quality`: Full frame compression quality.
   * :guilabel:`Full frame in PNG`: Send full frames in PNG and not in JPEG as set by default. Do not enable this parameter without consulting with our technical experts (support@ntechlab.com) as it can affect the entire system functioning.
   * :guilabel:`Overlap threshold`: The percentage of overlap of bboxes between two serial frames so that these bboxes are considered as one track. The range of values is from 0 to 1. Do not change the default value without consulting with our technical experts (support@ntechlab.com).
   * :guilabel:`Track maximum duration`: The maximum approximate number of frames in a track, after which the track is forcefully completed. Enable it to forcefully terminate endless tracks, for example, tracks with faces from advertising media.
   * :guilabel:`Forced termination interval`: Terminate the track if no new object has been detected within the specified time (in seconds).
   * :guilabel:`Send track history`: Send array of bbox coordinates along with the event. May be applicable for external integrations to map the path of an object. 
   * :guilabel:`Crop full frame`: Select to crop the full frame to the size of the ROT area before sending it for recognition. The size of the full frame will be equal to the size of ROT area.
   * :guilabel:`Offline mode (overall_only)`: By default, the system uses the offline mode to process the video, i.e., it posts one snapshot of the best quality per track to save disk space. Disable it to receive more face snapshots if needed. If the offline mode is on, the parameters of the real-time mode are off.

   Real-time mode parameters:
 
   .. note::
      These parameters are non-functional if the offline mode is on.

   * :guilabel:`Interval`: Time interval in seconds (integer or decimal) within which the object tracker picks up the best snapshot in the real-time mode.
   * :guilabel:`Post first object immediately`: Select to post the first object from a track immediately after it passes through the quality, size, and ROI filters, without waiting for the first ``realtime_post_interval`` to complete in real-time mode. Deselect the option to post the first object after the first ``realtime_post_interval`` completes.
   * :guilabel:`Post track first frame`: At the end of the track, the first frame of the track will be additionally sent complimentary to the overall frame of the track. May be applicable for external integrations.
   * :guilabel:`Post in every interval`: Select to post the best snapshot within each time interval (``realtime_post_interval``) in real-time mode. Deselect the option to post the best snapshot only if its quality has improved comparing to the posted snapshot.
   * :guilabel:`Post track last frame`: At the end of the track, the last frame of the track will be additionally sent complimentary to the overall frame of the track. May be applicable for external integrations.
   * :guilabel:`Confidence threshold`: A confidence threshold is used for matching the detected object with the internal entity object.

#. (Optional) On the :guilabel:`GEO` tab, specify the camera geographical location.

     |camera_geo_en|

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

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

.. _custom_vms_cleanup:

7. Disabled by default, the :guilabel:`VMS cleanup settings` tab allows you to configure video cleanup for a single camera. Follow this instruction :ref:`vms_cleanup_ui` to enable the tab in the web interface. 

     |custom_vms_cleanup_en|

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

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

   
   Custom VMS cleanup settings override the global ones for a single camera. The following custom VMS cleanup settings are available:
   
   **Clean up between tracks**

   * :guilabel:`Enable custom cleanup`: enable custom clean up between tracks' settings. By default, global settings are used.
   * :guilabel:`Clean up between tracks`: remove those intervals between tracks that do not contain recognition events.
   * :guilabel:`Save tracks of events`: save tracks of events for a selected object (face, body, or vehicle).
   * :guilabel:`Keep events before and after`: a video interval in seconds before and after a track with events that is kept along with the track.
   * :guilabel:`Cleanup threshold`: a minimum interval between tracks in seconds. If an interval between tracks is below the threshold, the video is not removed. A minimum allowed value for this field is 360 seconds.
   * :guilabel:`Clean up between tracks from`: time period (in days) during which the entire video archive is kept. After this period, the intervals between tracks will be cleaned up as configured in the settings. The value can be greater than or equal to zero.

   **Clean up archive**

   * :guilabel:`Enable custom cleanup`: enable custom archive cleanup settings. By default, global settings are used.   
   * :guilabel:`Clean up archive`: enable the entire video archive cleanup.
   * :guilabel:`Archive cleanup age`: a number of days the video archive is kept in the system. After that period, the video archive is removed.

   Clicking on :guilabel:`Display global settings` will display global VMS cleanup settings.

   .. seealso::
      :ref:`global_vms_cleanup`

.. _upload_video_file:

Upload and Process Video File
==========================================

To upload and process a video, do the following:

#. Navigate to the :guilabel:`Video Sources` → :guilabel:`Uploads`.
#. Click :guilabel:`Upload files` or :guilabel:`Upload`.

     |video_uploads_en|

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

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

#. Specify a URL to the online storage, or select a file. Click :guilabel:`Upload`.

     |video_upload_file_en|

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

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

#. Designate a camera group to which the system will attribute the object recognition events from the video. The ``Video archive default Camera Group`` is perfect for this task. You can also create a :ref:`new camera group <camera-group>` with basic settings specifically for this video file. Select detectors that you want to enable on this video: faces, bodies, vehicles.

     |video_upload_pref_en|

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

     .. |video_upload_pref_ru| image:: /_static/video_upload_pref_ru.png
        :scale: 70%
   
    Click :guilabel:`Add and configure`. The video will be uploaded and shown in the source list.

#. Click the video on the list to open the processing configuration wizard. Specify parameters of :ref:`video processing <video_processing_parameters>` in the same way as for cameras.
   
     |video_upload_configuration_en|

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

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

    * (Optional) Select a camera within that camera group to tag the object recognition events from this video more precisely.
    * (Optional) Configure the timestamps for object recognition events.
 
#. On the list of video uploads, click three dots → :guilabel:`Process` to start object identification. You can view object identification events on the :guilabel:`Events` and :guilabel:`Episodes` tabs by filtering the list of events by the camera group/camera associated with the video.



External Detector
===================================
 
A camera object can also be used for integrating an :guilabel:`External Detector`.
    
     |camera_ex_detect_en|

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

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

If necessary, change the External detector name. Specify the Initial camera group and Description, enable liveness.

     |camera_ex_detect_set_en|

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

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




.. _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: 80%

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

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 an object.
* 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 object postings. To do so, modify the following parameters in the ``/opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py`` configuration file:

   .. code::
   
      sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

      FFSECURITY = {
         ...

         # max camera frames_dropped percent
         'MAX_CAMERA_DROPPED_FRAMES': {'yellow': 0.1, 'red': 0.3},
         # max camera objects failed percent
         'MAX_CAMERA_FAILED_OBJECTS': {'yellow': 0.1, 'red': 0.3},

         ...
         }   

   Restart all FindFace Multi containers.

   .. code::

      cd /opt/findface-multi/

      sudo docker-compose restart


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 :guilabel:`Restart`. In this case, the number of errors will be reset to ``0``.

     |camera_restart_en| 

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

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

If there are numerous cameras in the system, use the following filters:

* :guilabel:`Name contains`,
* :guilabel:`Camera groups`,
* Activity :guilabel:`Status` (Any / Only active / Only inactive),
* :guilabel:`Status` of operation (Any / Gray / Green / Read / Yellow).

     |camera_filters_en| 

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

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