🛰️ GPS-Denied Visual-Inertial Navigation & Localization Stack

İnsansız Hava Araçları (İHA) için GPS karartması (jamming), aldatması (spoofing) veya sinyal yokluğunda yüksek hassasiyetli, gerçek zamanlı seyrüsefer ve mutlak konumlandırma sağlayan hiyerarşik görsel-eylemsel (Visual-Inertial Odometry / Absolute Georeferenced Localization) seyrüsefer sistemi.

Sistem, hem Python (algoritma doğrulama, simülasyon, video/telemetri testleri) hem de C++ / ROS 2 (NVIDIA Jetson Orin Nano ve Pixhawk / PX4 donanımında düşük gecikmeli uçuş) mimarisiyle tam uyumlu olarak geliştirilmiştir.

• Proje Genel Bakış
• Sistem Mimarisi ve Katmanlar
• Temel Özellikler
• Dizin Yapısı
• Kurulum
  • 1. Python Ortamı
  • 2. C++ & ROS 2 Ortamı (Jetson Orin / Linux)
• Kullanım ve Test Adımları
  • Adım 1: Uçuş Öncesi Referans Harita Üretimi
  • Adım 2: Sentetik Uçuş Simülasyonu
  • Adım 3: Video ve Telemetri (SRT) ile Test & Görselleştirme
  • Adım 4: C++ Yüksek Performanslı Runner (WSL / Orin)
  • Adım 5: Gerçek Donanımda Uçuş (ROS 2 + PX4 uXRCE-DDS)
• Koordinat Sistemleri ve Sensör Füzyonu
• Failsafe ve Güvenlik Modları
• Katkıda Bulunma ve Lisans

Geleneksel otopilotlar GPS kesildiğinde yalnızca dahili IMU (ivmeölçer ve jiroskop) verilerini çift entegre ederek ölü kestirim (Dead Reckoning) yapar. Sensörlerdeki beyaz gürültü ve bias kaymaları, tahmin hatasının kuadratik/kübik büyümesine ve uçağın saniyeler içinde rotadan sapıp düşmesine yol açar.

Bu projede geliştirilen sistem, GPS'in olmadığı ortamlarda aşağıdaki 5 kritik mühendislik problemini katmanlı yaklaşımla çözer:

Aşağıdaki mimari şema, uçuş öncesi hazırlıktan otopilot motor kontrolüne kadar veri akışını özetlemektedir:

flowchart TD
    subgraph PreFlight ["Katman 0: Uçuş Öncesi Hazırlık"]
        MB["Mapbox Uydu Servisi"] --> MapPipeline["preflight_map_pipeline.py"]
        MapPipeline --> GeoTIFF["GeoTIFF Referans Harita<br/>Grayscale + CLAHE Filtresi"]
    end

    subgraph Sensors ["Uçuş Sensörleri"]
        IMU["Pixhawk IMU - 100 Hz<br/>İvmeölçer ve Jiroskop"]
        CAM["Aşağı Bakan Kamera - 30 Hz<br/>Monoküler Canlı Görüntü"]
        BARO["Barometre ve Telemetri<br/>İrtifa Z Ölçümü"]
    end

    subgraph Estimator ["Füzyon Motoru - Orin Nano"]
        IMU -->|"Tahmin Adımı - 100 Hz"| ESKF["16-Durumlu Gecikmeli ESKF<br/>Konum, Hız, Oryantasyon, Biaslar, Gecikme"]
        
        CAM -->|"Katman 1.5 - 30 Hz"| KLT["KLT Optik Akış<br/>Yatay Hız Kestirimi"]
        BARO --> KLT
        KLT -->|"Hız Güncellemesi"| ESKF

        CAM -->|"Katman 2 ve 3 - 1 Hz"| LG["SuperPoint ve LightGlue<br/>Çift Modelli RANSAC"]
        GeoTIFF -->|"Kovaryans Güdümlü Dinamik ROI"| LG
        LG -->|"Gecikmeli Mutlak Poz"| RingBuf["TimeIndexedRingBuffer<br/>Tarihsel Geri Sarma"]
        RingBuf -->|"Gecikmeli Kalman Düzeltmesi"| ESKF
    end

    subgraph Output ["Otopilot Entegrasyonu"]
        ESKF -->|"NED Eksen Dönüşümü"| DDS["PX4 uXRCE-DDS Köprüsü<br/>/fmu/in/vehicle_visual_odometry"]
        DDS --> PX4["Pixhawk Otopilot - EKF2"]
        ESKF --> Status["/advanced_localization/status<br/>Failsafe ve Durum Bildirimi"]
    end

• Adım: Uçuş yapılacak koordinatların merkez enlem/boylamı, yarıçapı ve piksel başına zemin çözünürlüğü (GSD) belirlenir.
• İşlem: Mapbox API üzerinden yüksek çözünürlüklü uydu karoları (tiles) indirilir, mozaiklenir ve GeoTIFF formatına dönüştürülür.
• İyileştirme: Farklı güneş açıları ve aydınlatma farklarına karşı CLAHE (Contrast Limited Adaptive Histogram Equalization) uygulanarak haritanın yerel kontrastı normalize edilir.

• Adım: Pixhawk'tan gelen 100 Hz IMU ölçümleri integrasyon denklemine sokulur.
• Durum Vektörü: $\mathbf{x} = [\mathbf{p}{3\times 1}, \mathbf{v}{3\times 1}, \mathbf{q}{4\times 1}, \mathbf{b}a{3\times 1}, \mathbf{b}g{3\times 1}, t_d]{16\times 1}$
• Özellik: Standart EKF yerine açılardaki singülerlikleri (gimbal lock) engelleyen ve kuaterniyon kinematiğinde hata durumunu lineere yakın tutan Hata Durumu (Error-State) formülasyonu kullanılır.

• Adım: Yere bakan monoküler kameradan gelen ardışık iki kare arasında Lucas-Kanade (KLT) algoritmasıyla belirgin pikseller takip edilir.
• İşlem: Piksel kayması ($\Delta u, \Delta v$) ve barometrik irtifa ($h$) kullanılarak uçağın yerdeki anlık yatay hızı ($\hat{v}_x, \hat{v}_y$) hesaplanır.
• Çözüm: Harita eşleşmesi beklenirken (1 sn boyunca) İHA'nın IMU kaymasını sıfıra yakın tutar.

• Adım 1 (Dinamik ROI): Tüm uydu haritasını taramak yüksek gecikmeye neden olur. Filtrenin mevcut konum kovaryansı ($3\sigma$) ve uçuş hızı kadar haritadan dinamik bir alt bölge (ROI) kesilir.
• Adım 2 (Öznitelik Çıkarımı): Canlı kamera karesi ile kesilen harita parçası SuperPoint evrişimli sinir ağına sokularak anahtar noktalar ve tanımlayıcılar (descriptors) çıkarılır.
• Adım 3 (LightGlue Eşleme): Transformer mimarili LightGlue ile noktalar eşleştirilir.
• Adım 4 (Geometrik ve İstatistiksel Kapılama):
  • Düz araziler için Homografi ($H$), engebeli araziler için Temel Matris ($F$) RANSAC modelleri yarıştırılır.
  • Uçağın irtifasıyla piksel ölçeği tutarlılığı doğrulanır.
  • Mahalanobis kapısı ($d_M \le 9.21$) ile ani sıçramalar elenir.
• Adım 5 (Gecikmeli Güncelleme): Çıkarım süresi $t_d$ kadar halka tamponda geçmişe dönülerek Kalman güncellemesi yapılır ve filtre güncel zamana kadar ileri simüle edilir.

• Tarihsel Gecikme Telafisi (Historical Replay): Derin öğrenme eşleştirmesi 100-300 ms sürse dahi, zaman damgalı halka tampon sayesinde filtre geçmişe dönüp ölçümü uygular ve günümüze doğru hatasız ilerler.
• Çift Dil Desteği: Araştırma, hiperparametre optimizasyonu ve görselleştirme için Python; uçuş donanımı için sıfır-kopyalama (zero-copy) C++ ve Eigen mimarisi.
• Modern PX4 Entegrasyonu: MAVROS bağımlılığı olmadan, PX4 v1.14+ yerel standardı olan Micro XRCE-DDS üzerinden doğrudan /fmu/in/vehicle_visual_odometry beslemesi.
• Gelişmiş Failsafe Mekanizması: Görsel eşleşme kaybı, sensör tutarsızlığı ve kovaryans patlaması anında otomatik tespit ve durum bildirimi.
• Zengin Test ve Kıyaslama (Benchmark): DJI / GoPro MP4 videoları ve altyazı (SRT) telemetri dosyaları ile çevrimdışı (offline) birebir uçuş simülasyonu.

gps-denied-navigation/
├── advanced_localization_cpp/       # Yüksek performanslı C++ / ROS 2 paketi (Jetson Orin için)
│   ├── CMakeLists.txt              # Derleme kuralları ve bağımlılıklar (Eigen3, OpenCV, YAML)
│   ├── package.xml                 # ROS 2 paket manifestosu (px4_msgs, sensor_msgs vb.)
│   ├── include/                    # C++ başlık dosyaları (eskf, ring_buffer, optical_flow vb.)
│   ├── src/                        # C++ kaynak kodları ve ROS 2 düğümü (localization_node.cpp)
│   └── launch/                     # ROS 2 başlatma dosyaları (localization.launch.py)
├── config/                         # Sistem konfigürasyonları
│   ├── system_config.yaml          # Filtre kovaryansları, sensör hızları, gürültü modelleri
│   ├── system_config_video_lightglue.yaml # Video testleri için optimize LightGlue ayarları
│   └── camera_info_dummy.yaml      # Kamera iç parametreleri (intrinsics: fx, fy, cx, cy)
├── docs/                           # Teknik dökümantasyon ve donanım entegrasyon raporları
│   └── pixhawk_orin_cpp_migration_report.md # Pixhawk + Orin Nano uXRCE-DDS göç raporu
├── scripts/                        # Yardımcı araçlar ve test betikleri
│   ├── preflight_map_pipeline.py   # Mapbox API'den uydu haritası indirip GeoTIFF üreten araç
│   ├── run_video_testing.py        # Video (.mp4) ve telemetri (.srt) ile uçuş simülasyonu
│   ├── profile_lightglue_gpu.py    # LightGlue GPU çıkarım gecikmesi profilleyici
│   └── compress_jpg.py             # Harita ve görsel sıkıştırma aracı
├── simulation/                     # Simülasyon ortamı
│   └── synthetic_flight.py         # Yapay 3B yörünge ve IMU/kamera sentetik veri üreteci
├── src/advanced_localization/      # Çekirdek Python paketi
│   ├── eskf.py                     # 16-durumlu Hata Durumlu Kalman Filtresi motoru
│   ├── ring_buffer.py              # Zaman damgalı halka tampon (TimeIndexedRingBuffer)
│   ├── failsafe.py                 # Durum makinesi ve arıza tespit yöneticisi
│   ├── map_store.py                # GeoTIFF harita yönetimi ve dinamik ROI çıkarımı
│   ├── math_utils.py               # Kuaterniyon, rotasyon ve Lie cebiri matematiği
│   ├── types.py                    # Tip tanımlamaları (ImuSample, VisionMeasurement vb.)
│   ├── video_testing.py            # Video test işleme motoru
│   ├── ros2/                       # Python ROS 2 düğümü (navigation_node.py)
│   └── vision/                     # Bilgisayarlı görü katmanları
│       ├── superpoint_layer.py     # SuperPoint öznitelik çıkarımı
│       ├── lightglue_layer.py      # LightGlue derin öğrenme eşleyicisi & RANSAC
│       ├── optical_flow_layer.py   # OpenCV KLT optik akış hız kestirimi
│       └── roi_selector.py         # Dinamik harita arama penceresi seçici
├── tests/                          # Pytest birim ve entegrasyon testleri
├── requirements.txt                # Python bağımlılık listesi
└── pyproject.toml                  # Python proje metaverileri

Gereksinimler: Python 3.10+, PyTorch (CUDA destekli önerilir), OpenCV.

# 1. Depoyu klonlayın
git clone https://github.com/kadir465/Locating-without-GPS.git
cd Locating-without-GPS

# 2. Sanal ortam oluşturun ve aktif edin
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 3. Bağımlılıkları yükleyin
pip install -r requirements.txt

# 4. Paketi geliştirici modunda kurun
pip install -e .

Gereksinimler: Ubuntu 22.04, ROS 2 Humble, OpenCV 4.x, Eigen3, px4_msgs.

# 1. ROS 2 çalışma alanı oluşturun
mkdir -p ~/gps_denied_ws/src
cd ~/gps_denied_ws/src

# 2. Depoyu ve PX4 mesaj tanımlarını çekin
git clone https://github.com/kadir465/Locating-without-GPS.git
git clone https://github.com/PX4/px4_msgs.git

# 3. Derleyin
cd ~/gps_denied_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select advanced_localization_cpp --cmake-args -DCMAKE_BUILD_TYPE=Release

Uçulacak bölgenin enlem, boylam ve yarıçapını girerek Mapbox üzerinden CLAHE uygulanmış GeoTIFF haritası oluşturun:

python scripts/preflight_map_pipeline.py \
  --mapbox-token "MAPBOX_TOKENINIZ" \
  --center-lat 41.0151 \
  --center-lon 28.9795 \
  --radius-m 2000 \
  --gsd 0.2 \
  --output deployment/map_preflight_clahe.tif

Filtrenin matematiksel tutarlılığını yapay IMU ve kamera verileriyle test edin:

python -m simulation.synthetic_flight
# Birim testleri çalıştırmak için:
pytest

Daha önce kaydedilmiş bir İHA uçuş videosunu (.mp4) ve telemetri altyazısını (.srt) harita üzerinde canlı görselleştirerek test edin:

python scripts/run_video_testing.py \
  --video data/flight_sample.mp4 \
  --srt data/flight_sample.srt \
  --map-path deployment/map_preflight_clahe.tif \
  --map-gsd 0.2 \
  --show-map-window \
  --csv-output outputs/flight_result.csv

Kare hızını (FPS) ve bellek profilini C++ motoruyla doğrudan test etmek için:

./build/advanced_localization_cpp/video_testing_runner \
  --video data/flight_sample.mp4 \
  --srt data/flight_sample.srt \
  --map-path deployment/map_preflight_clahe.tif \
  --map-gsd 0.2 \
  --profile \
  --csv-output outputs/cpp_benchmark.csv

1. Micro XRCE-DDS Agent'ı Başlatın:

   # Seri port (Telem portu üzerinden):
   MicroXRCEAgent serial --dev /dev/ttyTHS1 -b 921600
   # veya Ethernet/UDP üzerinden:
   MicroXRCEAgent udp4 -p 8888

2. C++ Seyrüsefer Düğümünü Başlatın:

   source ~/gps_denied_ws/install/setup.bash
   ros2 launch advanced_localization_cpp localization.launch.py \
     config_yaml:=config/system_config.yaml \
     map_path:=deployment/map_preflight_clahe.tif

   Düğüm otomatik olarak PX4'ün IMU verisini dinleyecek, filtre çıktısını /fmu/in/vehicle_visual_odometry konusuna basarak otopilotun EKF2 modülünü besleyecektir.

Farklı sistemler arasındaki eksen çakışmalarını önlemek için izolasyon adaptörü kullanılır:

Filtre tüm hesaplamalarını robotik standardı olan ENU ekseninde yürütür; PX4'e odometri basarken eksenler otomatik olarak NED formatına dönüştürülür.

Sistem uçuş güvenliğini sağlamak için sürekli durum analizi yapar ve /advanced_localization/status üzerinden otopilota bilgi sağlar:

• VISION_LOSS: Görsel özelliklerin yetersizliği (örneğin su üstü veya bulut içi uçuş). Bu durumda filtre otomatik olarak KLT Optik Akış ve IMU dead-reckoning moduna geçer.
• INCONSISTENCY: Optik akış hızı ile harita eşleşmesi arasında Mahalanobis mesafe kapısını aşan tutarsızlık tespiti. Hatalı eşleşme dışlanır (outlier rejection).
• HIGH_COVARIANCE: Kovaryans matrisinin $P_{xy}$ izi eşik değeri aştığında otopilota güven seviyesinin düştüğünü bildirir.

• LightGlue: LightGlue: Local Feature Matching at Light Speed (ICCV 2023)
• SuperPoint: SuperPoint: Self-Supervised Interest Point Detection and Description
• ESKF Mantığı: Joan Solà - Quaternion kinematics for the error-state Kalman filter
• PX4 Micro XRCE-DDS: PX4 ROS 2 User Guide