# muhkartal/slamai-istanbulcanyon architecture

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

- Interactive diagram: https://gitdiagram.com/muhkartal/slamai-istanbulcanyon
- Repository: https://github.com/muhkartal/slamai-istanbulcanyon

## Overview

##### Project type and purpose
- This is a domain‐specific research and development pipeline rather than a traditional web or mobile full‐stack app.
- Purpose: simulate drone flights in İstanbul‐style urban canyons (using AirSim), collect and preprocess data, run baseline SLAM, train and apply ML enhancements to SLAM (feature enhancement, loop closure, patch descriptors), integrate ML models with SLAM, and evaluate results.

##### File structure
- Top‐level Python scripts:
- airsim_setup.py – configures and launches the AirSim environment
- data_preprocessing.py – ingests raw sensor data, converts to SLAM/ML formats
- baseline_slam.py – wrappers/invocations for ORB-SLAM3, DSO, SVO
- ml_enhancement.py – training/inference of CNNs for feature, loop‐closure, descriptor networks
- slam_integration.py – stitches ML outputs into SLAM pipelines
- main.py – orchestrator for modes: simulate, preprocess, train_ml, evaluate_baseline, enhance_slam, evaluate_enhanced
- Secondary modules (from README’s structure):
- configs/ – YAML or JSON configuration files (paths, parameters)
- environments/ – definitions of simulation scenarios (urban_canyon, lighting, textureless)
- data/ – raw and converted datasets with ground‐truth
- models/ – saved ML models (ONNX, PyTorch)
- evaluation/ – scripts and metric calculators (ATE, RPE, success rate)
- results/ – processed outputs, plots, tables
- images/ – architecture and scenario illustrations

##### README for additional insights
- Describes a modular architecture allowing plug‐and‐play SLAM algorithms and ML modules, and a comprehensive evaluation framework.
- Lists required packages, external SLAM dependencies, and execution modes.

a. Components
1. AirSim Simulation
– Simulated drone in İstanbul urban canyon
– Outputs: raw RGB, depth, IMU, ground‐truth poses
2. Data Preprocessing
– Converts raw outputs into TUM or KITTI formats
– Normalizes, segments, augments datasets
3. Baseline SLAM Module
– ORB-SLAM3, DSO, SVO wrappers
– Consumes preprocessed data, writes baseline trajectories
4. ML Enhancement Module
– Feature Enhancement Network (CNN)
– Loop Closure Detection Network
– Patch Descriptor Network
– Serialization of trained models
5. SLAM Integration Layer
– Injects ML predictions into SLAM pipelines
– Modifies feature detection, matching, loop closing
6. Evaluation Framework
– Computes ATE, RPE, tracking success
– Generates plots and metrics tables
7. Configuration & Storage
– configs/ for parameterization
– models/, data/, results/ for persistence
8. External SLAM Libraries
– ORB-SLAM3, DSO, SVO (C++ compiled code)

b. Interactions and data flow
- AirSim → raw data → Data Preprocessing
- Preprocessed data → Baseline SLAM → baseline outputs
- Preprocessed data → ML Training → saved models
- Preprocessed data + saved models → SLAM Integration → enhanced SLAM outputs
- Baseline & enhanced outputs → Evaluation → results
- main.py orchestrates these flows based on command‐line mode flags

c. Architectural patterns and principles
- Pipeline pattern: clear sequential stages (simulate → preprocess → train → integrate → evaluate)
- Modular “plugin” approach for SLAM algorithms and ML networks
- Separation of concerns: each .py handles one responsibility
- Config‐driven design: parameters in configs/ allow scenario swaps without code changes
- External dependency isolation: C++ SLAM libraries invoked through wrappers

d. Key technologies and frameworks
- AirSim (drone simulator)
- Python 3.7+ with NumPy, OpenCV, PyTorch, ONNX Runtime
- C++17 SLAM libraries (ORB-SLAM3, DSO, SVO)
- Metrics with SciPy, pandas, matplotlib
- CLI orchestration via argparse in main.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator
    main["Main Orchestrator\n(main.py)"]:::controller

    %% Pipeline stages
    subgraph "Pipeline Stages"
        direction TB
        sim["AirSim Simulation"]:::simulation
        preprocess["Data Preprocessing"]:::data
        baseline["Baseline SLAM Module"]:::slam
        ml["ML Enhancement Module"]:::ml
        integrate["SLAM Integration Layer"]:::slam
        evaluate["Evaluation Framework"]:::evaluation
    end

    %% Storage & Config
    subgraph "Storage & Config"
        direction TB
        configs["Configuration Files\n(configs/)"]:::config
        dataStore["Datasets & Results\n(data/, results/)"]:::storage
        models["Saved ML Models\n(models/)"]:::storage
    end

    %% Documentation & Images
    subgraph "Documentation & Illustrations"
        direction TB
        docs["Project Documentation\n(README.md)"]:::docs
        imgs["Architecture & Scenarios\n(images/)"]:::docs
    end

    %% External SLAM Libraries
    subgraph "External SLAM Libraries"
        direction TB
        orb["ORB-SLAM3 v1.0"]:::external
        dso["DSO"]:::external
        svo["SVO"]:::external
    end

    %% Flows
    main --> sim
    sim --> preprocess
    preprocess --> baseline
    preprocess --> ml
    baseline --> integrate
    ml --> integrate
    integrate --> evaluate
    evaluate --> dataStore

    %% Config injections
    configs -.-> sim
    configs -.-> preprocess
    configs -.-> baseline
    configs -.-> ml
    configs -.-> integrate
    configs -.-> evaluate

    %% Storage links
    preprocess --> dataStore
    ml --> models
    integrate --> models

    %% Documentation links
    main --- docs
    main --- imgs

    %% External SLAM integrations
    baseline --> orb
    baseline --> dso
    baseline --> svo
    integrate --> orb
    integrate --> dso
    integrate --> svo

    %% Click Events
    click sim "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/airsim_setup.py"
    click preprocess "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/data_preprocessing.py"
    click baseline "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/baseline_slam.py"
    click ml "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/ml_enhancement.py"
    click integrate "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/slam_integration.py"
    click main "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/main.py"
    click imgs "https://github.com/muhkartal/slamai-istanbulcanyon/tree/main/images/"
    click docs "https://github.com/muhkartal/slamai-istanbulcanyon/blob/main/README.md"

    %% Styles
    classDef simulation fill:#cce5ff,stroke:#3399ff,color:#000
    classDef data fill:#ffe5cc,stroke:#ff9933,color:#000
    classDef ml fill:#ccffcc,stroke:#33cc33,color:#000
    classDef slam fill:#e5ccff,stroke:#9933ff,color:#000
    classDef evaluation fill:#f2f2f2,stroke:#999,color:#000
    classDef config fill:none,stroke-dasharray: 5 5,stroke:#666,color:#000
    classDef storage fill:#f2f2f2,stroke:#666,color:#000
    classDef docs fill:#ffffcc,stroke:#cccc33,color:#000
    classDef external fill:#f9e6ff,stroke:#cc99ff,color:#000
    classDef controller fill:#ffd9d9,stroke:#ff4d4d,color:#000
```
