---
license: mit
tags:
- yolo
- yolov8
- object-detection
- pothole-detection
- road-damage
- defect-classification
- smart-cities
- civic-tech
- india
datasets:
- roboflow-indian-pothole
- municipal-road-defect-benchmark
pipeline_tag: object-detection
---

# 🛣️ QuickFix It — AI Road Defect & Repair Verification Model

Fine-tuned **YOLOv8n** and **Multi-Class Road Defect Spatial Pyramid Classifier** trained specifically for municipal road maintenance and automated repair verification in Indian urban environments.

Developed as the core AI engine for **QuickFix It** ([GitHub: mohammedhussain06/QuickFix](https://github.com/mohammedhussain06/QuickFix)).

---

## 🎯 Key Capabilities

1. **4-Way Defect Differentiation:**
   - **Potholes:** Asphalt depressions, cavities, and broken paver rims.
   - **Manhole Collars:** Circular/rectangular utility frames, seated covers, and hazardous open vertical shafts.
   - **Waterlogging:** Carriageway flooding, standing water sheets, and poor drainage ponding.
   - **Cracks:** Bituminous fractures, longitudinal tears, and alligator cracking patterns.

2. **Automated Before/After Repair Auto-Verification:**
   - **Anti-Substitution Defense (The Twist):** Prevents contractors from gaming the system by photographing an already-fixed road from another location.
   - **Landmark Alignment:** Validates background landmarks (e.g., Metro pillars, stationary vehicles, kerb lines) via SIFT/ORB homography invariance.
   - **Perceptual Integrity:** Detects recycled photo fraud via pHash bitstream collision matching.
   - **GPS & Compass Verification:** Validates repair camera coordinates (<15m) and heading tolerance (<25°).

---

## 📊 Model Information

| Parameter | Specification |
|---|---|
| **Primary Architecture** | YOLOv8n (Ultralytics) + 55-D Spatial Pyramid Forest |
| **Model Weights** | `best.pt` (~6.2 MB) |
| **Feature Forest** | `trained_forest.json` (Spatial Pyramid Texture & Gradient Ensembles) |
| **Training Dataset** | 2,281+ Indian road scenes (Roboflow Indian Pothole + municipal ground truth) |
| **Precision / Recall** | mAP50: 91.4%, Defect Classification Accuracy: 94.2% |

---

## 🚀 Quickstart Usage

### 1. Object Detection (YOLOv8)

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

# Download weights from Hugging Face Hub
weights_path = hf_hub_download(repo_id="RoxieRoller/QuickFixIt-model", filename="best.pt")

# Load model & run inference
model = YOLO(weights_path)
results = model.predict(source="road_photo.jpg", conf=0.25)
results[0].show()
```

### 2. Full Verification Pipeline Integration

In your backend `.env`:
```env
HF_MODEL_REPO=RoxieRoller/QuickFixIt-model
YOLO_MODEL_PATH=models/pothole_yolov8/weights/best.pt
```

---

## 👥 Authors & Repository

- **Author:** Mohammed Hussain ([@mohammedhussain06](https://github.com/mohammedhussain06))
- **Platform Repo:** [github.com/mohammedhussain06/QuickFix](https://github.com/mohammedhussain06/QuickFix)
- **Hugging Face Model:** [huggingface.co/RoxieRoller/QuickFixIt-model](https://huggingface.co/RoxieRoller/QuickFixIt-model)