horyniuk-stepan-dev/dronelocalization

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.