Circle Object Detection with YOLO

A complete end-to-end pipeline for training, evaluating, exporting, and deploying a YOLO-based object detector for circle detection tasks using dataets from RoboFlow.

This repository includes:

• YOLO training pipeline
• Weights & Biases (W&B) experiment tracking
• Automatic metrics and plot generation
• Model export to ONNX and TensorRT
• Real-time inference for robotics applications
• Structured and modular codebase

---

Features

• YOLO-based circle detection

• Supports standard YOLO26 label format

• W&B experiment tracking

• Automatic generation of:

    - Loss curves
    - Precision-Recall curves
    - Confusion matrices
    - mAP metrics
    - Validation visualizations
  

• ONNX export

• TensorRT export

• Real-time webcam inference

• Robotics deployment ready

---

Dataset Structure

The dataset must follow the YOLO format:

data/
+-- train/
    +-- images/
    +-- labels/
 
+-- valid/
    +-- images/
    +-- labels/

+-- test/
    +-- images/
    +-- labels/

Each label file must have the standard YOLO annotation format:

class_id x_center y_center width height

Example:

0 0.523 0.412 0.126 0.126

---

Repository Structure

Circle_Object_Detection/

+-- configs/
    +-- circle_dataset.yaml

+-- data/
     +-- train/
     +-- valid/
     +-- test/

+-- runs/

+-- src/
     +-- train.py
     +-- infer.py
     +-- export.py
     +-- utils.py

+-- requirements.txt

+-- README.md

---

Installation

Clone Repository

git clone https://github.com/SanaNazari/Circle_Object_Detection.git

cd Circle_Object_Detection

---

Create Environment

conda create -n circle_detector python=3.10

conda activate circle_detector

or

python -m venv venv

source venv/bin/activate

---

Install Dependencies

pip install -r requirements.txt

---

Docker Setup

Prerequisites

1. Docker: Install from https://docs.docker.com/get-docker/
2. NVIDIA Docker Runtime (for GPU support): Install from https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
   • Verify: docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi

Building the Docker Image

With GPU (NVIDIA CUDA):

docker build -t circle-detector:latest .
# or
docker-compose build

Without GPU (CPU-only):

docker build -f Dockerfile.cpu -t circle-detector:cpu-latest .
# or
docker-compose -f docker-compose.cpu.yml build

Running the Container

GPU Version:

docker-compose up -d
docker-compose exec circle-detector /bin/bash
docker-compose down  # to stop

CPU-only Version (No GPU required):

docker-compose -f docker-compose.cpu.yml up -d
docker-compose -f docker-compose.cpu.yml exec circle-detector-cpu /bin/bash
docker-compose -f docker-compose.cpu.yml down  # to stop

Using Docker CLI directly:

# With GPU
docker run -it --rm --gpus all \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/runs:/app/runs \
  circle-detector:latest

# Without GPU (CPU-only)
docker run -it --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/runs:/app/runs \
  circle-detector:cpu-latest

Running with Camera Input

For real-time camera inference, uncomment the device mapping in docker-compose.yml:

devices:
  - /dev/video0:/dev/video0
environment:
  - DISPLAY=${DISPLAY}
volumes:
  - /tmp/.X11-unix:/tmp/.X11-unix

Then run: docker-compose up

Running with Image/Video Files

Modify src/infer.py to accept file paths as arguments, then run:

docker run -it --rm --gpus all \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/runs:/app/runs \
  circle-detector:latest \
  python3 src/infer.py --input /app/data/test/images/image.jpg

For more details, see DOCKER_SETUP.md.

---

Weights & Biases Setup

Create a W&B account:

https://wandb.ai

Login:

wandb login

Paste your API key when prompted.

---

Dataset Configuration

Edit:

configs/circle_dataset.yaml

Example:

path: /Circle_Object_Detection/data

train: train/images
val: valid/images
test: test/images

names:
  0: circle

---

Training

Start training:

python src/train.py

Training outputs will be saved to:

runs/
+-- circle_detector/

including:

weights/
+-- best.pt
+-- last.pt

results.csv
results.png
confusion_matrix.png
PR_curve.png
F1_curve.png

---

Training Configuration

Default configuration:

Parameter	Value
Epochs	200
Image Size	640
Batch Size	16
Optimizer	AdamW
Learning Rate	1e-3
Weight Decay	5e-4
Early Stopping	50 epochs

These can be modified in:

src/train.py

---

Evaluation

Validation metrics are automatically computed during training.

Metrics include:

• Precision
• Recall
• mAP50
• mAP50-95
• Confusion Matrix
• F1 Score

A final evaluation on the test split is performed after training.

---

Exporting Models

After training:

python src/export.py

Generated files:

best.onnx
best.engine

Supported exports:

Format	Usage
PyTorch (.pt)	Development
ONNX (.onnx)	Cross-platform deployment
TensorRT (.engine)	NVIDIA GPUs / Jetson

---

Real-Time Inference

Run:

python src/infer.py

The script:

• Opens webcam stream
• Runs object detection
• Displays confidence scores
• Displays FPS

---

Inference Thresholds

Current deployment thresholds:

conf_threshold = 0.90
iou_threshold = 0.90

These values prioritize precision and reduce false positives.

Recommended values for most applications:

conf_threshold = 0.50
iou_threshold = 0.60

---

Results

These results are generated after training the model on the combined dataset from data/dataset_sources.

Validation metrics:

Metric	Value
Precision	0.100
Recall	0.938
mAP50	0.992
mAP50-95	0.860

Test metrics:

Metric	Value
Precision	0.968
Recall	0.999
mAP50	0.994
mAP50-95	0.845

Actual results depend on dataset quality and size.

---

Weights & Biases Tracking

Tracked automatically:

• Training Loss
• Validation Loss
• Precision
• Recall
• mAP50: Mean average precision calculated at an intersection over union (IoU) threshold of 0.50. It's a measure of the model's accuracy considering only the "easy" detections.
• mAP50-95: The average of the mean average precision calculated at varying IoU thresholds, ranging from 0.50 to 0.95. It gives a comprehensive view of the model's performance across different levels of detection difficulty.
• Learning Rate
• Prediction Visualizations
• Confusion Matrix
• Precision-Recall Curves

Example dashboard:

https://wandb.ai/<username>/<project>

---

Performance Optimization

For maximum speed:

Use FP16

half=True

Export TensorRT

python src/export.py

Use Batch Inference

For offline processing:

batch > 1

Use GPU

device=0

---

Troubleshooting

CUDA Not Found

Verify:

nvidia-smi

and

python -c "import torch; print(torch.cuda.is_available())"

---

W&B Login Issues

Re-login:

wandb login --relogin

---

Dataset Errors

Verify:

train/images
train/labels

valid/images
valid/labels

test/images
test/labels

and ensure every image has a matching label file.

---