matheeusper/epi-with-keypoints

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, que combina a detecção de capacete com keypoints corporais e tracking temporal para produzir um resultado por pessoa em imagens e vídeos.

Este repositório no Hugging Face contém apenas a release do modelo. O código de treinamento, avaliação, inferência, tracking e a documentação completa são mantidos no repositório GitHub.

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:

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:

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:

from huggingface_hub import hf_hub_download

checkpoint = hf_hub_download(
    repo_id="matheeusper/epi-with-keypoints",
    filename="helmet_only_576_best.pth",
)

from rfdetr import RFDETRSmall

model = RFDETRSmall.from_checkpoint(checkpoint)
detections = model.predict("imagem.jpg", threshold=0.35)

Métricas

Avaliação em 1.234 imagens e 597 capacetes do split de teste completo do PPE_Detection, incluindo imagens negativas sem capacete:

Métrica	Resultado
mAP@[0.50:0.95]	58,90%
mAP@0.50	89,62%
mAP@0.75	67,41%
mAR@100	74,09%
Precisão@0.50	86,68%
Recall@0.50	90,45%
F1@0.50	88,52%
Confiança no melhor F1	0,570

Treinamento

• Arquitetura: RFDETRSmall.
• Resolução: 576 px.
• Classe: helmet (id=0).
• Seed: 42.
• Batch efetivo: 16 (batch_size=4, grad_accum_steps=4).
• Checkpoint regular selecionado na época 19, após 20 épocas e 2.000 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 51ddhesh/PPE_Detection é distribuído sob CC BY 4.0; o checkpoint derivado é publicado sob a mesma licença.