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

As seguintes famílias treinam e rodam predições: YOLOv9, RF-DETR, EdgeCrafter, RT-DETR, D-FINE, DEIM, Dome-DETR, GTR, YOLO-NAS, YOLOX, YOLOv7, RTMDet e PicoDet. YOLOv9 e RF-DETR são as duas famílias principais, e os recursos chegam primeiro nelas. RF-DETR precisa do seu próprio extra, pip install "libreyolo[rfdetr]"; as demais rodam com o 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, Gemma 4, Moondream, North Micro Vision, LocateAnything, SenseNova-Vision, WeVisOne-VL e LibreMODUS. Esses carregam pela sua própria factory e pelos seus extras; cada página de modelo traz a chamada exata.

PP-YOLOE e TinyFormer também suportam treinamento de detecção.

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. agnostic_nms=True acrescenta um passo de supressão agnóstico a classes em iou que vale para esses dois também; veja limiares e filtragem. 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: datasettrain: images/trainval: images/valnames:  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.

Use classes= para manter IDs originais selecionados do dataset; single_cls=True reúne as labels mantidas na classe 0. Veja hiperparâmetros para famílias suportadas e herança na validação.

Validação

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

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # Um dict de chaves metrics/, com resultados por classe como atributos.metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/AR100"])print(metrics.confusion_matrix.class_accuracy())

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).

O resultado também traz confusion_matrix, indexada matrix[predicted, true] com uma linha e uma coluna background, e precisão, recall e F1 por classe ao longo das confianças em box: box.px, box.p_curve, box.r_curve, box.f1_curve, uma linha por classe em box.ap_class_index. Validação e métricas cobre os dois, junto com val(agnostic_nms=True).

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.