# raulmur/orb_slam architecture

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

- Interactive diagram: https://gitdiagram.com/raulmur/orb_slam
- Repository: https://github.com/raulmur/orb_slam

## Overview

##### Project type and purpose
- ORB-SLAM Monocular is a robotics/perception system implemented in C++ and ROS. It computes in real time the camera trajectory and a sparse 3D reconstruction from a single camera.
- It tightly integrates with ROS for image I/O and visualization, uses OpenCV for feature extraction, Boost for threading, g2o for graph optimization, and DBoW2 for place recognition.

##### Main components
a. ROS Interface
- Subscriber: listens on `/camera/image_raw`
- Publishers:
– `/ORB_SLAM/Frame` (processed image)
– `/ORB_SLAM/Map` (3D point cloud)
– `/tf` transforms for camera and world
- Launch files (ExampleFuerte.launch, ExampleGroovyOrNewer.launch)
b. Tracking Module
- Receives raw images → ORBextractor → ORBmatcher against local map
- Chooses between initialization (Initializer) and normal tracking
- Outputs camera pose and decides when to insert a KeyFrame
c. Initialization Module
- Bootstraps map from initial frames (planar or general scenes) using the Initializer class
d. Local Mapping Thread
- Takes new KeyFrames → triangulates new MapPoints → culls redundant keyframes/points
e. Loop Closing Thread
- Queries KeyFrameDatabase (DBoW2) to detect loops
- When loop found, computes Sim3 transformation via Sim3Solver → runs global pose‐graph optimization in g2o
f. Data Structures
- MapPoint, KeyFrame, KeyFrameDatabase, ORBVocabulary
g. Optimizer
- Uses g2o to optimize pose graphs and bundle adjustment
h. Converter / PnP / Sim3 Solvers
- Geometry utilities (Converter) and solvers for pose estimation

##### Relationships and data flow
- Raw images (ROS) → Tracking →
├─ if not initialized → Initializer → Tracking
├─ if new KeyFrame → push to Local Mapping
└─ always publishes pose/frame/map via ROS topics
- Local Mapping and Loop Closing run in parallel, both updating the central Map
- Loop Closing uses KeyFrameDatabase (DBoW2) and g2o to correct drift and update all KeyFrame poses
- Optimizer invoked by Local Mapping (local BA) and Loop Closing (global BA)

##### Architectural patterns and design principles
- Multi-threaded pipeline: Tracking / LocalMapping / LoopClosing run concurrently
- Publisher/Subscriber: ROS topics for decoupled communication
- Graph-based SLAM: poses and landmarks form a sparse graph optimized by g2o
- Separation of concerns: clear modules for feature extraction, mapping, loop detection, optimization

##### Important technologies/frameworks
- ROS (message passing, rviz visualization)
- OpenCV (image processing, ORB features)
- Boost (thread management)
- Eigen3 (linear algebra)
- g2o (nonlinear optimization)
- DBoW2 (Bag-of-Words place recognition)

##### Final recommendations
- Related components visually (e.g., put all optimization in one region) to improve readability

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ROS Interface
    subgraph "ROS Interface"
        LF1["ExampleFuerte.launch"]:::ros
        LF2["ExampleGroovyOrNewer.launch"]:::ros
        Med["manifest.xml"]:::ros
        MN["src/main.cc"]:::ros
        SUB["/camera/image_raw"]:::topic
        PUB1["/ORB_SLAM/Frame"]:::topic
        PUB2["/ORB_SLAM/Map"]:::topic
        PUB3["/tf"]:::topic
        FP["FramePublisher"]:::ros
        MP["MapPublisher"]:::ros
    end

    %% Core SLAM Threads
    subgraph "Core SLAM Threads"
        TR["Tracking (thread)"]:::core
        INI["Initializer"]:::core
        LM["Local Mapping (thread)"]:::core
        LC["Loop Closing (thread)"]:::core
    end

    %% Data Stores
    subgraph "Data Stores"
        MAP["Map"]:::store
        KFDB["KeyFrameDatabase"]:::store
        VOC["ORBVocabulary"]:::store
    end

    %% External Libraries
    subgraph "External Libraries"
        OPENCV["OpenCV"]:::ext
        BOOST["Boost"]:::ext
        EIGEN["Eigen"]:::ext
        G2O["g2o"]:::ext
        DBOW2["DBoW2"]:::ext
    end

    %% Data Flows
    SUB -->|"/camera/image_raw"| TR
    TR -->|"initialize"| INI
    INI --> TR
    TR -->|"new KeyFrame"| LM
    LM -->|"MapPoints"| MAP
    LC -->|"pose corrections"| MAP
    MAP -->|"map data"| TR
    DBOW2 --> LC
    LC -->|"loop queries"| DBOW2
    TR -->|"/ORB_SLAM/Frame"| PUB1
    TR -->|"/ORB_SLAM/Map"| PUB2
    TR -->|"/tf"| PUB3
    LM --> G2O
    LC --> G2O

    %% Click Events
    click LF1 "https://github.com/raulmur/orb_slam/blob/master/ExampleFuerte.launch"
    click LF2 "https://github.com/raulmur/orb_slam/blob/master/ExampleGroovyOrNewer.launch"
    click Med "https://github.com/raulmur/orb_slam/blob/master/manifest.xml"
    click MN "https://github.com/raulmur/orb_slam/blob/master/src/main.cc"
    click FP "https://github.com/raulmur/orb_slam/blob/master/include/FramePublisher.h"
    click FP "https://github.com/raulmur/orb_slam/blob/master/src/FramePublisher.cc"
    click MP "https://github.com/raulmur/orb_slam/blob/master/include/MapPublisher.h"
    click MP "https://github.com/raulmur/orb_slam/blob/master/src/MapPublisher.cc"
    click TR "https://github.com/raulmur/orb_slam/blob/master/include/Tracking.h"
    click TR "https://github.com/raulmur/orb_slam/blob/master/src/Tracking.cc"
    click INI "https://github.com/raulmur/orb_slam/blob/master/include/Initializer.h"
    click INI "https://github.com/raulmur/orb_slam/blob/master/src/Initializer.cc"
    click LM "https://github.com/raulmur/orb_slam/blob/master/include/LocalMapping.h"
    click LM "https://github.com/raulmur/orb_slam/blob/master/src/LocalMapping.cc"
    click LC "https://github.com/raulmur/orb_slam/blob/master/include/LoopClosing.h"
    click LC "https://github.com/raulmur/orb_slam/blob/master/src/LoopClosing.cc"
    click MAP "https://github.com/raulmur/orb_slam/blob/master/include/Map.h"
    click MAP "https://github.com/raulmur/orb_slam/blob/master/src/Map.cc"
    click KFDB "https://github.com/raulmur/orb_slam/blob/master/include/KeyFrameDatabase.h"
    click KFDB "https://github.com/raulmur/orb_slam/blob/master/src/KeyFrameDatabase.cc"
    click VOC "https://github.com/raulmur/orb_slam/blob/master/include/ORBVocabulary.h"

    %% Styles
    classDef ros fill:#D8BFD8,stroke:#976A97;
    classDef core fill:#ADD8E6,stroke:#1E90FF;
    classDef store fill:#90EE90,stroke:#228B22,stroke-width:2px;
    classDef ext fill:#FFA500,stroke:#CC8400;
    classDef topic fill:#E6E6FA,stroke:#9370DB,shape:parallelogram;
```
