# stevemacenski/slam_toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/stevemacenski/slam_toolbox
- Repository: https://github.com/stevemacenski/slam_toolbox

## Overview

1. **Repository purpose and shape**  
   This is a ROS 2 package for 2D SLAM, localization, and pose-graph map management. It is not a single app: it ships multiple ROS nodes, RViz tooling, custom messages/services, solver plugins, and a vendored scan-matching/graph library under `lib/karto_sdk`.

2. **Core runtime boundary: the SLAM toolbox node family**  
   The main runtime entry points live in `src/*_node.cpp` and map to distinct operating modes:
   - `online_sync`
   - `online_async`
   - `offline`
   - `localization`
   - `lifelong`
   - `decentralized_multirobot`
   - experimental map-and-localization variants  
   These nodes are thin launch/runtime wrappers around the shared logic in the corresponding classes under `include/slam_toolbox/` and `src/`.

3. **Shared SLAM engine and pose-graph pipeline**  
   The common subsystem is the pose-graph SLAM engine: laser scans plus TF/odometry are converted into `PosedScan`-style inputs, queued, scan-matched, added as graph nodes/edges, and optimized when loop closures are found. This core behavior is centralized in `slam_toolbox_common`, `slam_mapper`, `laser_utils`, and the mode-specific classes for sync/async/localization/lifelong operation.

4. **Data flow from robot sensors to map output**  
   The primary data path is:
   - subscribe to `/scan`
   - look up `tf` between `odom_frame`, `base_frame`, and `map_frame`
   - create/update pose-graph nodes and constraints
   - optimize the graph
   - publish `map` as `nav_msgs/OccupancyGrid`
   - publish `pose` as `geometry_msgs/PoseWithCovarianceStamped`
   - publish `map -> odom` transform periodically  
   In async mode the queue is designed to absorb lag; in sync mode scan throttling and queueing are more explicit.

5. **Graph persistence and lossless map state**  
   A major architectural feature is serialization/deserialization of the full pose graph, not just an occupancy map. Services such as `SerializePoseGraph`, `DeserializePoseGraph`, and `SaveMap` support saving either the lossless graph state for continued SLAM/localization or a raster map for external consumers like AMCL-style workflows. This is the boundary that enables lifelong mapping and offline refinement.

6. **Loop closure, manual correction, and graph manipulation**  
   Loop closure is part of the core graph optimizer, but the system also exposes manual intervention. Custom services like `LoopClosure`, `ToggleInteractive`, `Clear`, and `Reset` let a user or RViz plugin trigger corrections, move nodes interactively, clear pending changes, and re-run optimization. This is a distinct control/diagnostics subsystem layered on top of the SLAM graph.

7. **Optimization backend as a plugin boundary**  
   Solver selection is abstracted behind a plugin interface (`ScanSolver`). Concrete implementations live in `solvers/` and are loaded via plugin metadata (`solver_plugins.xml`). The repo supports Ceres as the primary optimizer, with optional G2O/GTSAM/SPA-related support depending on build configuration. CMake find modules for SuiteSparse, CHOLMOD, CSparse, MKL, G2O, and GTSAM show that solver backends are optional external dependencies rather than hardwired code paths.

8. **Mode-specific subsystems**  
   - **Localization mode**: loads an existing serialized pose graph and maintains a rolling buffer of scans for local pose refinement without permanently changing the map.  
   - **Lifelong mode**: continues mapping from a prior graph, allowing updates over time and optional pruning/experimental node decay.  
   - **Offline mode**: processes recorded scans and TF data rather than live robot input.  
   These modes share the same underlying graph machinery but differ in queueing, persistence, and whether the graph is allowed to grow indefinitely.

9. **Multi-robot and map-merging path**  
   `slam_toolbox_decentralized_multirobot` extends the single-robot graph model to a shared global frame across namespaces. Each robot runs its own instance, exchanges localized scans/graph data, and aligns pose graphs collaboratively. Separately, `merge_maps_kinematic` supports manual composition of multiple serialized maps into one global map. These are related but distinct: one is decentralized online coordination, the other is offline/manual fusion.

10. **RViz plugin as the operator interface**  
   `rviz_plugin/` provides a user-facing control surface for the toolbox. It is not the SLAM engine itself; it invokes services, toggles interactive mode, displays nodes/edges, and supports manual map alignment and map generation. Architecturally, RViz is the operator/visualization boundary for the underlying graph state and control services.

11. **ROS interface contracts**  
   The package defines custom messages for incremental graph publication (`NewNodeEvent`, `LoopClosureEvent`, `PoseGraph`, `GraphNode`, `GraphEdge`, `LocalizedLaserScan`) and services for lifecycle/control operations (`SaveMap`, `SerializePoseGraph`, `DeserializePoseGraph`, `Pause`, `Reset`, `MergeMaps`, etc.). These interfaces are the integration surface for external tools, RViz, and higher-level navigation stacks.

12. **Vendored scanning/math subsystem**  
   `lib/karto_sdk/` is a bundled dependency providing the scan matching and graph primitives that the toolbox builds on. This is an important architectural boundary: the SLAM toolbox layers ROS 2 behavior, persistence, and tooling around a modified Karto core rather than implementing the scan matcher from scratch.

13. **Configuration and launch topology**  
   Runtime behavior is driven by YAML configs under `config/` and mode-specific launch files under `launch/`. The configs are mostly about frames, queueing, scan-matching thresholds, optimizer choice, and occupancy-grid settings; the launch files select the node variant and wiring appropriate to each operational mode.

14. **Testing and metrics artifacts**  
   The test directory contains graph-processing metrics and a known constraints dataset, indicating the project includes some algorithm-level validation rather than only integration tests. This supports the idea that optimization/graph behavior is a first-class part of the architecture, not just a side effect of ROS messaging.

Main entry points: [`src/slam_toolbox_common.cpp`](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_common.cpp) (Common engine), [`launch/online_sync_launch.py`](https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/online_sync_launch.py) (Launch/config), [`src/slam_mapper.cpp`](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_mapper.cpp) (Graph mapper), [`msg/PoseGraph.msg`](https://github.com/stevemacenski/slam_toolbox/blob/ros2/msg/PoseGraph.msg) (ROS API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_sync_node["Sync node<br/>ROS2 node"]
  node_async_node["Async node<br/>ROS2 node"]
  node_offline_node["Offline node<br/>ROS2 node"]
  node_localization_node["Localization node<br/>ROS2 node"]
  node_lifelong_node["Lifelong node<br/>ROS2 node"]
  node_multirobot_node["Multi-robot node<br/>ROS2 node"]
  node_sync_core["Sync core<br/>SLAM mode"]
  node_async_core["Async core<br/>SLAM mode"]
  node_localization_core["Localization core<br/>SLAM mode"]
  node_lifelong_core["Lifelong core<br/>SLAM mode"]
  node_common_engine["Common engine<br/>SLAM core"]
  node_slam_mapper["Graph mapper<br/>Graph pipeline<br/>[slam_mapper.cpp]"]
  node_laser_utils["Laser utils<br/>Sensor prep<br/>[laser_utils.cpp]"]
  node_loop_closure["Loop closure<br/>Graph control"]
  node_map_saver["Map saver<br/>Persistence<br/>[map_saver.cpp]"]
  node_merge_maps["Merge maps<br/>Map fusion"]
end

subgraph group_interfaces["Interfaces"]
  node_msg_api["ROS API<br/>Msg/srv contract<br/>[PoseGraph.msg]"]
  node_solver_plugin["Solver plugin<br/>Optimization backend<br/>[ceres_solver.cpp]"]
end

subgraph group_tooling["Tooling"]
  node_rviz_plugin["RViz plugin<br/>Operator UI"]
  node_launch_config["Launch/config<br/>Runtime setup"]
  node_multirobot_launch["Multi-robot launch<br/>Runtime setup"]
  node_merge_launch["Merge launch<br/>Runtime setup"]
end

subgraph group_vendor["Vendor"]
  node_karto_sdk["Karto SDK<br/>Vendored library<br/>[Karto.cpp]"]
end

node_sync_node -->|"runs"| node_sync_core
node_async_node -->|"runs"| node_async_core
node_offline_node -->|"reuses"| node_async_core
node_localization_node -->|"runs"| node_localization_core
node_lifelong_node -->|"runs"| node_lifelong_core
node_multirobot_node -->|"extends"| node_common_engine
node_sync_core -->|"shares"| node_common_engine
node_async_core -->|"shares"| node_common_engine
node_localization_core -->|"shares"| node_common_engine
node_lifelong_core -->|"shares"| node_common_engine
node_common_engine -->|"coordinates"| node_slam_mapper
node_common_engine -->|"uses"| node_laser_utils
node_slam_mapper -->|"triggers"| node_loop_closure
node_slam_mapper -->|"optimizes with"| node_solver_plugin
node_slam_mapper -->|"built on"| node_karto_sdk
node_loop_closure -->|"publishes"| node_msg_api
node_map_saver -->|"serializes"| node_msg_api
node_merge_maps -->|"consumes"| node_msg_api
node_rviz_plugin -->|"controls"| node_msg_api
node_rviz_plugin -->|"invokes"| node_loop_closure
node_launch_config -->|"launches"| node_sync_node
node_launch_config -->|"launches"| node_async_node
node_launch_config -->|"launches"| node_localization_node
node_launch_config -->|"launches"| node_lifelong_node
node_multirobot_launch -->|"launches"| node_multirobot_node
node_merge_launch -->|"launches"| node_merge_maps

click node_sync_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_sync_node.cpp"
click node_async_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async_node.cpp"
click node_offline_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async_node.cpp"
click node_localization_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_localization_node.cpp"
click node_lifelong_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/experimental/slam_toolbox_lifelong_node.cpp"
click node_multirobot_node "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_decentralized_multirobot_node.cpp"
click node_sync_core "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_sync.cpp"
click node_async_core "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async.cpp"
click node_localization_core "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_localization.cpp"
click node_lifelong_core "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/experimental/slam_toolbox_lifelong.cpp"
click node_common_engine "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_common.cpp"
click node_slam_mapper "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_mapper.cpp"
click node_laser_utils "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/laser_utils.cpp"
click node_loop_closure "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/loop_closure_assistant.cpp"
click node_map_saver "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/map_saver.cpp"
click node_merge_maps "https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/merge_maps_kinematic.cpp"
click node_rviz_plugin "https://github.com/stevemacenski/slam_toolbox/blob/ros2/rviz_plugin/slam_toolbox_rviz_plugin.cpp"
click node_msg_api "https://github.com/stevemacenski/slam_toolbox/blob/ros2/msg/PoseGraph.msg"
click node_solver_plugin "https://github.com/stevemacenski/slam_toolbox/blob/ros2/solvers/ceres_solver.cpp"
click node_karto_sdk "https://github.com/stevemacenski/slam_toolbox/blob/ros2/lib/karto_sdk/src/Karto.cpp"
click node_launch_config "https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/online_sync_launch.py"
click node_multirobot_launch "https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/online_async_decentralized_multirobot_launch.py"
click node_merge_launch "https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/merge_maps_kinematic_launch.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_sync_node,node_async_node,node_offline_node,node_localization_node,node_lifelong_node,node_multirobot_node,node_sync_core,node_async_core,node_localization_core,node_lifelong_core,node_common_engine,node_slam_mapper,node_laser_utils,node_loop_closure,node_map_saver,node_merge_maps toneBlue
class node_msg_api,node_solver_plugin toneAmber
class node_rviz_plugin,node_launch_config,node_multirobot_launch,node_merge_launch toneMint
class node_karto_sdk toneRose
```

## Components

### Runtime

ROS nodes and shared SLAM engine

- [Sync node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_sync_node.cpp): ROS2 node · Online synchronous SLAM entry point · `src/slam_toolbox_sync_node.cpp`
- [Async node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async_node.cpp): ROS2 node · Online asynchronous SLAM entry point · `src/slam_toolbox_async_node.cpp`
- [Offline node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async_node.cpp): ROS2 node · Recorded-data SLAM entry point · `src/slam_toolbox_async_node.cpp`
- [Localization node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_localization_node.cpp): ROS2 node · Load-and-localize mode entry point · `src/slam_toolbox_localization_node.cpp`
- [Lifelong node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/experimental/slam_toolbox_lifelong_node.cpp): ROS2 node · Continual mapping entry point · `src/experimental/slam_toolbox_lifelong_node.cpp`
- [Multi-robot node](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_decentralized_multirobot_node.cpp): ROS2 node · Decentralized multi-robot SLAM entry point · `src/slam_toolbox_decentralized_multirobot_node.cpp`
- [Sync core](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_sync.cpp): SLAM mode · Shared synchronous graph management · `src/slam_toolbox_sync.cpp`
- [Async core](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_async.cpp): SLAM mode · Queued asynchronous scan processing · `src/slam_toolbox_async.cpp`
- [Localization core](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_localization.cpp): SLAM mode · Localization against an existing graph · `src/slam_toolbox_localization.cpp`
- [Lifelong core](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/experimental/slam_toolbox_lifelong.cpp): SLAM mode · Continual mapping over a prior graph · `src/experimental/slam_toolbox_lifelong.cpp`
- [Common engine](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_toolbox_common.cpp): SLAM core · Shared pose-graph SLAM orchestration and lifecycle · `src/slam_toolbox_common.cpp`
- [Graph mapper](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/slam_mapper.cpp): Graph pipeline · Scan insertion, constraints, and optimization coordination · `src/slam_mapper.cpp`
- [Laser utils](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/laser_utils.cpp): Sensor prep · Scan handling and TF/pose utilities · `src/laser_utils.cpp`
- [Loop closure](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/loop_closure_assistant.cpp): Graph control · Loop closure discovery and assistant logic · `src/loop_closure_assistant.cpp`
- [Map saver](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/map_saver.cpp): Persistence · Occupancy-grid and graph export · `src/map_saver.cpp`
- [Merge maps](https://github.com/stevemacenski/slam_toolbox/blob/ros2/src/merge_maps_kinematic.cpp): Map fusion · Offline or manual map composition · `src/merge_maps_kinematic.cpp`

### Interfaces

Messages, services, and plugin contracts

- [ROS API](https://github.com/stevemacenski/slam_toolbox/blob/ros2/msg/PoseGraph.msg): Msg/srv contract · Custom messages and services exposed to tools and external nodes · `msg/PoseGraph.msg`
- [Solver plugin](https://github.com/stevemacenski/slam_toolbox/blob/ros2/solvers/ceres_solver.cpp): Optimization backend · Pluggable scan-graph optimization interface · `solvers/ceres_solver.cpp`

### Tooling

RViz, launch, configs, and map utilities

- [RViz plugin](https://github.com/stevemacenski/slam_toolbox/blob/ros2/rviz_plugin/slam_toolbox_rviz_plugin.cpp): Operator UI · Visualization and interactive control surface · `rviz_plugin/slam_toolbox_rviz_plugin.cpp`
- [Launch/config](https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/online_sync_launch.py): Runtime setup · Mode selection, parameters, and launch wiring · `launch/online_sync_launch.py`
- [Multi-robot launch](https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/online_async_decentralized_multirobot_launch.py): Runtime setup · Namespace and coordination launch for decentralized operation · `launch/online_async_decentralized_multirobot_launch.py`
- [Merge launch](https://github.com/stevemacenski/slam_toolbox/blob/ros2/launch/merge_maps_kinematic_launch.py): Runtime setup · Launch wrapper for manual map composition · `launch/merge_maps_kinematic_launch.py`

### Vendor

Bundled scan-matching and graph library

- [Karto SDK](https://github.com/stevemacenski/slam_toolbox/blob/ros2/lib/karto_sdk/src/Karto.cpp): Vendored library · Bundled scan matching and graph primitives · `lib/karto_sdk/src/Karto.cpp`

## Connections

- Sync node → Sync core: runs
- Async node → Async core: runs
- Offline node → Async core: reuses
- Localization node → Localization core: runs
- Lifelong node → Lifelong core: runs
- Multi-robot node → Common engine: extends
- Sync core → Common engine: shares
- Async core → Common engine: shares
- Localization core → Common engine: shares
- Lifelong core → Common engine: shares
- Common engine → Graph mapper: coordinates
- Common engine → Laser utils: uses
- Graph mapper → Loop closure: triggers
- Graph mapper → Solver plugin: optimizes with
- Graph mapper → Karto SDK: built on
- Loop closure → ROS API: publishes
- Map saver → ROS API: serializes
- Merge maps → ROS API: consumes
- RViz plugin → ROS API: controls
- RViz plugin → Loop closure: invokes
- Launch/config → Sync node: launches
- Launch/config → Async node: launches
- Launch/config → Localization node: launches
- Launch/config → Lifelong node: launches
- Multi-robot launch → Multi-robot node: launches
- Merge launch → Merge maps: launches
