Object Detection

Ensuring effective gun detection is vital in contemporary times to address escalating concerns about public safety and combat the increasing occurrences of crimes. This project benchmarks multiple deep learning pipelines for firearm localization using both convolutional backbones and modern one-stage detectors.

🎯 Goals

• Define a reproducible pipeline for evaluating multiple object detection families on the same dataset.
• Experiment with hyperparameter schedules to trade off latency and accuracy.
• Focus on reducing false positives while preserving high recall on crowded scenes.
• Track every experiment (ClearML) to keep the training/evaluation lineage audit-ready.

📂 Repository Structure

• YOLOv5s_Training.ipynb: Ultralytics YOLOv5s fine-tuning with 416×416 crops, batch 16, 50 epochs, ClearML logging, cache-enabled dataloader.
• YOLOv7_Training.ipynb: Official YOLOv7 repo with 640×640 images, batch 16, 55 epochs, COCO pretraining (yolov7_training.pt).
• YOLOv8_Training.ipynb: Ultralytics YOLOv8 CLI (v8.0.20) with 640×640 images, mixed precision, and five ClearML-tracked runs.
• VGG16_Training.ipynb: Two-stage TensorFlow/Keras pipeline for bounding-box regression on 224×224 crops with transfer learning from ImageNet.
• Best Performing models.txt: Direct links to the exported best.pt/.h5 weights.
• requirements.txt: Aggregated dependencies for offline replication.

📚 Dataset

• Source: Roboflow workspace nizar-assad/pistols-lhjbh.
• Versions: V1642 (YOLOv5), V1643 (YOLOv7), V1645 (YOLOv8), V1646 (VGG16/TensorFlow).
• Class distribution: single class Gun with 2,960 annotated boxes in the primary train split (see VGG16_Training.ipynb).
• Structure: Roboflow export delivers train/, valid/, test/, YAML metadata, and YOLO TXT labels.
• Download:

  pip install roboflow
  from roboflow import Roboflow
  rf = Roboflow(api_key="YOUR_KEY")
  project = rf.workspace("nizar-assad").project("pistols-lhjbh")
  dataset = project.version(<version_id>).download("<format>")

🧠 Training Notebooks

Notebook	Model	Dataset Version	Key Hyperparameters	Tracking
YOLOv5s_Training.ipynb	YOLOv5s	1642	img=416, batch=16, epochs=50, SGD w/ default hyp.scratch-low	ClearML + TensorBoard
YOLOv7_Training.ipynb	YOLOv7 (training head)	1643	img=640, batch=16, epochs=55, pretrained yolov7_training.pt	TensorBoard
YOLOv8_Training.ipynb	YOLOv8s	1645	Ultralytics CLI, epochs=100, auto mixed precision, 5 sweeps	ClearML
VGG16_Training.ipynb	VGG16 + dense head	1646 (TensorFlow export)	lr=1e-4, batch=32, epochs=50 (early stop), frozen conv body	ModelCheckpoint + EarlyStopping

Each notebook contains embedded Roboflow download cells, ClearML credentials, visualization utilities, and inference blocks on unseen data.

🧪 Experiment Tracking & Checkpoints

• ClearML links for every YOLO run are embedded at the top of the notebooks for full metric history, GPU telemetry, and artifact management.
• Best checkpoints (best.pt, last.pt, vgg16.h5) are mirrored here: https://drive.google.com/drive/folders/1o37wWBGuH7HGw9sc2HK1VMCc3maSKQuM?usp=sharing
• Store downloaded weights inside a models/ directory to keep paths consistent with the notebooks.

🚀 Reproducing the Results

1. Create environment

   python -m venv .venv && source .venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

2. Configure API keys
   • Replace YOUR_API_KEY in notebooks with your Roboflow API key
   • For ClearML tracking, run clearml-init or configure credentials in notebooks
3. Download dataset using Roboflow export matching the notebook you plan to run.
4. Launch Jupyter (jupyter lab), open the desired notebook, and update file paths to match your system.
5. Enable logging
   • ClearML: pip install clearml + clearml-init (or run clearml.browser_login() cell).
   • TensorBoard: tensorboard --logdir runs/train.
6. Train using the provided cells; GPUs with ≥12 GB VRAM recommended (T4-class was used originally).
7. Evaluate using the inference cells (detect.py or TensorFlow inference loop) on test/ or custom folders.

Note: The notebooks contain placeholder API keys and file paths from the original development environment. Update these before running.

📊 Results Snapshot

Model	Precision	Recall	F1 Score	mAP@0.5	Test Time
YOLOv5s	0.89	0.77	0.83	0.84	10s
YOLOv7	0.81	0.73	0.80	0.80	13s
YOLOv8s	0.91	0.75	0.83	0.83	9s
VGG16	0.86	0.85	0.82	0.81	20s

• VGG16 regression head additionally reports MSE=0.0109, MAE=0.0749, R²=0.713 on the held-out test set (VGG16_Training.ipynb Cell 18).
• YOLO models include qualitative overlays (val_batch*.jpg, runs/detect/exp*/) for visual inspection.

📥 Dataset & Model Downloads

• Dataset portal: https://universe.roboflow.com/upc-tf3xi/guns-dataset-j8cz1
• Pretrained weights: https://drive.google.com/drive/folders/1o37wWBGuH7HGw9sc2HK1VMCc3maSKQuM?usp=sharing
• Place downloaded weights inside a local models/ directory when running inference notebooks.

✅ Next Steps

• Add automated evaluation scripts (e.g., scripts/eval.py) to compare new checkpoints.
• Integrate mixed precision and channel pruning sweeps for YOLOv7 to match YOLOv8 latency.
• Expand dataset beyond single-class firearms to stress-test multi-class behavior.