How stevemacenski/slam_toolbox works
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: slam_toolbox_common.cpp Common engine · online_sync_launch.py Launch/config · slam_mapper.cpp Graph mapper · PoseGraph.msg ROS API
Components 23
Runtime
ROS nodes and shared SLAM engine
- Sync node · Online synchronous SLAM entry point
src/slam_toolbox_sync_node.cpp - Async node · Online asynchronous SLAM entry point
src/slam_toolbox_async_node.cpp - Offline node · Recorded-data SLAM entry point
src/slam_toolbox_async_node.cpp - Localization node · Load-and-localize mode entry point
src/slam_toolbox_localization_node.cpp - Lifelong node · Continual mapping entry point
src/experimental/slam_toolbox_lifelong_node.cpp - Multi-robot node · Decentralized multi-robot SLAM entry point
src/slam_toolbox_decentralized_multirobot_node.cpp - Sync core · Shared synchronous graph management
src/slam_toolbox_sync.cpp - Async core · Queued asynchronous scan processing
src/slam_toolbox_async.cpp - Localization core · Localization against an existing graph
src/slam_toolbox_localization.cpp - Lifelong core · Continual mapping over a prior graph
src/experimental/slam_toolbox_lifelong.cpp - Common engine · Shared pose-graph SLAM orchestration and lifecycle
src/slam_toolbox_common.cpp - Graph mapper · Scan insertion, constraints, and optimization coordination
src/slam_mapper.cpp - Laser utils · Scan handling and TF/pose utilities
src/laser_utils.cpp - Loop closure · Loop closure discovery and assistant logic
src/loop_closure_assistant.cpp - Map saver · Occupancy-grid and graph export
src/map_saver.cpp - Merge maps · Offline or manual map composition
src/merge_maps_kinematic.cpp
Interfaces
Messages, services, and plugin contracts
- ROS API · Custom messages and services exposed to tools and external nodes
msg/PoseGraph.msg - Solver plugin · Pluggable scan-graph optimization interface
solvers/ceres_solver.cpp
Tooling
RViz, launch, configs, and map utilities
- RViz plugin · Visualization and interactive control surface
rviz_plugin/slam_toolbox_rviz_plugin.cpp - Launch/config · Mode selection, parameters, and launch wiring
launch/online_sync_launch.py - Multi-robot launch · Namespace and coordination launch for decentralized operation
launch/online_async_decentralized_multirobot_launch.py - Merge launch · Launch wrapper for manual map composition
launch/merge_maps_kinematic_launch.py
Vendor
Bundled scan-matching and graph library
- Karto SDK · Bundled scan matching and graph primitives
lib/karto_sdk/src/Karto.cpp
Connections 26
- 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