Metadata-Version: 2.4
Name: mini-vision
Version: 0.3.0
Summary: YOLO segmentation utilities for video streams
Author: Deivid Manfre
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: ultralytics
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: websockets

# mini_vision

Simple Python library for object segmentation in video streams using YOLO models.

The goal of this library is to provide a modular pipeline to:

- consume video streams
- perform object segmentation
- render contours or masks

The library follows data-oriented design and low coupling principles, allowing easy replacement of computer vision models.

---

## Installation

```
pip install mini-vision
```

## Usage

Example showing how to use vision-seg to consume a video stream, run YOLO segmentation, and render object contours.

### Import the library

```
from vision_seg import (
    YoloSegmenter,
    SegmentationRenderer,
    WSFrameClient
)
```

### Components:

| Component              | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `YoloSegmenter`        | Runs object segmentation using a YOLO segmentation model |
| `SegmentationRenderer` | Draws segmentation contours on the frame                 |
| `WSFrameClient`        | Connects to a WebSocket video stream and yields frames   |


#### YoloSegmenter

Runs object segmentation using a YOLO segmentation model.

```
segmenter = YoloSegmenter("yolov8n-seg.pt")
detections = segmenter.segment(frame)
```

#### SegmentationRenderer

Responsible for rendering segmentation contours on frames.

````
renderer = SegmentationRenderer()
frame = renderer.draw(
    frame,
    detections,
    mode="contour",
    detect_object=["car","person","dog"],
    detect_color=["gold","neon_pink","lime"],
    thickness=2
)
````
##### JSON Output (optional)

SegmentationRenderer can optionally return structured detection data in JSON format.
This allows integration with logging systems, APIs, analytics pipelines, or other downstream processing tools.
To enable this feature, pass return_json=True

```
frame, data = renderer.draw(
    frame,
    detections,
    mode="contour",
    detect_object=["car","person","dog"],
    detect_color=["gold","neon_pink","lime"],
    thickness=2,
    return_json=True
)
```

Example JSON output:

```
{
  "detections": [
    {
      "label": "person",
      "confidence": 0.92,
      "bbox": [120, 80, 240, 300]
    },
    {
      "label": "car",
      "confidence": 0.88,
      "bbox": [400, 210, 560, 350]
    }
  ]
}
```

If return_json is not enabled, the renderer behaves normally and only returns the processed frame.

##### TOON Output

the renderer can also return detections in TOON format, a lightweight 
text representation designed for agent pipelines, logging, and token-efficient LLM processing. Enable it using return_toon=True

```
frame, toon = renderer.draw(
    frame,
    detections,
    return_toon=True
)
```

Example TOON output:

```
frame_width=1280 frame_height=720
label=person x=412 y=210 w=120 h=260 cx=472 cy=340 area=31200 score=0.91
label=car x=102 y=320 w=180 h=90 cx=192 cy=365 area=16200 score=0.88
```


#### WSFrameClient

Connects to a WebSocket video stream and yields frames.

```
client = WSFrameClient("ws://127.0.0.1:8000/ws/frames")
async for frame in client.frames():
```
