# snt-arg/semantic_orb_slam3_ros architecture

> Architecture diagram of the GitHub repository snt-arg/semantic_orb_slam3_ros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snt-arg/semantic_orb_slam3_ros
- Repository: https://github.com/snt-arg/semantic_orb_slam3_ros

## Overview

##### Project Type and Purpose
- This is a robotics/SLAM system: a ROS wrapper around the C++ ORB-SLAM3 library, extended with semantics (doors, walls, rooms, markers) for map augmentation and hierarchical visualization.
- It uses ROS1 (catkin), C++ for core SLAM, Python for evaluation scripts, and config files for multiple sensor/dataset modes.

##### File-Structure Analysis
- Top-level artifacts:
- CMakeLists.txt, package.xml – build and ROS metadata
- Dockerfile – containerized ROS Noetic + RealSense
- Dependencies.md – lists third-party libraries
- LICENSE, README.md
- Directories:
- orb_slam3/… – upstream ORB-SLAM3 core sources, third-party libs (DBoW2, g2o, Sophus, nlohmann/json) and vocabulary file
- src/… – ROS node wrappers (ros_mono, ros_rgbd, ros_stereo, ros_*_inertial), AR viewer code, common utilities
- /… – headers for shared utilities
- config/… – YAML camera calibration and dataset parameters, RViz scenes
- launch/… – ROS launch files per sensor/dataset mode
- evaluation/… – Python scripts to generate pose files and compute ATE
- doc/… – sample launch snippets and instructions
- srv/SaveMap.srv – custom ROS service definition

##### Key Components and Interactions
a. Sensors & Preprocessing
- Physical sensors (RealSense, stereo cameras, IMU)
- External driver nodes:
- realsense2_camera (image, depth, IMU topics)
- aruco_ros marker publisher (/aruco_marker_publisher/markers)
- Output ROS topics: /camera/…, /imu, /aruco_marker_publisher/markers
b. SLAM & Semantic Processing
- orb_slam3_ros node (C++ executable): subscribes to sensor topics, invokes ORB-SLAM3 core (orb_slam3/System.cc, Tracking, LocalMapping, LoopClosing, Viewer)
- Semantic module integrated in Tracking/System: publishes walls, doors, rooms, fiducial markers on topics (/orb_slam3/walls, /orb_slam3/doors, /orb_slam3/rooms, /orb_slam3/fiducial_markers)
- Pangolin viewer (optional) renders real-time map/keyframes
c. Storage & Services
- Persistence via System.SaveAtlasToFile & SaveMap.srv
- Trajectory saving via SaveTrajectory service
d. Visualization & Evaluation
- evaluation scripts subscribe to bag files and stored pose txt for offline ATE scale evaluation

##### Architectural Patterns & Principles
- Layered architecture: Sensor abstraction, Processing (SLAM + semantics), Interface (ROS topics/services), and Visualization/Evaluation
- Modular separation:
- Core SLAM code isolated under orb_slam3/
- ROS interface code under src/
- Config-driven parameterization (YAML, launch)
- Extensibility: semantic entities plugged in via header/src under Semantic subfolders

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers as subgraphs
    subgraph "Sensors & Drivers" 
        style Sensors fill:#ccffcc,stroke:#333,stroke-width:1px
        RS["RealSense Driver\n(realsense2_camera)"]:::external
        ARUCO["Aruco Marker Publisher\n(aruco_ros)"]:::external
    end

    subgraph "ROS Transport\n(Message Bus)"
        style ROSBus fill:#ffffff,stroke:#333,stroke-width:1px
        TOPICS["Topics:\n/camera/...  \n/imu  \n/aruco_marker_publisher/markers\n/orb_slam3/..."]:::bus
        SERVICES["Services:\n/orb_slam3/save_map\n/orb_slam3/save_trajectory"]:::bus
    end

    subgraph "SLAM Core & Semantic\n(Blue Layer)"
        style SLAM fill:#cce5ff,stroke:#333,stroke-width:1px
        SLAMNode["orb_slam3_ros Node\n(C++ Executable)"]:::service
        subgraph "ORB-SLAM3 Core"
            CoreLib["ORB-SLAM3 Library"]:::library
        end
        subgraph "Semantic Module"
            Semantic["Semantic Processing\n(Doors, Walls, Rooms, Markers)"]:::module
        end
    end

    subgraph "Persistence & Services\n(Orange Layer)"
        style Persist fill:#ffe0b3,stroke:#333,stroke-width:1px
        SaveMapSrv["SaveMap.srv"]:::service
        TrajSave["SaveTrajectory Service"]:::service
        AtlasFunc["System.SaveAtlasToFile"]:::service
    end

    subgraph "Visualization & Evaluation\n(Purple/Grey Layer)"
        style Viz fill:#e6ccff,stroke:#333,stroke-width:1px
        RViz["RViz Configurations"]:::tool
        Pangolin["Pangolin Viewer"]:::tool
        EvalScripts["Evaluation Scripts"]:::script
        GroundTruth["Ground Truth Data"]:::data
    end

    %% Config & Launch
    Config["Configuration Files\n(YAML & RViz)"]:::config
    Launch["ROS Launch Files"]:::config

    %% Connections
    RS -->|"/camera/..."/imu| TOPICS
    ARUCO -->|"/aruco_marker_publisher/markers"| TOPICS
    TOPICS -->|subscribes| SLAMNode
    SLAMNode -->|invokes| CoreLib
    SLAMNode -->|publishes semantics| Semantic
    SLAMNode -->|publishes keyframes/map| TOPICS
    SLAMNode -->|calls| SaveMapSrv
    SLAMNode -->|calls| TrajSave
    SLAMNode -->|calls| AtlasFunc
    SLAMNode -->|renders| Pangolin
    TOPICS -->|visualizes| RViz
    EvalScripts -->|reads| GroundTruth
    EvalScripts -->|reads| TOPICS

    Config -->|feeds params| SLAMNode
    Launch -->|starts nodes| RS
    Launch -->|starts nodes| ARUCO
    Launch -->|starts nodes| SLAMNode

    %% Click Events
    click CoreLib "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/src/"
    click CoreLib "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/include/"
    click CoreLib "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/Thirdparty/"
    click CoreLib "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/orb_slam3/Vocabulary/ORBvoc.txt.bin"
    click Semantic "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/src/Semantic/"
    click Semantic "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/include/Semantic/"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_mono.cc"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_mono_inertial.cc"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_rgbd.cc"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_rgbd_inertial.cc"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_stereo.cc"
    click SLAMNode "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/ros_stereo_inertial.cc"
    click RS "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/config/RealSense_D435i.yaml"
    click Config "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/config/"
    click Launch "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/launch/"
    click SaveMapSrv "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/srv/SaveMap.srv"
    click AtlasFunc "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/orb_slam3/src/System.cc"
    click AtlasFunc "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/orb_slam3/include/System.h"
    click Pangolin "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/orb_slam3/src/Viewer.cc"
    click Pangolin "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/orb_slam3/include/Viewer.h"
    click RViz "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/config/*.rviz"
    click EvalScripts "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/evaluation/associate.py"
    click EvalScripts "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/evaluation/evaluate_ate_scale.py"
    click EvalScripts "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/evaluation/generate_pose_txt_files.py"
    click GroundTruth "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/evaluation/Ground_truth/"
    click Config "https://github.com/snt-arg/semantic_orb_slam3_ros/tree/master/orb_slam3/Examples/"
    click Config "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/include/common.h"
    click Config "https://github.com/snt-arg/semantic_orb_slam3_ros/blob/master/src/common.cc"

    %% Styles
    classDef external fill:#ccffcc,stroke:#009900,stroke-width:2px
    classDef bus fill:#f2f2f2,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
    classDef service fill:#ffcc99,stroke:#cc6600,stroke-width:2px
    classDef library fill:#cce5ff,stroke:#004080,stroke-width:2px
    classDef module fill:#cce5ff,stroke:#0066cc,stroke-width:2px
    classDef tool fill:#e6ccff,stroke:#660099,stroke-width:2px
    classDef script fill:#d9d9d9,stroke:#666,stroke-width:1px
    classDef data fill:#f2f2f2,stroke:#666,stroke-width:1px
    classDef config fill:#fff0b3,stroke:#cc9900,stroke-width:1px
```
