Rewrite model card for practical use

README.md

@@ -10,87 +10,131 @@ tags:
 - object-detection
 - face-detection
 - widerface
+- onnx
 pipeline_tag: object-detection
 ---
 
-# YOLO26l face detector (WiderFace fine-tune)
+# YOLO26l face detector (WiderFace)
 
-Single-class **face** detector based on **[Ultralytics YOLO26l](https://docs.ultralytics.com/models/yolo26/)**, fine-tuned on **[WIDER FACE](http://shuoyang1213.me/WIDERFACE/)**.
+Single-class **face** detector: [Ultralytics YOLO26l](https://docs.ultralytics.com/models/yolo26/) fine-tuned on [WIDER FACE](http://shuoyang1213.me/WIDERFACE/).
 
-This repo contains the Ultralytics `best.pt` checkpoint from a supervised fine-tune of the official YOLO26 large detection model.
+| | |
+|---|---|
+| Classes | `face` (`0`) |
+| Params | ~24.7M (fused) |
+| Weights | `best.pt` ≈ 151 MB |
+| Train size | 1280 |
+| Ultralytics | 8.4.114+ (YOLO26) |
+| License | AGPL-3.0 |
 
-> Base model: [YOLO26 documentation](https://docs.ultralytics.com/models/yolo26/) · [Ultralytics GitHub](https://github.com/ultralytics/ultralytics)  
-> Dataset: [WIDER FACE](http://shuoyang1213.me/WIDERFACE/)
+> Base: [YOLO26 docs](https://docs.ultralytics.com/models/yolo26/) · Dataset: [WIDER FACE](http://shuoyang1213.me/WIDERFACE/)
 
-## Files
+## Examples (val images)
 
-| File | Description |
-|------|-------------|
-| `best.pt` | Ultralytics YOLO weights (`ultralytics.YOLO`) |
-| `metrics.txt` | Snapshot of peak validation metrics from this run |
+![Crowd / parade example](assets/pred_01.jpg)
+![Marching band example](assets/pred_02.jpg)
+![Concert example](assets/pred_03.jpg)
+![Parade example](assets/pred_04.jpg)
 
 ## Quick start
 
 ```bash
-pip install ultralytics
-huggingface-cli download uralman/yolo26l-widerface best.pt --local-dir .
+pip install "ultralytics>=8.4.0" huggingface_hub
 ```
 
 ```python
+from huggingface_hub import hf_hub_download
 from ultralytics import YOLO
 
-model = YOLO("best.pt")
-results = model.predict("image.jpg", imgsz=1280, conf=0.25)
+weights = hf_hub_download("uralman/yolo26l-widerface", "best.pt")
+model = YOLO(weights)
+
+results = model.predict(
+    "image.jpg",
+    imgsz=1280,   # match training
+    conf=0.25,    # lower (e.g. 0.15) for recall; raise for fewer FPs
+    iou=0.7,
+    max_det=300,
+)
+for r in results:
+    print(r.boxes.xyxy, r.boxes.conf)  # face boxes
+    r.save("out.jpg")
 ```
 
-Recommended inference size: **1280** (same as training).
+### Recommended defaults
+
+| Setting | Value | Notes |
+|---------|------:|-------|
+| `imgsz` | **1280** | Trained at 1280; smaller sizes are faster but can miss tiny faces |
+| `conf` | 0.25 | Start here; try 0.15–0.35 per domain |
+| `iou` | 0.7 | NMS IoU |
+| `max_det` | 300 | Crowds / parades need headroom |
+
+Approximate latency (PyTorch, `imgsz=1280`, conf=0.25): **~14 ms/image on NVIDIA H100** (single image, warmed). Expect slower on smaller GPUs / CPU.
+
+## When to use this vs nano face models
+
+- Prefer this **L** checkpoint when you care about **small / crowded faces** and can afford ~25M params / ~150MB.
+- Prefer a **nano** face YOLO when you need max FPS on edge or CPU and faces are relatively large in frame.
+
+## Validation metrics
+
+Ultralytics COCO-style box metrics on the **YOLO-formatted WIDER FACE val** split used in this run (~3.2k images). Peak by **mAP50-95** (epoch 71; training stopped ~epoch 73):
+
+| Metric | Best |
+|--------|-----:|
+| Precision | 0.896 |
+| Recall | 0.725 |
+| **mAP50** | **0.801** |
+| **mAP50-95** | **0.455** |
+
+**Not** the official WIDER FACE Easy/Medium/Hard protocol. Numbers depend on label conversion, `imgsz`, and NMS — use them to reproduce *this* setup, not as a leaderboard claim.
 
-## Training summary
+## Training (short)
 
 | Item | Value |
 |------|-------|
-| Base weights | Ultralytics `yolo26l.pt` |
-| Task | `detect`, single class `face` |
-| Dataset | WIDER FACE converted to YOLO format (~12.9k train / ~3.2k val) |
-| Image size | 1280 |
-| Hardware | 2× NVIDIA H100, DDP |
-| Batch | 8, AMP, `cache=ram` |
-| Schedule | up to 200 epochs, patience 50, cosine LR |
-| Augmentations | mosaic, multi-scale, Ultralytics detect defaults |
-| Stopped at | epoch **73** (early stop; gains near plateau) |
+| Base | Ultralytics `yolo26l.pt` |
+| Data | WIDER FACE → YOLO labels (~12.9k train / ~3.2k val), 1 class |
+| Setup | imgsz 1280, batch 8, AMP, cosine LR, mosaic + multi-scale |
+| Hardware | 2× H100, DDP |
+| Stop | Early (~73 / 200) near plateau |
 
-## Validation metrics (WIDER FACE val)
-
-Ultralytics built-in box metrics on the YOLO-formatted WIDER FACE validation split used for this run. Peak selected by **mAP50-95**:
+## Files
 
-| Metric | Epoch 1 | Best (epoch 71) |
-|--------|--------:|-------------------------------:|
-| Precision | — | 0.896 |
-| Recall | — | 0.725 |
-| mAP50 | 0.699 | **0.801** |
-| mAP50-95 | 0.331 | **0.455** |
+| File | Description |
+|------|-------------|
+| `best.pt` | Ultralytics PyTorch weights |
+| `model.onnx` | ONNX export (`imgsz=1280`, dynamic) |
+| `assets/pred_*.jpg` | Example predictions on WIDER FACE val |
 
-These are COCO-style Ultralytics mAP scores for this training setup — **not** the official WIDER FACE Easy/Medium/Hard evaluation protocol. Useful for reproducing this run; absolute numbers depend on label conversion, `imgsz`, and NMS.
+### ONNX
 
-## Experiment notes (ClearML)
+```bash
+pip install onnxruntime  # or onnxruntime-gpu
+```
 
-Training was logged in ClearML (project `yolo-face`). Highlights from the run:
+```python
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
 
-- Val **mAP50** rose from ~0.70 → ~0.80 and **mAP50-95** from ~0.33 → ~0.455 over ~70 epochs
-- Precision / recall at best checkpoint ≈ **0.90 / 0.72**
-- Stable epoch time ≈ **6.5–7 min** on 2×H100 at batch 8 / imgsz 1280
-- Train & val box/cls losses plus per-epoch detection metrics were tracked throughout; DDP job with additional train-batch scalars for monitoring
+onnx_path = hf_hub_download("uralman/yolo26l-widerface", "model.onnx")
+model = YOLO(onnx_path)
+model.predict("image.jpg", imgsz=1280, conf=0.25)
+```
 
-## Intended use
+Or export yourself from `best.pt`:
 
-- Face **detection** (boxes) for privacy blur or similar downstream pipelines
-- Benchmarking YOLO26-scale face detectors on WIDER FACE-style data
+```python
+YOLO("best.pt").export(format="onnx", imgsz=1280, dynamic=True, simplify=True)
+```
 
-## Limitations
+## Limitations & ethics
 
-- Domain shift is expected outside WIDER FACE-like photos (extreme motion blur, unusual viewpoints, etc.)
-- Not a face recognition / re-identification model
-- Ultralytics stack is **AGPL-3.0** — review [license terms](https://www.ultralytics.com/license) before commercial redistribution
+- Face **detection only** (boxes) — not recognition / identity.
+- Domain shift expected outside WIDER FACE-like photos (strong blur, unusual cameras, etc.).
+- False positives/negatives can affect privacy pipelines; validate on your data before production.
+- Ultralytics / YOLO26 are **AGPL-3.0** — see [license](https://www.ultralytics.com/license).
 
 ## Acknowledgements