# senseroboticslab/aqua-slam architecture

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

## Overview

AQUA-SLAM combines stereo vision, IMU, and DVL measurements for underwater pose estimation and mapping. Its main workflow is ROS sensor input, frame tracking and initialization, local map construction and sensor fusion, then loop closure and visualization. The README also documents sensor extrinsic calibration, optional loop detection, and environmental reconstruction. Sampled source confirms vocabulary-based place recognition, graph optimization, camera projection, and DVL calibration; wiring for other subsystems is inferred only where the documented product workflow supports it.

Main entry points: [`src/System.cc`](https://github.com/senseroboticslab/aqua-slam/blob/main/src/System.cc) (SLAM System), [`src/Tracking.cc`](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Tracking.cc) (Frame Tracking), [`src/Optimizer.cc`](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Optimizer.cc) (Graph Optimizer), [`src/LocalMapping.cc`](https://github.com/senseroboticslab/aqua-slam/blob/main/src/LocalMapping.cc) (Local Mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest_track["Sensor Ingestion & Tracking"]
  node_ros_adapter["ROS Sensor Adapter<br/>[RosHandling.cpp]"]
  node_ros_entry["ROS SLAM Node"]
  node_system["SLAM System<br/>[System.cc]"]
  node_tracking["Frame Tracking<br/>[Tracking.cc]"]
  node_frame["Frame &amp; Features<br/>[Frame.cc]"]
  node_extractor["ORB Extraction<br/>[ORBextractor.cc]"]
  node_camera["Camera Models<br/>[KannalaBrandt8.cpp]"]
  node_initializer["Visual Initialization<br/>[Initializer.cc]"]
end

subgraph group_mapping_fusion["Mapping &amp; Sensor Fusion"]
  node_local_mapping["Local Mapping<br/>[LocalMapping.cc]"]
  node_atlas["Map Atlas<br/>[Atlas.cc]"]
  node_map["Map &amp; Points<br/>[Map.cc]"]
  node_dvl_imu["DVL-IMU Fusion"]
  node_dvl_optimizer["DVL-Gyro Calibration"]
end

subgraph group_recognition["Recognition &amp; Optimization"]
  node_optimizer["Graph Optimizer<br/>[Optimizer.cc]"]
  node_loop_closing["Loop Closing<br/>[LoopClosing.cc]"]
  node_keyframe_db["Keyframe Database"]
  node_vocabulary["Place Vocabulary"]
end

subgraph group_outputs["Mapping &amp; Visualization"]
  node_dense_mapper["Dense Reconstruction<br/>[DenseMapper.cpp]"]
  node_octomap["Occupancy Mapping"]
  node_viewer["SLAM Viewer<br/>[Viewer.cc]"]
end

node_sensors(("Stereo, IMU, DVL"))
node_ros_output(("ROS / RViz"))

node_sensors -->|"publish measurements"| node_ros_adapter
node_ros_entry -->|"subscribe to data"| node_ros_adapter
node_ros_entry -->|"start SLAM"| node_system
node_ros_adapter -->|"deliver sensor data"| node_system
node_system -->|"track input"| node_tracking
node_tracking -->|"construct frames"| node_frame
node_frame -->|"extract features"| node_extractor
node_tracking -->|"project observations"| node_camera
node_tracking -->|"initialize map"| node_initializer
node_tracking -->|"submit keyframes"| node_local_mapping
node_local_mapping -->|"update map"| node_map
node_system -->|"manage maps"| node_atlas
node_tracking -->|"integrate measurements"| node_dvl_imu
node_dvl_imu -->|"provide constraints"| node_optimizer
node_dvl_optimizer -->|"calibrate constraints"| node_optimizer
node_local_mapping -->|"optimize map"| node_optimizer
node_system -->|"coordinate loop detection"| node_loop_closing
node_loop_closing -->|"query candidates"| node_keyframe_db
node_keyframe_db -->|"score visual words"| node_vocabulary
node_loop_closing -->|"correct map"| node_optimizer
node_dense_mapper -->|"update occupancy map"| node_octomap
node_system -->|"provide map data"| node_dense_mapper
node_system -->|"publish visualization state"| node_viewer
node_viewer -->|"display results"| node_ros_output
node_system -->|"publish SLAM output"| node_ros_output

click node_ros_adapter "https://github.com/senseroboticslab/aqua-slam/blob/main/src/RosHandling.cpp"
click node_ros_entry "https://github.com/senseroboticslab/aqua-slam/blob/main/src/ros_stereo_DVL_tighly.cc"
click node_system "https://github.com/senseroboticslab/aqua-slam/blob/main/src/System.cc"
click node_tracking "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Tracking.cc"
click node_frame "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Frame.cc"
click node_extractor "https://github.com/senseroboticslab/aqua-slam/blob/main/src/ORBextractor.cc"
click node_camera "https://github.com/senseroboticslab/aqua-slam/blob/main/src/CameraModels/KannalaBrandt8.cpp"
click node_initializer "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Initializer.cc"
click node_local_mapping "https://github.com/senseroboticslab/aqua-slam/blob/main/src/LocalMapping.cc"
click node_atlas "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Atlas.cc"
click node_map "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Map.cc"
click node_dvl_imu "https://github.com/senseroboticslab/aqua-slam/blob/main/src/DVLGroPreIntegration.cpp"
click node_dvl_optimizer "https://github.com/senseroboticslab/aqua-slam/blob/main/src/DvlGyroOptimizer.cpp"
click node_optimizer "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Optimizer.cc"
click node_loop_closing "https://github.com/senseroboticslab/aqua-slam/blob/main/src/LoopClosing.cc"
click node_keyframe_db "https://github.com/senseroboticslab/aqua-slam/blob/main/src/KeyFrameDatabase.cc"
click node_vocabulary "https://github.com/senseroboticslab/aqua-slam/blob/main/Thirdparty/DBoW2/DBoW2/TemplatedVocabulary.h"
click node_dense_mapper "https://github.com/senseroboticslab/aqua-slam/blob/main/src/DenseMapper.cpp"
click node_octomap "https://github.com/senseroboticslab/aqua-slam/blob/main/Thirdparty/octomap/include/octomap/OccupancyOcTreeBase.h"
click node_viewer "https://github.com/senseroboticslab/aqua-slam/blob/main/src/Viewer.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_ros_adapter,node_ros_entry,node_system,node_tracking,node_frame,node_extractor,node_camera,node_initializer toneBlue
class node_local_mapping,node_atlas,node_map,node_dvl_imu,node_dvl_optimizer toneAmber
class node_optimizer,node_loop_closing,node_keyframe_db,node_vocabulary toneMint
class node_dense_mapper,node_octomap,node_viewer toneRose
class node_sensors,node_ros_output toneIndigo
```

## Components

### Sensor Ingestion & Tracking

- [ROS Sensor Adapter](https://github.com/senseroboticslab/aqua-slam/blob/main/src/RosHandling.cpp): `src/RosHandling.cpp`
- [ROS SLAM Node](https://github.com/senseroboticslab/aqua-slam/blob/main/src/ros_stereo_DVL_tighly.cc): `src/ros_stereo_DVL_tighly.cc`
- [SLAM System](https://github.com/senseroboticslab/aqua-slam/blob/main/src/System.cc): `src/System.cc`
- [Frame Tracking](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Tracking.cc): `src/Tracking.cc`
- [Frame & Features](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Frame.cc): `src/Frame.cc`
- [ORB Extraction](https://github.com/senseroboticslab/aqua-slam/blob/main/src/ORBextractor.cc): `src/ORBextractor.cc`
- [Camera Models](https://github.com/senseroboticslab/aqua-slam/blob/main/src/CameraModels/KannalaBrandt8.cpp): `src/CameraModels/KannalaBrandt8.cpp`
- [Visual Initialization](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Initializer.cc): `src/Initializer.cc`

### Mapping & Sensor Fusion

- [Local Mapping](https://github.com/senseroboticslab/aqua-slam/blob/main/src/LocalMapping.cc): `src/LocalMapping.cc`
- [Map Atlas](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Atlas.cc): `src/Atlas.cc`
- [Map & Points](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Map.cc): `src/Map.cc`
- [DVL-IMU Fusion](https://github.com/senseroboticslab/aqua-slam/blob/main/src/DVLGroPreIntegration.cpp): `src/DVLGroPreIntegration.cpp`
- [DVL-Gyro Calibration](https://github.com/senseroboticslab/aqua-slam/blob/main/src/DvlGyroOptimizer.cpp): `src/DvlGyroOptimizer.cpp`

### Recognition & Optimization

- [Graph Optimizer](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Optimizer.cc): `src/Optimizer.cc`
- [Loop Closing](https://github.com/senseroboticslab/aqua-slam/blob/main/src/LoopClosing.cc): `src/LoopClosing.cc`
- [Keyframe Database](https://github.com/senseroboticslab/aqua-slam/blob/main/src/KeyFrameDatabase.cc): `src/KeyFrameDatabase.cc`
- [Place Vocabulary](https://github.com/senseroboticslab/aqua-slam/blob/main/Thirdparty/DBoW2/DBoW2/TemplatedVocabulary.h): `Thirdparty/DBoW2/DBoW2/TemplatedVocabulary.h`

### Mapping & Visualization

- [Dense Reconstruction](https://github.com/senseroboticslab/aqua-slam/blob/main/src/DenseMapper.cpp): `src/DenseMapper.cpp`
- [Occupancy Mapping](https://github.com/senseroboticslab/aqua-slam/blob/main/Thirdparty/octomap/include/octomap/OccupancyOcTreeBase.h): `Thirdparty/octomap/include/octomap/OccupancyOcTreeBase.h`
- [SLAM Viewer](https://github.com/senseroboticslab/aqua-slam/blob/main/src/Viewer.cc): `src/Viewer.cc`

### Other components

- **Stereo, IMU, DVL**
- **ROS / RViz**

## Connections

- Stereo, IMU, DVL → ROS Sensor Adapter: publish measurements
- ROS SLAM Node → ROS Sensor Adapter: subscribe to data
- ROS SLAM Node → SLAM System: start SLAM
- ROS Sensor Adapter → SLAM System: deliver sensor data
- SLAM System → Frame Tracking: track input
- Frame Tracking → Frame & Features: construct frames
- Frame & Features → ORB Extraction: extract features
- Frame Tracking → Camera Models: project observations
- Frame Tracking → Visual Initialization: initialize map
- Frame Tracking → Local Mapping: submit keyframes
- Local Mapping → Map & Points: update map
- SLAM System → Map Atlas: manage maps
- Frame Tracking → DVL-IMU Fusion: integrate measurements
- DVL-IMU Fusion → Graph Optimizer: provide constraints
- DVL-Gyro Calibration → Graph Optimizer: calibrate constraints
- Local Mapping → Graph Optimizer: optimize map
- SLAM System → Loop Closing: coordinate loop detection
- Loop Closing → Keyframe Database: query candidates
- Keyframe Database → Place Vocabulary: score visual words
- Loop Closing → Graph Optimizer: correct map
- Dense Reconstruction → Occupancy Mapping: update occupancy map
- SLAM System → Dense Reconstruction: provide map data
- SLAM System → SLAM Viewer: publish visualization state
- SLAM Viewer → ROS / RViz: display results
- SLAM System → ROS / RViz: publish SLAM output