# nathanrasami/bruce-slam architecture

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

- Interactive diagram: https://gitdiagram.com/nathanrasami/bruce-slam
- Repository: https://github.com/nathanrasami/bruce-slam

## Overview

Bruce-SLAM is a ROS sonar-based SLAM system, extended for the Aracati2017 dataset with command-velocity odometry, Cartesian sonar handling, optional sonar-context and USBL methods, HoloOcean simulation, and evaluation tools. The principal workflow takes sensor data through feature extraction and graph optimization to maps and trajectories, then evaluates completed runs. Source excerpts establish several internal calls; README statements support the dataset adaptations and broader capabilities. Unsampled subsystem links are omitted where their callers are not evidenced.

Main entry points: [`bruce_slam/src/bruce_slam/slam.py`](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam.py) (Graph SLAM), [`bruce_slam/src/bruce_slam/slam_ros.py`](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam_ros.py) (SLAM ROS interface), [`bruce_slam/src/bruce_slam/utils/conversions.py`](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/conversions.py) (ROS conversions), [`bruce_slam/src/bruce_slam/mapping.py`](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/mapping.py) (Occupancy mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Dataset and Ingestion"]
  node_cmdodom["Command odometry<br/>[cmd_vel_odom.py]"]
  node_aracodom["Aracati odometry<br/>[Odom.cpp]"]
  node_aracsonar["Cartesian sonar bridge"]
end

subgraph group_estimate["SLAM Estimation"]
  node_feature["Feature extraction"]
  node_cfar["CFAR detection<br/>[CFAR.py]"]
  node_sonar["Sonar model<br/>[sonar.py]"]
  node_slamros["SLAM ROS interface<br/>[slam_ros.py]"]
  node_slam["Graph SLAM<br/>[slam.py]"]
  node_slamobjects["SLAM objects<br/>[slam_objects.py]"]
  node_brucemsg["iSAM2 messages<br/>[conversions.cpp]"]
end

subgraph group_outputs["Mapping and Output"]
  node_mappingnode["Mapping ROS node<br/>[mapping_node.py]"]
  node_mapping["Occupancy mapping<br/>[mapping.py]"]
  node_visualization["Visualization<br/>[visualization.py]"]
end

subgraph group_eval["Simulation and Evaluation"]
  node_simulation["HoloOcean simulation"]
  node_trajectoryeval["Trajectory evaluation<br/>[traj_eval.py]"]
  node_papereval["Paper evaluation<br/>[paper_eval.py]"]
  node_cloudeval["Structure cloud scoring<br/>[traj_on_cloud.py]"]
end

subgraph group_support["Shared Utilities"]
  node_topics["ROS topic names<br/>[topics.py]"]
  node_conversions["ROS conversions<br/>[conversions.py]"]
  node_io["Bag and run I/O<br/>[io.py]"]
end

node_rov(("ROV data"))

node_rov -.->|"provides commands"| node_cmdodom
node_rov -.->|"provides sensor data"| node_aracodom
node_rov -.->|"provides sonar images"| node_aracsonar
node_cmdodom -.->|"supplies odometry"| node_slamros
node_aracodom -.->|"supplies odometry"| node_slamros
node_aracsonar -.->|"supplies images"| node_feature
node_feature -.->|"runs detection"| node_cfar
node_slamros -->|"invokes"| node_slam
node_slam -->|"uses"| node_sonar
node_slam -->|"uses"| node_slamobjects
node_mappingnode -->|"runs mapping"| node_mapping
node_mapping -->|"uses sonar model"| node_sonar
node_mapping -->|"uses conversions"| node_conversions
node_slam -->|"uses conversions"| node_conversions
node_slam -->|"uses visualization"| node_visualization
node_slamros -->|"uses run I/O"| node_io
node_slamros -->|"uses visualization"| node_visualization
node_sonar -->|"converts messages"| node_conversions
node_conversions -->|"uses topic types"| node_topics
node_io -->|"uses topic names"| node_topics
node_rov -.->|"synthetic scenarios"| node_simulation
node_trajectoryeval -->|"provides metrics"| node_papereval
node_trajectoryeval -.->|"scores trajectories"| node_cloudeval
node_papereval -->|"scores map cloud"| node_cloudeval
node_slamros -.->|"exchanges graph updates"| node_brucemsg
node_slam -.->|"adds USBL factors"| node_slam

click node_cmdodom "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/cmd_vel_odom.py"
click node_aracodom "https://github.com/nathanrasami/bruce-slam/blob/main/aracati2017/src/Odom.cpp"
click node_aracsonar "https://github.com/nathanrasami/bruce-slam/blob/main/aracati2017/src/AerialImageNode.cpp"
click node_feature "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/feature_extraction.py"
click node_cfar "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/CFAR.py"
click node_sonar "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/sonar.py"
click node_slamros "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam_ros.py"
click node_slam "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam.py"
click node_slamobjects "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam_objects.py"
click node_brucemsg "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_msgs/src/bruce_msgs/conversions.cpp"
click node_mappingnode "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/scripts/mapping_node.py"
click node_mapping "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/mapping.py"
click node_visualization "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/visualization.py"
click node_topics "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/topics.py"
click node_conversions "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/conversions.py"
click node_io "https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/io.py"
click node_simulation "https://github.com/nathanrasami/bruce-slam/tree/main/offline_sim"
click node_trajectoryeval "https://github.com/nathanrasami/bruce-slam/blob/main/analysis/traj_eval.py"
click node_papereval "https://github.com/nathanrasami/bruce-slam/blob/main/analysis/paper_eval.py"
click node_cloudeval "https://github.com/nathanrasami/bruce-slam/blob/main/analysis/traj_on_cloud.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_cmdodom,node_aracodom,node_aracsonar toneBlue
class node_feature,node_cfar,node_sonar,node_slamros,node_slam,node_slamobjects,node_brucemsg toneAmber
class node_mappingnode,node_mapping,node_visualization toneMint
class node_simulation,node_trajectoryeval,node_papereval,node_cloudeval toneRose
class node_topics,node_conversions,node_io,node_rov toneIndigo
```

## Components

### Dataset and Ingestion

- [Command odometry](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/cmd_vel_odom.py): `bruce_slam/src/bruce_slam/cmd_vel_odom.py`
- [Aracati odometry](https://github.com/nathanrasami/bruce-slam/blob/main/aracati2017/src/Odom.cpp): `aracati2017/src/Odom.cpp`
- [Cartesian sonar bridge](https://github.com/nathanrasami/bruce-slam/blob/main/aracati2017/src/AerialImageNode.cpp): `aracati2017/src/AerialImageNode.cpp`

### SLAM Estimation

- [Feature extraction](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/feature_extraction.py): `bruce_slam/src/bruce_slam/feature_extraction.py`
- [CFAR detection](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/CFAR.py): `bruce_slam/src/bruce_slam/CFAR.py`
- [Sonar model](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/sonar.py): `bruce_slam/src/bruce_slam/sonar.py`
- [SLAM ROS interface](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam_ros.py): `bruce_slam/src/bruce_slam/slam_ros.py`
- [Graph SLAM](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam.py): `bruce_slam/src/bruce_slam/slam.py`
- [SLAM objects](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/slam_objects.py): `bruce_slam/src/bruce_slam/slam_objects.py`
- [iSAM2 messages](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_msgs/src/bruce_msgs/conversions.cpp): `bruce_msgs/src/bruce_msgs/conversions.cpp`

### Mapping and Output

- [Mapping ROS node](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/scripts/mapping_node.py): `bruce_slam/scripts/mapping_node.py`
- [Occupancy mapping](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/mapping.py): `bruce_slam/src/bruce_slam/mapping.py`
- [Visualization](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/visualization.py): `bruce_slam/src/bruce_slam/utils/visualization.py`

### Simulation and Evaluation

- [HoloOcean simulation](https://github.com/nathanrasami/bruce-slam/tree/main/offline_sim): `offline_sim`
- [Trajectory evaluation](https://github.com/nathanrasami/bruce-slam/blob/main/analysis/traj_eval.py): `analysis/traj_eval.py`
- [Paper evaluation](https://github.com/nathanrasami/bruce-slam/blob/main/analysis/paper_eval.py): `analysis/paper_eval.py`
- [Structure cloud scoring](https://github.com/nathanrasami/bruce-slam/blob/main/analysis/traj_on_cloud.py): `analysis/traj_on_cloud.py`

### Shared Utilities

- [ROS topic names](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/topics.py): `bruce_slam/src/bruce_slam/utils/topics.py`
- [ROS conversions](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/conversions.py): `bruce_slam/src/bruce_slam/utils/conversions.py`
- [Bag and run I/O](https://github.com/nathanrasami/bruce-slam/blob/main/bruce_slam/src/bruce_slam/utils/io.py): `bruce_slam/src/bruce_slam/utils/io.py`

### Other components

- **ROV data**

## Connections

- ROV data → Command odometry: provides commands
- ROV data → Aracati odometry: provides sensor data
- ROV data → Cartesian sonar bridge: provides sonar images
- Command odometry → SLAM ROS interface: supplies odometry
- Aracati odometry → SLAM ROS interface: supplies odometry
- Cartesian sonar bridge → Feature extraction: supplies images
- Feature extraction → CFAR detection: runs detection
- SLAM ROS interface → Graph SLAM: invokes (evidence: `bruce_slam/src/bruce_slam/slam_ros.py`)
- Graph SLAM → Sonar model: uses (evidence: `bruce_slam/src/bruce_slam/slam.py`)
- Graph SLAM → SLAM objects: uses (evidence: `bruce_slam/src/bruce_slam/slam.py`)
- Mapping ROS node → Occupancy mapping: runs mapping (evidence: `bruce_slam/scripts/mapping_node.py`)
- Occupancy mapping → Sonar model: uses sonar model (evidence: `bruce_slam/src/bruce_slam/mapping.py`)
- Occupancy mapping → ROS conversions: uses conversions (evidence: `bruce_slam/src/bruce_slam/mapping.py`)
- Graph SLAM → ROS conversions: uses conversions (evidence: `bruce_slam/src/bruce_slam/slam.py`)
- Graph SLAM → Visualization: uses visualization (evidence: `bruce_slam/src/bruce_slam/slam.py`)
- SLAM ROS interface → Bag and run I/O: uses run I/O (evidence: `bruce_slam/src/bruce_slam/slam_ros.py`)
- SLAM ROS interface → Visualization: uses visualization (evidence: `bruce_slam/src/bruce_slam/slam_ros.py`)
- Sonar model → ROS conversions: converts messages (evidence: `bruce_slam/src/bruce_slam/sonar.py`)
- ROS conversions → ROS topic names: uses topic types (evidence: `bruce_slam/src/bruce_slam/utils/conversions.py`)
- Bag and run I/O → ROS topic names: uses topic names (evidence: `bruce_slam/src/bruce_slam/utils/io.py`)
- ROV data → HoloOcean simulation: synthetic scenarios
- Trajectory evaluation → Paper evaluation: provides metrics (evidence: `analysis/paper_eval.py`)
- Trajectory evaluation → Structure cloud scoring: scores trajectories
- Paper evaluation → Structure cloud scoring: scores map cloud (evidence: `analysis/holoocean_report.py`)
- SLAM ROS interface → iSAM2 messages: exchanges graph updates
- Graph SLAM → Graph SLAM: adds USBL factors (evidence: `bruce_slam/src/bruce_slam/slam.py`)