umutsaray/DroneSwarm-Operational-Intelligence

# DroneSwarm Operational Intelligence Publication-ready implementation of an AI-based drone swarm detection and threat assessment pipeline built around YOLOv8 and an explainable threat-scoring model. This repository accompanies the academic work: **AI-Based Detection and Threat Assessment System for Drone Swarm Attacks Using Deep Learning** The public repository is intentionally lightweight. It includes source code, tests, configuration, paper-ready output figures/tables, and a small sample YOLO-format dataset for reproducibility checks. Large training runs, full datasets, and model checkpoints are not bundled in the GitHub release. ## Project Overview The system supports the following research workflow: 1. Prepare a YOLO-format drone swarm dataset. 2. Create train/validation/test splits. 3. Train and compare YOLOv8n and YOLOv8s. 4. Run dataset-level inference on the test split. 5. Convert real detections into threat-score features. 6. Generate paper-ready figures and tables from experiment outputs. 7. Inspect outputs through a Streamlit application. No random dashboard values, fake detections, or simulated threat scores are generated by the pipeline. ## System Architecture Input Image or Video -> Image Preprocessing -> YOLOv8 Detection -> Feature Extraction -> Threat Scoring Engine -> Risk Classification -> Streamlit Dashboard -> Decision Support The corresponding publication figure is included at: paper_outputs/figure_system_architecture.png ## Explainable Threat Scoring The threat model follows the paper equation: TS = alpha * N_norm + beta * D + gamma * P where: N = detected drone count N_norm = min(N / N_max, 1) A_swarm = normalized area of the minimum rectangle covering detected boxes D = min((N / A_swarm) / D_max, 1) d = normalized distance between swarm centroid and protected region center P = max(0, min(1, 1 - d / d_max)) TS = max(0, min(1, alpha * N_norm + beta * D + gamma * P)) Risk levels are: 0.00-0.25 Low 0.25-0.50 Medium 0.50-0.75 High 0.75-1.00 Critical All weights, thresholds, and protected-region settings are configurable in: config/config.yaml ## Repository Structure DroneSwarm-Operational-Intelligence/ ├── app.py ├── config/ │ └── config.yaml ├── data/ │ ├── images/ # lightweight sample images only │ ├── labels/ # matching YOLO labels for sample images │ └── splits/ # generated split files ├── paper_outputs/ # publication figures, tables, and summaries ├── src/ │ ├── augment_dataset.py │ ├── benchmark_realtime.py │ ├── check_project.py │ ├── dataset.py │ ├── evaluate.py │ ├── infer.py │ ├── threat_score.py │ ├── train.py │ ├── utils.py │ └── visualization.py ├── tests/ ├── requirements.txt ├── README.md └── .gitignore ## Installation Use Python 3.10 or newer. pip install -r requirements.txt For CUDA acceleration, install a PyTorch build that matches your local CUDA driver before running training or benchmarking. CPU execution is supported but slower. ## Dataset Placement The repository contains a lightweight sample dataset with 5 image-label pairs for smoke tests and command validation. For full experiments, replace or extend: data/images/ data/labels/ Labels must be standard YOLO text files with matching image stems. Full dataset and trained weights are available upon reasonable academic request. ## Prepare Splits Generate absolute POSIX split files and a YOLO-compatible `data.yaml`: python -m src.dataset --config config/config.yaml Outputs: data/splits/train.txt data/splits/val.txt data/splits/test.txt data/splits/data.yaml data/splits/split_summary.csv ## Reproducibility Check python -m src.check_project --config config/config.yaml This verifies local data folders, image-label pairing, split files, paper outputs, requirements, and model-readiness conditions. The GitHub release does not bundle `.pt` checkpoints; YOLOv8 pretrained weights can be downloaded by Ultralytics during training, while trained paper weights are distributed separately on academic request. ## Training Train both configured models: python -m src.train --config config/config.yaml Train one model: python -m src.train --config config/config.yaml --models yolov8n Optional augmentation for the training split only: python -m src.augment_dataset --config config/config.yaml python -m src.train --config config/config.yaml --use-augmented Validation and test images are never augmented. ## Dataset-Level Inference After training, run inference on the test split: python -m src.infer --config config/config.yaml --run-dir experiments/run_ Prediction CSVs are saved under: experiments/run_/predictions/ Each row includes image name, model name, detection count, average confidence, bounding boxes, inference time, FPS, `N_norm`, `A_swarm`, `D`, `P`, final `TS`, and risk level. ## Inference Example python -m src.dataset --config config/config.yaml python -m src.train --config config/config.yaml --models yolov8n python -m src.infer --config config/config.yaml --run-dir experiments/run_ --models yolov8n Use the run directory printed by the training command in place of `experiments/run_`. ## Generate Paper Figures and Tables python -m src.evaluate --config config/config.yaml --run-dir experiments/run_ Publication outputs are written to: paper_outputs/ Included paper outputs: figure_system_architecture.png figure_detection_examples.png figure_dashboard.png figure_training_curves.png figure_confusion_matrix.png figure_threat_workflow.png figure_dense_swarm_example.png table_model_comparison.csv table_threat_scores.csv table_experiment_configuration.csv experiment_summary.md ## Real-Time Benchmarking CPU or selected-device benchmark: python -m src.benchmark_realtime --config config/config.yaml CUDA benchmark, when CUDA-enabled PyTorch is installed: python -m src.benchmark_realtime --config config/config.yaml --device cuda:0 --output-suffix gpu The benchmark uses 640x640 input resolution, 10 warmup inferences, all test images, and reports: FPS = 1000 / average_inference_time_ms ## Streamlit Application Launch from the repository root: streamlit run app.py The app provides: - single-image inference after trained weights are available, - model selection for YOLOv8n and YOLOv8s, - detection visualization, - prediction-derived threat scoring, - experiment table viewing, - paper-output figure and table viewing. ## Tests python -m unittest discover -s tests The tests cover: - threat-score formula behavior, - risk-level classification, - YOLO label parsing, - swarm-area calculation, - inference CSV schema, - augmentation label validity, - real-time benchmark table schema. ## Reproducibility Statement This release is designed to run from the repository root without user-specific Desktop paths or external hardcoded directories. The sample dataset is intentionally small and is provided only for software validation. Scientific claims in the manuscript should be reproduced with the full dataset, fixed train/validation/test splits, real YOLO training outputs, and prediction-derived threat-score CSV files. The pipeline separates real data from augmented training examples. Augmented images are not treated as new real-world observations; validation and test sets remain non-augmented. ## Citation If this repository supports your work, please cite the associated manuscript: @article{drone_swarm_threat_assessment, title = {AI-Based Detection and Threat Assessment System for Drone Swarm Attacks Using Deep Learning}, author = {Authors to be added after journal submission}, journal = {Manuscript under review}, year = {2026} } ## Data and Weight Availability Full dataset and trained weights are available upon reasonable academic request. Large checkpoints are intentionally excluded from the GitHub repository to keep the release suitable for public hosting. If released publicly later, trained weights should be distributed through GitHub Releases, Zenodo, institutional storage, or another persistent research artifact repository. ## Limitations - The threat score is image-normalized and does not estimate physical distance without camera calibration. - Threat-score weights and thresholds require independent operational validation. - The lightweight sample dataset is not sufficient for scientific performance claims. - Paper figures must be regenerated from complete experiment outputs for final manuscript revision. ## Citation If you use this framework in your research, please cite: U. Saray, “AI-Based Detection and Threat Assessment System for Drone Swarm Attacks Using Deep Learning,” 2026. ## Reproducibility Statement This repository contains the lightweight public release version of the proposed operational UAV swarm intelligence framework. A lightweight sample dataset is included for demonstration and reproducibility purposes. The full dataset and trained model weights are available upon reasonable academic request. Note: Pretrained model weights are not included in the lightweight public release version in order to minimize repository size. Users may train models using the provided dataset configuration and training pipeline.