System - ORB-SLAM3

Overview

The System class is the main entry point for ORB-SLAM3. It initializes and manages all SLAM components including tracking, local mapping, loop closing, and visualization threads.

Constructor

System(const string &strVocFile, 
       const string &strSettingsFile, 
       const eSensor sensor, 
       const bool bUseViewer = true, 
       const int initFr = 0, 
       const string &strSequence = std::string())

Initializes the SLAM system and launches Local Mapping, Loop Closing, and Viewer threads.

Parameters

strVocFile: Path to the ORB vocabulary file
strSettingsFile: Path to the settings configuration file
sensor: Sensor type (see eSensor enum)
bUseViewer: Enable/disable the visualization viewer (default: true)
initFr: Initial frame ID (default: 0)
strSequence: Optional sequence name for dataset identification

Example

ORB_SLAM3::System SLAM("Vocabulary/ORBvoc.txt", 
                       "Examples/Monocular/TUM1.yaml",
                       ORB_SLAM3::System::MONOCULAR,
                       true);

Enumerations

eSensor

Defines the input sensor type:

enum eSensor {
    MONOCULAR = 0,
    STEREO = 1,
    RGBD = 2,
    IMU_MONOCULAR = 3,
    IMU_STEREO = 4,
    IMU_RGBD = 5
}

FileType

Defines the file output format:

enum FileType {
    TEXT_FILE = 0,
    BINARY_FILE = 1
}

Tracking Methods

TrackMonocular

Sophus::SE3f TrackMonocular(const cv::Mat &im, 
                            const double &timestamp, 
                            const vector<IMU::Point>& vImuMeas = vector<IMU::Point>(), 
                            string filename = "")

Processes a monocular frame and optionally IMU data. Parameters:

im: Input image (RGB CV_8UC3 or grayscale CV_8U). RGB is converted to grayscale
timestamp: Frame timestamp in seconds
vImuMeas: Optional vector of IMU measurements
filename: Optional filename for debugging

Returns: Camera pose as SE3 transformation (empty if tracking fails)

TrackStereo

Sophus::SE3f TrackStereo(const cv::Mat &imLeft, 
                        const cv::Mat &imRight, 
                        const double &timestamp, 
                        const vector<IMU::Point>& vImuMeas = vector<IMU::Point>(), 
                        string filename = "")

Processes a stereo frame pair. Images must be synchronized and rectified. Parameters:

imLeft: Left rectified image (RGB CV_8UC3 or grayscale CV_8U)
imRight: Right rectified image (RGB CV_8UC3 or grayscale CV_8U)
timestamp: Frame timestamp in seconds
vImuMeas: Optional vector of IMU measurements
filename: Optional filename for debugging

Returns: Camera pose as SE3 transformation (empty if tracking fails)

TrackRGBD

Sophus::SE3f TrackRGBD(const cv::Mat &im, 
                      const cv::Mat &depthmap, 
                      const double &timestamp, 
                      const vector<IMU::Point>& vImuMeas = vector<IMU::Point>(), 
                      string filename = "")

Processes an RGB-D frame. Depth map must be registered to the RGB frame. Parameters:

im: RGB image (CV_8UC3) or grayscale (CV_8U)
depthmap: Depth map (CV_32F float format)
timestamp: Frame timestamp in seconds
vImuMeas: Optional vector of IMU measurements
filename: Optional filename for debugging

Returns: Camera pose as SE3 transformation (empty if tracking fails)

Mode Control

ActivateLocalizationMode

void ActivateLocalizationMode()

Stops the local mapping thread and performs only camera tracking. Use this for localization-only mode without map building.

DeactivateLocalizationMode

void DeactivateLocalizationMode()

Resumes the local mapping thread and performs full SLAM (tracking + mapping).

State Management

Reset

void Reset()

Resets the system by clearing the entire Atlas.

ResetActiveMap

void ResetActiveMap()

Resets only the currently active map without affecting other maps in the Atlas.

Shutdown

void Shutdown()

Requests all threads to finish and waits for completion. Must be called before saving trajectories.

isShutDown

bool isShutDown()

Returns: True if the system has been shut down

Map Change Detection

MapChanged

bool MapChanged()

Detects if a significant map change (loop closure, global BA) has occurred since the last call. Returns: True if the map has changed significantly

Trajectory Export

SaveTrajectoryTUM

void SaveTrajectoryTUM(const string &filename)

Saves the camera trajectory in TUM RGB-D dataset format. Only works for stereo and RGB-D. Note: Call Shutdown() first. Format: http://vision.in.tum.de/data/datasets/rgbd-dataset

SaveKeyFrameTrajectoryTUM

void SaveKeyFrameTrajectoryTUM(const string &filename)

Saves keyframe poses in TUM RGB-D format. Works for all sensor types.

SaveTrajectoryEuRoC

void SaveTrajectoryEuRoC(const string &filename)
void SaveTrajectoryEuRoC(const string &filename, Map* pMap)

Saves trajectory in EuRoC dataset format. Optionally for a specific map.

SaveKeyFrameTrajectoryEuRoC

void SaveKeyFrameTrajectoryEuRoC(const string &filename)
void SaveKeyFrameTrajectoryEuRoC(const string &filename, Map* pMap)

Saves keyframe trajectory in EuRoC format. Optionally for a specific map.

SaveTrajectoryKITTI

void SaveTrajectoryKITTI(const string &filename)

Saves trajectory in KITTI dataset format. Only works for stereo and RGB-D. Note: Call Shutdown() first. Format: http://www.cvlibs.net/datasets/kitti/eval_odometry.php

Frame Information

GetTrackingState

int GetTrackingState()

Returns the current tracking state. Call immediately after Track methods. Returns: Tracking state integer (see Tracking::eTrackingState)

GetTrackedMapPoints

std::vector<MapPoint*> GetTrackedMapPoints()

Returns: Vector of map points tracked in the most recent frame

GetTrackedKeyPointsUn

std::vector<cv::KeyPoint> GetTrackedKeyPointsUn()

Returns: Vector of undistorted keypoints tracked in the most recent frame

Debugging Methods

GetTimeFromIMUInit

double GetTimeFromIMUInit()

Returns: Time elapsed since IMU initialization

isLost

bool isLost()

Returns: True if tracking is currently lost

isFinished

bool isFinished()

Returns: True if the system has finished processing

ChangeDataset

void ChangeDataset()

Signals a dataset change for multi-sequence processing.

GetImageScale

float GetImageScale()

Returns: Current image scale factor

SaveDebugData

void SaveDebugData(const int &iniIdx)

Saves data used for initialization debugging.

Usage Example

#include "System.h"
#include <opencv2/opencv.hpp>

int main() {
    // Initialize system
    ORB_SLAM3::System SLAM("Vocabulary/ORBvoc.txt",
                           "config.yaml",
                           ORB_SLAM3::System::MONOCULAR,
                           true);
    
    // Process frames
    cv::VideoCapture cap(0);
    cv::Mat frame;
    double timestamp = 0.0;
    
    while (cap.read(frame)) {
        Sophus::SE3f pose = SLAM.TrackMonocular(frame, timestamp);
        
        if (!pose.translation().isZero()) {
            std::cout << "Pose: " << pose.translation().transpose() << std::endl;
        }
        
        timestamp += 0.033; // 30 FPS
    }
    
    // Cleanup
    SLAM.Shutdown();
    SLAM.SaveTrajectoryTUM("CameraTrajectory.txt");
    
    return 0;
}

Thread Safety

The System class manages multiple threads internally:

Tracking: Runs in the main thread
Local Mapping: Runs in a separate thread (mptLocalMapping)
Loop Closing: Runs in a separate thread (mptLoopClosing)
Viewer: Runs in a separate thread (mptViewer)

All public methods are thread-safe and use mutexes for synchronization.

Tracking - Camera tracking and pose estimation
LocalMapping - Local map management
LoopClosing - Loop detection and correction

Core API

Data Structures

Camera Models

IMU & Sensors

Utilities

​Overview

​Constructor

​Parameters

​Example

​Enumerations

​eSensor

​FileType

​Tracking Methods

​TrackMonocular

​TrackStereo

​TrackRGBD

​Mode Control

​ActivateLocalizationMode

​DeactivateLocalizationMode

​State Management

​Reset

​ResetActiveMap

​Shutdown

​isShutDown

​Map Change Detection

​MapChanged

​Trajectory Export

​SaveTrajectoryTUM

​SaveKeyFrameTrajectoryTUM

​SaveTrajectoryEuRoC

​SaveKeyFrameTrajectoryEuRoC

​SaveTrajectoryKITTI

​Frame Information

​GetTrackingState

​GetTrackedMapPoints

​GetTrackedKeyPointsUn

​Debugging Methods

​GetTimeFromIMUInit

​isLost

​isFinished

​ChangeDataset

​GetImageScale

​SaveDebugData

​Usage Example

​Thread Safety

​Related Classes

Build docs developers (and LLMs) love

Overview

Constructor

Parameters

Example

Enumerations

eSensor

FileType

Tracking Methods

TrackMonocular

TrackStereo

TrackRGBD

Mode Control

ActivateLocalizationMode

DeactivateLocalizationMode

State Management

Reset

ResetActiveMap

Shutdown

isShutDown

Map Change Detection

MapChanged

Trajectory Export

SaveTrajectoryTUM

SaveKeyFrameTrajectoryTUM

SaveTrajectoryEuRoC

SaveKeyFrameTrajectoryEuRoC

SaveTrajectoryKITTI

Frame Information

GetTrackingState

GetTrackedMapPoints

GetTrackedKeyPointsUn

Debugging Methods

GetTimeFromIMUInit

isLost

isFinished

ChangeDataset

GetImageScale

SaveDebugData

Usage Example

Thread Safety

Related Classes