# lemonci/coko-slam architecture

> Architecture diagram of the GitHub repository lemonci/coko-slam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lemonci/coko-slam
- Repository: https://github.com/lemonci/coko-slam

## Overview

Coko-SLAM is a multi-agent Gaussian-splatting SLAM system for reconstructing scenes and estimating camera trajectories from RGB-D datasets. The main workflow loads a configured dataset, runs per-agent tracking and mapping, coordinates submaps and loop/pose-graph optimization, and evaluates and saves results. The README also documents offline visualization. The graph preserves those major stages and the Gaussian representation; some orchestration links rely on the SOURCE INDEX or README because the relevant implementation excerpts are incomplete.

Main entry points: [`src/entities/magic_slam.py`](https://github.com/lemonci/coko-slam/blob/main/src/entities/magic_slam.py) (SLAM coordinator), [`src/entities/mapper.py`](https://github.com/lemonci/coko-slam/blob/main/src/entities/mapper.py) (Submap mapper), [`run_slam.py`](https://github.com/lemonci/coko-slam/blob/main/run_slam.py) (SLAM runner), [`src/entities/agent.py`](https://github.com/lemonci/coko-slam/blob/main/src/entities/agent.py) (Agent controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Run and data"]
  node_entry["SLAM runner<br/>[run_slam.py]"]
  node_config["Run configuration"]
  node_datasets["Dataset loaders<br/>[datasets.py]"]
end

subgraph group_agents["Agent estimation"]
  node_agent["Agent controller<br/>[agent.py]"]
  node_tracker["Pose tracker<br/>[tracker.py]"]
  node_odometer["Visual odometer<br/>[visual_odometer.py]"]
end

subgraph group_mapping["Mapping and optimization"]
  node_mapper["Submap mapper<br/>[mapper.py]"]
  node_gaussian["Gaussian model<br/>[gaussian_model.py]"]
  node_losses["Mapping losses<br/>[losses.py]"]
  node_render["Render utilities<br/>[utils.py]"]
  node_merge["Submap refinement"]
end

subgraph group_coordination["Multi-agent coordination"]
  node_loop["Loop detection<br/>[loop_detector.py]"]
  node_features["Feature extraction"]
  node_poseadapter["Pose-graph adapter"]
  node_posegraph["Pose graph"]
  node_slam["SLAM coordinator<br/>[magic_slam.py]"]
end

subgraph group_results["Evaluation and output"]
  node_eval["Map evaluation<br/>[mapping_eval.py]"]
  node_logger["Run logger<br/>[logger.py]"]
  node_io["Result I/O<br/>[io_utils.py]"]
  node_visualize["Offline visualization"]
  node_visualutils["Visualization utilities<br/>[vis_utils.py]"]
  node_results["Saved run results"]
end

node_user(("Researcher"))

node_user -->|"starts run"| node_entry
node_entry -->|"loads settings"| node_config
node_entry -->|"starts SLAM"| node_slam
node_slam -->|"loads frames"| node_datasets
node_slam -->|"runs agents"| node_agent
node_agent -->|"uses tracker"| node_tracker
node_tracker -->|"uses odometry"| node_odometer
node_agent -->|"uses mapper"| node_mapper
node_mapper -->|"updates model"| node_gaussian
node_mapper -->|"uses losses"| node_losses
node_mapper -->|"renders model"| node_render
node_gaussian -->|"render inputs"| node_render
node_slam -->|"detects loops"| node_loop
node_loop -->|"extracts features"| node_features
node_slam -->|"adapts poses"| node_poseadapter
node_slam -->|"optimizes poses"| node_posegraph
node_slam -->|"refines map"| node_merge
node_slam -->|"evaluates map"| node_eval
node_slam -->|"logs run"| node_logger
node_logger -->|"writes metrics"| node_io
node_slam -->|"saves outputs"| node_io
node_eval -->|"renders frames"| node_render
node_io -.->|"writes artifacts"| node_results
node_user -->|"views saved run"| node_visualize
node_visualize -->|"reads results"| node_results
node_visualize -->|"uses utilities"| node_visualutils

click node_entry "https://github.com/lemonci/coko-slam/blob/main/run_slam.py"
click node_config "https://github.com/lemonci/coko-slam/tree/main/configs"
click node_datasets "https://github.com/lemonci/coko-slam/blob/main/src/entities/datasets.py"
click node_agent "https://github.com/lemonci/coko-slam/blob/main/src/entities/agent.py"
click node_tracker "https://github.com/lemonci/coko-slam/blob/main/src/entities/tracker.py"
click node_odometer "https://github.com/lemonci/coko-slam/blob/main/src/entities/visual_odometer.py"
click node_mapper "https://github.com/lemonci/coko-slam/blob/main/src/entities/mapper.py"
click node_gaussian "https://github.com/lemonci/coko-slam/blob/main/src/entities/gaussian_model.py"
click node_losses "https://github.com/lemonci/coko-slam/blob/main/src/entities/losses.py"
click node_render "https://github.com/lemonci/coko-slam/blob/main/src/utils/utils.py"
click node_loop "https://github.com/lemonci/coko-slam/blob/main/src/entities/loop_detection/loop_detector.py"
click node_features "https://github.com/lemonci/coko-slam/blob/main/src/entities/loop_detection/feature_extractors.py"
click node_poseadapter "https://github.com/lemonci/coko-slam/blob/main/src/entities/pose_graph_adapter.py"
click node_posegraph "https://github.com/lemonci/coko-slam/blob/main/src/entities/gtsam_pose_graph.py"
click node_slam "https://github.com/lemonci/coko-slam/blob/main/src/entities/magic_slam.py"
click node_merge "https://github.com/lemonci/coko-slam/blob/main/src/utils/magic_slam_utils.py"
click node_eval "https://github.com/lemonci/coko-slam/blob/main/src/utils/mapping_eval.py"
click node_logger "https://github.com/lemonci/coko-slam/blob/main/src/entities/logger.py"
click node_io "https://github.com/lemonci/coko-slam/blob/main/src/utils/io_utils.py"
click node_visualize "https://github.com/lemonci/coko-slam/blob/main/run_visualization.py"
click node_visualutils "https://github.com/lemonci/coko-slam/blob/main/src/utils/vis_utils.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_entry,node_config,node_datasets toneBlue
class node_agent,node_tracker,node_odometer toneAmber
class node_mapper,node_gaussian,node_losses,node_render,node_merge toneMint
class node_loop,node_features,node_poseadapter,node_posegraph,node_slam toneRose
class node_eval,node_logger,node_io,node_visualize,node_visualutils,node_results,node_user toneIndigo
```

## Components

### Run and data

- [SLAM runner](https://github.com/lemonci/coko-slam/blob/main/run_slam.py): `run_slam.py`
- [Run configuration](https://github.com/lemonci/coko-slam/tree/main/configs): `configs`
- [Dataset loaders](https://github.com/lemonci/coko-slam/blob/main/src/entities/datasets.py): `src/entities/datasets.py`

### Agent estimation

- [Agent controller](https://github.com/lemonci/coko-slam/blob/main/src/entities/agent.py): `src/entities/agent.py`
- [Pose tracker](https://github.com/lemonci/coko-slam/blob/main/src/entities/tracker.py): `src/entities/tracker.py`
- [Visual odometer](https://github.com/lemonci/coko-slam/blob/main/src/entities/visual_odometer.py): `src/entities/visual_odometer.py`

### Mapping and optimization

- [Submap mapper](https://github.com/lemonci/coko-slam/blob/main/src/entities/mapper.py): `src/entities/mapper.py`
- [Gaussian model](https://github.com/lemonci/coko-slam/blob/main/src/entities/gaussian_model.py): `src/entities/gaussian_model.py`
- [Mapping losses](https://github.com/lemonci/coko-slam/blob/main/src/entities/losses.py): `src/entities/losses.py`
- [Render utilities](https://github.com/lemonci/coko-slam/blob/main/src/utils/utils.py): `src/utils/utils.py`
- [Submap refinement](https://github.com/lemonci/coko-slam/blob/main/src/utils/magic_slam_utils.py): `src/utils/magic_slam_utils.py`

### Multi-agent coordination

- [Loop detection](https://github.com/lemonci/coko-slam/blob/main/src/entities/loop_detection/loop_detector.py): `src/entities/loop_detection/loop_detector.py`
- [Feature extraction](https://github.com/lemonci/coko-slam/blob/main/src/entities/loop_detection/feature_extractors.py): `src/entities/loop_detection/feature_extractors.py`
- [Pose-graph adapter](https://github.com/lemonci/coko-slam/blob/main/src/entities/pose_graph_adapter.py): `src/entities/pose_graph_adapter.py`
- [Pose graph](https://github.com/lemonci/coko-slam/blob/main/src/entities/gtsam_pose_graph.py): `src/entities/gtsam_pose_graph.py`
- [SLAM coordinator](https://github.com/lemonci/coko-slam/blob/main/src/entities/magic_slam.py): `src/entities/magic_slam.py`

### Evaluation and output

- [Map evaluation](https://github.com/lemonci/coko-slam/blob/main/src/utils/mapping_eval.py): `src/utils/mapping_eval.py`
- [Run logger](https://github.com/lemonci/coko-slam/blob/main/src/entities/logger.py): `src/entities/logger.py`
- [Result I/O](https://github.com/lemonci/coko-slam/blob/main/src/utils/io_utils.py): `src/utils/io_utils.py`
- [Offline visualization](https://github.com/lemonci/coko-slam/blob/main/run_visualization.py): `run_visualization.py`
- [Visualization utilities](https://github.com/lemonci/coko-slam/blob/main/src/utils/vis_utils.py): `src/utils/vis_utils.py`
- **Saved run results**

### Other components

- **Researcher**

## Connections

- Researcher → SLAM runner: starts run (evidence: `README.md`)
- SLAM runner → Run configuration: loads settings (evidence: `README.md`)
- SLAM runner → SLAM coordinator: starts SLAM (evidence: `run_slam.py`)
- SLAM coordinator → Dataset loaders: loads frames (evidence: `src/entities/magic_slam.py`)
- SLAM coordinator → Agent controller: runs agents (evidence: `src/entities/magic_slam.py`)
- Agent controller → Pose tracker: uses tracker (evidence: `src/entities/agent.py`)
- Pose tracker → Visual odometer: uses odometry (evidence: `src/entities/tracker.py`)
- Agent controller → Submap mapper: uses mapper (evidence: `src/entities/agent.py`)
- Submap mapper → Gaussian model: updates model (evidence: `src/entities/mapper.py`)
- Submap mapper → Mapping losses: uses losses (evidence: `src/entities/mapper.py`)
- Submap mapper → Render utilities: renders model (evidence: `src/entities/mapper.py`)
- Gaussian model → Render utilities: render inputs (evidence: `src/utils/utils.py`)
- SLAM coordinator → Loop detection: detects loops (evidence: `src/entities/magic_slam.py`)
- Loop detection → Feature extraction: extracts features (evidence: `src/entities/loop_detection/loop_detector.py`)
- SLAM coordinator → Pose-graph adapter: adapts poses (evidence: `src/entities/magic_slam.py`)
- SLAM coordinator → Pose graph: optimizes poses (evidence: `src/entities/magic_slam.py`)
- SLAM coordinator → Submap refinement: refines map (evidence: `src/entities/magic_slam.py`)
- SLAM coordinator → Map evaluation: evaluates map (evidence: `src/entities/magic_slam.py`)
- SLAM coordinator → Run logger: logs run (evidence: `src/entities/magic_slam.py`)
- Run logger → Result I/O: writes metrics (evidence: `src/entities/logger.py`)
- SLAM coordinator → Result I/O: saves outputs (evidence: `src/entities/magic_slam.py`)
- Map evaluation → Render utilities: renders frames (evidence: `src/utils/mapping_eval.py`)
- Result I/O → Saved run results: writes artifacts
- Researcher → Offline visualization: views saved run (evidence: `README.md`)
- Offline visualization → Saved run results: reads results (evidence: `README.md`)
- Offline visualization → Visualization utilities: uses utilities (evidence: `run_visualization.py`)
