Metadata-Version: 2.4
Name: viso-sdk-python
Version: 2.0.0
Summary: VisoSDK: A Python SDK for use in Viso containers
Home-page: https://gitlab.com/TopKamera/03_edge/Base/viso-sdk-python-public.git
Author: support@viso.ai
Author-email: support@viso.ai
License: LGPLv3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
License-File: AUTHORS
Requires-Dist: requests
Requires-Dist: requests-toolbelt
Requires-Dist: setuptools
Requires-Dist: paho-mqtt
Requires-Dist: iceoryx2==0.10.0
Requires-Dist: opencv-contrib-python-headless~=4.10.0
Requires-Dist: cython~=3.0.2
Requires-Dist: numpy~=1.26.2
Requires-Dist: six~=1.16.0
Requires-Dist: traceback2~=1.4.0
Requires-Dist: shapely~=2.0.7
Requires-Dist: python-magic
Requires-Dist: orjson>=3.9.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# viso-sdk-python

**viso-sdk-python** is a Python SDK providing shared utilities for [viso.ai](https://viso.ai) edge containers. It covers logging, the frame bus between containers, MQTT communication, model fetching, ROI handling, detection structures, and more.

Licensed under [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.html).

---

## Requirements

- **Python** >= 3.10
- **glibc** >= 2.34, x86_64 (iceoryx2 wheels)
- **System library**: `libmagic1` (required by the `model` module)

```shell
apt-get install libmagic1
```

---

## Installation

```shell
pip install viso-sdk-python
```

2.x replaces Redis with the iceoryx2 frame bus; pin `"viso-sdk-python<2"` for the Redis-based SDK.

Releases are also uploaded to `s3://viso-dev-euc1-codebuild/viso_sdk_python/` (sdist and cp310/cp311/cp312 wheels):

```shell
aws s3 cp s3://viso-dev-euc1-codebuild/viso_sdk_python/ dist/ --recursive --exclude "*" --include "viso_sdk_python-2.0.0*"
pip install --find-links dist/ "viso-sdk-python==2.0.0"
```

---

## Modules

| Module | Description |
|---|---|
| `viso_sdk.constants` | Shared constants and environment-driven configuration |
| `viso_sdk.model` | Model fetching, extraction, and type detection |
| `viso_sdk.logging` | Centralised logger factory |
| `viso_sdk.ipc` | Frame bus: zero-copy frames between containers (iceoryx2) plus results/triggers/status on local MQTT |
| `viso_sdk.image` | JPEG/BMP/base64 image encode and decode helpers |
| `viso_sdk.mqtt` | MQTT client wrapper |
| `viso_sdk.roi` | Region-of-interest helpers |
| `viso_sdk.detection` | Detection result structures |
| `viso_sdk.edge` | Edge device utilities |
| `viso_sdk.status` | Container status reporting |
| `viso_sdk.nodered` | Node-RED integration helpers |

---

## Usage Examples

### Frame bus

Every output port of a node is an iceoryx2 service `viso/<node_id>/<port>`. Frames
(uint8 BGR/GRAY/BGRA) and the meta/result JSON travel together through shared
memory; subscribers always get the newest frame. The JSON is mirrored to the local
MQTT topic `viso_local/flow/<node_id>/<port>/result` for Node-RED.

```python
from viso_sdk.ipc import FramePublisher, FrameSubscriber, VisoData

# producer
viso_data = VisoData(feed_idx=0, cur_node=config)
pub = FramePublisher(node_id=config["id"], port=0, node_config=config)
pub.publish(viso_data.create_viso_data(result=detections), frame)

# or write straight into shared memory (no copy), e.g. while resizing
loaned = pub.loan((480, 640, 3))
cv2.resize(src, (640, 480), dst=loaned.image)
loaned.send(viso_data.create_viso_data(result=[]))

# consumer of the previous node's port
sub = FrameSubscriber(node_id=prev_node["id"], port=prev_port, data_manager=viso_data)
is_new, frame = sub.get_frame()                 # (False, None) on timeout / end of stream
is_new, frame, data = sub.receive_metadata()    # data["meta"], data["result"], data["frame"]

with sub.receive(copy=False) as f:              # zero-copy view, valid inside the block
    small = cv2.resize(f.image, (640, 640))

pub.close()                                     # sends end-of-stream to subscribers
```

Triggers from Node-RED:

```python
from viso_sdk.ipc import on_trigger

on_trigger(config["id"], lambda message: handle(message))
```

All participants must share `/dev/shm` (`podman run --ipc=host`), use the same
`/etc/iceoryx2/iceoryx2.toml` (`[global] root-path = "/dev/shm/iceoryx2/"`) and run as
the same host uid. The QoS in `viso_sdk/ipc/qos.py` and the header in
`viso_sdk/ipc/frame_header.py` are shared with viso-sdk-cpp.

### MQTT Messaging

```python
from viso_sdk.mqtt import MqttWrapper

# Initialize MQTT client
mqtt = MqttWrapper()

# Publish message
mqtt.publish(topic="device/status", message='{"state": "online"}')
```

### Logging

```python
from viso_sdk.logging import get_logger

logger = get_logger("MyModule")
logger.info("Application started")
logger.error("An error occurred")
```

---

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing guidelines, and CI pipeline information.

---

## License

Licensed under [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.html).
