# 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.
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/mxcube/argussight",
"name": "argussight",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": null,
"keywords": "MXCuBEWeb, video streaming, computer vision, multistream, process management",
"author": "Yan Walesch",
"author_email": "<yan.walesch@esrf.fr",
"download_url": "https://files.pythonhosted.org/packages/d7/75/238160e0602774dcce606ea00d193f470204c6f73016c4b0f7ce94452160/argussight-0.1.0.tar.gz",
"platform": null,
"description": "# Argussight\n\n`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.\n\nOriginally 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.\n\n## Advantages of using Argussight\n\n- **Enhanced User Experience**: Multiple streams could be displayed at once from the same source, providing a comprehensive view from different angles and/or sources.\n\n- **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.\n\n- **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.\n\n## Design Overview\n\n`Argussight` is built around four key components, each playing a vital role in its functionality.\n\n- `Spawner`: The core of `Argussight`, responsible for controlling, spawning and terminating video processes.\n\n- `GRPC Server`: Thightly connected to the `Spawner`, it handles the communication with a client application.\n\n- `Video processes`: Processes that are each running a specific video-related task, like generating or modifying camera streams.\n\n- `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.\n\n\n\n## Documentation \ud83d\udcda\n\nCheck out the full [documentation](https://mxcube.github.io/argussight/) to explore everything, this project has to offer! Including:\n\n- Information about all natively integrated video-related processes\n- A detailed explanation about the project's core functionalities\n- A comprehensive guide on how to start and run the project\n- A developers guide\n- and more!\n\n## Installation\n\nFirst you need to clone the repository.\n\n```\ngit clone https://github.com/mxcube/argussight.git\n\n# Navigate to the newly created directory\ncd argussight\n```\n\nOptionally, you can create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) environment for this project\n\n```\nconda env create -f conda-envrionment.yml\n```\n\nIf you chose not to, you need to have `ffmpeg` installed on your system, you can do so via your corresponding package manager.\nOn Debian-based Linux distributions (Ubuntu, Debian, Pop!_OS, ...) for example you can install it like this\n\n```\nsudo apt-get install ffmpeg\n```\n\nNow install the remaining dependencies using `pip`\n\n```\n# for Development\npip install -e .\n\n# for Usage\npip install .\n```\n\nor `poetry`\n\n```\npoetry install\n```\n\n## Usage\n\n> ### \u26a0\ufe0f Attention \u26a0\ufe0f\n> 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.\n> 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`).\n> - To rename the temporary folder, go to `argussight/core/configurations/processes/savers/video_recorder.yaml` and change the value of `temp_folder`.\n> - To disable the `Recorder` class, go to `argussight/core/configurations/config.yaml` and remove the process named `Recorder`\n\n### Start the Server\n\nOnce you installed all the dependencies, you can run the `argussight` server by using\n\n```\nargussight\n```\n\ncommand in a terminal window.\n\n### Start communication with the GRPC Server\n\nTo 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`:\n\n```\nimport grpc\nimport argussight.grpc.argus_service_pb2 as pb2\nimport argussight.grpc.argus_service_pb2_grpc as pb2_grpc\n\nchannel = grpc.insecure_channel(\"localhost:50051\")\nstub = pb2_grpc.SpawnerServiceStub(channel)\n\n# try to reach the server\ntry:\n response = stub.GetProcesses(pb2.GetProcessesRequest())\nexcept Exception as e:\n # handle exception here\n print(e)\n```\n\n### Access your streams\n\nTo 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.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An addition to MXCuBEWeb enabling simultaneous video streaming and distributed computer vision tasks.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://mxcube.github.io/argussight/",
"Homepage": "https://github.com/mxcube/argussight",
"Repository": "https://github.com/mxcube/argussight"
},
"split_keywords": [
"mxcubeweb",
" video streaming",
" computer vision",
" multistream",
" process management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2261b693d9a1cf6097fc31b6e1f61046c751f542e840fcd215dccd7bd9a66da7",
"md5": "9aa4c9121021140264d3a6567ac18375",
"sha256": "0f914890f2d9fcc4b1ff49a459f412a03c005b5ac8caea03f2e490d2cd7ae742"
},
"downloads": -1,
"filename": "argussight-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9aa4c9121021140264d3a6567ac18375",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10",
"size": 35192,
"upload_time": "2025-01-06T15:42:00",
"upload_time_iso_8601": "2025-01-06T15:42:00.300171Z",
"url": "https://files.pythonhosted.org/packages/22/61/b693d9a1cf6097fc31b6e1f61046c751f542e840fcd215dccd7bd9a66da7/argussight-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d775238160e0602774dcce606ea00d193f470204c6f73016c4b0f7ce94452160",
"md5": "abc15b2be079e1194844950d03bd4f2f",
"sha256": "72430a3f28cab3c85b5f4ad6453527d21ee8744121cf3f393f8d98871d216766"
},
"downloads": -1,
"filename": "argussight-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "abc15b2be079e1194844950d03bd4f2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 26653,
"upload_time": "2025-01-06T15:42:01",
"upload_time_iso_8601": "2025-01-06T15:42:01.876451Z",
"url": "https://files.pythonhosted.org/packages/d7/75/238160e0602774dcce606ea00d193f470204c6f73016c4b0f7ce94452160/argussight-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-06 15:42:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mxcube",
"github_project": "argussight",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "argussight"
}
JSON
