Prever numa imagem
Executa um modelo YOLO26 pré-treinado em Python, lê as classes, as confianças e as caixas em píxeis dos resultados e ajusta os argumentos que resolvem a maioria das deteções falhadas.
Qualquer utilização real de um detetor — contar produtos numa prateleira, recortar rostos para os desfocar, enviar caixas para uma API JSON — começa por interpretar corretamente o objeto de resultado. Basta enganares-te num detalhe, como indexar os nomes das classes com um tensor, para a tua aplicação falhar na primeira imagem.
Um modelo YOLO26 de deteção pré-treinado já conhece as 80 classes COCO. Nesta lição, vais executar o modo Predict em Python, extrair dos resultados todos os campos úteis e aprender qual o argumento a alterar para resolver deteções falhadas, duplicadas e de objetos pequenos. Mais tarde, o mesmo objeto de resultado será devolvido pelo teu próprio modelo treinado.
Prático
Prever e imprimir cada deteção#
Chamar o modelo com uma origem executa o modo Predict e devolve uma lista com um objeto Results por imagem. Com uma imagem, lê results[0].
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
results = model("https://ultralytics.com/images/bus.jpg")
result = results[0]
for box in result.boxes:
name = result.names[int(box.cls)]
conf = float(box.conf)
x1, y1, x2, y2 = box.xyxy[0].tolist()
print(f"{name:>8} {conf:.2f} ({x1:.0f}, {y1:.0f}) -> ({x2:.0f}, {y2:.0f})")
result.save("bus_annotated.jpg")Resultado real de predict.py, após a linha de registo habitual:
bus 0.88 (0, 230) -> (803, 751)
person 0.87 (49, 398) -> (240, 902)
person 0.86 (223, 405) -> (345, 861)
person 0.85 (670, 395) -> (810, 880)
person 0.65 (0, 553) -> (60, 871)Como interpretar:
bus 0.88: nome da classe e confiança. As caixas estão ordenadas por confiança, da mais alta para a mais baixa.(0, 230) -> (803, 751): cantos superior esquerdo e inferior direito em píxeis da imagem original de 810×1080, com origem no canto superior esquerdo. Podes recortar ou desenhar diretamente com estas coordenadas.person 0.65em(0, 553): uma quinta pessoa, parcialmente cortada pelo limite esquerdo, tem uma pontuação mais baixa. Os objetos parcialmente visíveis costumam ter pontuações mais baixas.
result.save() grava a imagem anotada; result.show() abre-a numa janela.
O que contém um resultado#
Cada tarefa devolve o mesmo tipo Results; só os campos preenchidos é que mudam. Podes consultar todos os campos no guia de utilização de Python.
| Atributo | Contém |
|---|---|
boxes | Deteções: píxeis xyxy, formato de centro normalizado xywhn, conf, cls e id quando há seguimento |
masks, keypoints, obb, probs | Resultados de modelos de segmentação, pose, OBB e classificação (None para um modelo de deteção) |
names | Dicionário de índice da classe → nome da classe |
orig_img, orig_shape | A imagem de entrada como matriz NumPy e a respetiva altura × largura |
speed | Tempos de pré-processamento, inferência e pós-processamento em ms |
path, save_dir | Origem da entrada e destino dos resultados gravados |
Para a deteção de objetos, vais precisar sobretudo de boxes, as caixas delimitadoras. result.summary() devolve as mesmas deteções como uma lista de dicionários simples, pronta para uma API JSON.
Ajustar a previsão#
As predefinições são adequadas para a maioria das imagens. Quando não forem, altera um argumento de cada vez:
| Problema observado | Argumento | Padrão | Alteração |
|---|---|---|---|
| Deteções falhadas: um objeto visível não tem caixa | conf | 0.25 | Reduz, por exemplo, 0.1 |
| Falsos positivos: caixas em zonas vazias | conf | 0.25 | Aumenta, por exemplo, 0.5 |
| Duas caixas para um objeto | iou | 0.7 | Reduz: o limiar de sobreposição (IoU) da NMS para fundir duplicados |
| Objetos pequenos e distantes não detetados | imgsz | 640 | Aumenta, por exemplo, 1280 (arredondado para um múltiplo de 32) |
| Só algumas classes são relevantes | classes | todas | por exemplo, classes=[0] para pessoas |
| Hardware incorreto | device | automático | cpu, mps ou um índice de GPU, como 0 |
A confiança altera o resultado, não apenas a contagem. Na mesma imagem de um autocarro:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
model("https://ultralytics.com/images/bus.jpg", conf=0.5, classes=[0]) # 4 persons
model("https://ultralytics.com/images/bus.jpg", conf=0.1) # 5 pessoas, 1 autocarro, 1 sinal de paragemCom conf=0.1, o modelo também deteta um sinal de paragem sobre o qual não tinha a certeza. Reduzir conf é a forma mais rápida de ver o que o modelo quase detetou. Encontras todos os outros argumentos na referência de configuração.
Quando uma previsão não devolve resultados, segue estes passos:
Executar em várias imagens#
Indica uma lista, uma pasta ou um padrão glob, como "photos/*.jpg". Por predefinição, Predict usa batch=1; define batch para processar várias imagens de uma só vez, o que é muito mais rápido numa GPU:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
images = ["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"]
for result in model(images, batch=2):
print(result.path, len(result.boxes), result.verbose())image0.jpg 5 4 persons, 1 bus,
image1.jpg 3 2 persons, 1 tie,Evita estes erros#
Sintoma: KeyError: tensor([5.]). Causa: box.cls e box.conf são tensores do PyTorch, e result.names é um dicionário indexado por int. Solução: converta primeiro: result.names[int(box.cls)], float(box.conf), box.xyxy[0].tolist().
Sintoma: uma função auxiliar que chama YOLO("yolo26n.pt") dentro da função é executada lentamente. Em uma CPU de laptop, recarregar o modelo para cada imagem levou 71 ms, contra 25 ms com o modelo carregado uma única vez. Solução: crie o modelo uma vez na inicialização e reutilize-o para cada imagem.
model(list_or_folder) coleta todos os objetos Results na memória antes de retornar. Para pastas grandes e todos os vídeos, passa stream=True e faz um loop: os resultados chegam um de cada vez. A lição sobre vídeo aborda isso em profundidade.
Mostrar solução
from ultralytics import YOLO
model = YOLO("yolo26n.pt") # load once
images = ["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"]
for result in model(images, verbose=False):
top3 = sorted(result.summary(), key=lambda d: d["confidence"], reverse=True)[:3]
print(f"{result.path}: {len(result.boxes)} detections")
for d in top3:
print(f" {d['name']:>8} {d['confidence']:.2f}")image0.jpg: 5 detections
bus 0.90
person 0.85
person 0.85
image1.jpg: 3 detections
person 0.89
person 0.79
tie 0.59summary() já devolve nomes simples e números decimais, por isso não há tensores para converter. As confianças diferem ligeiramente de predict.py porque uma lista de imagens é preenchida até atingir uma forma comum. Em conf=0.1, bus.jpg acrescenta um sinal de paragem.