# osupcvlab/pcvlabdrone2021 architecture

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

- Interactive diagram: https://gitdiagram.com/osupcvlab/pcvlabdrone2021
- Repository: https://github.com/osupcvlab/pcvlabdrone2021

## Overview

##### Project type and purpose
- This is a specialized geospatial data-processing pipeline rather than a typical web or mobile full-stack app. It consists of three cooperating Python-based subsystems:
a. “Satellite Map Generation” (offline data collection and tiling)
b. “GIS Mask from OSM” (offline building-mask generation)
c. “UAV Geolocalization” (online/localization pipeline using UAV imagery against prepared map data)

##### Key top-level components
- Offline Data Preparation
- Satellite Map Generator (create_map.py, main.py, MapAnalysis.ipynb, datasets/)
- GIS Mask Generator (GISgenerator.ipynb)
- Data Storage
- Raw satellite tiles (Satellite Map Generation/datasets/satellite_imgs)
- Coordinate look-up (datasets/coordinates.txt)
- OSM-derived building masks
- Featurebase (UAV Geolocalization/featurebase/)
- Model weights (superpoint_v1.pth, etc.)
- Online Geolocalization Pipeline
- Feature Extraction (superpoint, Feature_extractor.py)
- Feature Matching (SuperGlue, matching.py)
- Quad-Tree Spatial Index for fast geo-lookup
- Pose Estimation (rotation, height modules)
- Output generation (images, videos under output/)

##### Data-flow and interactions
1. User supplies target area → Satellite Map Generation
2. Output: Tiled satellite imagery + coordinate index
3. GIS Mask Generation against same bounds → building masks
4. Store all artifacts in a shared data repository
- Online UAV Pipeline (right side):
1. UAV camera frames feed into Feature Extractor
2. Queries Quad-Tree index to retrieve corresponding satellite tile & GIS mask
3. Pass features + mask into SuperGlue matcher for putative correspondences
4. Run pose estimation modules (rotation, height) → compute geo-location
5. Log outputs (geoposition, annotated maps, videos)

##### Architectural patterns and design principles
- Separation of Concerns: clearly split offline data generation vs. real-time localization
- Pipeline stages: each major step is its own Python module/notebook—facilitates testing and swapping algorithms
- Data-driven flow: artifacts flow from storage → retrieval → processing → results
- Use of spatial indexing (Quad-Tree) for O(log n) map lookups

##### Technologies, frameworks and libraries
- Python 3.8+ scripts and Jupyter notebooks
- OpenCV, NumPy for image processing
- PyTorch for SuperPoint & SuperGlue networks
- OSMnx for OSM queries & building mask generation
- Selenium (chromedriver.exe) for Google Maps scraping
- Geographic indexing via custom Quad-Tree implementation

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% Offline Preparation
    subgraph "Offline Prep"
        direction TB
        CM["create_map.py"]:::processing
        MI["main.py"]:::processing
        MA["MapAnalysis.ipynb"]:::processing
        GIS["GISgenerator.ipynb"]:::processing
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        ST["[(Satellite Tiles)]"]:::storage
        CI["[(Coordinates Index)]"]:::storage
        BM["[(OSM Building Masks)]"]:::storage
        FB["[(Featurebase)]"]:::storage
        MW["[(Model Weights .pth)]"]:::storage
    end

    %% Online UAV Pipeline
    subgraph "Online UAV Pipeline"
        direction TB
        FE["Feature_extractor.py"]:::processing
        QT["Quad-Tree Spatial Index"]:::processing
        SP["superpoint.py"]:::ml
        SG["superglue.py"]:::ml
        MT["matching.py"]:::processing
        UT["utils.py"]:::processing
        UL["utils_loc.py"]:::processing
        UP["utils_plot.py"]:::processing
        PE["Pose Estimation"]:::processing
        OI["Images/"]:::io
        OV["Videos/"]:::io
        OL["LIVE/"]:::io
    end

    %% Offline to Storage
    CM -->|"tile output (.png)"| ST
    CM -->|"index output (.txt)"| CI
    GIS -->|"mask output (.png)"| BM

    %% Storage to Online
    FE -->|"query quad-tree"| QT
    QT -->|"return tile"| ST
    QT -->|"return mask"| BM

    FE -->|"features"| MT

    %% Models and matching
    MW -->|"load weights"| SP
    MW -->|"load weights"| SG
    SP -->|"keypoints"| MT
    SG -->|"matcher"| MT

    MT -->|"correspondences"| PE
    UT --> PE
    UL --> PE
    UP --> PE

    %% Output
    PE -->|"annotated frames"| OI
    PE -->|"videos"| OV
    PE -->|"live log"| OL

    %% Click Events
    click CM "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/Satellite Map Generation/create_map.py"
    click MI "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/Satellite Map Generation/main.py"
    click MA "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/Satellite Map Generation/MapAnalysis.ipynb"
    click GIS "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/GISMaskfromOSM/GISgenerator.ipynb"
    click ST "https://github.com/osupcvlab/pcvlabdrone2021/tree/main/Satellite Map Generation/datasets/satellite_imgs/"
    click CI "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/Satellite Map Generation/datasets/coordinates.txt"
    click FB "https://github.com/osupcvlab/pcvlabdrone2021/tree/main/UAV Geolocalization/featurebase/"
    click MW "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/weights/superpoint_v1.pth"
    click FE "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/Feature_extractor.py"
    click SP "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/superpoint.py"
    click SG "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/superglue.py"
    click MT "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/matching.py"
    click UT "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/utils/utils.py"
    click UL "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/utils/utils_loc.py"
    click UP "https://github.com/osupcvlab/pcvlabdrone2021/blob/main/UAV Geolocalization/models/utils/utils_plot.py"
    click OI "https://github.com/osupcvlab/pcvlabdrone2021/tree/main/UAV Geolocalization/output/images/"
    click OV "https://github.com/osupcvlab/pcvlabdrone2021/tree/main/UAV Geolocalization/output/videos/"
    click OL "https://github.com/osupcvlab/pcvlabdrone2021/tree/main/UAV Geolocalization/output/LIVE/"

    %% Styles
    classDef processing fill:#a8e6cf,stroke:#379683,color:#05386b
    classDef storage fill:#84d2f6,stroke:#045a8d,color:#03396c
    classDef ml fill:#ffd3b6,stroke:#ff8b94,color:#880e4f
    classDef io fill:#f0f0f0,stroke:#cccccc,color:#333333
```
