# rohansaw/falcon-eye architecture

> Architecture diagram of the GitHub repository rohansaw/falcon-eye, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohansaw/falcon-eye
- Repository: https://github.com/rohansaw/falcon-eye

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation Layer
    subgraph "Data Preparation" 
        direction TB
        dsProcessing["Data Preparation\n(dev_utils/ds_processing/)"]:::dataprep
    end

    %% Baselines Suite Layer
    subgraph "Baselines Suite"
        direction TB
        effdet["EfficientDet\n(baselines/efficientdet)"]:::baseline
        mmdet["MMDetection\n(baselines/mmdet)"]:::baseline
        yolov8["YOLOv8\n(baselines/yolov8)"]:::baseline
    end

    %% Core Detector Library Layer
    subgraph "Core Detector Library"
        direction TB
        model["Model Definition\n(detector/model.py)"]:::core
        attention["Attention Modules\n(detector/attention/)"]:::core
        backends["Backbone Backends\n(detector/backends/)"]:::core
        heads["Detection Heads\n(detector/heads/)"]:::core
        dataset["Dataset & Data Loaders\n(detector/dataset/)"]:::core
        train["Training Entry Point\n(detector/train.py)"]:::core
        sweep["Hyperparameter Sweep\n(detector/sweep.py & sweep.yaml)"]:::core
        inference["Inference Scripts\n(detector/inference.py,\npredict.py, predict_sliced.py)"]:::core
        onnxExport["ONNX Export\n(detector/to_onnx.py)"]:::core
        utils["Utilities\n(detector/utils/)"]:::core
        bench["Micro-benchmarks & Calibration\n(detector/benchmark_slicing.py,\ncreate_calib_data_quant.py)"]:::core
    end

    %% Export & Evaluation Layer
    subgraph "Export & Evaluation"
        direction TB
        modelExport["Model Export & Conversion Tools\n(dev_utils/model_export/)"]:::export
        evalSuite["Evaluation & Benchmark Suite\n(dev_utils/eval/)"]:::export
    end

    %% Deployment Target Layer
    subgraph "Deployment Target"
        direction TB
        device["Embedded Device Runtime"]:::deploy
    end

    %% Data Stores and Raw Inputs
    rawImages(("Raw Imagery")):::data
    rawAnno(("Raw Annotations")):::data

    %% Data Flow
    rawImages -->|images| dsProcessing
    rawAnno -->|annotations| dsProcessing
    dsProcessing -->|"COCO/YOLO dataset"| dataset
    dataset -->|"DataLoader"| model
    model -->|"features"| heads
    attention -->|"attention outputs"| model
    backends -->|"backbone outputs"| model
    heads -->|"predictions"| inference
    train -->|"trained .pth"| onnxExport
    sweep -->|"config params"| train

    %% Baselines to Export & Evaluation
    effdet -->|"to_onnx.sh / quantize.sh"| modelExport
    mmdet -->|"quantization modules"| modelExport
    yolov8 -->|"quantize.py"| modelExport
    modelExport -->|".onnx/.tflite"| evalSuite
    inference -->|"predictions"| evalSuite

    %% Feedback loops
    evalSuite -->|"metrics & visualizations"| sweep
    evalSuite -->|"deployment artifacts"| device

    %% Click Events
    click effdet "https://github.com/rohansaw/falcon-eye/tree/main/baselines/efficientdet"
    click mmdet "https://github.com/rohansaw/falcon-eye/tree/main/baselines/mmdet"
    click yolov8 "https://github.com/rohansaw/falcon-eye/tree/main/baselines/yolov8"
    click model "https://github.com/rohansaw/falcon-eye/blob/main/detector/model.py"
    click attention "https://github.com/rohansaw/falcon-eye/tree/main/detector/attention/"
    click backends "https://github.com/rohansaw/falcon-eye/tree/main/detector/backends/"
    click heads "https://github.com/rohansaw/falcon-eye/tree/main/detector/heads/"
    click dataset "https://github.com/rohansaw/falcon-eye/tree/main/detector/dataset/"
    click train "https://github.com/rohansaw/falcon-eye/blob/main/detector/train.py"
    click sweep "https://github.com/rohansaw/falcon-eye/blob/main/detector/sweep.py"
    click inference "https://github.com/rohansaw/falcon-eye/blob/main/detector/inference.py"
    click onnxExport "https://github.com/rohansaw/falcon-eye/blob/main/detector/to_onnx.py"
    click utils "https://github.com/rohansaw/falcon-eye/tree/main/detector/utils/"
    click bench "https://github.com/rohansaw/falcon-eye/blob/main/detector/benchmark_slicing.py"
    click dsProcessing "https://github.com/rohansaw/falcon-eye/tree/main/dev_utils/ds_processing/"
    click modelExport "https://github.com/rohansaw/falcon-eye/tree/main/dev_utils/model_export/"
    click evalSuite "https://github.com/rohansaw/falcon-eye/tree/main/dev_utils/eval/"

    %% Styles
    classDef dataprep fill:#D0E6FF,stroke:#0057D9,color:#000
    classDef baseline fill:#FFE5B4,stroke:#E67E00,color:#000
    classDef core fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef export fill:#F3E5F5,stroke:#8E44AD,color:#000
    classDef deploy fill:#EEEEEE,stroke:#7F8C8D,color:#000
    classDef data fill:#FFFFFF,stroke:#2C3E50,stroke-dasharray: 2 2,color:#000
```
