Detecção de objetos

Definição

A detecção de objetos responde onde cada objeto está e o que ele é. Uma imagem entra, uma linha por instância sai: quatro números para o retângulo, um índice de classe e um score. Nada de forma em pixels, orientação ou partes é incluído, e é isso que a separa da segmentação de instâncias, das caixas orientadas e da pose.

detect é a chave canônica da tarefa e o padrão: um checkpoint cujo nome de arquivo não traz sufixo de tarefa é carregado como detector.

predict() preenche result.boxes. .xyxy dá os cantos em pixels no canvas da imagem original, .conf o score e .cls o índice da classe em result.names. .xywh, .xyxyn e .xywhn são visões derivadas das mesmas linhas, e .id carrega um id de track assim que um tracker é acoplado. Iterar um objeto Boxes produz fatias de uma linha, então box.cls, box.conf e box.xyxy funcionam por detecção.

Modelos

Doze famílias treinam e fazem predição: YOLOv9, RF-DETR, EdgeCrafter, RT-DETR, D-FINE, DEIM, Dome-DETR, YOLO-NAS, YOLOX, YOLOv7, RTMDet e PicoDet. YOLOv9 e RF-DETR são as duas famílias principais, e as novidades chegam nelas primeiro. O RF-DETR precisa do seu próprio extra, pip install "libreyolo[rfdetr]"; o resto roda no pacote base.

Outras onze fazem predição, validação e exportação, mas o train() delas lança NotImplementedError: LW-DETR, DETR, Deformable DETR, DINO-DETR, Faster R-CNN, Mask R-CNN, FCOS, RetinaNet, SSD, CenterNet e EfficientDet.

A linhagem Darknet, YOLOv1, YOLOv2, YOLOv3 e YOLOv4, é mantida congelada, como peça de museu: predição, validação e exportação funcionam, treinamento não.

Um grupo à parte recebe sua lista de classes em runtime, e não do checkpoint, então detecta nomes nunca vistos no treinamento: Grounding DINO, OWLv2, OMDet-Turbo e OV-DEIM, além das famílias de visão-linguagem Florence-2, Kosmos-2, Qwen3-VL, SmolVLM2, InternVL3, LFM2-VL, LocateAnything, SenseNova-Vision e LibreMODUS. Esses carregam pela sua própria factory e pelos seus extras; cada página de modelo traz a chamada exata.

Predição

Os pesos são baixados do Hugging Face no primeiro uso e ficam em cache localmente.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(result.names[int(box.cls)], float(box.conf), box.xyxy)

libreyolo predict model=LibreYOLO9t.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # A factory roteia pelo checkpoint, e todo detector devolve o mesmo# objeto Results, então trocar de família é uma mudança de uma linha.model = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy.shape)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # Qualquer fonte que a biblioteca aceita: arquivo, pasta, URL, índice# de webcam, stream RTSP ou uma lista .streams.for result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

conf define o limiar de confiança e max_det limita o número de linhas. iou é o limiar do NMS, então só tem efeito em uma família que roda NMS; o RF-DETR e a cabeça end-to-end do YOLOv9 decodificam um conjunto fixo de predições e o ignoram. Veja predição para fontes, streaming e tratamento de resultados.

Formato do dataset

Um arquivo .txt de rótulos por imagem, encontrado trocando images por labels no caminho da imagem e mudando a extensão.

dataset/
  data.yaml
  images/
    train/000001.jpg
    val/000101.jpg
  labels/
    train/000001.txt
    val/000101.txt

Cada linha tem exatamente cinco campos, um índice de classe seguido de uma caixa normalizada de centro e tamanho:

<class_id> <cx> <cy> <w> <h>

As coordenadas são floats em [0, 1], relativas à largura e à altura da imagem original. w e h precisam ser positivos. Um arquivo de rótulos ausente ou vazio significa que a imagem não tem objetos. As linhas não carregam confiança nem id de track.

O YAML nomeia os splits e as classes:

path: dataset
train: images/train
val: images/val
names:
  0: person
  1: bicycle

train e val podem ser diretórios de imagens, arquivos .txt com listas de imagens ou listas de qualquer um dos dois. nc é opcional e precisa bater com names quando estiver presente. COCO JSON nativo também funciona: adicione um mapeamento annotations de nome do split para arquivo JSON, e o caminho do split passa a dar a raiz das imagens. Quando names está presente, ele define os ids dos rótulos, então os nomes de categoria do JSON têm que bater com ele.

Treinamento

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # coco128.yaml baixa uma amostra de 128 imagens no primeiro uso. Aponte# data para o YAML do seu próprio dataset em uma execução real.model.train(data="coco128.yaml", epochs=50, imgsz=640, batch=8)

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 imgsz=640 batch=8

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 device=0,1 batch=-1

epochs, imgsz, batch e lr0 são os primeiros argumentos a mexer. lr0 é o que não se transfere entre famílias: uma taxa que um detector convolucional tolera faz um transformer divergir, então pegue o valor na página do modelo em vez do exemplo de outra família. Uma família também pode ignorar um argumento por completo, e a página dela lista quais. Veja treinamento para datasets, data augmentation, multi-GPU e loggers.

Validação

val() devolve um dicionário simples de chaves metrics/, calculadas com a avaliação COCO sobre o split indicado por val no YAML do dataset.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # val() devolve um dict simples, não um objeto.metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/AR100"])

libreyolo val model=LibreYOLO9t.pt data=coco128.yaml

metrics/mAP50-95 é a média da mean average precision sobre os limiares de IoU de 0.50 a 0.95, e é o número de destaque. metrics/mAP50 e metrics/mAP75 são as versões de um único limiar. metrics/mAP_small, metrics/mAP_medium e metrics/mAP_large separam a mesma média por área do objeto, e metrics/AR1, metrics/AR10, metrics/AR100, metrics/AR_small, metrics/AR_medium e metrics/AR_large são os números correspondentes de average recall. metrics/AR_max_det e metrics/max_det registram o limite de detecções que a execução usou.

Leia metrics/precision e metrics/recall com cuidado nesta tarefa. Elas são mantidas por compatibilidade retroativa e são apelidos, não um ponto de operação: metrics/precision guarda o mesmo valor que metrics/mAP50-95, e metrics/recall o mesmo valor que metrics/AR100. Plotar as duas como um par precisão-recall reporta o mesmo número duas vezes. Quatro chaves também se repetem com o sufixo (B), de box, para que uma chave de detecção seja lida do mesmo jeito em um modelo que também prediz máscaras: metrics/mAP50-95(B), metrics/mAP50(B), metrics/precision(B) e metrics/recall(B).

Exportação

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLO9t.pt format=onnx imgsz=640

from libreyolo import LibreYOLO, SAMPLE_IMAGE # A factory roteia pelo sufixo do arquivo, então um artefato exportado# carrega como um checkpoint e devolve o mesmo objeto Results.model = LibreYOLO("LibreYOLO9t.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

Um artefato exportado volta a carregar por LibreYOLO() pelo sufixo do arquivo, então um arquivo .onnx ou .engine se comporta como um checkpoint e devolve o mesmo Results. A cobertura de formatos varia por família; a matriz em cada página de modelo é gerada a partir do conjunto validado, não digitada à mão. Veja exportação e deploy para os formatos, seus extras e suas restrições.