Como fazer visão computacional em Python com Supervision do Roboflow (com ou sem OpenCV)

Ferramentas de IA — Geral
, , , , , ,
1

Supervision é a biblioteca de visão artificial em Python da Roboflow: pega as detecções de qualquer modelo (YOLO, RF-DETR, Transformers ou Gemini) e te dá uma única API para desenhá-las, contá-las por zonas, rastreá-las entre fotogramas e converter datasets entre YOLO, COCO e Pascal VOC. É gratuita, com licença MIT, e a partir da versão 0.30.0 instala-se sem OpenCV. Medimos quanto custa isso e, se você trabalha com vídeo, a resposta é: bastante.

Verificado em 17 de setembro de 2026 com supervision 0.30.3 (PyPI, 14 de setembro de 2026) e o branch develop. No momento da publicação desta nota, o repositório tinha 50,8 mil estrelas no GitHub.

O que é Supervision da Roboflow?

Supervision é a camada que fica entre seu modelo e sua aplicação de visão artificial. Cada framework de detecção de objetos devolve seu próprio tipo de resultado. Supervision os converte todos em um único objeto, sv.Detections. Assim, o código que anota, filtra, conta e exporta não muda quando você troca de modelo.

Sua documentação lista conversores para Ultralytics, Roboflow Inference, Transformers, SAM, Detectron2 e MMDetection, entre outros. Também inclui parsers para modelos de visão e linguagem como Florence-2, PaliGemma, Qwen VL e Gemini. RF-DETR, o detector próprio da Roboflow, pula o passo de conversão: seu método predict já devolve um sv.Detections.

Não é um projeto novo:

  • O primeiro commit é de novembro de 2022.
  • O repositório tem mais de 5.000 commits de mais de 200 autores.
  • Registrou 97 commits nos 30 dias anteriores a esta nota.

A documentação da Roboflow afirma que a biblioteca ultrapassa um milhão de downloads mensais no PyPI; esse número é do próprio fornecedor.

Como instalar Supervision e por que ainda precisa de OpenCV?

pip install supervision

Requer Python 3.10 ou superior; o suporte para 3.9 foi removido na 0.30.0.

Essa mesma versão adicionou um backend alternativo construído sobre NumPy, Pillow e PyAV. O guia de migração do projeto indica que Supervision não instala mais OpenCV nem oferece um extra para OpenCV. O guia inclui uma linha para verificar qual backend seu processo escolheu:

python -c "from supervision import _cv2; print(_cv2.BACKEND_NAME)"

Em um ambiente limpo imprime fallback. Ao importar a biblioteca aparece também um UserWarning que recomenda instalar opencv-python para obter o desempenho e a compatibilidade completos. Quisemos saber quanto desempenho se perde.

Nossa medição. Usamos dois ambientes virtuais novos:

  • Máquina: Linux x86_64, uma vCPU Xeon de 2,1 GHz, Python 3.12.3 e supervision 0.30.3.
  • Ambientes: um com o backend alternativo e outro com opencv-python-headless 5.0.0.93.
  • Teste: fotogramas sintéticos de 1920×1080. Medimos apenas o desenho, sem inferência de nenhum modelo. Cada valor é a média de 30 execuções.
Detecções por fotograma BoxAnnotator sem OpenCV BoxAnnotator com OpenCV
1 8,1 ms 0,6 ms
5 30,2 ms 0,6 ms
50 268,9 ms 1,0 ms

As outras operações mostraram o mesmo padrão:

  • LabelAnnotator: 284,6 ms contra 1,3 ms com 50 detecções.
  • sv.resize_image para 640×360: 6,9 ms contra 0,6 ms.

O custo de desenho sem OpenCV cresce cerca de 5 ms para cada caixa. Com 50 objetos, isso deixa menos de quatro fotogramas por segundo apenas desenhando, antes de o modelo rodar.

O que você economiza é espaço em disco: o site-packages do ambiente sem OpenCV pesou 434 MB, contra 586 MB com OpenCV, cerca de 150 MB a menos. PyAV, que o backend alternativo precisa para vídeo, ocupa por si só 103 MB em ambos.

A regra prática:

  • Datasets, métricas, conversões e servidores que não desenham: o backend sem OpenCV funciona bem e a imagem fica mais leve.
  • Qualquer coisa que anote vídeo: instale OpenCV em Python. O guia de migração pede escolher exatamente uma família de pacotes e nunca as duas:
    • opencv-python-headless para servidores e contêineres.
    • opencv-python para aplicações de desktop.

Um detalhe: o exemplo de anotação do próprio README começa com import cv2. Com um pip install supervision sem nada mais, essa linha falha com ModuleNotFoundError: No module named 'cv2'. Reproduzimos isso.

Como detectar objetos com YOLO ou RF-DETR em Python?

O guia do projeto mostra os mesmos três passos para qualquer framework: executar o modelo, carregar o resultado em sv.Detections e anotar. Esta é a versão com RF-DETR, copiada da documentação. Usa cv2.imread, então pressupõe que você instalou OpenCV conforme explicado acima:

import cv2
import supervision as sv
from rfdetr import RFDETRMedium

model = RFDETRMedium()
image = cv2.imread("dog.jpeg")
detections = model.predict(image[:, :, ::-1])

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

annotated_image = box_annotator.annotate(
    scene=image, detections=detections)
annotated_image = label_annotator.annotate(
    scene=annotated_image, detections=detections)

Com YOLO da Ultralytics mudam apenas a chamada ao modelo e uma linha de conversão: detections = sv.Detections.from_ultralytics(results). Com Transformers, a linha é sv.Detections.from_transformers(...). Tudo que vem depois fica idêntico.

Essa portabilidade tem uma consequência de licença que convém revisar antes de escolher. Segundo os metadados do PyPI em 17 de setembro de 2026:

  • rfdetr (1.10.1) usa Apache-2.0.
  • ultralytics (8.4.155) usa AGPL-3.0.

Supervision é MIT, mas o modelo que você conectar traz suas próprias condições.

Como fazer um contador de pessoas com Python?

Um contador de pessoas com Supervision tem três partes:

  1. Um polígono que define a zona.
  2. Um sv.PolygonZone criado a partir desse polígono.
  3. Uma chamada a trigger sobre as detecções de cada fotograma, que devolve uma máscara booleana com as que caem dentro da zona.

Do guia de contagem do projeto:

zones = [sv.PolygonZone(polygon=polygon) for polygon in polygons]

mask = zone.trigger(detections=detections)
detections_filtered = detections[mask]
```Para obter as coordenadas do polígono, a Roboflow oferece uma ferramenta web, [PolygonZone](https://roboflow.github.io/polygonzone/): você carrega um fotograma, marca os cantos e ela retorna os arrays do NumPy.

Para contar apenas pessoas, filtre por classe antes de passar as detecções para a zona. O exemplo `count_people_in_zone` do repositório faz isso com RF-DETR:

```python
filter_by_class = detections.class_id == PERSON_CLASS_ID
filter_by_confidence = detections.confidence > confidence_threshold
return detections[filter_by_class & filter_by_confidence]

Aqui está a armadilha de um „sem se prender a um modelofrom_coco, from_pascal_voc, as_yolo e as_pascal_voc seguem o mesmo padrão, então qualquer conversão entre os três formatos são duas chamadas.

Um bug que você pode encontrar hoje. Se seus arquivos de rótulos YOLO escrevem os IDs de classe com decimais (1.0 em vez de 1), a 0.30.3 aborta o carregamento completo com ValueError: invalid literal for int() with base 10: '1.0'. É o que produz np.savetxt por padrão, e nós reproduzimos.

A correção (#2580) já foi mesclada em develop, mas em 17 de setembro de 2026 não estava em nenhuma versão publicada. Esse mesmo lote pendente corrige os nomes de classe com caracteres fora de ASCII (como café), que falham no Windows (#2585). Até a próxima versão, escreva IDs de classe como números inteiros.

O Supervision é gratuito e te prende ao Roboflow?

Supervision é gratuito, com licença MIT, e não precisa de uma conta do Roboflow. Você só precisa de uma chave de API do Roboflow se executar modelos com seu pacote inference ou se baixar datasets do Roboflow.

Esse pacote tem hoje seu próprio atrito. Fizemos uma resolução de teste com pip install --dry-run em 17 de setembro de 2026 (Linux x86_64, Python 3.12):

  • pip install inference resolveu inference 1.6.0 com supervision 0.29.1, não com a 0.30.x.
  • A mesma resolução trouxe três famílias de OpenCV: opencv-python, opencv-contrib-python e opencv-python-headless.
  • Forçando supervision==0.30.3, pip recuou para inference 1.3.8.

Se você quer a versão atual do Supervision, os conversores que vão direto para RF-DETR, Ultralytics ou Transformers evitam esse conflito.

O que traz a próxima versão do Supervision?

Isso está em develop e, em 17 de setembro de 2026, não havia sido publicado:

  • Remoções previstas para a 0.31.0, entre outras:
    • sv.ByteTrack.
    • O módulo supervision.keypoint; use supervision.key_points.
    • sv.LMM e Detections.from_lmm; use sv.VLM e Detections.from_vlm.
    • O caminho de importação antigo de MeanAveragePrecision.
  • Novos analisadores de modelos de visão e linguagem:
    • A saída estruturada de detecção do Gemini 3.6 e 3.7. Gemini 3.5 já chegou na 0.30.0.
    • Kosmos-2.
  • Métricas: aggregate_metric_results() e plot_aggregate_metric_results(), para comparar vários modelos em uma única tabela ou gráfico.
  • Correções de datasets:
    • Os IDs de classe com decimais e a codificação no Windows mencionados acima.
    • O tratamento da orientação EXIF em fotos tiradas com o telefone.

Se você fixar supervision==0.30.3 hoje, leia o changelog antes de atualizar.