pavimentos-yolo11s

PavimentOS-YOLO11s — Detector de Defeitos em Pavimentos

Detector de objetos baseado na arquitetura YOLO11s (Ultralytics) treinado para identificar cinco categorias de defeitos em pavimentos urbanos a partir de imagens de superfície rodoviária. Otimizado para inferência eficiente em CPU/GPU de baixo custo, com exportações prontas para ONNX, OpenVINO, TorchScript e TensorRT.

Sumário Executivo

Classes

Métricas por Classe (conjunto de teste)

Matriz de Confusão (normalizada)

Curva Precision-Recall

Amostras de Predição (validação)

Como Usar

Python (Ultralytics)

from ultralytics import YOLO

# Carrega direto do Hugging Face
model = YOLO("hf://Kodjaoglanian/pavimentos-yolo11s/weights/best.pt")

results = model("imagem.jpg", conf=0.25, imgsz=512)
for r in results:
    for box in r.boxes:
        cls_id = int(box.cls[0])
        conf = float(box.conf[0])
        x1, y1, x2, y2 = box.xyxy[0].tolist()
        print(f"{model.names[cls_id]}: {conf:.2f} {[round(v) for v in [x1,y1,x2,y2]]}")

ONNX Runtime (CPU, sem PyTorch)

import onnxruntime as ort
import cv2, numpy as np

session = ort.InferenceSession("best.onnx")
img = cv2.imread("imagem.jpg")
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
img = cv2.resize(img, (512, 512))
img = (img.astype(np.float32) / 255.0)[None].transpose(0, 3, 1, 2)
out = session.run(None, {session.get_inputs()[0].name: img})

CLI (Ultralytics)

yolo predict model=hf://Kodjaoglanian/pavimentos-yolo11s/weights/best.pt source=./imagens/ imgsz=512

Detecção em vídeo (performance em tempo real)

Incluímos o script detectar_video.py para inferência em vídeo/arquivo com exportação de dataset YOLO (images/ + labels/):

huggingface-cli download Kodjaoglanian/pavimentos-yolo11s exports/best.torchscript --local-dir ./modelo
python detectar_video.py --model ./modelo/best.torchscript --video rua.mp4 --imgsz 416

Formatos Disponíveis

Detalhes do Treino

Dataset

Imagens de pavimentos brasileiros consolidadas a partir de múltiplas fontes (Roboflow), unificadas em um único dataset com mapeamento de classes consistente. As 4 classes originais com anotações insuficientes (remendo, afundamento, desgaste, poça de água) foram removidas por adicionarem ruído ao treino.

Hiperparâmetros

Hardware

• GPU: NVIDIA Tesla T4 (15 GB VRAM) — Google Colab
• Treino completo: ~30 épocas em ~2h48min (~336s/época)
• Pós-processamento: validação + exportação + upload automáticos

Aumento de Dados

Toda a augmentação é feita online na GPU durante o treino (Ultralytics nativo): mosaic, mixup, copy-paste, HSV jitter, flip horizontal, escala/translação, randaugment e erasing. Sem augmentação offline (Albumentations) para manter o pipeline enxuto.

Estrutura do Repositório

weights/
  best.pt                Pesos PyTorch (melhor época)
  last.pt                Pesos da última época
exports/
  best.onnx              ONNX (opset 12, entrada fixa 512x512)
  best.torchscript       TorchScript (entrada dinâmica)
  best_openvino_model/   OpenVINO IR (.xml/.bin/.yaml)
  best.engine            TensorRT (gerado na T4)
runs/
  results.csv            Métricas por época
  results.png            Gráfico de treino
  confusion_matrix*.png  Matriz de confusão
  BoxPR_curve.png        Curva Precision-Recall
  BoxF1_curve.png        Curva F1
  val_batch*_pred.jpg    Predições na validação
  train_batch*.jpg       Lotes de treino (com augmentação)
  labels.jpg             Distribuição de labels
  args.yaml              Configuração completa do treino

Treino — Evolução das Métricas

Comparação com modelo yolo11l (H100)

Modelo irmão treinado em H100 com dataset expandido (RDD2022 + Brasil) e arquitetura yolo11l:

O yolo11s é 2.7x menor e 4x mais leve — ideal para inferência em CPU local e tempo real, a custa de ~4% de mAP50.

Licença

A arquitetura YOLO11 é licenciada sob AGPL-3.0 pela Ultralytics. O dataset RDD2022 possui seus próprios termos. Para uso comercial, consulte a licença em docs.ultralytics.com/license.

Citação

@software{pavimentos_yolo11s,
  author  = {Bruno Kodjaoglanian Cardoso Tulux},
  title   = {PavimentOS-YOLO11s — Pavement Defect Detection},
  year    = {2025},
  url     = {https://huggingface.co/Kodjaoglanian/pavimentos-yolo11s}
}

Referências

• Ultralytics YOLO11
• RDD2022 — Road Damage Detection Dataset
• Hugging Face Hub — Kodjaoglanian/pavimentos-yolo11s
• Repositório irmão — yolo11l treinado em H100