argussight 0.1.0__tar.gz

argussight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 European Synchrotron Radiation Facility
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argussight-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.1
+Name: argussight
+Version: 0.1.0
+Summary: An addition to MXCuBEWeb enabling simultaneous video streaming and distributed computer vision tasks.
+Home-page: https://github.com/mxcube/argussight
+License: MIT
+Keywords: MXCuBEWeb,video streaming,computer vision,multistream,process management
+Author: Yan Walesch
+Author-email: <yan.walesch@esrf.fr
+Requires-Python: >=3.10,<3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: Flask (>=3.0.3,<4.0.0)
+Requires-Dist: grpcio (>=1.38.0,<2.0.0)
+Requires-Dist: grpcio-tools (>=1.38.0,<2.0.0)
+Requires-Dist: mxcube-video-streamer (>=1.6.0)
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: opencv-python (==4.10.0.84)
+Requires-Dist: pillow (>=9.4.0,<=10.4.0)
+Requires-Dist: pydantic (>=2.8.2,<2.9.0)
+Requires-Dist: python-levenshtein (>=0.25.1,<0.26.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: redis (==4.6.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: websocket-client (>=1.8.0,<2.0.0)
+Project-URL: Documentation, https://mxcube.github.io/argussight/
+Project-URL: Repository, https://github.com/mxcube/argussight
+Description-Content-Type: text/markdown
+
+# Argussight
+
+`Argussight` is a versatile video processing tool designed to manage and run multiple streaming processes using one or several input sources. It primarily works with FFmpeg streams, ensuring high compatibility and performance for video processing tasks.
+
+Originally developed as an extension of the [video-streamer](https://github.com/mxcube/video-streamer) project by the [MXCuBE](https://github.com/mxcube) organization, `Argussight` can also operate as a standalone application. Its flexible design allows it to be reconfigured for integration with other components, making it adaptable to various use cases.
+
+## Advantages of using Argussight
+
+- **Enhanced User Experience**: Multiple streams could be displayed at once from the same source, providing a comprehensive view from different angles and/or sources.
+
+- **Facilitates Usage of Computer Vision Algorithms**: Developers can make use of different computer vision algorithms, directly on the images and do not need to handle the complexity of handling video-loading or streaming.
+
+- **On-the-Fly Configuration**: The system can dynamically adjust streams, such as changing parameters for video anlaysis, change position of region of interest or simply switching between views according to user preferences, withou needing to restart or reconfigure the entire process.
+
+## Design Overview
+
+`Argussight` is built around four key components, each playing a vital role in its functionality.
+
+- `Spawner`: The core of `Argussight`, responsible for controlling, spawning and terminating video processes.
+
+- `GRPC Server`: Thightly connected to the `Spawner`, it handles the communication with a client application.
+
+- `Video processes`: Processes that are each running a specific video-related task, like generating or modifying camera streams.
+
+- `Stream-Layer`: An abstraction layer positioned between **streaming** processes and external systems. This layer simplifies access to the streams while enhancing security through port abstraction.
+
+![Argussight Overview](./assets/Overview.svg)
+
+## Documentation 📚
+
+Check out the full [documentation](https://mxcube.github.io/argussight/) to explore everything, this project has to offer! Including:
+
+- Information about all natively integrated video-related processes
+- A detailed explanation about the project's core functionalities
+- A comprehensive guide on how to start and run the project
+- A developers guide
+- and more!
+
+## Installation
+
+First you need to clone the repository.
+
+```
+git clone https://github.com/mxcube/argussight.git
+
+# Navigate to the newly created directory
+cd argussight
+```
+
+Optionally, you can create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) environment for this project
+
+```
+conda env create -f conda-envrionment.yml
+```
+
+If you chose not to, you need to have `ffmpeg` installed on your system, you can do so via your corresponding package manager.
+On Debian-based Linux distributions (Ubuntu, Debian, Pop!_OS, ...) for example you can install it like this
+
+```
+sudo apt-get install ffmpeg
+```
+
+Now install the remaining dependencies using `pip`
+
+```
+# for Development
+pip install -e .
+
+# for Usage
+pip install .
+```
+
+or `poetry`
+
+```
+poetry install
+```
+
+## Usage
+
+> ### ⚠️ Attention ⚠️
+> If you want to use the `Recorder` class (enabled per default), please be aware that it creates a temporary folder in the location, you start the server at.
+> In the configurations folder, you can change the name of said folder, please make sure that no other folder in your current location has the same name, as it will otherwise **delete** the contents of that folder (default is `temp`).
+> - To rename the temporary folder, go to `argussight/core/configurations/processes/savers/video_recorder.yaml` and change the value of `temp_folder`.
+> - To disable the `Recorder` class, go to `argussight/core/configurations/config.yaml` and remove the process named `Recorder`
+
+### Start the Server
+
+Once you installed all the dependencies, you can run the `argussight` server by using
+
+```
+argussight
+```
+
+command in a terminal window.
+
+### Start communication with the GRPC Server
+
+To communicate with the grpc server, you need to establish a connection with the channel. By default the server is running on port 50051 (changeable in the `argussight/grpc/server.py` file). The code example below shows how to start a connection and get a response for the `GetProcessesRequest`:
+
+```
+import grpc
+import argussight.grpc.argus_service_pb2 as pb2
+import argussight.grpc.argus_service_pb2_grpc as pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = pb2_grpc.SpawnerServiceStub(channel)
+
+# try to reach the server
+try:
+    response = stub.GetProcesses(pb2.GetProcessesRequest())
+except Exception as e:
+    # handle exception here
+    print(e)
+```
+
+### Access your streams
+
+To access your streams, you first need a running streaming process. To create one, you need to make a process that inherits the `Streamer` class. Please refer to the [documentation](https://mxcube.github.io/argussight/devs/vprocess/#streamer) on how to do that. If your class inherits `Streamer` and is correctly configured in the `config.yaml` file, the `Argussight` class will take care of adding every instance of your class to the `Abstraction-Layer`. To access the streams from outside, you can then create a websocket connection to `ws://localhost:7000/ws/${name}`, where `localhost:7000` is the default location of the `Abstraction-Layer` (configurable in `config.yaml`), and `name` is the unique name of your process instance.
+

argussight-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Argussight
+
+`Argussight` is a versatile video processing tool designed to manage and run multiple streaming processes using one or several input sources. It primarily works with FFmpeg streams, ensuring high compatibility and performance for video processing tasks.
+
+Originally developed as an extension of the [video-streamer](https://github.com/mxcube/video-streamer) project by the [MXCuBE](https://github.com/mxcube) organization, `Argussight` can also operate as a standalone application. Its flexible design allows it to be reconfigured for integration with other components, making it adaptable to various use cases.
+
+## Advantages of using Argussight
+
+- **Enhanced User Experience**: Multiple streams could be displayed at once from the same source, providing a comprehensive view from different angles and/or sources.
+
+- **Facilitates Usage of Computer Vision Algorithms**: Developers can make use of different computer vision algorithms, directly on the images and do not need to handle the complexity of handling video-loading or streaming.
+
+- **On-the-Fly Configuration**: The system can dynamically adjust streams, such as changing parameters for video anlaysis, change position of region of interest or simply switching between views according to user preferences, withou needing to restart or reconfigure the entire process.
+
+## Design Overview
+
+`Argussight` is built around four key components, each playing a vital role in its functionality.
+
+- `Spawner`: The core of `Argussight`, responsible for controlling, spawning and terminating video processes.
+
+- `GRPC Server`: Thightly connected to the `Spawner`, it handles the communication with a client application.
+
+- `Video processes`: Processes that are each running a specific video-related task, like generating or modifying camera streams.
+
+- `Stream-Layer`: An abstraction layer positioned between **streaming** processes and external systems. This layer simplifies access to the streams while enhancing security through port abstraction.
+
+![Argussight Overview](./assets/Overview.svg)
+
+## Documentation 📚
+
+Check out the full [documentation](https://mxcube.github.io/argussight/) to explore everything, this project has to offer! Including:
+
+- Information about all natively integrated video-related processes
+- A detailed explanation about the project's core functionalities
+- A comprehensive guide on how to start and run the project
+- A developers guide
+- and more!
+
+## Installation
+
+First you need to clone the repository.
+
+```
+git clone https://github.com/mxcube/argussight.git
+
+# Navigate to the newly created directory
+cd argussight
+```
+
+Optionally, you can create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) environment for this project
+
+```
+conda env create -f conda-envrionment.yml
+```
+
+If you chose not to, you need to have `ffmpeg` installed on your system, you can do so via your corresponding package manager.
+On Debian-based Linux distributions (Ubuntu, Debian, Pop!_OS, ...) for example you can install it like this
+
+```
+sudo apt-get install ffmpeg
+```
+
+Now install the remaining dependencies using `pip`
+
+```
+# for Development
+pip install -e .
+
+# for Usage
+pip install .
+```
+
+or `poetry`
+
+```
+poetry install
+```
+
+## Usage
+
+> ### ⚠️ Attention ⚠️
+> If you want to use the `Recorder` class (enabled per default), please be aware that it creates a temporary folder in the location, you start the server at.
+> In the configurations folder, you can change the name of said folder, please make sure that no other folder in your current location has the same name, as it will otherwise **delete** the contents of that folder (default is `temp`).
+> - To rename the temporary folder, go to `argussight/core/configurations/processes/savers/video_recorder.yaml` and change the value of `temp_folder`.
+> - To disable the `Recorder` class, go to `argussight/core/configurations/config.yaml` and remove the process named `Recorder`
+
+### Start the Server
+
+Once you installed all the dependencies, you can run the `argussight` server by using
+
+```
+argussight
+```
+
+command in a terminal window.
+
+### Start communication with the GRPC Server
+
+To communicate with the grpc server, you need to establish a connection with the channel. By default the server is running on port 50051 (changeable in the `argussight/grpc/server.py` file). The code example below shows how to start a connection and get a response for the `GetProcessesRequest`:
+
+```
+import grpc
+import argussight.grpc.argus_service_pb2 as pb2
+import argussight.grpc.argus_service_pb2_grpc as pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = pb2_grpc.SpawnerServiceStub(channel)
+
+# try to reach the server
+try:
+    response = stub.GetProcesses(pb2.GetProcessesRequest())
+except Exception as e:
+    # handle exception here
+    print(e)
+```
+
+### Access your streams
+
+To access your streams, you first need a running streaming process. To create one, you need to make a process that inherits the `Streamer` class. Please refer to the [documentation](https://mxcube.github.io/argussight/devs/vprocess/#streamer) on how to do that. If your class inherits `Streamer` and is correctly configured in the `config.yaml` file, the `Argussight` class will take care of adding every instance of your class to the `Abstraction-Layer`. To access the streams from outside, you can then create a websocket connection to `ws://localhost:7000/ws/${name}`, where `localhost:7000` is the default location of the `Abstraction-Layer` (configurable in `config.yaml`), and `name` is the unique name of your process instance.

argussight-0.1.0/argussight/core/config.py

@@ -0,0 +1,20 @@
+from typing import Union
+
+from pydantic import BaseModel, Field
+
+
+class RedisConfiguration(BaseModel):
+    host: str = Field("localhost", description="redis host")
+    port: int = Field(6379, description="redis port")
+    channel: str = Field(
+        "video-streamer", description="redis-channel to publish stream"
+    )
+
+
+class CollectorConfiguration(BaseModel):
+    redis: RedisConfiguration
+
+
+def get_config_from_dict(config_data: dict) -> Union[CollectorConfiguration, None]:
+    data = CollectorConfiguration(**config_data)
+    return data

argussight-0.1.0/argussight/core/configurations/config.yaml

@@ -0,0 +1,40 @@
+---
+
+# This indicates the path to the files of the process classes
+modules_path: argussight.core.video_processes
+
+# List of available processes and their file locations from modules_path
+# If accessible=true then process can be started via grpc call
+worker_classes:
+  test:
+    location: vprocess.Test
+    accessible: true
+  flow_detection:
+    location: streamer.optical_flow_detection.OpticalFlowDetection
+    accessible: true
+  stream_buffer:
+    location: savers.stream_buffer.StreamBuffer
+    accessible: false
+  video_recorder:
+    location: savers.video_recorder.Recorder
+    accessible: false
+
+# This indicates the processes that are started by argussight,
+# if killed due to no response, they are restarted automatically
+processes:
+  - name: "Saver"
+    type: stream_buffer
+  - name: "Recorder"
+    type: video_recorder
+
+# This indicates the maximal waiting time (s),
+# the spawner waits on responds from processes, before killing them
+wait_time: 5
+
+# This is the port for the rerouting of the streams
+streams_layer_port: 7000
+
+# Argussight is configured to run streams on different ports
+# It will check for free ports, whenever a new streaming process starts
+# The value below indicates at which port the search for a free port begins,
+streams_starting_port: 9000

argussight-0.1.0/argussight/core/configurations/processes/savers/stream_buffer.yaml

@@ -0,0 +1,15 @@
+---
+
+parameters:
+  max_queue_len:
+    value: 200
+    exposed: false
+  main_save_folder:
+    value: "logs/"
+    exposed: false
+  save_format:
+    value: "both"
+    exposed: true
+  personnal_folder:
+    value: "test"
+    exposed: true

argussight-0.1.0/argussight/core/configurations/processes/savers/video_recorder.yaml

@@ -0,0 +1,22 @@
+---
+
+parameters:
+  main_save_folder:
+    value: "logs/recordings"
+    exposed: false
+  # pay attention to the setting of the temp folder, as the folder will
+  # be cleared when the recorder is initialised,
+  # IMPORTANT: do NOT use an existing folder!!!
+  temp_folder:
+    value: "temp"
+    exposed: false
+  save_format:
+    value: "both"
+    exposed: true
+  personnal_folder:
+    value: "test"
+    exposed: true
+  max_recording_time:
+    # unit: seconds, 0 means not set
+    value: 0
+    exposed: false

argussight-0.1.0/argussight/core/configurations/processes/savers/video_saver.yaml

@@ -0,0 +1,16 @@
+---
+
+parameters:
+  main_save_folder:
+    value: "logs/"
+    exposed: false
+  save_format:
+    value: "both"
+    exposed: true
+  personnal_folder:
+    value: "test"
+    exposed: true
+  max_recording_time:
+    # unit: seconds, 0 means not set
+    value: 0
+    exposed: false

argussight-0.1.0/argussight/core/configurations/processes/streamer/flow_detection.yaml

@@ -0,0 +1,21 @@
+---
+
+parameters:
+  feature_params:
+    value:
+      maxCorners: 5
+      qualityLevel: 0.7
+      minDistance: 50
+      blockSize: 7
+    exposed: false
+
+  lk_params:
+    value:
+      winSize: [15, 15]
+      maxLevel: 2
+      criteria: [3, 10, 0.03]
+    exposed: false
+
+  roi:
+    value: [550, 450, 200, 500]
+    exposed: true

argussight-0.1.0/argussight/core/configurations/processes/streamer/optical_flow_detection.yaml

@@ -0,0 +1,16 @@
+---
+
+parameters:
+  flow_params:
+    value:
+      pyr_scale: 0.5
+      levels: 3
+      winsize: 15
+      iterations: 3
+      poly_n: 5
+      poly_sigma: 1.1
+      flags: 0
+    exposed: false
+  roi:
+    value: [550, 450, 200, 500]
+    exposed: true

argussight-0.1.0/argussight/core/configurations/processes/streamer/streamer.yaml

@@ -0,0 +1,3 @@
+---
+
+parameters: {}

argussight-0.1.0/argussight/core/configurations/processes/vprocess.yaml

@@ -0,0 +1,3 @@
+---
+
+parameters: {}

argussight-0.1.0/argussight/core/helper_functions.py

@@ -0,0 +1,35 @@
+import socket
+from typing import Union
+
+import Levenshtein
+
+
+def find_close_key(d: dict, key: str, max_distance: int = 3) -> Union[str, None]:
+    """Return first key in dict whose Levenshtein distance to key is <= max_distance"""
+    min_distance = float("inf")
+    closest_key = None
+
+    for dict_key in d:
+        distance = Levenshtein.distance(key, dict_key)
+        if distance < min_distance:
+            min_distance = distance
+            closest_key = dict_key
+
+    if min_distance <= max_distance:
+        return closest_key
+
+    return None
+
+
+def is_port_free(port):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(1)  # Optional: set a short timeout for connection attempt
+        result = s.connect_ex(("localhost", port))
+        return result != 0  # If result is non-zero, port is free
+
+
+def find_free_port(start_port=9000):
+    port = start_port
+    while not is_port_free(port):
+        port += 1
+    return port

argussight-0.1.0/argussight/core/manager.py

@@ -0,0 +1,71 @@
+import queue
+from datetime import datetime
+from multiprocessing import Queue
+from threading import Event
+
+from argussight.core.video_processes.vprocess import ProcessError
+
+
+class Manager:
+    def __init__(
+        self,
+        command_queue: Queue,
+        response_queue: Queue,
+        finished_event: Event,
+        failed_event: Event,
+    ) -> None:
+        self._commands_list = queue.Queue(
+            maxsize=20
+        )  # commands that are waiting to be processed by Manager
+        self._command_queue = (
+            command_queue  # commands that are sent to process for being processed
+        )
+        self._response_queue = response_queue
+        self._finished_event = finished_event
+        self._failed_event = failed_event
+
+    def receive_command(
+        self,
+        command: str,
+        wait_time: int,
+        processed_event: Event,
+        result_queue: queue.Queue,
+        args,
+    ) -> None:
+        if self._commands_list.full():
+            raise ProcessError(
+                f"Cannot execute command {command}: too many commands in waiting list"
+            )
+        self._commands_list.put(
+            {
+                "command": command,
+                "max_wait_time": wait_time,
+                "time_stamp": datetime.now(),
+                "args": args,
+                "processed_event": processed_event,
+                "result_queue": result_queue,
+            }
+        )
+
+    def handle_commands(self) -> None:
+        while not self._commands_list.empty():
+            command = self._commands_list.get()
+
+            # Check if command is alive
+            if (datetime.now() - command["time_stamp"]).total_seconds() > command[
+                "max_wait_time"
+            ]:
+                continue
+
+            self._command_queue.put((command["command"], command["args"]))
+            command["processed_event"].set()
+
+            try:
+                result = self._response_queue.get(timeout=command["max_wait_time"])
+                command["result_queue"].put(result)
+
+            except queue.Empty:
+                self._failed_event.set()
+                break
+
+        self._finished_event.set()