README.md

---
license: mit
tags:
- computer-vision
- object-detection
- yolov8
- vehicle-detection
- traffic-analysis
- highway-monitoring
library_name: ultralytics
pipeline_tag: object-detection
---

# Highway Vehicle Detection - Code & Models

A complete vehicle detection system for highway traffic monitoring. This repository contains the trained models, source code, and documentation - ready to use without requiring dataset downloads.

## Quick Start

### Installation
```bash
pip install ultralytics opencv-python numpy
```

### Basic Usage
```python
from ultralytics import YOLO

# Load the trained model
model = YOLO('models/yolov8m_stage2_improved_best.pt')

# Run inference on an image
results = model('path/to/image.jpg')
results[0].show()

# Process video
results = model('path/to/video.mp4', save=True)
```

### Using the Main Application
```bash
python main.py
```

## Repository Contents

### Trained Models
- `models/yolov8m_stage2_improved_best.pt` - **Final model** (recommended)
- `models/yolov8m_stage1_smart_best.pt` - Stage 1 model (for comparison)

### Source Code
- `main.py` - Complete vehicle detection and counting application
- `example_usage.py` - Simple usage examples
- `requirements.txt` - Python dependencies
- `test_improved_model.bat` - Windows testing script

### Fine-tuning Dataset
- `finetune_dataset/images/` - 92 fine-tuning images
- `finetune_dataset/labels/` - Corresponding annotation files
- `finetune_dataset/README.dataset.txt` - Dataset information
- `finetune_dataset/README.roboflow.txt` - Roboflow export info

### Configuration
- `dataset_configs/main_data.yaml` - Main dataset configuration (8 classes)
- `dataset_configs/finetune_data.yaml` - Fine-tuning dataset configuration

### Training Logs
- `training_logs/stage2_results.png` - Training results visualization
- `training_logs/stage2_confusion_matrix.png` - Confusion matrix
- `training_logs/stage2_results.csv` - Detailed training metrics
- `training_logs/stage2_val_batch0_pred.jpg` - Sample validation predictions

### Training Runs Structure
- `training_runs/stage1_smart/` - Stage 1 training configuration and weights
  - `args.yaml` - Training arguments
  - `weights/last.pt` - Last epoch weights
- `training_runs/stage2_improved/` - Stage 2 training configuration and weights
  - `args.yaml` - Training arguments
  - `weights/last.pt` - Last epoch weights
  - `BoxF1_curve.png` - F1 score curve
  - `BoxPR_curve.png` - Precision-Recall curve
  - `labels.jpg` - Label distribution visualization

### Documentation
- `PROJECT_REPORT.md` - Complete project documentation
- `README.md` - This file

## Model Performance

### Classes Detected
1. **auto** - Three-wheelers
2. **bus** - Public transport vehicles  
3. **car** - Passenger cars
4. **lcv** - Light Commercial Vehicles
5. **motorcycle** - Two-wheelers
6. **multiaxle** - Multi-axle heavy vehicles
7. **tractor** - Agricultural/construction vehicles
8. **truck** - Heavy vehicles

### Training Stages
- **Stage 1**: Initial training on 8,219 highway images
- **Stage 2**: Fine-tuning on 92 additional images for improved truck/bus detection

### Fine-tuning Dataset Details
- **Images**: 92 carefully selected highway images
- **Focus**: Improved detection of trucks and buses
- **Classes**: Enhanced examples for problematic vehicle types
- **Format**: YOLO format with bounding box annotations
- **Quality**: High-quality images with clear vehicle visibility

## External Resources

### Test Video
Watch the model in action on YouTube:
[Highway Vehicle Detection Demo](https://www.youtube.com/watch?v=wqctLW0Hb_0&list=PLJKyZ_NuOhJQzif2-6-Kq9OiOj_UjJWvi)

### Main Dataset
Download the complete training dataset from Kaggle:
[Vehicle Detection 8 Classes Dataset](https://www.kaggle.com/datasets/sakshamjn/vehicle-detection-8-classes-object-detection/data)

## Technical Details

- **Architecture**: YOLOv8m (Medium)
- **Framework**: Ultralytics YOLO
- **Input**: Images/Videos
- **Output**: Bounding boxes with class labels and confidence scores
- **Hardware**: CPU/GPU compatible

## Usage Examples

### Vehicle Detection
```python
from ultralytics import YOLO
import cv2

# Load the final model
model = YOLO('models/yolov8m_stage2_improved_best.pt')

# Detect vehicles in image
results = model('highway_image.jpg')

# Process results
for result in results:
    boxes = result.boxes
    for box in boxes:
        x1, y1, x2, y2 = box.xyxy[0]
        conf = box.conf[0]
        cls = int(box.cls[0])
        class_name = model.names[cls]
        print(f"Detected: {class_name} (confidence: {conf:.2f})")
```

### Video Processing with Counting
```python
# Process video with vehicle counting
results = model('traffic_video.mp4', save=True, save_txt=True)

# The main.py script provides advanced counting and tracking features
```

### Using the Complete Application
```python
# Run the full application with counting and visualization
from main import VehicleCounter

counter = VehicleCounter()
counter.process_video('input_video.mp4', 'output_video.mp4')
```

## Applications

- Highway traffic monitoring
- Vehicle counting and classification
- Traffic flow analysis
- Automated surveillance systems
- Road safety monitoring
- Traffic data collection

## Related Repositories

- **Full Dataset**: [highway-vehicle-detection-full](https://huggingface.co/datasets/bichuche0705/highway-vehicle-detection-full) - Complete project with datasets and videos
- **Model Only**: [highway-vehicle-detection](https://huggingface.co/bichuche0705/highway-vehicle-detection) - Just the trained model

## License

MIT License - Free to use for research and commercial purposes

## Contributing

This is a research project. For questions or improvements, please contact the author.

## Contact

**Author**: Nguyen Quoc Viet  
**Repository**: https://huggingface.co/bichuche0705/highway-vehicle-detection-code

## Citation

If you use this model in your research, please cite:

```bibtex
@misc{highway-vehicle-detection-code,
  title={Highway Vehicle Detection - Code \& Models},
  author={Nguyen Quoc Viet},
  year={2025},
  url={https://huggingface.co/bichuche0705/highway-vehicle-detection-code}
}
```