A comprehensive object detection pipeline built on Ultralytics YOLOv8, providing end-to-end support for custom dataset preparation, model training with advanced augmentation strategies, evaluation, and real-time inference via a FastAPI service.
- Dataset Preparation -- Convert COCO and Pascal VOC annotations to YOLO format, split datasets with stratification, validate annotations, and analyze class distributions.
- Training -- Full training loop with configurable hyperparameters, augmentation pipelines (mosaic, mixup, HSV jitter, geometric transforms), checkpoint resumption, and multi-format model export.
- Evaluation -- Compute mAP@50 and mAP@50-95, per-class precision/recall/F1, confusion matrices, precision-recall curves, error analysis, and inference speed benchmarks.
- Inference -- Single image, batch directory, video file, and live webcam/RTSP stream detection with configurable NMS, confidence filtering, and region-of-interest masking.
- REST API -- FastAPI service with endpoints for image detection, annotated image responses, real-time WebSocket streaming, and model introspection.
yolov8-object-detection/
├── configs/
│ └── training_config.yaml
├── src/
│ ├── dataset_preparation.py
│ ├── trainer.py
│ ├── inference.py
│ ├── evaluation.py
│ └── api.py
├── requirements.txt
├── .gitignore
└── README.md
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtfrom src.dataset_preparation import DatasetPreparator
preparator = DatasetPreparator(data_dir="./data/raw", output_dir="./data/prepared")
preparator.convert_coco_to_yolo("annotations.json", "images/")
preparator.split_dataset(train_ratio=0.8, val_ratio=0.15, test_ratio=0.05)
preparator.create_dataset_yaml(class_names=["car", "truck", "pedestrian", "cyclist"])
preparator.compute_class_distribution()from src.trainer import YOLOTrainer
trainer = YOLOTrainer(config_path="configs/training_config.yaml")
trainer.setup_model()
trainer.configure_augmentations()
results = trainer.train()
trainer.export_model(format="onnx")from src.inference import YOLOInference
detector = YOLOInference(model_path="runs/detect/train/weights/best.pt")
detections = detector.detect_image("test.jpg", confidence=0.4)
detector.draw_detections("test.jpg", detections, output_path="result.jpg")from src.evaluation import YOLOEvaluator
evaluator = YOLOEvaluator(model_path="runs/detect/train/weights/best.pt")
metrics = evaluator.evaluate(data_yaml="data/prepared/dataset.yaml")
evaluator.plot_confusion_matrix(save_path="confusion_matrix.png")
evaluator.speed_benchmark(image_size=640, batch_sizes=[1, 8, 16, 32])uvicorn src.api:app --host 0.0.0.0 --port 8000| Method | Endpoint | Description |
|---|---|---|
| POST | /detect |
Upload an image and receive detection results as JSON |
| POST | /detect/annotated |
Upload an image and receive an annotated image |
| WS | /ws/stream |
WebSocket endpoint for real-time detection streaming |
| GET | /model/info |
Retrieve model metadata and configuration |
| GET | /health |
Health check |
All training parameters are managed through configs/training_config.yaml. Key settings include model architecture selection (yolov8n through yolov8x), augmentation strengths, optimizer configuration, and early stopping patience.
Trained models can be exported to multiple formats for deployment:
- ONNX -- Cross-platform inference
- TensorRT -- Optimized NVIDIA GPU inference
- CoreML -- Apple device deployment
- OpenVINO -- Intel hardware acceleration
- Python 3.9+
- CUDA-capable GPU recommended for training
- See
requirements.txtfor full dependency list
MIT License