# bdrc-com/mcldrone architecture

> Architecture diagram of the GitHub repository bdrc-com/mcldrone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bdrc-com/mcldrone
- Repository: https://github.com/bdrc-com/mcldrone

## Overview

MCLDrone combines a GNSS-denied UAV localization runtime with an offline similarity-model training and evaluation workflow. Training builds map-patch data, pretrains and flight-finetunes a model; deployment combines camera imagery, IMU and VIO with map matching to publish visual odometry for mission control. Bag replay supports offline localization analysis, while MapDB indexing is a separate map-preparation capability. The README describes further workflow details, but its excerpt ends during real-patch preparation; links for unsampled stages are kept at documented subsystem level.

Main entry points: [`train_similarity.py`](https://github.com/bdrc-com/mcldrone/blob/main/train_similarity.py) (Train pipeline), [`ovws/src/ov_mcl/ov_mcl/mcl_node.py`](https://github.com/bdrc-com/mcldrone/blob/main/ovws/src/ov_mcl/ov_mcl/mcl_node.py) (Live MCL node), [`mission_manager.py`](https://github.com/bdrc-com/mcldrone/blob/main/mission_manager.py) (Mission manager), [`bag_mcl.py`](https://github.com/bdrc-com/mcldrone/blob/main/bag_mcl.py) (Bag replay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Model training"]
  node_trainer["Train pipeline"]
  node_config["Training config<br/>[train_config.yml]"]
  node_networks["Similarity networks<br/>[orthosimilarity.py]"]
  node_tensorutils["Image utilities<br/>[utils.py]"]
  node_trainingdata[("Training imagery")]
  node_patchbank[("Patch bank")]
  node_flightdata[("Flight recordings")]
  node_realpairs[("Real patch pairs")]
  node_checkpoint["Model checkpoint"]
  node_evaluation["Real-patch evaluation"]
end

subgraph group_localization["Localization"]
  node_replay["Bag replay<br/>[bag_mcl.py]"]
  node_bagreader["Bag reader<br/>[bag_reader.py]"]
  node_orthoproject["Orthoprojection<br/>[orthoprojection.py]"]
  node_filter["Particle filter<br/>[mcl.py]"]
  node_mclnode["Live MCL node<br/>[mcl_node.py]"]
  node_launch["Localization launch"]
end

subgraph group_mission["Mission control"]
  node_mission["Mission manager<br/>[mission_manager.py]"]
  node_guard["Mission guard<br/>[mission_guard.py]"]
end

subgraph group_mapdata["Map data"]
  node_map[("Stitched map")]
  node_tileindex["Tile index builder"]
  node_tiles[("Offline map tiles")]
end

node_developer(("Data curator"))
node_vio["VIO estimator"]
node_camera(("Downward camera"))
node_imu(("IMU"))
node_px4["PX4 autopilot"]
node_operator(("Mission operator"))

node_developer -->|"prepares imagery"| node_trainingdata
node_developer -->|"records flights"| node_flightdata
node_config -->|"configures"| node_trainer
node_trainingdata -->|"builds bank from"| node_trainer
node_trainer -->|"writes"| node_patchbank
node_trainer -->|"trains"| node_networks
node_trainer -->|"uses"| node_tensorutils
node_flightdata -->|"supplies flight data"| node_trainer
node_trainer -->|"builds real pairs"| node_realpairs
node_patchbank -->|"supplies patches"| node_trainer
node_realpairs -->|"fine-tunes with"| node_trainer
node_trainer -->|"saves"| node_checkpoint
node_checkpoint -->|"evaluated by"| node_evaluation
node_realpairs -->|"provides truth pairs"| node_evaluation
node_flightdata -->|"replayed from"| node_replay
node_replay -->|"reads frames"| node_bagreader
node_replay -->|"orthoprojects frames"| node_orthoproject
node_replay -->|"runs localization"| node_filter
node_camera -->|"publishes images"| node_mclnode
node_imu -->|"publishes measurements"| node_mclnode
node_launch -->|"starts"| node_vio
node_launch -->|"starts"| node_mclnode
node_vio -->|"publishes odometry"| node_mclnode
node_mclnode -->|"orthoprojects frames"| node_orthoproject
node_mclnode -->|"runs particle filter"| node_filter
node_map -->|"supplies map imagery"| node_mclnode
node_checkpoint -->|"loads model"| node_mclnode
node_mclnode -->|"publishes visual odometry"| node_mission
node_px4 -->|"sends vehicle state"| node_mission
node_operator -->|"provides mission"| node_mission
node_mission -->|"checks mission state"| node_guard
node_mission -->|"publishes setpoints"| node_px4
node_tiles -->|"indexes tiles"| node_tileindex

click node_trainer "https://github.com/bdrc-com/mcldrone/blob/main/train_similarity.py"
click node_config "https://github.com/bdrc-com/mcldrone/blob/main/train_config.yml"
click node_networks "https://github.com/bdrc-com/mcldrone/blob/main/sivl/models/orthosimilarity.py"
click node_tensorutils "https://github.com/bdrc-com/mcldrone/blob/main/sivl/utils/utils.py"
click node_checkpoint "https://github.com/bdrc-com/mcldrone/tree/main/checkpoints_huizhou"
click node_evaluation "https://github.com/bdrc-com/mcldrone/blob/main/eval_real_patches.py"
click node_replay "https://github.com/bdrc-com/mcldrone/blob/main/bag_mcl.py"
click node_bagreader "https://github.com/bdrc-com/mcldrone/blob/main/bag_reader.py"
click node_orthoproject "https://github.com/bdrc-com/mcldrone/blob/main/orthoprojection.py"
click node_filter "https://github.com/bdrc-com/mcldrone/blob/main/mcl.py"
click node_mclnode "https://github.com/bdrc-com/mcldrone/blob/main/ovws/src/ov_mcl/ov_mcl/mcl_node.py"
click node_launch "https://github.com/bdrc-com/mcldrone/blob/main/ovws/src/ov_mcl/launch/mcl_localization.launch.py"
click node_map "https://github.com/bdrc-com/mcldrone/tree/main/maps"
click node_tileindex "https://github.com/bdrc-com/mcldrone/blob/main/gnss_free/gnss_free_core/mapdb/build_tile_index.py"
click node_mission "https://github.com/bdrc-com/mcldrone/blob/main/mission_manager.py"
click node_guard "https://github.com/bdrc-com/mcldrone/blob/main/mission_guard.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_trainer,node_config,node_networks,node_tensorutils,node_trainingdata,node_patchbank,node_flightdata,node_realpairs,node_checkpoint,node_evaluation toneBlue
class node_replay,node_bagreader,node_orthoproject,node_filter,node_mclnode,node_launch toneAmber
class node_mission,node_guard toneMint
class node_map,node_tileindex,node_tiles toneRose
class node_developer,node_vio,node_camera,node_imu,node_px4,node_operator toneIndigo
```

## Components

### Model training

- [Train pipeline](https://github.com/bdrc-com/mcldrone/blob/main/train_similarity.py): `train_similarity.py`
- [Training config](https://github.com/bdrc-com/mcldrone/blob/main/train_config.yml): `train_config.yml`
- [Similarity networks](https://github.com/bdrc-com/mcldrone/blob/main/sivl/models/orthosimilarity.py): `sivl/models/orthosimilarity.py`
- [Image utilities](https://github.com/bdrc-com/mcldrone/blob/main/sivl/utils/utils.py): `sivl/utils/utils.py`
- **Training imagery**
- **Patch bank**
- **Flight recordings**
- **Real patch pairs**
- [Model checkpoint](https://github.com/bdrc-com/mcldrone/tree/main/checkpoints_huizhou): `checkpoints_huizhou`
- [Real-patch evaluation](https://github.com/bdrc-com/mcldrone/blob/main/eval_real_patches.py): `eval_real_patches.py`

### Localization

- [Bag replay](https://github.com/bdrc-com/mcldrone/blob/main/bag_mcl.py): `bag_mcl.py`
- [Bag reader](https://github.com/bdrc-com/mcldrone/blob/main/bag_reader.py): `bag_reader.py`
- [Orthoprojection](https://github.com/bdrc-com/mcldrone/blob/main/orthoprojection.py): `orthoprojection.py`
- [Particle filter](https://github.com/bdrc-com/mcldrone/blob/main/mcl.py): `mcl.py`
- [Live MCL node](https://github.com/bdrc-com/mcldrone/blob/main/ovws/src/ov_mcl/ov_mcl/mcl_node.py): `ovws/src/ov_mcl/ov_mcl/mcl_node.py`
- [Localization launch](https://github.com/bdrc-com/mcldrone/blob/main/ovws/src/ov_mcl/launch/mcl_localization.launch.py): `ovws/src/ov_mcl/launch/mcl_localization.launch.py`

### Mission control

- [Mission manager](https://github.com/bdrc-com/mcldrone/blob/main/mission_manager.py): `mission_manager.py`
- [Mission guard](https://github.com/bdrc-com/mcldrone/blob/main/mission_guard.py): `mission_guard.py`

### Map data

- [Stitched map](https://github.com/bdrc-com/mcldrone/tree/main/maps): `maps`
- [Tile index builder](https://github.com/bdrc-com/mcldrone/blob/main/gnss_free/gnss_free_core/mapdb/build_tile_index.py): `gnss_free/gnss_free_core/mapdb/build_tile_index.py`
- **Offline map tiles**

### Other components

- **Data curator**
- **VIO estimator**
- **Downward camera**
- **IMU**
- **PX4 autopilot**
- **Mission operator**

## Connections

- Data curator → Training imagery: prepares imagery
- Data curator → Flight recordings: records flights
- Training config → Train pipeline: configures
- Training imagery → Train pipeline: builds bank from
- Train pipeline → Patch bank: writes
- Train pipeline → Similarity networks: trains
- Train pipeline → Image utilities: uses
- Flight recordings → Train pipeline: supplies flight data
- Train pipeline → Real patch pairs: builds real pairs
- Patch bank → Train pipeline: supplies patches
- Real patch pairs → Train pipeline: fine-tunes with
- Train pipeline → Model checkpoint: saves
- Model checkpoint → Real-patch evaluation: evaluated by
- Real patch pairs → Real-patch evaluation: provides truth pairs
- Flight recordings → Bag replay: replayed from
- Bag replay → Bag reader: reads frames
- Bag replay → Orthoprojection: orthoprojects frames
- Bag replay → Particle filter: runs localization
- Downward camera → Live MCL node: publishes images
- IMU → Live MCL node: publishes measurements
- Localization launch → VIO estimator: starts
- Localization launch → Live MCL node: starts
- VIO estimator → Live MCL node: publishes odometry
- Live MCL node → Orthoprojection: orthoprojects frames
- Live MCL node → Particle filter: runs particle filter
- Stitched map → Live MCL node: supplies map imagery
- Model checkpoint → Live MCL node: loads model
- Live MCL node → Mission manager: publishes visual odometry
- PX4 autopilot → Mission manager: sends vehicle state
- Mission operator → Mission manager: provides mission
- Mission manager → Mission guard: checks mission state
- Mission manager → PX4 autopilot: publishes setpoints
- Offline map tiles → Tile index builder: indexes tiles