# starrytank/satortho architecture

> Architecture diagram of the GitHub repository starrytank/satortho, 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/starrytank/satortho
- Repository: https://github.com/starrytank/satortho

## Overview

SatOrtho’s documented workflow aligns satellite-map observations with UAV visual poses, asynchronously fuses relative and absolute pose estimates, then incrementally builds a georeferenced orthophoto. This snapshot includes pose-fusion and mapping code, keyframe state, and ZeroMQ messaging; the README says the visual-SLAM and satellite-matching implementations are not present in this partial release. Edges between the documented stages reflect that workflow, while the sampled source specifically supports keyframe state, GeoMap reconstruction, and messaging responsibilities. The complete runtime wiring cannot be confirmed from the available excerpts.

Main entry points: [`src/map/key_frame.cc`](https://github.com/starrytank/satortho/blob/main/src/map/key_frame.cc) (Keyframe state), [`src/map/zmq_com.cc`](https://github.com/starrytank/satortho/blob/main/src/map/zmq_com.cc) (Map messaging), [`src/map/geo_fuse.cc`](https://github.com/starrytank/satortho/blob/main/src/map/geo_fuse.cc) (Pose fusion), [`src/map/geo_map.cc`](https://github.com/starrytank/satortho/blob/main/src/map/geo_map.cc) (GeoMap builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pose["Pose estimation"]
  node_relative["Relative pose"]
  node_keyframe["Keyframe state<br/>[key_frame.cc]"]
  node_absolute["Absolute pose"]
end

subgraph group_fusion["Pose fusion"]
  node_fusion["Pose fusion<br/>[geo_fuse.cc]"]
end

subgraph group_mapping["Map reconstruction"]
  node_geo_map["GeoMap builder<br/>[geo_map.cc]"]
  node_local_map["Local map<br/>[local_map.cc]"]
  node_orthophoto["Georeferenced orthophoto<br/>[geo_map.cc]"]
end

subgraph group_messaging["Messaging"]
  node_zmq_com["Map messaging<br/>[zmq_com.cc]"]
  node_zmq_ipc["ZeroMQ transport<br/>[zmq_IPC.cc]"]
  node_frames["Message frames<br/>[zmq_frame.cc]"]
end

node_uav(("UAV frames"))
node_satmaps[("Satellite maps")]
node_consumer(("Map consumer"))

node_uav -->|"provides frames"| node_relative
node_relative -->|"selects keyframes"| node_keyframe
node_keyframe -->|"matches keyframes"| node_absolute
node_satmaps -->|"provides prior"| node_absolute
node_relative -->|"relative poses"| node_fusion
node_absolute -->|"absolute observations"| node_fusion
node_fusion -->|"aligned poses"| node_geo_map
node_keyframe -->|"keyframe imagery"| node_geo_map
node_geo_map -->|"creates regions"| node_local_map
node_local_map -->|"updates mosaic"| node_orthophoto
node_orthophoto -.->|"publishes maps"| node_zmq_com
node_zmq_com -->|"sends messages"| node_zmq_ipc
node_zmq_com -->|"encodes frames"| node_frames
node_zmq_ipc -.->|"transmits maps"| node_consumer

click node_keyframe "https://github.com/starrytank/satortho/blob/main/src/map/key_frame.cc"
click node_fusion "https://github.com/starrytank/satortho/blob/main/src/map/geo_fuse.cc"
click node_geo_map "https://github.com/starrytank/satortho/blob/main/src/map/geo_map.cc"
click node_local_map "https://github.com/starrytank/satortho/blob/main/src/map/local_map.cc"
click node_orthophoto "https://github.com/starrytank/satortho/blob/main/src/map/geo_map.cc"
click node_zmq_com "https://github.com/starrytank/satortho/blob/main/src/map/zmq_com.cc"
click node_zmq_ipc "https://github.com/starrytank/satortho/blob/main/src/zmq/zmq_IPC.cc"
click node_frames "https://github.com/starrytank/satortho/blob/main/src/zmq/zmq_frame.cc"

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_relative,node_keyframe,node_absolute toneBlue
class node_fusion,node_satmaps toneAmber
class node_geo_map,node_local_map,node_orthophoto toneMint
class node_zmq_com,node_zmq_ipc,node_frames toneRose
class node_uav,node_consumer toneIndigo
```

## Components

### Pose estimation

- **Relative pose**
- [Keyframe state](https://github.com/starrytank/satortho/blob/main/src/map/key_frame.cc): `src/map/key_frame.cc`
- **Absolute pose**

### Pose fusion

- [Pose fusion](https://github.com/starrytank/satortho/blob/main/src/map/geo_fuse.cc): `src/map/geo_fuse.cc`

### Map reconstruction

- [GeoMap builder](https://github.com/starrytank/satortho/blob/main/src/map/geo_map.cc): `src/map/geo_map.cc`
- [Local map](https://github.com/starrytank/satortho/blob/main/src/map/local_map.cc): `src/map/local_map.cc`
- [Georeferenced orthophoto](https://github.com/starrytank/satortho/blob/main/src/map/geo_map.cc): `src/map/geo_map.cc`

### Messaging

- [Map messaging](https://github.com/starrytank/satortho/blob/main/src/map/zmq_com.cc): `src/map/zmq_com.cc`
- [ZeroMQ transport](https://github.com/starrytank/satortho/blob/main/src/zmq/zmq_IPC.cc): `src/zmq/zmq_IPC.cc`
- [Message frames](https://github.com/starrytank/satortho/blob/main/src/zmq/zmq_frame.cc): `src/zmq/zmq_frame.cc`

### Other components

- **UAV frames**
- **Satellite maps**
- **Map consumer**

## Connections

- UAV frames → Relative pose: provides frames
- Relative pose → Keyframe state: selects keyframes
- Keyframe state → Absolute pose: matches keyframes
- Satellite maps → Absolute pose: provides prior
- Relative pose → Pose fusion: relative poses
- Absolute pose → Pose fusion: absolute observations
- Pose fusion → GeoMap builder: aligned poses
- Keyframe state → GeoMap builder: keyframe imagery
- GeoMap builder → Local map: creates regions
- Local map → Georeferenced orthophoto: updates mosaic
- Georeferenced orthophoto → Map messaging: publishes maps
- Map messaging → ZeroMQ transport: sends messages
- Map messaging → Message frames: encodes frames
- ZeroMQ transport → Map consumer: transmits maps