cv-based-pothole-detection

a computer vision pipeline for real-time pothole detection using YOLOv8. trained on a custom annotated dataset and packaged as a proper Python module with a clean src layout and unit tests.

what it does

detects potholes in images using a fine-tuned YOLOv8 object detection model. the pipeline covers everything from dataset preparation and model training to inference on new images, with results saved under model/runs/detect/.

project structure

cv-based-pothole-detection/
├── dataset/                  # annotated training data (images + labels)
├── model/
│   └── runs/
│       └── detect/           # YOLOv8 training outputs (weights, metrics, plots)
├── notebooks/                # jupyter notebooks for training and experimentation
├── src/                      # core source code (detection logic, utilities)
├── tests/                    # unit tests for the pipeline
├── test_images/              # sample images for quick inference testing
├── pothole_detection.egg-info/  # package metadata (auto-generated)
├── pyproject.toml            # build config and package declaration
└── .gitignore

setup

clone the repo

git clone https://github.com/fourtysevencode/cv-based-pothole-detection.git
cd cv-based-pothole-detection

install the package in editable mode

pip install -e .

this uses setuptools under the hood (declared in pyproject.toml) and makes the src/ modules importable from anywhere.

install dependencies

pip install ultralytics opencv-python

you'll also need torch — follow the official PyTorch install guide for your platform.

training

open the notebook in notebooks/ and run it end-to-end. it handles:

• loading the dataset from dataset/
• configuring and launching YOLOv8 fine-tuning
• saving model weights and training metrics to model/runs/detect/

alternatively, you can run training headlessly from the command line using Ultralytics' CLI:

yolo detect train data=dataset/data.yaml model=yolov8n.pt epochs=50 imgsz=640

inference

run detection on your own images using the trained weights:

from ultralytics import YOLO

model = YOLO("model/runs/detect/train/weights/best.pt")
results = model("test_images/your_image.jpg")
results[0].show()

or batch-run on the included test images:

yolo detect predict model=model/runs/detect/train/weights/best.pt source=test_images/

running tests

pytest tests/

the .gitignore already excludes __pycache__ and .pytest_cache directories.

tech stack

dataset

the dataset/ directory contains annotated road images in YOLO format (.txt label files with bounding box coordinates). if you want to add more data or re-annotate, tools like Roboflow or LabelImg work well.

results

training artifacts (loss curves, precision-recall plots, confusion matrix, and final weights) are stored under:

model/runs/detect/train2/

the best checkpoint is at weights/best.pt and the last at weights/last.pt.

future work

• real-time video inference using webcam or dashcam feed
• severity classification (small / medium / large pothole)
• GPS-tagged pothole logging
• lightweight deployment using YOLOv8n or ONNX export

author

built by fourtysevencode — part of an ongoing computer vision portfolio.

PS

this project is nowhere near completion and may have errors present. for demonstration purposes only as of now.

** ai aided in the writing of only this README.