Add Agent to support RTSP compatible IP cameras (#605)

* Draft of RTSP camera agent

* Implement motion detection and add a fake camera class.

* Add option to disable motion detection.  Add documentation.

* Add import test

* Small cleanup

* Small tweak to docs

* Fix typo in docs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add opencv to mock imports

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address silly flake8 complaints

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Move common camera tools out of rtsp agent

* Rename rtsp camera directory

* Rename agent to RTSPCameraAgent

* Change name of snapshot interval argument

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Clean up imports.  First draft of motion detection start/stop times.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs

* Fix flake8 errors

* Apparently relative imports do not work here.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix name in plugin loader

* Another naming fix

* Pass motion start / stop to agent class

* Remove stale debug statement

* Add agent to plugin.py

* Fix sidebar link to agent docs

* Add dependencies in other needed locations

* Clean up examples in docs

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Brian Koopman <[email protected]>

docs/agents/rtsp_camera.rst

@@ -0,0 +1,89 @@
+.. highlight:: rst
+
+.. _rtsp_camera:
+
+====================
+RTSP Camera Agent
+====================
+
+This OCS Agent which grabs screenshots and records video from IP cameras
+supporting the RTSP streaming protocol.
+
+.. argparse::
+    :filename: ../socs/agents/rtsp_camera/agent.py
+    :func: add_agent_args
+    :prog: python3 agent.py
+
+Configuration File Examples
+---------------------------
+
+Below are configuration examples for the ocs config file and for running the
+Agent in a docker container.
+
+OCS Site Config
+```````````````
+
+To configure the RTSP Camera Agent we need to add a RTSPCameraAgent block to our
+ocs configuration file. Here is an example configuration block using all of the
+common arguments. Many options do not normally need to be changed::
+
+      {'agent-class': 'RTSPCameraAgent',
+       'instance-id': 'camera-c3',
+       'arguments': ['--mode', 'acq',
+                     '--directory', '/camera',
+                     '--address', 'camera-c3.example.org',
+                     '--user', 'ocs',
+                     '--password', '<password>',
+                     '--motion_start', '19:00:00-04:00',
+                     '--motion_stop', '07:00:00-04:00',
+                     '--snapshot_seconds', '10',
+                     '--record_duration', '120']},
+
+Docker Compose
+``````````````
+
+The RTSP camera Agent should be configured to run in a Docker container. An
+example docker-compose service configuration is shown here::
+
+  ocs-camera-c3:
+    image: simonsobs/socs:latest
+    hostname: ocs-docker
+    environment:
+      - INSTANCE_ID=camera-c3
+      - SITE_HUB=ws://127.0.0.1:8001/ws
+      - SITE_HTTP=http://127.0.0.1:8001/call
+      - LOGLEVEL=info
+    volumes:
+      - ${OCS_CONFIG_DIR}:/config:ro
+      - /so/cameras/c3:/camera
+    user: 9000:9000
+
+The ``LOGLEVEL`` environment variable can be used to set the log level for
+debugging. The default level is "info". The volume must mount to whatever
+location inside the container that you specified in the config file. The user
+must have permissions to write to the mounted local directory.
+
+Description
+-----------
+
+The indoor IP cameras at the site support the RTSP protocol. These cameras are
+mainly for security monitoring. The directory specified in the configuration is
+the top level directory for storing files. Two subdirectories, "snapshots" and
+"recordings" are created below this. Snapshots are saved every 10 seconds and a
+couple days worth are kept in a circular buffer on disk. A symlink
+("latest.jpg") is kept for the latest snapshot acquired, and this can be
+displayed in a Grafana text panel using an HTML image tag.
+
+By default, these snapshots are processed for motion detection. If motion is
+detected, a 20fps video recording is triggered. During recording, further motion
+detection is disabled. After the recording stops, motion detection resumes.
+These recordings are also kept in a circular disk buffer in the "recordings"
+subdirectory. These full video files are for manual download and viewing after a
+security event. All image and video files contain the ISO timestamp when they
+were acquired.
+
+Agent API
+---------
+
+.. autoclass:: socs.agents.rtsp_camera.agent.RTSPCameraAgent
+    :members:

docs/conf.py

@@ -109,6 +109,8 @@
                         'sodetlib.det_config',
                         'src',
                         'src.pid_controller',
+                        'cv2',
+                        'imutils',
                         ]
 from unittest import mock
 

docs/index.rst

@@ -69,6 +69,7 @@ API Reference        Full API documentation for core parts of the SOCS library.
     agents/pfeiffer_tc400
     agents/pysmurf-controller
     agents/pysmurf-monitor
+    agents/rtsp_camera
     agents/scpi_psu
     agents/smurf_crate_monitor
     agents/smurf_timing_card

pyproject.toml

@@ -52,8 +52,10 @@ acu = [
 # Note: Not including the holography deps, which are Python 3.8 only. Also not
 # including any dependencies with only direct references.
 all = [
+    "imutils",
     "labjack-ljm",
     "numexpr",
+    "opencv-python",
     "pandas",
     "pfeiffer-vacuum-protocol==0.4",
     "pixell",
@@ -78,6 +80,11 @@ magpie = [
     "scipy",
     "so3g",
 ]
+# Camera control
+camera = [
+    "opencv-python",
+    "imutils",
+]
 # Pfeiffer TC 400 Agent
 pfeiffer = [
     "pfeiffer-vacuum-protocol==0.4",

requirements.txt

@@ -33,6 +33,10 @@ labjack-ljm
 scipy
 pandas
 
+# camera control
+imutils
+opencv-python
+
 # pfeiffer tc 400
 pfeiffer-vacuum-protocol==0.4
 

socs/agents/ocs_plugin_so.py

@@ -39,6 +39,7 @@
         ('PfeifferTC400Agent', 'pfeiffer_tc400/agent.py'),
         ('PysmurfController', 'pysmurf_controller/agent.py'),
         ('PysmurfMonitor', 'pysmurf_monitor/agent.py'),
+        ('RTSPCameraAgent', 'rtsp_camera/agent.py'),
         ('ScpiPsuAgent', 'scpi_psu/agent.py'),
         ('SmurfFileEmulator', 'smurf_file_emulator/agent.py'),
         ('SmurfStreamSimulator', 'smurf_stream_simulator/agent.py'),

socs/agents/rtsp_camera/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (C) 2023-2024 Simons Observatory Collaboration
+# See top-level LICENSE.txt file for more information.
+"""Agent to capture images from cameras which support the RTSP protocol.
+"""