docs: update model card with 4-way defect classifier and anti-gaming repair verification details
5f36c75 verified | 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) | |