How rohansaw/falcon-eye works
Project type and purpose
• Falcon-Eye is a research/engineering codebase implementing and benchmarking efficient object-detection models (EfficientDet, MMDetection, YOLOv8, custom “detector” modules) for tiny objects in aerial high-resolution imagery, targeting embedded device deployment.
High-level architecture overview
The project naturally splits into four logical subsystems:
A. Baselines
B. Core detector library
C. Development utilities (dev_utils)
D. Deployment/Export tools
Main components & their responsibilities
A. Baselines directory
• Contains reference implementations:
– efficientdet: scripts for training, evaluating, quantizing, ONNX conversion.
– mmdet: MMDetection-based detectors, custom datasets, quantization modules, benchmark scripts.
– yolov8: Ultralytics YOLOv8 training, conversion, quantization, datasets.
• Purpose: provide off-the-shelf training/eval pipelines for comparison.
B. Detector directory (core library)
• detector/model.py + heads/, attention/, backends/: model definition, modular building blocks (MHSA, MQA, backbones, heads).
• detector/dataset/: data loading, slicing, augmentation, custom COCO wrappers.
• train.py / sweep.py: training entry points, hyperparameter sweeps.
• inference.py / predict*.py: single/multi-slice inference, ONNX export.
• utils/: callbacks, losses, metrics, postprocessing, visualization.
• benchmark_slicing.py, create_calib_data_quant.py: micro-benchmarks, calibration data.
C. dev_utils directory
• ds_processing/: raw data conversion, slicing, annotation cleaning and transformations.
• eval/: extensive evaluation scripts for TensorFlow, ONNX, MMDetection, YOLO-predictions, SAHI.
• model_export/: conversion scripts to ONNX, TFLite, dynamic tensor checks, AI-Edge tool integrations.
• ds_analysis/, pog_test/: notebooks and analysis helpers.
D. Deployment / export (within both Baselines & dev_utils)
• ONNX, TFLite conversion pipelines, quantization, Dockerfiles.
• Slurm training wrappers.
• Dockerfiles in baselines and detector for reproducible environments.
Relationships and dataflow
1. Raw imagery + annotations → dev_utils/ds_processing → standardized COCO/YOLO datasets
2. Dataset feed → Detector core (dataset module) → DataLoader → Model (backbones + heads + attention) → Training/Eval (train.py, eval scripts)
3. Trained weights → dev_utils/model_export OR baselines/*/to_onnx.sh → ONNX/TFLite/quantized models
4. Exported model → detector/inference*.py OR dev_utils/eval → inference metrics & visualizations
5. End-to-end benchmarking: baseline scripts vs core detector implementations
Architectural patterns & design principles
• Modular plug-in design: separate “backends” (backbones), “heads,” “attention” blocks.
• Config-driven workflows: shell scripts and YAML/JSON config files for hyperparams and dataset specs.
• Layered pipeline: data prep → training → export → evaluation
• Reproducibility: Dockerfiles per baseline, slurm / shell wrappers