README.md

---
license: mit
language:
- en
library_name: ultralytics
pipeline_tag: object-detection
tags:
- object-detection
- yolo
- yolov8
- yolov10
- yolo11
- road-damage
- computer-vision
- pytorch
metrics:
- mAP
model-index:
- name: Road_Damage_Object_Detection
  results:
  - task:
      type: object-detection
      name: Object Detection
    metrics:
    - type: mAP50
      value: 0.3936
      name: YOLOv8 mAP50
    - type: mAP50-95
      value: 0.2299
      name: YOLOv8 mAP50-95
---

<div align="center">

# 🛣️ Road Damage Object Detection

**Three YOLO generations, trained and benchmarked head-to-head on the same road-damage dataset — pick your trade-off: accuracy, speed, or size.**

[![License](https://img.shields.io/badge/License-MIT-green)](#license)
[![Ultralytics](https://img.shields.io/badge/Ultralytics-YOLO-111F68)](https://github.com/ultralytics/ultralytics)

</div>

---

## Benchmark Results

YOLOv8n, YOLOv10n, and YOLO11n were each trained from their official pretrained checkpoints for up to 50 epochs (640px, batch 16) on the same train/val split, then evaluated with `model.val()` on the same validation set:

| Model | mAP50 | mAP50-95 | Precision | Recall | Size (MB) | FPS (inference) |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| 🎯 **YOLOv8n** — best accuracy | **0.3936** | **0.2299** | 0.5835 | **0.3952** | 23.36 | 269.97 |
| ⚖️ **YOLOv10n** — balanced | 0.3694 | 0.2173 | **0.5849** | 0.3527 | 5.49 | 253.44 |
| ⚡ **YOLO11n** — smallest & fastest | 0.3344 | 0.1905 | 0.5093 | 0.3504 | **5.22** | **272.88** |

**Takeaway:** YOLOv8n gives the best detection quality but is ~4x larger than the other two. YOLO11n is the lightest and quickest to run, trading off some accuracy. YOLOv10n sits in between with the best raw precision. Pick the checkpoint that matches your deployment constraints (edge device vs. server, latency budget, etc.).

## Files in this Repository

| Path | Description |
|---|---|
| `Road_Damage.ipynb` | Full training & benchmarking notebook — dataset download, training all 3 models, evaluation, comparison table/plots. |
| `runs/detect/yolov8_road*/weights/best.pt` | Trained YOLOv8n checkpoint. |
| `runs/detect/yolov10_road/weights/best.pt` | Trained YOLOv10n checkpoint. |
| `runs/detect/yolov11_road*/weights/best.pt` | Trained YOLO11n checkpoint. |
| `runs/detect/val*` | Validation run artifacts (PR curves, confusion matrices, sample predictions) for each model. |
| `yolov8n.pt`, `yolov10n.pt`, `yolo11n.pt`, `yolo26n.pt` | Base pretrained checkpoints used as training starting points. |

> Note: some models have duplicate `*-2` run folders from repeated training/validation passes — the metrics above come from the primary evaluation run in the notebook.

## How to Use

```bash
pip install ultralytics huggingface_hub
```

```python
from huggingface_hub import hf_hub_download
from ultralytics import YOLO

weights_path = hf_hub_download(
    repo_id="nsr51324/Road_Damage_Object_Detection",
    filename="runs/detect/yolov8_road/weights/best.pt"   # swap for the v10 / v11 path to try another model
)

model = YOLO(weights_path)
results = model("path/to/road_image.jpg")
results[0].show()
```

## Training Data

Trained on a road-damage detection dataset hosted on Roboflow (7 damage classes, exported in YOLOv8 format). Bring your own Roboflow API key and project reference to re-download the exact split used in `Road_Damage.ipynb`, or substitute any YOLO-format road-damage dataset with a matching `data.yaml`.

## Training Procedure

- **Image size:** 640×640 · **Batch size:** 16 · **Epochs:** up to 50 (early stopping)
- **Early stopping patience:** 10 epochs for YOLOv8n, 3 epochs for YOLOv10n and YOLO11n
- Each model trained independently from its official Ultralytics pretrained weights (`yolov8n.pt`, `yolov10n.pt`, `yolo11n.pt`)
- Evaluated with the built-in Ultralytics validator (`model.val()`) — box precision/recall, mAP50, mAP50-95, and inference speed all reported directly from `DetMetrics`

# Gradio User Interface

This repository includes a modern **Gradio interface** that allows users to perform road damage detection directly from a web browser.

### Features

* Upload a road image.
* Detect multiple road damage classes.
* Display annotated prediction image.
* Show object counts.
* Display confidence score for every detection.
* Modern responsive interface.

---

# Run the UI

Simply execute:

```bash
python UI.py
```

After running, open your browser:

```text
http://127.0.0.1:7860
```

---

# Deployment

The Gradio interface can be deployed easily on:

* Hugging Face Spaces
* Local Machine
* Google Colab
* Linux Server
* Windows
* Docker

---

# Model Architecture

* Framework: Ultralytics YOLO
* Language: Python
* Interface: Gradio
* Backend: PyTorch
* Inference Engine: Ultralytics

---

## Limitations

This is a research/benchmarking project, not a production-ready inspection system. Detection quality (mAP50-95 in the 0.19–0.23 range) reflects a lightweight "nano" model family trained for a limited number of epochs on a single dataset — expect false negatives on damage types underrepresented in training data, and re-validate before any real-world deployment (e.g. road inspection, insurance assessment).

## License

MIT for the code and trained weights. Check the source dataset's license on Roboflow before commercial use.

## Author

**Nasr Mohamed** — AI Engineer
[🤗 huggingface.co/nsr51324](https://huggingface.co/nsr51324)