# horyniuk-stepan-dev/dronelocalization architecture

> Architecture diagram of the GitHub repository horyniuk-stepan-dev/dronelocalization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horyniuk-stepan-dev/dronelocalization
- Repository: https://github.com/horyniuk-stepan-dev/dronelocalization

## Overview

#### Purpose and entry points
Desktop and headless Python system for GPS-denied drone topometric localization from reference and live video. `main.py` selects PyQt6 GUI or headless execution; headless orchestration is in `src/core/headless_runner.py`. Projects, sources, and result export are lifecycle boundaries in `src/core/project.py` and `src/core/export_results.py`.

#### Application shells and concurrency
The GUI is the primary Windows-facing operator shell, centered on `src/gui/main_window.py`, with map/video/control widgets under `src/gui/widgets/`. Long-running database, calibration, tracking, panorama, and decode work is isolated into worker pipelines under `src/workers/`, avoiding UI-thread processing. Headless mode exposes the same operational pipeline through `src/network/rest_server.py`, `src/network/ws_server.py`, and `src/network/coordinates_broker.py`.

#### Reference database construction
A reference-flight video is decoded, sampled into keyframes, feature-processed, and persisted as a reusable localization database. `src/database/database_builder.py` owns build orchestration; `src/database/keyframe_selector.py` determines frame selection and `src/database/database_loader.py` restores stored artifacts. The stated storage boundary is HDF5 v2 plus LanceDB; multi-database coordination and spatial lookup reside in `src/database/multi_database_manager.py` and `src/database/spatial_index.py`.

#### Model and visual-feature boundary
`src/models/model_manager.py` centralizes loading/runtime selection for model wrappers, keeping ML implementations separate from localization logic. Wrappers cover semantic global descriptors, local features, dynamic-object masking, dense matching, and TensorRT acceleration: `src/models/wrappers/dinov3_wrapper.py`, `src/models/wrappers/aliked_wrapper.py`, and `src/models/wrappers/yolo_wrapper.py`. Depth inference is a separate dependency boundary in `src/depth/depth_estimator.py`; vendored RDD code is under `third_party/rdd/`.

#### Localization pipeline
`src/localization/localizer.py` is the online per-frame coordinator. It retrieves likely reference candidates via `src/localization/candidate_retriever.py` / `src/localization/geo_aware_retriever.py`, matches and geometrically validates them through `src/localization/matcher.py` and `src/localization/geometric_verifier.py`, then assembles coordinate/quality outputs in `src/localization/result_builder.py`. Preprocessing, masking, scale, and rotation handling are explicit sub-boundaries rather than UI concerns.

#### Calibration and global geometry
Operator-supplied GPS anchors initiate coordinate propagation across the reference route. `src/calibration/multi_calibration_manager.py` manages anchors, while `src/calibration/multi_anchor_calibration.py` supplies calibration logic. The propagation worker feeds pose constraints into the 5-DoF optimizer in `src/geometry/pose_graph/optimizer.py`; its model, pruning, diagnostics, and visual-odometry guards are isolated under `src/geometry/pose_graph/`. Coordinate transformations and ground-scale calculations live in `src/geometry/transformations.py` and `src/geometry/gsd_calculator.py`.

#### Live tracking and outputs
Incoming file, RTSP, or HTTP video is abstracted by `src/video/video_source.py` and decoded in `src/workers/video_decode_worker.py`. Localizer results flow through `src/workers/tracking_worker.py` into object/trajectory tracking, Kalman smoothing, and outlier detection in `src/tracking/object_tracker.py`, `src/tracking/kalman_filter.py`, and `src/tracking/outlier_detector.py`. Results can be rendered to the GUI/Leaflet map, broadcast through REST/WebSocket, and exported as CSV, GeoJSON, or KML.

#### Runtime and deployment
Primary runtime is Python 3.10–3.11 on Windows with CUDA-enabled PyTorch; NVIDIA GPU/TensorRT are material performance dependencies. PyQt6 supports desktop operation, while REST/WebSocket support server integration. Container and executable packaging paths are `Dockerfile` and `scripts/build_executable.py`; model acquisition and engine compilation are handled by `scripts/download_models.py` and `scripts/compile_dinov2_trt.py`.

Main entry points: [`src/localization/localizer.py`](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/localizer.py) (Online localizer), [`src/database/database_builder.py`](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/database_builder.py) (Database builder), [`src/core/export_results.py`](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/export_results.py) (Map, API & export), [`src/gui/main_window.py`](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/gui/main_window.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shells["Application Shells"]
  node_entry["Application entry<br/>Python entrypoint<br/>[main.py]"]
  node_gui["Desktop GUI<br/>PyQt6 shell<br/>[main_window.py]"]
  node_headless["Headless runner<br/>orchestrator<br/>[headless_runner.py]"]
  node_api["REST / WebSocket API<br/>network interface<br/>[rest_server.py]"]
  node_project["Project lifecycle<br/>project boundary<br/>[project.py]"]
end

subgraph group_reference["Reference Database"]
  node_db_builder["Database builder<br/>build orchestrator"]
  node_keyframes["Keyframe selection<br/>frame sampler"]
  node_reference_store[("Reference database<br/>HDF5 v2 + LanceDB")]
end

subgraph group_vision["Vision Models"]
  node_models["Model manager<br/>ML runtime boundary<br/>[model_manager.py]"]
  node_depth["Depth estimator<br/>depth boundary<br/>[depth_estimator.py]"]
end

subgraph group_localization["Localization &amp; Geometry"]
  node_localizer["Online localizer<br/>per-frame coordinator<br/>[localizer.py]"]
  node_retrieval["Candidate retrieval<br/>reference search"]
  node_matching["Match &amp; verification<br/>geometric validation<br/>[matcher.py]"]
  node_result_builder["Localization results<br/>coordinate output<br/>[result_builder.py]"]
  node_calibration["Multi-anchor calibration<br/>anchor manager"]
  node_pose_optimizer["5-DoF pose optimizer<br/>pose graph<br/>[optimizer.py]"]
end

subgraph group_live["Live Tracking &amp; Outputs"]
  node_video_source["Live video source<br/>input abstraction<br/>[video_source.py]"]
  node_decode["Video decode worker<br/>worker pipeline"]
  node_tracking["Tracking worker<br/>worker pipeline<br/>[tracking_worker.py]"]
  node_object_tracker["Object &amp; trajectory tracker<br/>tracking subsystem<br/>[object_tracker.py]"]
  node_outputs["Map, API &amp; export<br/>result delivery<br/>[export_results.py]"]
end

node_entry -->|"desktop mode"| node_gui
node_entry -->|"headless mode"| node_headless
node_headless -->|"serves"| node_api
node_gui -->|"operates projects"| node_project
node_project -->|"builds reference DB"| node_db_builder
node_db_builder -->|"samples frames"| node_keyframes
node_keyframes -->|"feature processing"| node_models
node_db_builder -->|"persists artifacts"| node_reference_store
node_video_source -->|"video stream"| node_decode
node_decode -->|"live frames"| node_localizer
node_localizer -->|"finds candidates"| node_retrieval
node_retrieval -->|"queries"| node_reference_store
node_localizer -->|"validates candidates"| node_matching
node_models -->|"inference services"| node_localizer
node_depth -.->|"depth estimates"| node_localizer
node_matching -->|"validated geometry"| node_result_builder
node_calibration -->|"pose constraints"| node_pose_optimizer
node_pose_optimizer -->|"route coordinates"| node_reference_store
node_result_builder -->|"localization results"| node_tracking
node_tracking -->|"updates tracks"| node_object_tracker
node_object_tracker -->|"smoothed trajectories"| node_outputs
node_outputs -->|"renders results"| node_gui
node_outputs -->|"broadcasts results"| node_api

click node_entry "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/main.py"
click node_gui "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/gui/main_window.py"
click node_headless "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/headless_runner.py"
click node_api "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/network/rest_server.py"
click node_project "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/project.py"
click node_db_builder "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/database_builder.py"
click node_keyframes "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/keyframe_selector.py"
click node_reference_store "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/multi_database_manager.py"
click node_models "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/models/model_manager.py"
click node_depth "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/depth/depth_estimator.py"
click node_localizer "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/localizer.py"
click node_retrieval "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/candidate_retriever.py"
click node_matching "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/matcher.py"
click node_result_builder "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/result_builder.py"
click node_calibration "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/calibration/multi_calibration_manager.py"
click node_pose_optimizer "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/geometry/pose_graph/optimizer.py"
click node_video_source "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/video/video_source.py"
click node_decode "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/workers/video_decode_worker.py"
click node_tracking "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/workers/tracking_worker.py"
click node_object_tracker "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/tracking/object_tracker.py"
click node_outputs "https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/export_results.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_gui,node_headless,node_api,node_project toneBlue
class node_db_builder,node_keyframes,node_reference_store toneAmber
class node_models,node_depth toneMint
class node_localizer,node_retrieval,node_matching,node_result_builder,node_calibration,node_pose_optimizer toneRose
class node_video_source,node_decode,node_tracking,node_object_tracker,node_outputs toneIndigo
```

## Components

### Application Shells

- [Application entry](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/main.py): Python entrypoint · Selects GUI or headless execution. · `main.py`
- [Desktop GUI](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/gui/main_window.py): PyQt6 shell · `src/gui/main_window.py`
- [Headless runner](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/headless_runner.py): orchestrator · `src/core/headless_runner.py`
- [REST / WebSocket API](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/network/rest_server.py): network interface · `src/network/rest_server.py`
- [Project lifecycle](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/project.py): project boundary · Owns projects, sources, and result export lifecycle. · `src/core/project.py`

### Reference Database

- [Database builder](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/database_builder.py): build orchestrator · `src/database/database_builder.py`
- [Keyframe selection](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/keyframe_selector.py): frame sampler · `src/database/keyframe_selector.py`
- [Reference database](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/database/multi_database_manager.py): HDF5 v2 + LanceDB · Reusable reference-flight artifacts and spatial lookup. · `src/database/multi_database_manager.py`

### Vision Models

- [Model manager](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/models/model_manager.py): ML runtime boundary · Loads and selects descriptor, feature, masking, matching, and accelerated wrappers. · `src/models/model_manager.py`
- [Depth estimator](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/depth/depth_estimator.py): depth boundary · `src/depth/depth_estimator.py`

### Localization & Geometry

- [Online localizer](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/localizer.py): per-frame coordinator · `src/localization/localizer.py`
- [Candidate retrieval](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/candidate_retriever.py): reference search · Uses visual and geo-aware candidate retrieval. · `src/localization/candidate_retriever.py`
- [Match & verification](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/matcher.py): geometric validation · `src/localization/matcher.py`
- [Localization results](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/localization/result_builder.py): coordinate output · Assembles coordinates and quality metrics. · `src/localization/result_builder.py`
- [Multi-anchor calibration](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/calibration/multi_calibration_manager.py): anchor manager · Propagates operator GPS anchors into pose constraints. · `src/calibration/multi_calibration_manager.py`
- [5-DoF pose optimizer](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/geometry/pose_graph/optimizer.py): pose graph · `src/geometry/pose_graph/optimizer.py`

### Live Tracking & Outputs

- [Live video source](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/video/video_source.py): input abstraction · Accepts file, RTSP, and HTTP video. · `src/video/video_source.py`
- [Video decode worker](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/workers/video_decode_worker.py): worker pipeline · `src/workers/video_decode_worker.py`
- [Tracking worker](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/workers/tracking_worker.py): worker pipeline · Feeds localization results to tracking and smoothing. · `src/workers/tracking_worker.py`
- [Object & trajectory tracker](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/tracking/object_tracker.py): tracking subsystem · Includes Kalman smoothing and outlier detection. · `src/tracking/object_tracker.py`
- [Map, API & export](https://github.com/horyniuk-stepan-dev/dronelocalization/blob/master/src/core/export_results.py): result delivery · Renders map results, broadcasts updates, and exports CSV, GeoJSON, or KML. · `src/core/export_results.py`

## Connections

- Application entry → Desktop GUI: desktop mode
- Application entry → Headless runner: headless mode
- Headless runner → REST / WebSocket API: serves
- Desktop GUI → Project lifecycle: operates projects
- Project lifecycle → Database builder: builds reference DB
- Database builder → Keyframe selection: samples frames
- Keyframe selection → Model manager: feature processing
- Database builder → Reference database: persists artifacts
- Live video source → Video decode worker: video stream
- Video decode worker → Online localizer: live frames
- Online localizer → Candidate retrieval: finds candidates
- Candidate retrieval → Reference database: queries
- Online localizer → Match & verification: validates candidates
- Model manager → Online localizer: inference services
- Depth estimator → Online localizer: depth estimates
- Match & verification → Localization results: validated geometry
- Multi-anchor calibration → 5-DoF pose optimizer: pose constraints
- 5-DoF pose optimizer → Reference database: route coordinates
- Localization results → Tracking worker: localization results
- Tracking worker → Object & trajectory tracker: updates tracks
- Object & trajectory tracker → Map, API & export: smoothed trajectories
- Map, API & export → Desktop GUI: renders results
- Map, API & export → REST / WebSocket API: broadcasts results