adsist-cms/python-detector-worker
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

refactor documentation for worker communication protocol; improve formatting and clarify crop coordinates and session ID handling
All checks were successful
Build Backend Application and Docker Image / build-docker (push) Successful in 8m50s
Details

Browse source
This commit is contained in:
Siwat Sirichai 2025-07-14 11:19:11 +07:00
parent 112ca9325d
commit c7bb46e1e3
1 changed files with 12 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

22
worker.md
View file

@ -20,16 +20,17 @@ Communication is bidirectional and asynchronous. All messages are JSON objects w
To enable modularity and dynamic configuration, the backend will send you a URL to a `.mpta` file when it issues a `subscribe` command. This file is a renamed `.zip` archive that contains everything your worker needs to perform its task. To enable modularity and dynamic configuration, the backend will send you a URL to a `.mpta` file when it issues a `subscribe` command. This file is a renamed `.zip` archive that contains everything your worker needs to perform its task.
**Your worker is responsible for:** **Your worker is responsible for:**
1. Fetching this file from the provided URL.
2. Extracting its contents. 1. Fetching this file from the provided URL.
3. Interpreting the contents to configure its internal pipeline. 2. Extracting its contents.
3. Interpreting the contents to configure its internal pipeline.
**The contents of the `.mpta` file are entirely up to the user who configures the model in the CMS.** This allows for maximum flexibility. For example, the archive could contain: **The contents of the `.mpta` file are entirely up to the user who configures the model in the CMS.** This allows for maximum flexibility. For example, the archive could contain:
* **AI/ML Models:** Pre-trained models for libraries like TensorFlow, PyTorch, or ONNX. - AI/ML Models: Pre-trained models for libraries like TensorFlow, PyTorch, or ONNX.
* **Configuration Files:** A `config.json` or `pipeline.yaml` that defines a sequence of operations, specifies model paths, or sets detection thresholds. - Configuration Files: A `config.json` or `pipeline.yaml` that defines a sequence of operations, specifies model paths, or sets detection thresholds.
* **Scripts:** Custom Python scripts for pre-processing or post-processing. - Scripts: Custom Python scripts for pre-processing or post-processing.
* **API Integration Details:** A JSON file with endpoint information and credentials for interacting with third-party detection services. - API Integration Details: A JSON file with endpoint information and credentials for interacting with third-party detection services.
Essentially, the `.mpta` file is a self-contained package that tells your worker *how* to process the video stream for a given subscription. Essentially, the `.mpta` file is a self-contained package that tells your worker *how* to process the video stream for a given subscription.
@ -69,6 +70,7 @@ This message is crucial for the backend to monitor your worker's health and stat
``` ```
> **Note:** > **Note:**
>
> - `cropX1`, `cropY1`, `cropX2`, `cropY2` (optional, integer) should be included in each camera connection to indicate the crop coordinates for that subscription. > - `cropX1`, `cropY1`, `cropX2`, `cropY2` (optional, integer) should be included in each camera connection to indicate the crop coordinates for that subscription.
### 4.2. Image Detection ### 4.2. Image Detection
@ -191,9 +193,9 @@ Instructs the worker to process a camera's RTSP stream using the configuration f
``` ```
> **Note:** > **Note:**
>
> - `cropX1`, `cropY1`, `cropX2`, `cropY2` (optional, integer) specify the crop coordinates for the camera stream. These values are configured per display and passed in the subscription payload. If not provided, the worker should process the full frame. > - `cropX1`, `cropY1`, `cropX2`, `cropY2` (optional, integer) specify the crop coordinates for the camera stream. These values are configured per display and passed in the subscription payload. If not provided, the worker should process the full frame.
> >
> **Important:** > **Important:**
> If multiple displays are bound to the same camera, your worker must ensure that only **one stream** is opened per camera. When you receive multiple subscriptions for the same camera (with different `subscriptionIdentifier` values), you should: > If multiple displays are bound to the same camera, your worker must ensure that only **one stream** is opened per camera. When you receive multiple subscriptions for the same camera (with different `subscriptionIdentifier` values), you should:
> >
@ -201,10 +203,8 @@ Instructs the worker to process a camera's RTSP stream using the configuration f
> - Capture each snapshot only once per cycle, and reuse it for all display subscriptions sharing that camera. > - Capture each snapshot only once per cycle, and reuse it for all display subscriptions sharing that camera.
> - Capture each frame/image only once per cycle. > - Capture each frame/image only once per cycle.
> - Reuse the same captured image and snapshot for all display subscriptions that share the camera, processing and routing detection results separately for each display as needed. > - Reuse the same captured image and snapshot for all display subscriptions that share the camera, processing and routing detection results separately for each display as needed.
>
> This avoids unnecessary load and bandwidth usage, and ensures consistent detection results and snapshots across all displays sharing the same camera. > This avoids unnecessary load and bandwidth usage, and ensures consistent detection results and snapshots across all displays sharing the same camera.
### 5.2. Unsubscribe from Camera ### 5.2. Unsubscribe from Camera
Instructs the worker to stop processing a camera's stream. Instructs the worker to stop processing a camera's stream.
@ -286,6 +286,7 @@ Or to clear the session:
``` ```
> **Note:** > **Note:**
>
> - The worker should store the session ID for the given subscription and use it in subsequent detection or patch messages as appropriate. If `sessionId` is `null`, the worker should treat the subscription as having no active session. > - The worker should store the session ID for the given subscription and use it in subsequent detection or patch messages as appropriate. If `sessionId` is `null`, the worker should treat the subscription as having no active session.
## Subscription Identifier Format ## Subscription Identifier Format
@ -303,6 +304,7 @@ This uniquely identifies a camera subscription for a specific display.
When the backend sends a `setSessionId` command, it will only provide the `displayIdentifier` (not the full `subscriptionIdentifier`). When the backend sends a `setSessionId` command, it will only provide the `displayIdentifier` (not the full `subscriptionIdentifier`).
**Worker Responsibility:** **Worker Responsibility:**
- The worker must match the `displayIdentifier` to all active subscriptions for that display (i.e., all `subscriptionIdentifier` values that start with `displayIdentifier;`). - The worker must match the `displayIdentifier` to all active subscriptions for that display (i.e., all `subscriptionIdentifier` values that start with `displayIdentifier;`).
- The worker should set or clear the session ID for all matching subscriptions. - The worker should set or clear the session ID for all matching subscriptions.