Metadata-Version: 2.5
Name: ml-pipes-ultralytics
Version: 0.1.2rc1
Summary: Ultralytics YOLO operators for ml-pipes
Project-URL: Homepage, https://trained-by-humans.github.io/ml-pipes-ultralytics/
Project-URL: Documentation, https://trained-by-humans.github.io/ml-pipes-ultralytics/
Project-URL: Repository, https://github.com/trained-by-humans/ml-pipes-ultralytics
Project-URL: Issues, https://github.com/trained-by-humans/ml-pipes-ultralytics/issues
Project-URL: Changelog, https://github.com/trained-by-humans/ml-pipes-ultralytics/releases
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: computer-vision,ml-pipes,ultralytics,yolo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: ml-pipes-core==0.1.2rc1
Requires-Dist: ml-pipes-vision==0.1.2rc1
Requires-Dist: ultralytics>=8.4.143
Provides-Extra: docs
Requires-Dist: mike>=2.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

![python-version](https://img.shields.io/pypi/pyversions/ultralytics)
[![Ultralytics Coverage](https://img.shields.io/badge/ultralytics-8.4.143-purple)](./docs/coverage.md)

# ml-pipes-ultralytics

> [!IMPORTANT] 
> `ml-pipes-ultralytics` remains a community-maintained operator package
> within the [ml-pipes](https://github.com/trained-by-humans) ecosystem. The
> project has its own maintainers and development roadmap, while benefiting
> from ml-pipes' verified publishing and distribution process. 
> 
> For contributions, issues, and project decisions, use this repository's
> maintainers and issue tracker.

[Ultralytics](https://github.com/ultralytics/ultralytics) is the open-source
repository behind the YOLO computer-vision framework. It provides model
training, validation, prediction, tracking, export, and native `Results`
objects for detection, segmentation, pose, classification, and oriented-box
tasks.

`ml-pipes-ultralytics` makes its prediction, embedding, tracking, and result
operations composable [ml-pipes](https://github.com/trained-by-humans/ml-pipes)
operators. Native Ultralytics models and `Results` remain intact at the
boundary, while pipeline configuration and data flow become explicit.

## Coverage

The package operator catalog is maintained in
[docs/reference.md](./docs/reference.md). The Ultralytics API comparison is in
[docs/coverage.md](./docs/coverage.md).

## Install

```bash
python -m pip install ml-pipes-ultralytics
```

## License and Ultralytics terms

`ml-pipes-ultralytics` is licensed under the [Apache License 2.0](./LICENSE.txt).
It requires [Ultralytics](https://github.com/ultralytics/ultralytics), which is
licensed separately under AGPL-3.0 or an [Ultralytics Enterprise
License](https://www.ultralytics.com/license). Installing or using this package
does not grant rights to Ultralytics software or model weights. Users of the
community Ultralytics distribution must comply with AGPL-3.0; Enterprise users
must ensure their Ultralytics agreement covers their intended use.

## Quickstart

Build a segmentation-and-annotation pipeline. The model configuration belongs
to `yolo.Predict`; the pipeline call receives only the BGR image.

```python
import cv2

from ml_pipes.core import Pipeline
from ml_pipes.standard import Select
from ml_pipes.ultralytics import results, yolo

pipeline = Pipeline(
    [
        yolo.Predict(model="yolo26n-seg.pt", conf=0.25),
        Select(0),
        results.Plot(color_mode="instance"),
    ]
)

image = cv2.imread("photo.jpg")
annotated = pipeline(image)
cv2.imwrite("annotated.jpg", annotated)
```

`yolo.Predict`, `yolo.Embed`, and `yolo.Track` accept normal Ultralytics
source types—paths, URLs, camera sources, in-memory images, tensors, and
batches—but do not support `stream=True`. For videos or large datasets, use a
pipeline that explicitly owns decoding, batching, and frame scheduling.

## Built with Ultralytics x ml-pipes

<details>
<summary>View runnable Ultralytics example pipelines</summary>

| Example | Upstream source | Note |
|---|---|---|
| [`run_detect_and_crop.py`](./examples/run_detect_and_crop.py) | [Object Cropping](https://docs.ultralytics.com/guides/object-cropping/) | Detects objects, saves native result crops, and renders the annotated image. |
| [`run_segment_and_annotate.py`](./examples/run_segment_and_annotate.py) | [Instance Segmentation and Tracking](https://docs.ultralytics.com/guides/instance-segmentation-and-tracking/) | Runs segmentation and renders instance-coloured masks. |
| [`run_object_blurrer.py`](./examples/run_object_blurrer.py) | [Object Blurring](https://docs.ultralytics.com/guides/object-blurring/) | Tracks and blurs COCO `person` detections. |
| [`run_detection_video.py`](./examples/run_detection_video.py) | [Ultralytics predict mode](https://docs.ultralytics.com/modes/predict/) | Uses an explicit OpenCV capture loop and one non-streaming prediction pipeline call per frame. |
| [`run_track_objects.py`](./examples/run_track_objects.py) | [Ultralytics track mode](https://docs.ultralytics.com/modes/track/) | Preserves native tracker state and draws native tracking IDs plus explicit motion traces. |

</details>

For additional YOLO examples and broader computer-vision use cases, see
[ml-pipes-supervision](https://github.com/trained-by-humans/ml-pipes-supervision).
