Metadata-Version: 2.4
Name: superiorvision
Version: 0.30.0.dev3
Summary: A tensor-native, inference-focused fork of Supervision
Author-email: "Roboflow et al." <develop@roboflow.com>
Maintainer-email: Piotr Skalski <piotr@roboflow.com>
License-Expression: MIT
Project-URL: Documentation, https://supervision.roboflow.com/latest/
Project-URL: Homepage, https://github.com/roboflow/superiorvision
Project-URL: Repository, https://github.com/roboflow/superiorvision
Keywords: AI,deep-learning,DL,machine-learning,ML,Roboflow,vision
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.21.2
Requires-Dist: opencv-python>=4.5.5.64
Requires-Dist: pillow>=9.4
Requires-Dist: pydeprecate<0.11,>=0.9
Requires-Dist: pyyaml>=5.3
Requires-Dist: requests>=2.26
Requires-Dist: scipy>=1.10
Requires-Dist: torch<3,>=2
Requires-Dist: tqdm>=4.62.3
Provides-Extra: geotiff
Requires-Dist: rasterio>=1.3; extra == "geotiff"
Provides-Extra: metrics
Requires-Dist: pandas>=2; extra == "metrics"
Dynamic: license-file

<div align="center">
  <p>
    <a align="center" href="https://supervision.roboflow.com" target="_blank">
      <img
        width="100%"
        src="https://media.roboflow.com/open-source/supervision/rf-supervision-banner.png?updatedAt=1678995927529"
      >
    </a>
  </p>

> Supervision, except the numbers have finally been informed that GPUs exist.

SuperiorVision is Roboflow's tensor-native, inference-focused fork of
[Supervision](https://github.com/roboflow/supervision). It preserves the
`import supervision as sv` API used by
[Roboflow Inference](https://github.com/roboflow/inference), while keeping
rectangular numeric state in `torch.Tensor` objects throughout the supported
code paths.

If detections begin as tensors, converting them to NumPy so the next operation
can turn them back into tensors is not "compatibility." It is cardio.
SuperiorVision declines the workout.

[![version](https://img.shields.io/pypi/v/superiorvision)](https://pypi.org/project/superiorvision/) [![downloads](https://img.shields.io/pypi/dm/superiorvision)](https://pypistats.org/packages/superiorvision) [![license](https://img.shields.io/pypi/l/superiorvision)](LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/superiorvision)](https://pypi.org/project/superiorvision/)

[![gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators) [![discord](https://img.shields.io/discord/1159501506232451173?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk)

Same API. Fewer NumPy vacations.

For the external multi-object trackers used by Inference, pair SuperiorVision
with the [Tracktors](https://pypi.org/project/tracktors/) package. The
dependency points one way—Tracktors consumes tensor-native `sv.Detections`—so
SuperiorVision keeps its existing `sv.ByteTrack` compatibility API without a
circular package dependency.

<details>
<summary><strong>📑 Table of Contents</strong></summary>

- [👋 Hello](#-hello)
- [💻 Install](#-install)
- [🔥 Quickstart](#-quickstart)
    - [Models](#models)
    - [Annotators](#annotators)
    - [Datasets](#datasets)
- [🎬 Tutorials](#-tutorials)
- [💜 Built with the API](#-built-with-the-api)
- [📚 Documentation](#-documentation)
- [🏆 Contribution](#-contribution)

</details>

## 👋 Hello

**The familiar computer-vision toolkit, now with fewer surprise trips to the
CPU.** From tensor-native detections to real-time zone counting, SuperiorVision
keeps the compatible building blocks used by Inference while letting GPUs do
the job they were purchased to do. 🤝

## 💻 Install

Install the SuperiorVision distribution in a
[**Python>=3.10**](https://www.python.org/) environment. The published version
is currently a development release, so pin it explicitly:

```bash
pip install superiorvision==0.30.0.dev3
```

For an editable checkout:

```bash
git clone git@github.com:roboflow/superiorvision.git
cd superiorvision
pip install -e .
```

Both imports are supported:

```python
import supervision as sv       # existing Inference code
import superiorvision as sv    # cheekier spelling, same API
```

The PyPI distribution is named `superiorvision`, but it intentionally provides
the `supervision` import namespace for drop-in compatibility. Install it as a
replacement for upstream Supervision, not beside it. Two distributions cannot
both own the same trench coat and pretend everything is fine.

The upstream documentation below remains useful for the compatible API surface.

## 🔥 Quickstart

### Models

SuperiorVision preserves Supervision's model-agnostic API. Just plug in any classification, detection, or segmentation model. The compatible [connectors](https://supervision.roboflow.com/latest/detection/core/#detections) cover popular libraries such as Ultralytics, Transformers, MMDetection, and Inference. Other integrations, including `rfdetr`, already return `sv.Detections` directly.

Install the optional dependencies for this example with `pip install pillow rfdetr`.

```python
import supervision as sv
from PIL import Image
from rfdetr import RFDETRSmall

image = Image.open("path/to/image.jpg")
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)

len(detections)
# 5
```

<details>
<summary>👉 more model connectors</summary>

- inference

    Running with [Inference](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).

    ```python
    import supervision as sv
    from PIL import Image
    from inference import get_model

    image = Image.open("path/to/image.jpg")
    model = get_model(model_id="rfdetr-small", api_key="ROBOFLOW_API_KEY")
    result = model.infer(image)[0]
    detections = sv.Detections.from_inference(result)

    len(detections)
    # 5
    ```

</details>

### Annotators

SuperiorVision retains the wide range of customizable [annotators](https://supervision.roboflow.com/latest/detection/annotators/) from its upstream API, allowing you to compose the visualization your use case needs.

```python
import cv2
import supervision as sv

image = cv2.imread("path/to/image.jpg")
# Assuming detections are obtained from a model
detections = sv.Detections(...)

box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(scene=image.copy(), detections=detections)
```

https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce

### Datasets

SuperiorVision retains the compatible [dataset utilities](https://supervision.roboflow.com/latest/datasets/core/) for loading, splitting, merging, and saving supported formats. Dataset and image I/O remain deliberate CPU boundaries; tensor-native runtime paths do not need to cosplay as JPEG encoders.

```python
import supervision as sv
from roboflow import Roboflow

project = Roboflow().workspace("WORKSPACE_ID").project("PROJECT_ID")
dataset = project.version("PROJECT_VERSION").download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
)

path, image, annotation = ds[0]
# loads image on demand

for path, image, annotation in ds:
    # loads image on demand
    pass
```

<details>
<summary>👉 more dataset utils</summary>

- load

    ```python
    dataset = sv.DetectionDataset.from_yolo(
        images_directory_path=...,
        annotations_directory_path=...,
        data_yaml_path=...,
    )

    dataset = sv.DetectionDataset.from_pascal_voc(
        images_directory_path=...,
        annotations_directory_path=...,
    )

    dataset = sv.DetectionDataset.from_coco(
        images_directory_path=...,
        annotations_path=...,
    )
    ```

- split

    ```python
    train_dataset, test_dataset = dataset.split(split_ratio=0.7)
    test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)

    len(train_dataset), len(test_dataset), len(valid_dataset)
    # (700, 150, 150)
    ```

- merge

    ```python
    ds_1 = sv.DetectionDataset(...)
    len(ds_1)
    # 100
    ds_1.classes
    # ['dog', 'person']

    ds_2 = sv.DetectionDataset(...)
    len(ds_2)
    # 200
    ds_2.classes
    # ['cat']

    ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
    len(ds_merged)
    # 300
    ds_merged.classes
    # ['cat', 'dog', 'person']
    ```

- save

    ```python
    dataset.as_yolo(
        images_directory_path=...,
        annotations_directory_path=...,
        data_yaml_path=...,
    )

    dataset.as_pascal_voc(
        images_directory_path=...,
        annotations_directory_path=...,
    )

    dataset.as_coco(
        images_directory_path=...,
        annotations_path=...,
    )
    ```

- convert

    ```python
    sv.DetectionDataset.from_yolo(
        images_directory_path=...,
        annotations_directory_path=...,
        data_yaml_path=...,
    ).as_pascal_voc(
        images_directory_path=...,
        annotations_directory_path=...,
    )
    ```

</details>

## 🎬 Tutorials

Want to learn the compatible API? Explore the upstream [how-to guides](https://supervision.roboflow.com/develop/how_to/detect_and_annotate/), [end-to-end examples](./examples), [cheatsheet](https://roboflow.github.io/cheatsheet-supervision/), and [cookbooks](https://supervision.roboflow.com/develop/cookbooks/)!

<br/>

<p align="left">
<a href="https://youtu.be/hAWpsIuem10" title="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing"><img src="https://github.com/user-attachments/assets/014cffc7-72b3-4c0a-bb89-6de265b2c06b" alt="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing" width="300px" align="left" /></a>
<a href="https://youtu.be/hAWpsIuem10" title="Dwell Time Analysis with Computer Vision | Real-Time Stream Processing"><strong>Dwell Time Analysis with Computer Vision | Real-Time Stream Processing</strong></a>
<div><strong>Created: 5 Apr 2024</strong></div>
<br/>Learn how to use computer vision to analyze wait times and optimize processes. This tutorial covers object detection, tracking, and calculating time spent in designated zones. Use these techniques to improve customer experience in retail, traffic management, or other scenarios.</p>

<br/>

<p align="left">
<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><img src="https://github.com/user-attachments/assets/b16b8e21-dc6c-4a73-a678-2f7d5d374793" alt="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source" width="300px" align="left" /></a>
<a href="https://youtu.be/uWP6UjDeZvY" title="Speed Estimation & Vehicle Tracking | Computer Vision | Open Source"><strong>Speed Estimation & Vehicle Tracking | Computer Vision | Open Source</strong></a>
<div><strong>Created: 11 Jan 2024</strong></div>
<br/>Learn how to track and estimate the speed of vehicles using YOLO, ByteTrack, and Roboflow Inference. This comprehensive tutorial covers object detection, multi-object tracking, filtering detections, perspective transformation, speed estimation, visualization improvements, and more.</p>

## 💜 Built with the API

Did you build something cool using the compatible `supervision` API? [Tell us in the SuperiorVision repository.](https://github.com/roboflow/superiorvision)

https://user-images.githubusercontent.com/26109316/207858600-ee862b22-0353-440b-ad85-caa0c4777904.mp4

https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-60e9c81b3900

https://github.com/roboflow/supervision/assets/26109316/3ac6982f-4943-4108-9b7f-51787ef1a69f

## 📚 Documentation

The [upstream Supervision documentation](https://supervision.roboflow.com/latest/) describes the compatible API. Fork-specific tensor coverage and Inference compatibility are tracked in [this repository](https://github.com/roboflow/superiorvision) and [the Inference API surface audit](INFERENCE_API_SURFACE.md).

## 🏆 Contribution

We love your input! Please see our [contributing guide](.github/CONTRIBUTING.md) to get started. The fork lives at [`roboflow/superiorvision`](https://github.com/roboflow/superiorvision); upstream-compatible changes may still belong in Supervision. Thank you 🙏 to all our contributors!

<p align="center">
    <a href="https://github.com/roboflow/superiorvision/graphs/contributors">
      <img src="https://contrib.rocks/image?repo=roboflow/superiorvision" />
    </a>
</p>

<br>

<div align="center">
      <a href="https://youtube.com/roboflow">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/youtube.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949634652"
            width="3%"
          />
      </a>
      <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
      <a href="https://roboflow.com">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/roboflow-app.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949746649"
            width="3%"
          />
      </a>
      <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
      <a href="https://www.linkedin.com/company/roboflow-ai/">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/linkedin.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949633691"
            width="3%"
          />
      </a>
      <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
      <a href="https://docs.roboflow.com">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/knowledge.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949634511"
            width="3%"
          />
      </a>
      <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
      <a href="https://discuss.roboflow.com">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/forum.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949633584"
            width="3%"
          />
      </a>
      <img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%"/>
      <a href="https://blog.roboflow.com">
          <img
            src="https://media.roboflow.com/notebooks/template/icons/purple/blog.png?ik-sdk-version=javascript-1.4.3&updatedAt=1672949633605"
            width="3%"
          />
      </a>
  </div>
