Publica checkpoint RF-DETR de capacetes

Adiciona o checkpoint treinado, model card, métricas, checksum e configuração de treinamento do projeto GitHub matheeusper/epi-with-keypoints.

README.md

@@ -1,3 +1,100 @@
 ---
-license: apache-2.0
+license: agpl-3.0
+library_name: rfdetr
+pipeline_tag: object-detection
+tags:
+  - computer-vision
+  - object-detection
+  - construction-safety
+  - ppe
+  - helmet-detection
+  - rf-detr
+datasets:
+  - Ultralytics/Construction-PPE
 ---
+
+# RF-DETR Small — detecção de capacetes em obras
+
+Checkpoint do `RFDETRSmall` treinado para detectar exclusivamente a classe positiva
+`helmet` em imagens de canteiros de obras. O modelo integra o projeto
+[epi-with-keypoints](https://github.com/matheeusper/epi-with-keypoints), que combina
+a detecção de capacete com keypoints corporais e tracking temporal para produzir
+um resultado por pessoa em imagens e vídeos.
+
+## Arquivo
+
+- `helmet_only_576_best.pth`: checkpoint RF-DETR em resolução 576 px.
+- `training_config.yaml`: configuração usada no treinamento.
+- `model_metadata.json`: classes, limiares recomendados, métricas e checksum.
+
+## Uso
+
+Clone o projeto e sincronize as dependências:
+
+```bash
+git clone https://github.com/matheeusper/epi-with-keypoints.git
+cd epi-with-keypoints
+uv sync
+```
+
+O script baixa este checkpoint automaticamente quando `models/helmet_only_576_best.pth`
+não está disponível:
+
+```bash
+uv run python infer_ppe_keypoints.py --image images/image2.jpg
+uv run python infer_ppe_keypoints.py --video videos/obra.mp4
+```
+
+Também é possível baixá-lo diretamente:
+
+```python
+from huggingface_hub import hf_hub_download
+
+checkpoint = hf_hub_download(
+    repo_id="matheeusper/epi-with-keypoints",
+    filename="helmet_only_576_best.pth",
+)
+```
+
+```python
+from rfdetr import RFDETRSmall
+
+model = RFDETRSmall.from_checkpoint(checkpoint)
+detections = model.predict("imagem.jpg", threshold=0.35)
+```
+
+## Métricas
+
+Avaliação em 141 imagens e 192 capacetes do split de teste derivado do
+Construction-PPE:
+
+| Métrica | Resultado |
+| --- | ---: |
+| mAP@[0.50:0.95] | 55,53% |
+| mAP@0.50 | 95,00% |
+| mAP@0.75 | 58,66% |
+| mAR@100 | 66,30% |
+| Precisão@0.50 | 93,75% |
+| Recall@0.50 | 93,75% |
+| F1@0.50 | 93,75% |
+| Confiança no melhor F1 | 0,435 |
+
+## Treinamento
+
+- Arquitetura: `RFDETRSmall`.
+- Resolução: 576 px.
+- Classe: `helmet` (`id=0`).
+- Seed: 42.
+- Batch efetivo: 16 (`batch_size=1`, `grad_accum_steps=16`).
+- Checkpoint selecionado após 11 épocas e 781 passos globais.
+
+## Limitações e uso responsável
+
+O modelo foi treinado em um conjunto específico de obras e pode falhar com pessoas
+pequenas, iluminação extrema, ângulos incomuns, aglomerações ou oclusões prolongadas.
+Ele detecta capacetes, mas não deve ser usado isoladamente para decisões disciplinares
+ou outras decisões críticas de segurança. Valide e calibre o limiar com imagens do
+ambiente de implantação.
+
+O dataset de origem Construction-PPE é distribuído sob AGPL-3.0; este repositório
+adota a mesma licença para o checkpoint derivado.

helmet_only_576_best.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7bf0a9009e7b6bdc4d1082932845e621b886c8a988c6277597f1c2105f48c690
+size 127784231

model_metadata.json

@@ -0,0 +1,35 @@
+{
+  "architecture": "RFDETRSmall",
+  "framework": "PyTorch",
+  "input_resolution": 576,
+  "classes": [
+    {
+      "id": 0,
+      "name": "helmet"
+    }
+  ],
+  "recommended_detection_threshold": 0.35,
+  "checkpoint": {
+    "filename": "helmet_only_576_best.pth",
+    "size_bytes": 127784231,
+    "sha256": "7bf0a9009e7b6bdc4d1082932845e621b886c8a988c6277597f1c2105f48c690"
+  },
+  "training": {
+    "seed": 42,
+    "completed_epochs": 11,
+    "global_steps": 781
+  },
+  "test_metrics": {
+    "images": 141,
+    "ground_truth_helmets": 192,
+    "map_50_95": 0.5553,
+    "map_50": 0.95,
+    "map_75": 0.5866,
+    "mar_100": 0.663,
+    "precision_50": 0.9375,
+    "recall_50": 0.9375,
+    "f1_50": 0.9375,
+    "confidence_at_best_f1": 0.435
+  },
+  "source_repository": "https://github.com/matheeusper/epi-with-keypoints"
+}

training_config.yaml

@@ -0,0 +1,32 @@
+# Treino de alta qualidade focado exclusivamente na classe positiva ``helmet``.
+general:
+  output_dir: "output_helmet_only_576"
+  dataset_dir: "construction-ppe-helmet"
+  device: "cuda"
+  seed: 42
+
+model:
+  resolution: 576
+  gradient_checkpointing: true
+
+training:
+  epochs: 120
+  batch_size: 1
+  grad_accum_steps: 16
+  lr: 1e-4
+  lr_encoder: 5e-5
+
+early_stopping:
+  enabled: true
+  patience: 20
+  min_delta: 0.001
+  use_ema: true
+
+augmentations:
+  HorizontalFlip: {p: 0.5}
+  RandomBrightnessContrast: {p: 0.35}
+  ShiftScaleRotate:
+    shift_limit: 0.03
+    scale_limit: 0.10
+    rotate_limit: 10
+    p: 0.35