Multi-Map System - ORB-SLAM3

Overview

ORB-SLAM3 features a sophisticated multi-map system called the Atlas, which can create, manage, and merge multiple independent maps within a single session. This capability enables robust long-term operation, seamless map merging, and recovery from tracking failures.

The Atlas system was introduced in ORB-SLAM3 based on the research paper “ORBSLAM-Atlas: a robust and accurate multi-map system” (IROS 2019).

The Atlas Class

The Atlas is the core data structure managing all maps in the system. Definition: include/Atlas.h:49-166

class Atlas
{
public:
    Atlas();
    Atlas(int initKFid);
    
    void CreateNewMap();
    void ChangeMap(Map* pMap);
    Map* GetCurrentMap();
    
    void AddKeyFrame(KeyFrame* pKF);
    void AddMapPoint(MapPoint* pMP);
    
    vector<Map*> GetAllMaps();
    int CountMaps();
    
    bool isInertial();
    void SetInertialSensor();
    bool isImuInitialized();
    
    void SetMapBad(Map* pMap);
    void RemoveBadMaps();
    
    void clearMap();
    void clearAtlas();
    
protected:
    std::set<Map*> mspMaps;      // All active maps
    std::set<Map*> mspBadMaps;   // Deprecated maps
    Map* mpCurrentMap;            // Currently active map
};

Key Concepts

Active Map

The active map is the map currently being used for tracking and mapping.

// Get the currently active map
Map* pActiveMap = mpAtlas->GetCurrentMap();

// Switch to a different map
mpAtlas->ChangeMap(pAnotherMap);

Only one map is active at any given time. Tracking and local mapping operate on the active map.

Map States

Maps in the Atlas can be in different states:

Active Map

Currently being used for tracking and mapping operations.

Inactive Maps

Previously created maps stored in the Atlas, available for reactivation.

Bad Maps

Maps marked as bad due to insufficient data or errors, scheduled for removal.

Multi-Map Workflows

Scenario 1: Tracking Loss and Recovery

Tracking Lost

Camera loses track due to fast motion, occlusion, or entering an unknown area.

Create New Map

If relocalization fails, the Atlas creates a new map and reinitializes SLAM.

mpAtlas->CreateNewMap();

Continue Tracking

The system continues tracking in the new map while preserving the previous map.

Map Merging

When the system detects overlap between maps (via place recognition), they are merged.

Scenario 2: Revisiting Locations

When the camera revisits a previously mapped area:

Place Recognition detects the known location
Map Matching identifies which inactive map corresponds to the location
Map Activation switches the active map or merges maps
Seamless Transition continues SLAM operation without interruption

Map Creation and Management

Creating a New Map

// Create new map (happens automatically on tracking failure)
void Atlas::CreateNewMap()
{
    Map* pNewMap = new Map();
    mspMaps.insert(pNewMap);
    mpCurrentMap = pNewMap;
    
    // Initialize map properties
    if (isInertial()) {
        pNewMap->SetInertialSensor();
    }
}

Creating a new map during operation indicates tracking was lost. The system automatically handles this to maintain robustness.

Accessing Maps

// Get the currently active map
Map* pCurrentMap = mpAtlas->GetCurrentMap();

// Check map properties
long unsigned int nKeyFrames = pCurrentMap->KeyFramesInMap();
long unsigned int nMapPoints = pCurrentMap->MapPointsInMap();

Inertial Map Properties

For visual-inertial SLAM, maps track additional IMU-related state:

// Check if atlas uses inertial sensor
bool bUseIMU = mpAtlas->isInertial();

// Enable inertial sensor
mpAtlas->SetInertialSensor();

// Check IMU initialization status
if (mpAtlas->isImuInitialized()) {
    // IMU is initialized, scale and gravity are known
}

IMU Initialization: Visual-inertial maps require 2-15 seconds of initialization to estimate scale, gravity direction, and velocity. The isImuInitialized() flag indicates when this process is complete.

Map Merging

Map merging is one of the most powerful features of the Atlas system.

When Maps Merge

Maps are merged when:

Loop Closure Detection finds a connection between maps
Place Recognition identifies overlapping areas
Sufficient Common Features are found between maps

Merging Process

Detect Overlap

Place recognition system identifies that the current location exists in an inactive map.

Compute Transformation

Calculate the relative transformation (rotation, translation, scale) between maps.

Merge Maps

Combine keyframes and map points from both maps into a single unified map.

Optimize

Perform pose graph optimization and bundle adjustment on the merged map.

Update Atlas

Remove the merged map and update the active map.

Seamless Fusion: Map merging happens automatically without user intervention, creating a unified map with globally consistent poses.

Map Persistence

ORB-SLAM3 supports saving and loading maps for reuse across sessions.

Saving Maps

// Save atlas to file (internal method)
void System::SaveAtlas(int type)
{
    // type: FileType::TEXT_FILE or FileType::BINARY_FILE
    
    // Serialize atlas including:
    // - All maps with keyframes and map points
    // - ORB vocabulary
    // - Camera parameters
}

Loading Maps

// Load atlas from file
bool System::LoadAtlas(int type)
{
    // Deserialize atlas and restore:
    // - Map structure
    // - Keyframe database
    // - Place recognition vocabulary
    
    return true; // if successful
}

File Formats:

TEXT_FILE (0): Human-readable but larger file size
BINARY_FILE (1): Compact binary format for production use

Camera and Map Association

Multi-Camera Support

The Atlas manages cameras across different maps:

// Add camera to atlas
GeometricCamera* pCamera = new Pinhole(vParameters);
GeometricCamera* pCamInAtlas = mpAtlas->AddCamera(pCamera);

// Get all cameras
std::vector<GeometricCamera*> vpCameras = mpAtlas->GetAllCameras();

Camera registration: Each unique camera model is stored once and shared across maps, defined in include/Atlas.h:92-93.

Reference Map Points

// Set reference map points for visualization
mpAtlas->SetReferenceMapPoints(vpRefMapPoints);

// Get reference map points
vector<MapPoint*> vpRefMPs = mpAtlas->GetReferenceMapPoints();

Reference map points are used by the viewer for visualization and represent the most reliable points in the map.

Database Integration

KeyFrame Database

The Atlas integrates with the keyframe database for place recognition:

// Set keyframe database
mpAtlas->SetKeyFrameDababase(mpKeyFrameDB);

// Get keyframe database
KeyFrameDatabase* pKFDB = mpAtlas->GetKeyFrameDatabase();

ORB Vocabulary

The ORB vocabulary is shared across all maps:

// Set vocabulary
mpAtlas->SetORBVocabulary(mpVocabulary);

// Get vocabulary
ORBVocabulary* pVoc = mpAtlas->GetORBVocabulary();

Statistics and Monitoring

// Current map statistics
long unsigned int nKFs = mpAtlas->KeyFramesInMap();
long unsigned int nMPs = mpAtlas->MapPointsInMap();

cout << "Current map: " << nKFs << " keyframes, " 
     << nMPs << " map points" << endl;

Map Cleanup

Removing Bad Maps

// Mark a map as bad
mpAtlas->SetMapBad(pMap);

// Remove all bad maps from atlas
mpAtlas->RemoveBadMaps();

Clearing Data

// Clear the current active map
mpAtlas->clearMap();

Clearing operations are destructive and cannot be undone. Use with caution.

Serialization

The Atlas supports Boost serialization for save/load operations:

template<class Archive>
void serialize(Archive &ar, const unsigned int version)
{
    ar.template register_type<Pinhole>();
    ar.template register_type<KannalaBrandt8>();
    
    ar & mvpBackupMaps;   // Vector of maps
    ar & mvpCameras;      // Cameras
    ar & Map::nNextId;    // Static IDs
    ar & Frame::nNextId;
    ar & KeyFrame::nNextId;
    ar & MapPoint::nNextId;
    ar & GeometricCamera::nNextId;
    ar & mnLastInitKFidMap;
}

This enables complete restoration of the Atlas state including all maps and their associations.

Best Practices

Map Management Strategy

Let the system handle map creation automatically on tracking loss
Don’t manually switch maps unless you have a specific reason
Monitor map statistics to understand system behavior
Save maps periodically for long-term applications

Memory Management

Each map consumes memory for keyframes and map points
Bad maps are automatically cleaned up
For long sessions, consider saving and clearing old maps
Merged maps free memory from the absorbed map

Inertial Considerations

Each new inertial map requires 2-15 seconds for IMU initialization
Scale consistency is maintained across merged maps
Check isImuInitialized() before relying on metric scale

Place Recognition

Map merging depends on reliable place recognition
Ensure good visual overlap between environments
Loop closure quality affects merge quality

Use Cases

Long-Term Operation

Robot operating over multiple days/weeks, automatically managing maps as it explores new areas.

Exploration and Mapping

Creating separate maps for different floors or buildings, merging when overlap is detected.

Recovery from Failure

Automatically recovering from tracking loss by creating a new map, then merging when possible.

Multi-Session SLAM

Saving maps from previous sessions and merging them with new explorations.

SLAM Overview

Understand the overall SLAM architecture

System API

System class methods for map management

Loop Closing

How loop closure triggers map merging

Save/Load Maps

Guide to persisting maps across sessions

Technical Details

Thread Safety

The Atlas class uses mutexes for thread-safe operation:

std::mutex mMutexAtlas;  // Protects map modifications

All public methods are thread-safe and can be called from tracking, mapping, or loop closing threads.

Map ID Tracking

unsigned long int mnLastInitKFidMap;  // Last initialization keyframe ID

unsigned long int GetLastInitKFid();

Tracks the last keyframe ID used for map initialization, useful for debugging and map versioning.

Performance Considerations

Memory: Each map stores keyframes (poses + features) and map points (3D positions)
Computation: Map merging involves pose graph optimization (expensive but infrequent)
Real-time: Active map operations are optimized for real-time performance
Scaling: System tested with multiple maps totaling thousands of keyframes

Get Started

Core Concepts

Guides

Examples

Advanced

​Overview

​The Atlas Class

​Key Concepts

​Active Map

​Map States

Active Map

Inactive Maps

Bad Maps

​Multi-Map Workflows

​Scenario 1: Tracking Loss and Recovery

​Scenario 2: Revisiting Locations

​Map Creation and Management

​Creating a New Map

​Accessing Maps

​Inertial Map Properties

​Map Merging

​When Maps Merge

​Merging Process

​Map Persistence

​Saving Maps

​Loading Maps

​Camera and Map Association

​Multi-Camera Support

​Reference Map Points

​Database Integration

​KeyFrame Database

​ORB Vocabulary

​Statistics and Monitoring

​Map Cleanup

​Removing Bad Maps

​Clearing Data

​Serialization

​Best Practices

​Use Cases

Long-Term Operation

Exploration and Mapping

Recovery from Failure

Multi-Session SLAM

​Related Topics

SLAM Overview

System API

Loop Closing

Save/Load Maps

​Technical Details

​Thread Safety

​Map ID Tracking

​Performance Considerations

Build docs developers (and LLMs) love

Overview

The Atlas Class

Key Concepts

Active Map

Map States

Multi-Map Workflows

Scenario 1: Tracking Loss and Recovery

Scenario 2: Revisiting Locations

Map Creation and Management

Creating a New Map

Accessing Maps

Inertial Map Properties

Map Merging

When Maps Merge

Merging Process

Map Persistence

Saving Maps

Loading Maps

Camera and Map Association

Multi-Camera Support

Reference Map Points

Database Integration

KeyFrame Database

ORB Vocabulary

Statistics and Monitoring

Map Cleanup

Removing Bad Maps

Clearing Data

Serialization

Best Practices

Use Cases

Related Topics

Technical Details

Thread Safety

Map ID Tracking

Performance Considerations